═══ 1. CICS Family: Client/Server Programming ═══ ═══ 2. Version Notice ═══ First edition (January, 1995) This edition applies to the following releases of the IBM licensed program Customer Information Control System (CICS): o IBM CICS Client for DOS, Version 1, program number 5622-543 o IBM CICS Client for OS/2, Version 1, program number 5622-543 o IBM CICS Client for Windows, Version 1, program number 5622-543 o IBM CICS Client for Macintosh, Version 1, program number 5622-543 o IBM CICS for OS/2, Version 2.0.1, program number 5648-036 o IBM Transaction Server for OS/2 Warp, Version 4, program number 5622-808 o IBM CICS for Windows NT, Version 2, program number 5622-347 o IBM CICS Client for Sun Systems, Release 1, program number 5765-290 o IBM AIX CICS/6000, Version 1.2, program number 5765-148 o IBM AIX Client for CICS/6000, Version 1.2, program number 5765-152 o IBM CICS for AIX Version 2.1, program number 5765-553 It will also apply to any subsequent versions, releases, and modifications until otherwise indicated in new editions. Consult the latest edition of the applicable IBM system bibliography for current information on these products. Order publications through your IBM representative or the IBM branch office serving your locality. Publications are not stocked at the address given below. A form for reader's comments appears at the back of this publication. If the form has been removed, address your comments to: IBM United Kingdom Laboratories Limited, Information Development, Mail Point 095, Hursley Park, Winchester, Hampshire, England, SO21 2JN. When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you. (c) Copyright International Business Machines Corporation 1989, 1996. All rights reserved. Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication, or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp. ═══ 3. Notices ═══ The following paragraph does not apply in any country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore this statement may not apply to you. References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM licensed program or other IBM product in this publication is not intended to state or imply that only IBM's program or other product may be used. Any functionally equivalent program that does not infringe any of IBM's intellectual property rights may be used instead of the IBM product. Evaluation and verification of operation in conjunction with other products, except those expressly designated by IBM, is the user's responsibility. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact Laboratory Counsel, MP151, IBM United Kingdom Laboratories, Hursley Park, Winchester, Hampshire, England SO21 2JN. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of Licensing, IBM Corporation, 500 Columbus Avenue, Thornwood, New York 10594, U.S.A. ═══ 3.1. Programming interface information ═══ This book is intended to help you to write application programs that use the features provided by various members of the CICS family. This book documents General-use Programming Interface and Associated Guidance Information provided by various members of the CICS family. General-use programming interfaces allow the customer to write programs that obtain the services of various members of the CICS family. ═══ 3.2. Trademarks and service marks ═══ The following terms, used in this publication, are trademarks or service marks of IBM Corporation in the United States or other countries or both: CICS CICS/ESA CICS/MVS CICS OS/2 CICS/VSE CICS/400 CICS/6000 IBM OS/2 Presentation Manager AIX IBMLink VisualAge The following terms used in this publication are trademarks of other companies: Microsoft Corporation: Microsoft Windows Microsoft Windows Windows NT Sun Systems: SunOS Sun Apple Computer Corp.: Macintosh Apple Macintosh Open Software Foundation: Motif Novell Inc.: Open Look Hewlett-Packard Company: HP-UX HP 9000 Micro Focus Limited: Micro Focus Micro Focus Object COBOL ═══ 4. Summary of changes ═══ Information about ECI and EPI user exits for IBM CICS on Open Systems Version 2 has been added as a appendix. Information about IBM Transaction Server for OS/2 Warp, Version 4 has been added. Corrections have been made to the list of related publications in the preface. More information about security in the ECI and the EPI has been added. A correction has been made to the description of the eci_transid field in the ECI parameter block. A correction has been made to the description of the Transid parameter of CICS_EpiStartTran. Various minor technical corrections have been made. Small typographical errors have been corrected. ═══ 5. Preface ═══ ═══ 5.1. What this book is about ═══ This book is about the CICS Family programming interfaces to enable non-CICS applications to use CICS facilities in a client-server environment. The interfaces described are: o External call interface (ECI) o External presentation interface (EPI). ═══ 5.2. Who this book is for ═══ This book is for application designers and application programmers in a client-server environment. ═══ 5.3. What you need to know to understand this book ═══ You should have a good knowledge of: o CICS, and the CICS servers that the applications will use o The concepts of client/server programming o The programming language in which the applications will be written o The programming environment in which the programs will operate. ═══ 5.4. Definitions ═══ In this book, `CICS on Open Systems' is used to refer to the following products, subject to availability: o CICS/6000 o CICS for AIX Version 2 o CICS for HP 9000 o CICS for Digital UNIX `CICS on System/390' is used to refer to: o CICS/VSE o CICS/MVS o CICS/ESA ═══ 5.5. Typographical conventions ═══ The presentation of names of program elements is as follows: 1. When a program element is in lowercase, or mixed case, it is always written in this book in a bold face: eci_userid, CICS_EpiAddTerminal. 2. When a program element is in uppercase, it is always written in this book in a normal face: ECI_ERR_LUW_TOKEN, CICS_EPI_EVENT_END_TERM. ═══ 5.6. Related publications ═══ ═══ 5.6.1. General ═══ o CICS Family: Library Guide, GC33-0356 o CICS Family: Interproduct Communication, SC33-0824. ═══ 5.6.2. Setting up client/server systems ═══ o IBM CICS Clients Administration, SC33-1436 o IBM CICS/6000 Version 1.2 Planning and Installation Guide, GC33-0816 o IBM CICS for AIX Version 2.1 Planning and Installation Guide, GC33-1561 o IBM CICS/6000 Version 1.2 Administration Guide, SC33-1532 o IBM CICS for AIX Version 2.1 Administration Guide, SC33-1562 o IBM CICS on Open Systems Version 1.2 Intercommunication Guide, SC33-0815 o IBM CICS on Open Systems Version 2.1 Intercommunication Guide, SC33-1564 o CICS for OS/2 Customization, SC33-0880 (Version 2), SC33-1581 (Version 3) o CICS for OS/2 Intercommunication, SC33-0826 (Version 2), SC33-1583 (Version 3) o CICS for Windows NT Customization, SC33-1421 o CICS for Windows NT Intercommunication, SC33-1423 o CICS/400 Administration and Operations Guide, SC33-1387 o CICS/400 Intercommunication, SC33-1388 o CICS/ESA Resource Definition Guide, SC33-1165 o CICS/ESA Customization Guide, SC33-1166 o CICS/MVS Resource Definition (Online), SC33-0508 o CICS/MVS Customization Guide, SC33-0507 o CICS/VSE Resource Definition (Online), SC33-0708 o CICS/VSE Customization Guide, SC33-0707. ═══ 5.6.3. Application programming on CICS servers ═══ This section lists books that describe the programming environment of the CICS servers. o CICS for OS/2 Application Programming, SC33-0883 (Version 2), SC33-1585 (Version 3) o CICS for OS/2 Problem Determination, SC33-1005 (Version 2), SC33-1584 (Version 3) o CICS Application Programming Primer (VS COBOL II), SC33-0674 o CICS/VSE Problem Determination Guide, SC33-0716 o CICS/400 Application Programming Guide, SC33-1386 o CICS/ESA Application Programming Guide, SC33-1169 o CICS/ESA Application Programming Reference, SC33-1170 o CICS/ESA Problem Determination Guide, SC33-0678 o CICS/MVS Application Programmer's Reference, SC33-0139 o CICS/MVS Application Programming Primer, SC33-0512 o CICS for Windows NT Application Programming, SC33-1425 o CICS on Open Systems Version 1.2 Application Programming Guide, SC33-0814 o CICS on Open Systems Version 2.1 Application Programming Guide, SC33-1568 o CICS on Open Systems Version 1.2 Application Programming Reference, SC33-0886 o CICS on Open Systems Version 2.1 Application Programming Reference, SC33-1569 o CICS on Open Systems Version 1.2 Problem Determination, SC33-0818 o CICS on Open Systems Version 2.1 Problem Determination Guide, SC33-1565. ═══ 5.6.4. Miscellaneous ═══ o An Introduction to the IBM 3270 Information Display System, GA27-2739 o IBM 3270 Information Display System Data Stream Programmer's Reference, GA23-0059 o PL/I for OS/2 Language Reference, SC26-8003 o PL/I for OS/2 Programming Guide, SC26-8001. o Guide to Writing DCE Applications, by John Shirley, published by O'Reilly Associates, Sebastopol, CA, USA, ISBN 1-56592-004-X ═══ 6. Introducing the external access interfaces ═══ This chapter introduces CICS Family Client/Server Programming, which comprises two application programming interfaces (APIs) that provide external access to CICS facilities: o External call interface (ECI) o External presentation interface (EPI) The chapter is organized as follows: Overview External call interface External presentation interface Using the external access interfaces ECI and EPI exits (CICS on Open Systems Version 2) ═══ 6.1. Overview ═══ The ECI and EPI allow your non-CICS applications to gain access to CICS facilities and data. External access interfaces in CICS client/server configurations illustrates the use of the external interfaces by a non-CICS application in a client system. This application is using the facilities of CICS in a server system. The CICS client software processes the application's ECI and EPI requests, and transmits them to the server system using an appropriate communication protocol. Although the figure shows the client system and server system as separate workstations, it is possible for the whole configuration to be on a single workstation. External access interfaces in CICS client/server configurations Some members of the CICS family provide the external interfaces to non-CICS applications without the use of a CICS client. The non-CICS application must be on the same workstation as the server, and is not able to communicate with other servers. This is illustrated in Server implementation of the external interfaces. In this case the application is using the server implementation of the external interfaces. Server implementation of the external interfaces The following can be client systems that can connect to any CICS server. In these systems an appropriate CICS client must be installed. See the CICS Clients Administration manual. o OS/2 - IBM CICS Client for OS/2 o DOS - IBM CICS Client for DOS o Microsoft Windows - IBM CICS Client for Windows o Apple Macintosh - IBM CICS Client for Macintosh The following can be client systems that connect only to CICS on Open Systems servers: o AIX - IBM AIX Client for CICS/6000 o SunOS - IBM CICS Client for Sun Systems (See note below.) o HP-UX - CICS for HP 9000 o Digital UNIX - CICS for Digital UNIX Note: For programming information for the SunOS environment, see the Installation and User's Guide for IBM CICS Client for Sun Systems. The following server systems provide a server implementation of the external interfaces: o IBM CICS for OS/2 o IBM CICS for Windows NT Any member of the CICS family can be a server, though CICS on System/390 servers support only the ECI. The CICS on Open Systems servers are: o IBM CICS/6000 o IBM CICS for AIX Version 2 o CICS for HP 9000 o CICS for Digital UNIX ═══ 6.2. External call interface ═══ The ECI allows a non-CICS application to call a CICS program in a CICS server. The application can be connected to several servers at the same time, and it can have several program calls outstanding at the same time. The CICS program cannot perform terminal I/O, but can access and update all other CICS resources. External call interface illustrated shows that the same CICS program can be called by a non-CICS application using the external call interface, or by a CICS program using EXEC CICS LINK. Data is exchanged between the two programs by means of a COMMAREA, in a similar way to CICS interprogram communication. External call interface illustrated Calls may be made synchronously or asynchronously. Synchronous calls return control when the called program completes, and the information returned is immediately available. Asynchronous calls return control without reference to the completion of the called program, and the application can ask to be notified when the information becomes available. Calls may also be extended. That is, a single logical unit of work may cover two or more successive calls, though only one call can be active for each logical unit of work at any time. The application can manage many logical units of work concurrently if it uses asynchronous calls. The called program can update resources on its own system, it can use distributed program link (DPL) to call CICS programs on other systems, and it can access resources on other CICS systems by function shipping, by distributed transaction processing (DTP), or (in the CICS/MVS and CICS/ESA environments) by the front end programming interface (FEPI). ═══ 6.3. External presentation interface ═══ The EPI allows a non-CICS application program to be viewed as a 3270 terminal by a CICS server system to which it is connected. External presentation interface shows how both an EPI application and a CICS terminal can schedule transactions in a CICS server. External presentation interface The application can be using the facilities of several servers at the same time, and can act as if it were many different 3270 terminals. The application can schedule CICS transactions, and for these transactions it is the principal facility. With CICS servers that support access through the EPI, other CICS transactions running in the server can use the CICS START command to schedule transactions that use the non-CICS application as their initiating terminal. When a non-CICS application uses the EPI to start a transaction in a CICS server, 3270 data streams and events are passed between the server and the application. The application can present the contents of the terminal I/O to its user in any manner appropriate to the application's operating environment. Transactions can be routed to other CICS systems by standard transaction routing. Resources on other CICS systems can be accessed by function shipping. Note that server transactions can be existing transactions that use 3270 input and output (with some restrictions). ═══ 6.4. Using the external access interfaces ═══ The external interfaces allow non-CICS applications to access and update CICS resources by initiating CICS transactions or calling CICS programs. When used in conjunction with the CICS communication facilities, they enable non-CICS programs to access and update resources on any CICS system. This supports such activities as: 1. Developing graphical user interface (GUI) front ends for CICS applications, using Presentation Manager or other presentation systems 2. Connecting external devices such as bar-code readers to CICS systems 3. Allowing the integration of CICS systems and non-CICS systems. The EPI allows you to develop GUIs, either for existing CICS systems or for new applications. It is particularly useful for developing new GUI front ends for existing CICS transactions, which need not be changed. The application can use the EPI to communicate with a CICS transaction, and can exploit the presentation facilities of the client system to communicate with the end user. If you attach an external device such as a bar code reader, the application can deal with device input and output, and can use the EPI to start a transaction, perhaps one already written to deal with the kind of data that the external device produces. The application converts the input from the external device into a 3270 data stream to start the transaction and pass the data to it. Output from the transaction, in the form of a 3270 data stream, is then converted into the signals and data streams that operate the external device. The integration of CICS and non-CICS systems usually involves passing user-defined data between the programs of the non-CICS system and a CICS program, and the ECI can be used for this. In any of these cases, the choice between EPI and ECI is not always clear-cut, because both interfaces can be used to pass data between a non-CICS application and a CICS program. However, the mechanism is different in the two cases: 3270 data streams for EPI; application-defined formats in a COMMAREA for ECI. ═══ 6.5. ECI and EPI exits (CICS on Open Systems Version 2) ═══ The operation of the EPI and ECI can be customized by the user exits described in ECI and EPI exits (CICS on Open Systems, Version 2). ═══ 7. External call interface ═══ This chapter provides reference information about the external call interface (ECI). The interface is described here in a language-independent manner, though the names chosen for the elements of the interface-functions, parameters, data structures, fields, constants, and so on-are similar to those provided for programming. Language-dependent information is in Creating ECI and EPI application programs. On some platforms, the ECI provides facilities that are not part of CICS Family Client/Server Programming, and these are summarized in ECI extensions that are environment-dependent. The chapter is organized as follows: Overview Program link calls Status information calls Reply solicitation calls CICS_ExternalCall ECI status block CICS_EciListSystems. ═══ 7.1. Overview ═══ ═══ 7.1.1. ECI function ═══ The ECI allows a non-CICS application program to call a CICS program in a CICS server. The non-CICS application does not issue any CICS commands itself; the CICS commands are issued by the called program running in the server. The called program thus appears to have been called by EXEC CICS LINK with the COMMAREA option. An ECI application can make use of existing CICS programs that obey the rules for distributed program link, or new CICS programs can be written to be called by ECI applications. The called programs must follow the rules for CICS programs called by DPL. In particular they must make no explicit use of the EXEC CICS SYNCPOINT or EXEC CICS SYNCPOINT ROLLBACK commands. In some circumstances it is possible for the application to be running more than one CICS program concurrently, and these programs might be distributed across several CICS servers. The function provided by the ECI is packaged in two parts as follows: CICS_ExternalCall Provides most of the function of the ECI. It has a single parameter, the ECI parameter block, in which various fields describe the function to be performed and the inputs and outputs. Most of the following sections are concerned with the use of CICS_ExternalCall. CICS_EciListSystems Used to find out about available servers to which CICS_ExternalCall requests can be directed. It is described in CICS_EciListSystems. ═══ 7.1.2. Types of ECI calls ═══ The calls to CICS_ExternalCall are of three types: o Program link calls o Status information calls o Reply solicitation calls. The type of call to CICS_ExternalCall is controlled by the setting of the eci_call_type parameter in the ECI parameter block. Restrictions on call type for particular operating environments are discussed in the descriptions of each call type. ═══ 7.1.2.1. Program link calls ═══ Program link calls cause a CICS program to be executed on a CICS server. These calls can be: o Synchronous - the application waits until the called program has finished. Returned information is immediately available. o Asynchronous - the application gets control back without reference to the completion of the called program. The application can ask to be notified later when the information is available. It must use a reply solicitation call to determine the outcome of the asynchronous request. ═══ 7.1.2.2. Status information calls ═══ Status information calls retrieve status information about the type of system on which the application is running and its status. These calls can be: o Synchronous - the application waits until the information has been made available. o Asynchronous - the application gets control back while the information is being retrieved. The application can ask to be notified later when the information is available. It must use a reply solicitation call to determine the outcome of the asynchronous request. ═══ 7.1.2.3. Reply solicitation calls ═══ Reply solicitation calls get information back after asynchronous program link or asynchronous status information calls. Reply solicitation calls can be: o General - retrieving any piece of outstanding information o Specific - retrieving information for a named asynchronous request. An application that uses the asynchronous method of calling may have several program link and status information calls outstanding at any time. The eci_message_qualifier parameter in the ECI parameter block can be used on an asynchronous call to provide a user-defined identifier for the call. The use of different identifiers for different asynchronous calls within a single application is the programmer's responsibility. When a general reply solicitation call is made, the ECI uses the eci_message_qualifier field to return the name of the call to which the reply belongs. When a specific reply solicitation call is made, you must supply a value in the eci_message_qualifier field to identify the asynchronous call about which information is begin sought. ═══ 7.2. Program link calls ═══ Program link calls can be either synchronous or asynchronous. For asynchronous calls, it is the responsibility of the calling application to solicit the reply using one of the reply solicitation calls. (See Reply solicitation calls.) ═══ 7.2.1. Managing logical units of work ═══ An ECI application is often concerned with updating recoverable resources on the server, and the application programmer needs to understand the facilities that the ECI provides for managing logical units of work. A logical unit of work is all the processing in the server that is needed to establish a set of updates to recoverable resources. When the logical unit of work ends normally, the changes will all be committed. When the logical unit of work ends abnormally, for instance because a program abends, the changes are all backed out. You can use the ECI to start and end logical units of work on the server. The changes to recoverable resources in a logical unit of work might be effected by: o A single program link call, or o A sequence of program link calls. On successful return from the first of a sequence of calls for a logical unit of work, the eci_luw_token field in the control block contains a token that should be used for all later calls related to the same logical unit of work. All program link calls for the same logical unit of work will be sent to the same server. Attention: You should be careful when extending a logical unit of work across multiple program link calls that may span a long time (for example, over user think time). The reason is that the logical unit of work holds various locks and other CICS resources on the server, and this may cause delays to other users who are waiting for those same locks and resources. When a logical unit of work ends, the CICS server attempts to commit the changes. The last, or only, program link call of a logical unit of work is advised whether the attempt was successful. Only one program link call per logical unit of work can be outstanding at any time. (An asynchronous program link call is outstanding until a reply solicitation call has processed the reply.) Logical units of work in the ECI shows how you can use combinations of eci_extend_mode, eci_program_name, and eci_luw_token parameter values to perform tasks associated with managing logical units of work through the ECI. In each case you must also store appropriate values in other fields for the call type you have chosen. Each logical unit of work ties up one CICS non-facility task for the duration of its execution. This means that you must define enough free tasks in the CICS server to service the maximum expected number of concurrent calls. Asynchronous program link calls with message qualifiers and LUW tokens shows an application program using asynchronous program calls. The program has two calls outstanding in one server and one call in another. To keep track of its requests, the program is using message qualifiers that it has generated itself, and LUW tokens returned in the eci_luw_token field. Asynchronous program link calls with message qualifiers and LUW tokens For more details of the program link calls, you should study the descriptions of the individual call types: ECI_SYNC for a synchronous program link call ECI_ASYNC for an asynchronous program link call. ═══ 7.2.1.1. Logical units of work in the ECI ═══ Call a program that is to be the only program of a logical unit of work. Set up the parameters as follows: o eci_extend_mode: ECI_NO_EXTEND o eci_program_name: provide it o eci_luw_token: zero Call a program that is to start a new logical unit of work that is to be extended. Set up the parameters as follows: o eci_extend_mode: ECI_EXTENDED o eci_program_name: provide it o eci_luw_token: zero Afterwards, save the token from eci_luw_token. Call a program that is to continue an existing logical unit of work. Set up the parameters as follows: o eci_extend_mode: ECI_EXTENDED o eci_program_name: provide it o eci_luw_token: provide it Call a program that is to be the last program of an existing logical unit of work, and commit the changes. Set up the parameters as follows: o eci_extend_mode: ECI_NO_EXTEND o eci_program_name: provide it o eci_luw_token: provide it End an existing logical unit of work, without calling another program, and commit changes to recoverable resources. Set up the parameters as follows: o eci_extend_mode: ECI_COMMIT o eci_program_name: null o eci_luw_token: provide it End an existing logical unit of work, without calling another program, and back out changes to recoverable resources. Set up the parameters as follows: o eci_extend_mode: ECI_BACKOUT o eci_program_name: null o eci_luw_token: provide it ═══ 7.2.2. Security in the ECI ═══ Not all CICS servers require the client to supply a userid and password for ECI_SYNC and ECI_ASYNC call types. Some CICS servers have configuration options to decide whether the userid and password are required. You should consult the publications for the appropriate server for more information. Some client environments support the use of userids and passwords in files, so that the userid and password need not be supplied by the non-CICS application. Some client environments support the use of dialogs with the workstation operator to determine userids and passwords. You should consult the publications for the appropriate client environment for more information. In the CICS on Open Systems environment, the operator might need DCE authorization to use the ECI application, depending on the local configuration. If the ECI program runs for a long time, for example longer than thirty minutes, you must make sure that the credential lifetime and renewable lifetime of the DCE principal are long enough to cover the maximum allowed duration of the ECI program. Whether userids and passwords are encrypted depends on the communications protocol being used between client and server. ═══ 7.3. Status information calls ═══ Status information calls can be either synchronous or asynchronous. For asynchronous calls, it is the responsibility of the calling application to obtain the reply using a reply solicitation call (see Reply solicitation calls). ═══ 7.3.1. How status information is supplied and used ═══ Status information is supplied in the ECI status block, which is passed across the interface in the eci_commarea parameter. The following status information is held in the ECI status block. For a more detailed description, see ECI status block. o The type of connection (whether the ECI program is locally connected to a CICS server, a CICS client, or nothing) o The state of the CICS server (available, unavailable, or unknown) o The state of the CICS client (available, not applicable, or unknown). The status information calls allow you to perform three tasks: o Enquire on the type of system the application is running on, and its connection with a given server. For this you need to provide a COMMAREA in which the status is returned. o Set up a request to be notified when the status changes from some specified value. For this you need to provide a COMMAREA in which the specified status is described. When the status is different from the status specified, you are notified of the new status. Only asynchronous calls can be used for this purpose. o Cancel a request for notification of status change. For this no COMMAREA is required. Status enquiries with CICS_ExternalCall shows how you can use combinations of eci_extend_mode, eci_commarea, eci_commarea_length, and eci_luw_token parameter values to perform tasks associated with status enquiries. In each case you must also store appropriate values in other fields for the call type you have chosen. For more details of the status information calls, you should study the descriptions of the individual call types: ECI_STATE_SYNC for a synchronous status information call ECI_STATE_ASYNC for an asynchronous status information call. ═══ 7.3.1.1. Status enquiries with CICS_ExternalCall ═══ Find the current status. Set up the parameters as follows: o eci_commarea: nulls o eci_commarea_length: length of ECI_STATUS o eci_extend_mode: ECI_STATE_IMMEDIATE Afterwards, consult the contents of the COMMAREA to find the status. Set up a request to find out about status change. Set up the parameters as follows: o eci_commarea: specified status o eci_commarea_length: length of ECI_STATUS o eci_extend_mode: ECI_STATE_CHANGED o eci_luw_token: zero Afterwards, save the token from eci_luw_token so that you can cancel the request later. Cancel a request to find out about status change. Set up the parameters as follows: o eci_commarea: none o eci_commarea_length: zero o eci_extend_mode: ECI_STATE_CANCEL o eci_luw_token: provide it ═══ 7.4. Reply solicitation calls ═══ After an asynchronous program link call or asynchronous status information call, it is the responsibility of the calling application to solicit the reply. All calls return any outstanding reply that meets the selection criteria specified in the call. For more details of the reply solicitation calls, you should study the descriptions of the individual call types: ECI_GET_REPLY for a reply solicitation call that gets any outstanding reply for any asynchronous call, if any reply is available. ECI_GET_REPLY_WAIT for a reply solicitation call that gets any outstanding reply for any asynchronous call, waiting if no replies are available. ECI_GET_SPECIFIC_REPLY for a reply solicitation call that gets any outstanding reply for a given asynchronous call, if any reply is available. ECI_GET_SPECIFIC_REPLY_WAIT for a reply solicitation call that gets any outstanding reply for a given asynchronous call, waiting if no replies are available. ═══ 7.5. CICS_ExternalCall ═══ CICS_ExternalCall ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ CICS_ExternalCall │ ECI_Parms │ └───────────────────────────────────────┴──────────────────────────────────────┘ Purpose CICS_ExternalCall gives access to the program link calls, status information calls, and reply solicitation calls described above. The function performed is controlled by the eci_call_type field in the ECI parameter block. Parameters ECI_Parms A pointer to the ECI parameter block. The parameter block must be set to nulls before use. The parameter block fields that are used as input and output are described in detail for each call type in the following sections. A brief summary of the fields is given next: eci_call_type An integer field defining the type of call being made. For details of the functions provided, see Types of ECI calls. eci_program_name The name of a program to be called. eci_userid Userid for security checking. eci_password Password for security checking. eci_transid A transaction identifier. eci_abend_code Abend code for a failed program. eci_commarea A COMMAREA for use by a called program, or for returned status information. eci_commarea_length The length of the COMMAREA. eci_timeout This field is provided for migration of existing ECI applications, and should normally be set to zero. eci_sys_return_code A return code giving more information about an unexpected error. eci_extend_mode A field that qualifies the function to be performed in various ways. eci_message_qualifier A user-provided reference to an asynchronous call. eci_luw_token An identifier for a logical unit of work. eci_sysid Reserved for future use, leave null. eci_version The version of the ECI for which the application is coded. In the CICS on Open Systems environment, only ECI_VERSION_1 may be specified. In other environments, you may use the values ECI_VERSION_1 or ECI_VERSION_1A. Facilities available only in version 1A are noted where they occur. The use of the value ECI_VERSION_0 is confined to programs migrated from previous versions of the ECI. eci_system_name The name of a CICS server. eci_callback A pointer to a callback routine for an asynchronous request. eci_userid2 Userid for security checking. eci_password2 Password for security checking. eci_tpn A transaction identifier for a mirror transaction. This field is available only when eci_version has the value ECI_VERSION_1A. Return codes In addition to the return codes described for each call type in the following sections, the following return codes are possible. ECI_ERR_INVALID_CALL_TYPE The call type was not one of the valid call types. ECI_ERR_CALL_FROM_CALLBACK The call was made from a callback routine. ECI_ERR_SYSTEM_ERROR An internal system error occurred. The error might have been in the client or in the server. The programmer should save the information returned in the eci_sys_return_code field, as this will help service personnel to diagnose the error. ECI_ERR_INVALID_VERSION The value supplied for eci_version was invalid. ECI_ERR_REQUEST_TIMEOUT The value in the eci_timeout field of the ECI parameter block is negative. In some implementations, some of the return codes documented here and for each call type will never be returned. ═══ 7.5.1. ECI_SYNC call type ═══ ECI_SYNC call type Environment The ECI_SYNC call type is available in all environments. Purpose The ECI_SYNC call type provides a synchronous program link call to start, continue, or end a logical unit of work. The calling application does not get control back until the called CICS program has run to completion. ECI parameter block fields The ECI parameter block should be set to nulls before setting the input parameter fields. eci_call_type Required input parameter. Must be set to ECI_SYNC. eci_program_name Input parameter, required except when eci_extend_mode is ECI_COMMIT or ECI_BACKOUT. (See Logical units of work in the ECI.) An 8-character field containing the name of the program to be called. Unused characters should be padded with spaces. This field is transmitted to the server without conversion to uppercase. eci_userid Required input parameter. An 8-character field containing a userid. Unused characters should be padded with spaces. On CICS on Open Systems clients, this field is transmitted to the server without conversion to uppercase. In other environments, you should consult the documentation for the client and the server to check whether this field is converted to upper case before being transmitted to the server. (If a userid or password longer than 8 characters is required, eci_version must not be ECI_VERSION_0; and eci_userid and eci_password must be set to nulls, and the fields eci_userid2 and eci_password2 used instead.) If a userid is supplied, then the server uses the userid and any supplied password to authenticate the user. The supplied userid and password are used in subsequent security checking in the server. eci_password Required input parameter. An 8-character field containing a password. Unused characters should be padded with spaces. On CICS on Open Systems clients, this field is transmitted to the server without conversion to uppercase. In other environments, you should consult the documentation for the client and the server to check whether this field is converted to upper case before being transmitted to the server. (If a userid or password longer than 8 characters is required, this field and eci_userid must be set to nulls, and the fields eci_userid2 and eci_password2 used instead.) eci_transid Optional input parameter A 4-character field optionally containing the ID of a CICS transaction. Unused characters should be padded with spaces. This field is transmitted to the server without conversion to uppercase. The use of this parameter depends on the server to which the request is directed. o For a CICS on Open Systems server, this is the name of the transaction that will be used to service the request. The name you choose must be defined as a transaction name on the server, and must be associated with the program DFHMIRS. o For other CICS servers, this is the name of the transaction under which the called program will run. This name is available to the called program for querying the transaction ID; use it if the CICS program issues a distributed program link, and if the transaction ID under which the program runs is important. Some servers use the transaction ID to determine security and performance attributes for the called program. You are recommended to use this parameter to control the processing of your called programs. If the ECI request is extended (see the description of eci_extend_mode), all calls in the same logical unit of work must use the same value for eci_transid. If the field is all nulls, the default server transaction ID is used. eci_abend_code Output parameter. A 4-character field in which a CICS abend code is returned if the transaction that executes the called program abends. Unused characters are padded with spaces. eci_commarea Optional input parameter. A pointer to the data to be passed to the called CICS program as its COMMAREA. The COMMAREA will be used by the called program to return information to the application. If no COMMAREA is required, supply a null pointer and set the length (specified in eci_commarea_length) to zero. If the code page of the application is different from the code page of the server, data conversion must be performed at the server. To do this, you need to make use of CICS-supplied resource conversion capabilities, such as the DFHCNV macro definitions. eci_commarea_length Optional input parameter. The length of the COMMAREA in bytes. This value may not exceed 32500. (Some client-server combinations may allow larger COMMAREAs, but this is not guaranteed to work as part of CICS Family Client/Server Programming.) If no COMMAREA is required, set this field to zero and supply a null pointer in eci_commarea. eci_sys_return_code Output parameter. An integer field containing additional information when the return code is ECI_ERR_SYSTEM_ERROR. The meaning of this information depends on the software and hardware platform. You should save this information, as it will help service personnel to diagnose the error. eci_extend_mode Required input parameter. An integer field determining whether a logical unit of work is terminated at the end of this call. (See Logical units of work in the ECI.) The values for this field (shown by their symbolic names) are as follows: ECI_NO_EXTEND 1. If the input eci_luw_token field is zero, this is the only call for a logical unit of work. 2. If the input eci_luw_token field is not zero, this is the last call for the specified logical unit of work. In either case, changes to recoverable resources are committed by a CICS end-of-task syncpoint, and the logical unit of work ends. ECI_EXTENDED 1. If the input eci_luw_token field is zero, this is the first call for a logical unit of work that is to be continued. 2. If the input eci_luw_token field is not zero, this call is intended to continue the specified logical unit of work. In either case the logical unit of work continues after the called program completes successfully, and changes to recoverable resources remain uncommitted. ECI_COMMIT Terminate the current logical unit of work, identified by the input eci_luw_token field, and commit all changes made to recoverable resources. ECI_BACKOUT Terminate the logical unit of work identified by the input eci_luw_token field, and back out all changes made to recoverable resources. eci_luw_token Required input and output parameter. An integer field used for identifying the logical unit of work to which a call belongs. It must be set to zero at the start of a logical unit of work (regardless of whether the logical unit of work is going to be extended). If the logical unit of work is to be extended, the ECI updates eci_luw_token with a valid value on the first call of the logical unit of work, and this value should be used as input to all later calls related to the same logical unit of work. (See Logical units of work in the ECI.) If the return code is not ECI_NO_ERROR, and the call was continuing or ending an existing logical unit of work, this field is used as output to report the condition of the logical unit of work. If it is set to zero, the logical unit of work has ended, and its updates have been backed out. If it is nonzero, it is the same as the input value, the logical unit of work is continuing, and its updates are still pending. eci_sysid Required input parameter. Reserved for future use, but this field should be initialized with nulls before the start of each logical unit of work. eci_version Required input parameter. The version of the ECI for which the application is coded. In the CICS on Open Systems environment, only ECI_VERSION_1 may be specified. In other environments, you may use the values ECI_VERSION_1 or ECI_VERSION_1A. All the facilities of version 1 are available in version 1A. Facilities available only in version 1A are noted where they occur. (ECI_VERSION_0 is provided to allow applications written for previous versions of the ECI to continue to execute, but many of the facilities of CICS Client/Server Programming are not available if eci_version has this value.) eci_system_name Optional input parameter. An 8-character field that specifies the name of the server to which the ECI request is to be directed. Unused characters should be padded with spaces. If supplied, it should be one of the server names returned by CICS_EciListSystems. The value may be supplied whenever eci_luw_token is set to zero. (If it is supplied when eci_luw_token is not zero, it is ignored, because the server was established at the start of the logical unit of work.) If the field is set to nulls, then a server, currently the default server, is selected; the name of the chosen server is returned in this field, and must be used in subsequent related ECI requests. If ECI requests made in different logical units of work must be directed to the same server, then eci_system_name must identify that server by name. eci_userid2 Optional input parameter. If the eci_userid field is set to nulls, then the eci_userid2 field specifies the userid (if any) to be used at the server for any authority validation. The userid can be up to 16 characters. eci_version must not be ECI_VERSION_0. See the description of the eci_userid field for information about how the userid is used. eci_password2 Optional input parameter. If the eci_password field is set to nulls, the eci_password2 field specifies the password (if any) to be used at the server for any authority validation. The password can be up to 16 characters. eci_version must not be ECI_VERSION_0. See the description of the eci_password field for information about how the password is used. eci_tpn Optional input parameter. Available only if the value of eci_version is ECI_VERSION_1A. A 4-character field that specifies the transaction ID of the transaction that will be used in the server to process the ECI request. This transaction must be defined in the server as a CICS mirror transaction. If the field is not set, the default mirror transaction CAMI is used. If the ECI request is extended (see the description of eci_extend_mode), you need specify this only for the first request. If you specify a value for subsequent requests, it is ignored, and the value specified for the first request is reused. Return codes See also the general list of return codes for CICS_ExternalCall in CICS_ExternalCall. ECI_NO_ERROR The call completed successfully. ECI_ERR_INVALID_DATA_LENGTH The value in eci_commarea_length field is outside the valid range, or is inconsistent with the value in eci_commarea, being zero for a non-null eci_commarea pointer, or non-zero for a null eci_commarea pointer. ECI_ERR_INVALID_EXTEND_MODE The value in eci_extend_mode field is not valid. ECI_ERR_NO_CICS The client is unavailable, or the server implementation is unavailable, or a logical unit of work was to be begun, but the CICS server specified in eci_system_name is not available. No resources have been updated. ECI_ERR_CICS_DIED A logical unit of work was to be begun or continued, but the CICS server was no longer available. If eci_extend_mode was ECI_EXTENDED, the changes are backed out, and the logical unit of work ends. If eci_extend_mode was ECI_NO_EXTEND, ECI_COMMIT, or ECI_BACKOUT, the application cannot determine whether the changes have been committed or backed out, and must log this condition to aid future manual recovery. ECI_ERR_TRANSACTION_ABEND The CICS transaction that executed the requested program abended. The abend code will be found in eci_abend_code. For information about abend codes and their meaning, you should consult the documentation for the server system to which the request was directed. ECI_ERR_LUW_TOKEN The value supplied in eci_luw_token is invalid. ECI_ERR_ALREADY_ACTIVE An attempt was made to continue an existing logical unit of work, but there was an outstanding asynchronous call for the same logical unit of work. ECI_ERR_RESOURCE_SHORTAGE The server implementation or the client did not have enough resources to complete the request. ECI_ERR_NO_SESSIONS A new logical unit of work was being created, but the application already has as many outstanding logical units of work as the configuration will support. ECI_ERR_INVALID_DATA_AREA Either the pointer to the ECI parameter block is invalid, or the pointer supplied in eci_commarea is invalid. ECI_ERR_ROLLEDBACK An attempt was made to commit a logical unit of work, but the server was unable to commit the changes, and backed them out instead. ECI_ERR_UNKNOWN_SERVER The requested server could not be located. Only servers returned by CICS_EciListSystems are acceptable. ECI_ERR_INVALID_TRANSID A logical unit of work was being extended, but the value supplied in eci_transid differed from the value used when the logical unit of work was started. ECI_ERR_MAX_SESSIONS There were not enough communication resources to satisfy the request. You should consult the documentation for your client or server to see how to control communication resources. ECI_ERR_MAX_SYSTEMS You attempted to start requests to more servers than your configuration allows. You should consult the documentation for your client or server to see how to control the number of servers you can use. ECI_ERR_SECURITY_ERROR You did not supply a valid combination of userid and password, though the server expects it. ═══ 7.5.2. ECI_ASYNC call type ═══ ECI_ASYNC call type Environment The ECI_ASYNC call type is available in all environments except DOS. Purpose The ECI_ASYNC call type provides an asynchronous program link call to start, continue, or end a logical unit of work. The calling application gets control back when the ECI has accepted the request. At this point the parameters have been validated; however, the request might still be queued for later processing. If no callback routine is provided, the application must use a reply solicitation call to determine that the request has ended and what the outcome was. If a callback routine is provided, the callback routine eci_callback is invoked when a response is available. Note: Some compilers do not support the use of callback routines. Consult your compiler documentation for more information. When the callback routine is called, it is passed a single parameter-the value specified in eci_message_qualifier. Use of this parameter enables the callback routine to identify the asynchronous call that is completing. Note the following guidelines on the use of the callback routine: 1. The minimum possible processing should be performed within the callback routine. 2. ECI functions cannot be invoked from within the callback routine. 3. The callback routine should indicate to the main body of the application that the reply is available using an appropriate technique for the operating system upon which the ECI application is executing. For example, in a multithreaded environment like OS/2, the callback routine might post a semaphore to signal another thread that an event has occurred. In a Presentation Manager environment, it might post a message to a window to indicate to the window procedure that an event has occurred. Other actions would be appropriate for other environments. 4. In a CICS on Open Systems environment, only thread-safe facilities should be used. 5. The application, not the callback routine, must use a reply solicitation call to receive the actual response. ECI parameter block fields The ECI parameter block should be set to nulls before setting the input parameter fields. eci_call_type Required input parameter. Must be set to ECI_ASYNC. eci_program_name Input only, required parameter except when eci_extend_mode is ECI_COMMIT or ECI_BACKOUT. (See Logical units of work in the ECI.) An 8-character field containing the name of the program to be called. Unused characters should be padded with spaces. This field is transmitted to the server without conversion to uppercase. eci_userid Required input parameter. An 8-character field containing a userid. Unused characters should be padded with spaces. On CICS on Open Systems clients, this field is transmitted to the server without conversion to uppercase. In other environments, you should consult the documentation for the client and the server to check whether this field is converted to upper case before being transmitted to the server. (If a userid or password longer than 8 characters is required, eci_version must not be ECI_VERSION_0; and eci_userid and eci_password must be set to nulls, and the fields eci_userid2 and eci_password2 used instead.) If a userid is supplied, then the userid and any supplied password will be used by the server to validate the authority of the user to execute the ECI request. The form of this validation is defined by the server. eci_password Required input parameter. An 8-character field containing a password. Unused characters should be padded with spaces. On CICS on Open Systems clients, this field is transmitted to the server without conversion to uppercase. In other environments, you should consult the documentation for the client and the server to check whether this field is converted to upper case before being transmitted to the server. (If a userid or password longer than 8 characters is required, this field and eci_userid must be set to nulls, and the fields eci_userid2 and eci_password2 used instead.) eci_transid Optional input parameter. A 4-character field optionally containing a CICS transaction ID. Unused characters should be padded with spaces. This field is transmitted to the server without conversion to uppercase. The use of this parameter depends on the server to which the request is directed. o For a CICS on Open Systems server, this is the name of the transaction that will be used to service the request. The name you choose must be defined as a transaction name on the server, and must be associated with the program DFHMIRS. o For other CICS servers, this is the name of the transaction under which the called program will run. This name is available to the called program for querying the transaction ID; use it if the CICS program issues a distributed program link, and if the transaction ID under which the program runs is important. Some servers use the transaction ID to determine security and performance attributes for the called program. You are recommended to use this parameter to control the processing of your called programs. If the ECI request is extended (see the description of eci_extend_mode), all calls in the same logical unit of work must use the same value for eci_transid. If the field is all nulls, the default server transaction ID is used. eci_commarea Required input parameter. A pointer to the data to be passed to the called CICS program as its COMMAREA. If no COMMAREA is required, supply a null pointer and set the length (specified in eci_commarea_length) to zero. If the code page of the application is different from the code page of the server, data conversion must be performed at the server. To do this, you need to make use of CICS-supplied resource conversion capabilities, such as the DFHCNV macro definitions. eci_commarea_length Required input parameter. The length of the COMMAREA in bytes. This value may not exceed 32500. (Some client-server combinations may allow larger COMMAREAs, but this is not guaranteed to work as part of CICS Family Client/Server Programming.) If no COMMAREA is required, set this field to zero and supply a null pointer in eci_commarea. eci_sys_return_code Output parameter. An integer field containing additional information when the return code is ECI_ERR_SYSTEM_ERROR. The meaning of this information depends on the software and hardware platform. You should save this information, as it will help service personnel to diagnose the error. eci_extend_mode Required input parameter. An integer field determining whether a logical unit of work is terminated at the end of this call. (See Logical units of work in the ECI.) Values (shown by their symbolic names) for this field are as follows: ECI_NO_EXTEND 1. If the input eci_luw_token field is zero, this is the only call for a logical unit of work. 2. If the input eci_luw_token field is not zero, this is the last call for the specified logical unit of work. In either case, changes to recoverable resources are committed by a CICS end-of-task syncpoint, and the logical unit of work ends. ECI_EXTENDED 1. If the input eci_luw_token field is zero, this is the first call for a logical unit of work that is to be continued. 2. If the input eci_luw_token field is not zero, this call is intended to continue the specified logical unit of work. In either case the logical unit of work continues after the called program completes, and changes to recoverable resources remain uncommitted. ECI_COMMIT Terminate the current logical unit of work, identified by the input eci_luw_token field, and commit all changes made to recoverable resources. ECI_BACKOUT Terminate the logical unit of work identified by the input eci_luw_token field, and back out all changes made to recoverable resources. eci_message_qualifier Optional input parameter. An integer field allowing the application to identify each asynchronous call if it is making more than one. If a callback routine is specified, the value in this field is returned to the callback routine during the notification process. eci_luw_token Required input and output parameter. An integer field used for identifying the logical unit of work to which a call belongs. It must be set to zero at the start of a logical unit of work (regardless of whether the logical unit of work is going to be extended), and the ECI updates it with a valid value on the first or only call of the logical unit of work. If the logical unit of work is to be extended, this value should be used as input to all later calls related to the same logical unit of work. See Logical units of work in the ECI. If the return code is not ECI_NO_ERROR, and the call was continuing or ending an existing logical unit of work, this field is used as output to report the condition of the logical unit of work. If it is set to zero, the logical unit of work has ended, and its updates have been backed out. If it is nonzero, it is the same as the input value, the logical unit of work is continuing, and its updates are still pending. eci_sysid Required input parameter. Reserved for future use, but this field should be initialized with nulls before the start of each logical unit of work. eci_version Required input parameter. The version of the ECI for which the application is coded. In the CICS on Open Systems environment, only ECI_VERSION_1 may be specified. In other environments, you may use the values ECI_VERSION_1 or ECI_VERSION_1A. All the facilities of version 1 are available in version 1A. Facilities available only in version 1A are noted where they occur. (ECI_VERSION_0 is provided to allow applications written for previous versions of the ECI to continue to execute, but many of the facilities of CICS Client/Server Programming are not available if eci_version has this value.) eci_system_name Optional input parameter. An 8-character field that specifies the name of the server to which the ECI request is to be directed. Unused characters should be padded with spaces. The value may be supplied whenever eci_luw_token is set to zero. (If it is supplied when eci_luw_token is not zero, it is ignored, because the server was established at the start of the logical unit of work.) If the field is set to nulls, then a server, currently the default server, is selected. You can obtain the name of the chosen server from the eci_system_name field of the reply solicitation call you use to get the result of this asynchronous request. (If later ECI requests made in different logical units of work must be directed to the same server as this request, then eci_system_name in those requests must identify that server by name.) eci_callback Optional input parameter. A pointer to the routine to be called when the asynchronous request completes. (The callback routine will be called only if the return code is ECI_NO_ERROR, and the pointer is not null.) eci_userid2 Optional input parameter. If the eci_userid field is set to nulls, then the eci_userid2 field specifies the userid (if any) to be used at the server for any authority validation. The userid can be up to 16 characters. eci_version must not be ECI_VERSION_0. See the description of the eci_userid field for information about how the userid is used. eci_password2 Optional input parameter. If the eci_password field is set to nulls, the eci_password2 field specifies the password (if any) to be used at the server for any authority validation. The password can be up to 16 characters. eci_version must not be ECI_VERSION_0. See the description of the eci_password field for information about how the password is used. eci_tpn Optional input parameter. Available only if the value of eci_version is ECI_VERSION_1A. A 4-character field that specifies the transaction ID of the transaction that will be used in the server to process the ECI request. This transaction must be defined in the server as a CICS mirror transaction. If the field is not set, the default mirror transaction CAMI is used. If the ECI request is extended (see the description of eci_extend_mode), you need specify this only for the first request. If you specify a value for subsequent requests, it is ignored, and the value specified for the first request is reused. Return codes See also the general list of return codes for CICS_ExternalCall in CICS_ExternalCall. If the return code is not ECI_NO_ERROR, the callback routine will not be called, and there will be no asynchronous reply for this request. ECI_NO_ERROR The call to the ECI completed successfully. No errors have yet been detected. The callback routine will be called when the request completes. ECI_ERR_INVALID_DATA_LENGTH The value in eci_commarea_length field is outside the valid range, or is inconsistent with the value in eci_commarea, being zero for a non-null eci_commarea pointer, or non-zero for a null eci_commarea pointer. ECI_ERR_INVALID_EXTEND_MODE The value in eci_extend_mode field is not valid. ECI_ERR_NO_CICS Either the client or the server implementation is not available. ECI_ERR_LUW_TOKEN The value supplied in eci_luw_token is invalid. ECI_ERR_THREAD_CREATE_ERROR The server implementation or the client failed to create a thread to process the request. ECI_ERR_ALREADY_ACTIVE An attempt was made to continue an existing logical unit of work, but there was an outstanding asynchronous call for the same logical unit of work. ECI_ERR_RESOURCE_SHORTAGE The server implementation or the client did not have enough resources to complete the request. ECI_ERR_NO_SESSIONS A new logical unit of work was being created, but the application already has as many outstanding logical units of work as the configuration will support. ECI_ERR_INVALID_DATA_AREA Either the pointer to the ECI parameter block is invalid, or the pointer supplied in eci_commarea is invalid. ECI_ERR_INVALID_TRANSID A logical unit of work was being extended, but the value supplied in eci_transid differed from the value used when the logical unit of work was started. ═══ 7.5.3. ECI_STATE_SYNC call type ═══ ECI_STATE_SYNC call type Environment The ECI_STATE_SYNC call type is available in all environments. Purpose The ECI_STATE_SYNC call type provides a synchronous status information call. ECI parameter block fields The ECI parameter block should be set to nulls before setting the input parameter fields. eci_call_type Required input parameter. Must be set to ECI_STATE_SYNC. eci_commarea Input parameter, required except when eci_extend_mode has the value ECI_STATE_CANCEL. A pointer to the area of storage where the application receives the returned COMMAREA containing status information (see Status information calls and ECI status block for more details). If eci_extend_mode has the value ECI_STATE_CANCEL, supply a null pointer and set the length (specified in eci_commarea_length) to zero. eci_commarea_length Required input and output parameter, except when eci_extend_mode has the value ECI_STATE_CANCEL. The length of the COMMAREA in bytes, which must be the length of the ECI_STATUS structure that gives the layout of the status information COMMAREA (see Status information calls and ECI status block for more details). If no COMMAREA is required, set this field to zero and supply a null pointer in eci_commarea. eci_sys_return_code Output parameter. An integer field containing additional information when the return code is ECI_ERR_SYSTEM_ERROR. The meaning of this information depends on the software and hardware platform. You should save this information, as it will help service personnel to diagnose the error. eci_extend_mode Required input parameter. An integer field further qualifying the call type. (See Status enquiries with CICS_ExternalCall.) The values for this field (shown by their symbolic names) are as follows: ECI_STATE_IMMEDIATE Force a status reply to be sent immediately it is available. The layout of the returned COMMAREA is defined in the ECI_STATUS structure (see Status information calls and ECI status block). ECI_STATE_CHANGED Force a status reply to be sent only when the status changes. The supplied COMMAREA must contain the status as perceived by the application. A reply is sent only when there is a change from the status that the application supplied. The layout of the COMMAREA is defined in the ECI_STATUS structure (see Status information calls and ECI status block for more details). The eci_luw_token field that is returned on the immediate response provides a token to identify the request. ECI_STATE_CANCEL Cancel an ECI_STATE_CHANGED type of operation. No COMMAREA is required for this request. The eci_luw_token field must contain the token that was received during the ECI_STATE_CHANGED call. eci_luw_token Optional input and output parameter. When a deferred status request is being set up (eci_extend_mode set to ECI_STATE_CHANGED), the token identifying the request is returned in the eci_luw_token field. When a deferred status request is being cancelled (eci_extend_mode set to ECI_STATE_CANCEL), the eci_luw_token field must contain the token that was received during the ECI_STATE_CHANGED call. This field is not used when other values of eci_extend_mode are specified. eci_sysid Required input parameter. Reserved for future use, but this field should be initialized with nulls before the start of each logical unit of work. eci_version Required input parameter. The version of the ECI for which the application is coded. In the CICS on Open Systems environment, only ECI_VERSION_1 may be specified. In other environments, you may use the values ECI_VERSION_1 or ECI_VERSION_1A. All the facilities of version 1 are available in version 1A. Facilities available only in version 1A are noted where they occur. (ECI_VERSION_0 is provided to allow applications written for previous versions of the ECI to continue to execute, but many of the facilities of CICS Client/Server Programming are not available if eci_version has this value.) eci_system_name Optional input parameter. An 8-character field that specifies the name of the server for which status information is required. Unused characters should be padded with spaces. If supplied, it should be one of the server names returned by CICS_EciListSystems. The value may be supplied whenever eci_luw_token is set to zero. If the field is set to nulls, then a server, currently the default server, is selected; the name of the chosen server is returned in this Return codes See also the general list of return codes for CICS_ExternalCall in CICS_ExternalCall. ECI_NO_ERROR The call completed successfully. ECI_ERR_INVALID_DATA_LENGTH The value in eci_commarea_length field is outside the valid range, or is inconsistent with the value in eci_commarea, being zero for a non-null eci_commarea pointer, or non-zero for a null eci_commarea pointer. ECI_ERR_INVALID_EXTEND_MODE The value in eci_extend_mode field is not valid. ECI_ERR_LUW_TOKEN The value supplied in eci_luw_token is invalid. ECI_ERR_INVALID_DATA_AREA Either the pointer to the ECI parameter block is invalid, or the pointer supplied in eci_commarea is invalid. ECI_ERR_UNKNOWN_SERVER The requested server could not be located. Only servers returned by CICS_EciListSystems are acceptable. ═══ 7.5.4. ECI_STATE_ASYNC call type ═══ ECI_STATE_ASYNC call type Environment The ECI_STATE_ASYNC call type is available in all environments except DOS. Purpose The ECI_STATE_ASYNC call type provides an asynchronous status information call. The calling application gets control back when the ECI accepts the request. At this point the parameters have been validated; however, the request might still be queued for later processing. If no callback routine is provided, the application must use a reply solicitation call to determine that the request has ended and what the outcome was. If a callback routine is provided, the callback routine eci_callback is invoked when a response is available. Note: Some compilers do not support the use of callback routines. Consult your compiler documentation for more information. When the callback routine is called, it is passed a single parameter-the value specified in eci_message_qualifier. Use of this parameter enables the callback routine to identify the asynchronous call that is completing. Note the following guidelines on the use of the callback routine: 1. The minimum possible processing should be performed within the callback routine. 2. ECI functions cannot be invoked from within the callback routine. 3. The callback routine should indicate to the main body of the application that the reply is available using an appropriate technique for the operating system upon which the ECI application is executing. For example, in a multithreaded environment like OS/2, the callback routine might post a semaphore to signal another thread that an event has occurred. In a Presentation Manager environment, it might post a message to a window to indicate to the window procedure that an event has occurred. Other actions would be appropriate for other environments. 4. In a CICS on Open Systems environment, only thread-safe facilities should be used. 5. The application, not the callback routine, must use a reply solicitation call to receive the actual response. ECI parameter block fields The ECI parameter block should be set to nulls before setting the input parameter fields. eci_call_type Required input parameter. Must be set to ECI_STATE_ASYNC. eci_commarea Input parameter, required except when eci_extend_mode has the value ECI_STATE_CANCEL. A pointer to the area of storage where the application receives the returned COMMAREA containing status information (see Status information calls and ECI status block for more details). If eci_extend_mode has the value ECI_STATE_CANCEL, supply a null pointer and set the length (specified in eci_commarea_length) to zero. eci_commarea_length Required input parameter, except when eci_extend_mode has the value ECI_STATE_CANCEL. The length of the COMMAREA in bytes, which must be the length of the ECI_STATUS structure that gives the layout of the status information COMMAREA (see Status information calls and ECI status block for more details). If no COMMAREA is required, set this field to zero and supply a null pointer in eci_commarea. eci_sys_return_code Output parameter. An integer field containing additional information when the return code is ECI_ERR_SYSTEM_ERROR. The meaning of this information depends on the software and hardware platform. You should save this information, as it will help service personnel to diagnose the error. eci_extend_mode Required input parameter. An integer field further qualifying the call type. (See Status enquiries with CICS_ExternalCall.) The values for this field (shown by their symbolic names) are as follows: ECI_STATE_IMMEDIATE Force a status reply to be sent immediately it is available. The layout of the returned COMMAREA is defined in the ECI_STATUS structure (see Status information calls and ECI status block ECI_STATE_CHANGED Force a status reply to be sent only when the status changes. The supplied COMMAREA must contain the status as perceived by the application. A reply is sent only when there is a change from the status that the application supplied. The layout of the COMMAREA is defined in the ECI_STATUS structure (see Status information calls and ECI status block for more details). The eci_luw_token field that is returned on the immediate response identifies the logical unit of work to which this call belongs. ECI_STATE_CANCEL Cancel an ECI_STATE_CHANGED type of operation. No COMMAREA is required for this request. The eci_luw_token field must contain the token that was received during the ECI_STATE_CHANGED call. eci_message_qualifier Optional input parameter. An integer field allowing you to identify each asynchronous call if you are making more than one. If a callback routine is specified, the value in this field is returned to the callback routine during the notification process. eci_luw_token Optional input and output parameter. When a deferred status request is being set up (eci_extend_mode set to ECI_STATE_CHANGED), the token identifying the request is returned in the eci_luw_token field. When a deferred status request is being cancelled (eci_extend_mode set to ECI_STATE_CANCEL), the eci_luw_token field must contain the token that was received during the ECI_STATE_CHANGED call. This field is not used when other values of eci_extend_mode are specified. eci_sysid Required input parameter. Reserved for future use, but this field should be initialized with nulls before the start of each logical unit of work. eci_version Required input parameter. The version of the ECI for which the application is coded. In the CICS on Open Systems environment, only ECI_VERSION_1 may be specified. In other environments, you may use the values ECI_VERSION_1 or ECI_VERSION_1A. All the facilities of version 1 are available in version 1A. Facilities available only in version 1A are noted where they occur. (ECI_VERSION_0 is provided to allow applications written for previous versions of the ECI to continue to execute, but many of the facilities of CICS Client/Server Programming are not available if eci_version has this value.) eci_system_name Optional input parameter. An 8-character field that specifies the name of the server for which status information is requested. Unused characters should be padded with spaces. If supplied, it should be one of the server names returned by CICS_EciListSystems. The value may be supplied whenever eci_luw_token is set to zero. If the field is set to nulls, then a server, currently the default server, is selected. You can find out the name of the server from the eci_system_name field of the reply solicitation call you use to get the result of this asynchronous request. field. eci_callback Optional input parameter. A pointer to the routine to be called when the asynchronous request completes. (The callback routine will be called only if the return code is ECI_NO_ERROR, and the pointer is not null.) Return codes See also the general list of return codes for CICS_ExternalCall in CICS_ExternalCall. If the return code is not ECI_NO_ERROR, the callback routine will not be called, and there will be no asynchronous reply for this request. ECI_NO_ERROR The call completed successfully. ECI_ERR_INVALID_DATA_LENGTH The value in eci_commarea_length field is outside the valid range, or is inconsistent with the value in eci_commarea, being zero for a non-null eci_commarea pointer, or non-zero for a null eci_commarea pointer. ECI_ERR_INVALID_EXTEND_MODE The value in eci_extend_mode field is not valid. ECI_ERR_LUW_TOKEN The value supplied in eci_luw_token is invalid. ECI_ERR_INVALID_DATA_AREA Either the pointer to the ECI parameter block is invalid, or the pointer supplied in eci_commarea is invalid. ═══ 7.5.5. ECI_GET_REPLY call type ═══ ECI_GET_REPLY call type Environment The ECI_GET_REPLY call type is available in all environments except DOS. Purpose The ECI_GET_REPLY call type provides a reply solicitation call to return information appropriate to any outstanding reply for any asynchronous request. If there is no such reply, ECI_ERR_NO_REPLY is returned. (To cause the application to wait until a reply is available, you should use call type ECI_GET_REPLY_WAIT instead.) ECI parameter block fields The ECI parameter block should be set to nulls before setting the input parameter fields. The following fields are the fields of the ECI parameter block that might be supplied as input. In the course of an ECI_GET_REPLY call, the ECI parameter block is updated as follows: 1. All the outputs from the reply, some of which overwrite input fields, are added. These fields are those that are output from the corresponding synchronous version of the asynchronous request. 2. The eci_message_qualifier value supplied as input to the asynchronous request to which this reply relates is restored. 3. Any inputs that are not updated become undefined, except the pointer to the COMMAREA. You should not use the contents of these fields again. eci_call_type Required input parameter. Must be set to ECI_GET_REPLY. eci_commarea Optional input parameter. A pointer to the area of storage where the application receives the returned COMMAREA. The contents of the returned commarea depend on the type of asynchronous call to which a reply is being sought. For a program link call, it is the COMMAREA expected to be returned from the called program, if any. For a status information call, except when eci_extend_mode has the value ECI_STATE_CANCEL, it is a COMMAREA containing status information (see Status information calls and ECI status block for more details). If no COMMAREA is required, supply a null pointer and set the length (specified in eci_commarea_length) to zero. If the code page of the application is different from the code page of the server, data conversion must be performed at the server. To do this, you need to make use of CICS-supplied resource conversion capabilities, such as the DFHCNV macro definitions. eci_commarea_length Required input parameter. The length of the COMMAREA in bytes. This value may not exceed 32500. (Some client-server combinations may allow larger COMMAREAs, but this is not guaranteed to work as part of CICS Family Client/Server Programming.) If no COMMAREA is required, set this field to zero and supply a null pointer in eci_commarea. eci_sysid Required input parameter. Reserved for future use, but this field should be initialized with nulls before the start of each logical unit of work. eci_version Required input parameter. The version of the ECI for which the application is coded. In the CICS on Open Systems environment, only ECI_VERSION_1 may be specified. In other environments, you may use the values ECI_VERSION_1 or ECI_VERSION_1A. All the facilities of version 1 are available in version 1A. Facilities available only in version 1A are noted where they occur. (ECI_VERSION_0 is provided to allow applications written for previous versions of the ECI to continue to execute, but many of the facilities of CICS Client/Server Programming are not available if eci_version has this value.) Return codes See also the general list of return codes for CICS_ExternalCall in CICS_ExternalCall. ECI_NO_ERROR The asynchronous request to which this reply relates completed successfully. ECI_ERR_INVALID_DATA_LENGTH The value in eci_commarea_length field is unacceptable for one of the following reasons: o It is outside the valid range. o It is inconsistent with the value in eci_commarea, being zero for a non-null eci_commarea pointer, or non-zero for a null eci_commarea pointer. o It is not large enough for the output COMMAREA from the asynchronous request to which this reply relates. In the last case, you can use the output eci_commarea_length to allocate more storage for the COMMAREA, and then use the output eci_message_qualifier (if it identifies the asynchronous request uniquely) with an ECI_GET_SPECIFIC_REPLY call type to retrieve the reply. ECI_ERR_NO_CICS The CICS server specified in eci_system_name in the asynchronous request to which this reply relates is not available. No resources have been updated. ECI_ERR_CICS_DIED A logical unit of work was to be begun or continued by the asynchronous request to which this reply relates, but the CICS server was no longer available. If eci_extend_mode was ECI_EXTENDED, the changes are backed out, and the logical unit of work ends. If eci_extend_mode was ECI_NO_EXTEND, ECI_COMMIT, or ECI_BACKOUT, the application cannot determine whether the changes have been committed or backed out, and must log this condition to aid future manual recovery. ECI_ERR_NO_REPLY There was no outstanding reply. ECI_ERR_TRANSACTION_ABEND The asynchronous request to which this reply relates caused a program to be executed in the server, but the CICS transaction that executed the requested program abended. The abend code will be found in eci_abend_code. For information about abend codes and their meaning, you should consult the documentation for the server system to which the request was directed. ECI_ERR_THREAD_CREATE_ERROR The CICS server or client failed to create the thread to process the asynchronous call to which this reply relates. ECI_ERR_RESOURCE_SHORTAGE The server implementation or client did not have enough resources to complete the asynchronous request to which this reply relates. ECI_ERR_INVALID_DATA_AREA Either the pointer to the ECI parameter block is invalid, or the pointer supplied in eci_commarea is invalid. ECI_ERR_ROLLEDBACK The asynchronous request to which this reply relates attempted to commit a logical unit of work, but the server was unable to commit the changes, and backed them out instead. ECI_ERR_UNKNOWN_SERVER The asynchronous request to which this reply relates specified a server that could not be located. Only servers returned by CICS_EciListSystems are acceptable. ECI_ERR_MAX_SESSIONS There were not enough communication resources to satisfy the asynchronous request to which this reply relates. You should consult the documentation for your client or server to see how to control communication resources. ECI_ERR_MAX_SYSTEMS The asynchronous request to which this reply relates attempted to start requests to more servers than your configuration allows. You should consult the documentation for your client or server to see how to control the number of servers you can use. ECI_ERR_SECURITY_ERROR You did not supply a valid combination of userid and password on the asynchronous request to which this reply relates, though the server expects it. ═══ 7.5.6. ECI_GET_REPLY_WAIT call type ═══ ECI_GET_REPLY_WAIT call type Environment The ECI_GET_REPLY_WAIT call type is available in all environments except DOS. Purpose The ECI_GET_REPLY_WAIT call type provides a reply solicitation call to return information appropriate to any outstanding reply for any asynchronous request. If there is no such reply, the application waits until there is. (In all environments except DOS, you can get an indication that no reply is available by using call type ECI_GET_REPLY instead.) ECI parameter block fields Same as for ECI_GET_REPLY, but eci_call_type must be set to ECI_GET_REPLY_WAIT. Return codes Same as for ECI_GET_REPLY, except that ECI_ERR_NO_REPLY cannot be returned. ═══ 7.5.7. ECI_GET_SPECIFIC_REPLY call type ═══ ECI_GET_SPECIFIC_REPLY call type Environment The ECI_GET_SPECIFIC_REPLY call type is available in all environments except DOS. Purpose The ECI_GET_SPECIFIC_REPLY call type provides a reply solicitation call to return information appropriate to any outstanding reply that matches the eci_message_qualifier input. If there is no such reply, ECI_ERR_NO_REPLY is returned. (To cause the application to wait until a reply is available, you should use call type ECI_GET_REPLY_WAIT instead.) ECI parameter block fields The ECI parameter block should be set to nulls before setting the input parameter fields. The following fields are the fields of the ECI parameter block that might be supplied as input. In the course of an ECI_GET_REPLY call, the ECI parameter block is updated as follows: 1. All the outputs from the reply, some of which overwrite input fields, are added. These fields are those that are output from the corresponding synchronous version of the asynchronous request. 2. Any inputs that are not updated become undefined, except the pointer to the COMMAREA and the input eci_message_qualifier. You should not use the contents of these fields again. eci_call_type Required input parameter. Must be set to ECI_GET_SPECIFIC_REPLY. eci_commarea Optional input parameter. A pointer to the area of storage where the application receives the returned COMMAREA. The contents of the returned commarea depend on the type of asynchronous call to which a reply is being sought. For a program link call, it is the COMMAREA expected to be returned from the called program, if any. For a status information call, except one in which eci_extend_mode had the value ECI_STATE_CANCEL, it is a COMMAREA containing status information (see Status information calls and ECI status block for more details). If the code page of the application is different from the code page of the server, data conversion must be performed at the server. To do this, you need to make use of CICS-supplied resource conversion capabilities, such as the DFHCNV macro definitions. eci_commarea_length Required input parameter. The length of the COMMAREA in bytes. This value may not exceed 32500. (Some client-server combinations may allow larger COMMAREAs, but this is not guaranteed to work as part of CICS Family Client/Server Programming.) eci_message_qualifier Required input parameter. An integer field that identifies the asynchronous call for which a reply is being solicited. eci_sysid Required input parameter. Reserved for future use, but this field should be initialized with nulls before the start of each logical unit of work. eci_version Required input parameter. The version of the ECI for which the application is coded. In the CICS on Open Systems environment, only ECI_VERSION_1 may be specified. In other environments, you may use the values ECI_VERSION_1 or ECI_VERSION_1A. All the facilities of version 1 are available in version 1A. Facilities available only in version 1A are noted where they occur. (ECI_VERSION_0 is provided to allow applications written for previous versions of the ECI to continue to execute, but many of the facilities of CICS Client/Server Programming are not available if eci_version has this value.) Return codes See also the general list of return codes for CICS_ExternalCall in CICS_ExternalCall. ECI_NO_ERROR The call completed successfully. ECI_ERR_INVALID_DATA_LENGTH The value in eci_commarea_length field is unacceptable for one of the following reasons: o It is outside the valid range. o It is inconsistent with the value in eci_commarea, being zero for a non-null eci_commarea pointer, or non-zero for a null eci_commarea pointer. o It is not large enough for the output COMMAREA from the asynchronous request to which this reply relates. In the last case, you can use the output eci_commarea_length to allocate more storage for the COMMAREA, and then retry the ECI_GET_SPECIFIC_REPLY call. ECI_ERR_NO_CICS The CICS server specified in eci_system_name in the asynchronous request to which this reply relates is not available. No resources have been updated. ECI_ERR_CICS_DIED A logical unit of work was to be begun or continued by the asynchronous request to which this reply relates, but the CICS server was no longer available. If eci_extend_mode was ECI_EXTENDED, the changes are backed out, and the logical unit of work ends. If eci_extend_mode was ECI_NO_EXTEND, ECI_COMMIT, or ECI_BACKOUT, the application cannot determine whether the changes have been committed or backed out, and must log this condition to aid future manual recovery. ECI_ERR_NO_REPLY There was no outstanding reply that matched the input eci_message_qualifier. ECI_ERR_TRANSACTION_ABEND The asynchronous request to which this reply relates caused a program to be executed in the server, but the CICS transaction that executed the requested program abended. The abend code will be found in eci_abend_code. For information about abend codes and their meaning, you should consult the documentation for the server system to which the request was directed. ECI_ERR_THREAD_CREATE_ERROR The CICS server or client failed to create the thread to process the asynchronous request to which this reply relates. ECI_ERR_RESOURCE_SHORTAGE The CICS server or client did not have enough resources to complete the asynchronous request to which this reply relates. ECI_ERR_INVALID_DATA_AREA Either the pointer to the ECI parameter block is invalid, or the pointer supplied in eci_commarea is invalid. ECI_ERR_ROLLEDBACK The asynchronous request to which this reply relates attempted to commit a logical unit of work, but the server was unable to commit the changes, and backed them out instead. ECI_ERR_UNKNOWN_SERVER The asynchronous request to which this reply relates specified a server that could not be located. Only servers returned by CICS_EciListSystems are acceptable. ECI_ERR_MAX_SESSIONS There were not enough communication resources to satisfy the asynchronous request to which this reply relates. You should consult the documentation for your client or server to see how to control communication resources. ECI_ERR_MAX_SYSTEMS The asynchronous request to which this reply relates attempted to start requests to more servers than your configuration allows. You should consult the documentation for your client or server to see how to control the number of servers you can use. ECI_ERR_SECURITY_ERROR You did not supply a valid combination of userid and password on the asynchronous request to which this reply relates, though the server expects it. ═══ 7.5.8. ECI_GET_SPECIFIC_REPLY_WAIT call type ═══ ECI_GET_SPECIFIC_REPLY_WAIT call type Environment The ECI_GET_SPECIFIC_REPLY_WAIT call type is available in all environments except DOS. Purpose The ECI_GET_SPECIFIC_REPLY_WAIT call type provides a reply solicitation call to return information appropriate to any outstanding reply that matches the input eci_message_qualifier. If there is no such reply, the application waits until there is. (In all environments except DOS, you can get an indication that no reply is available by using call type ECI_GET_SPECIFIC_REPLY instead.) ECI parameter block fields Same as for ECI_GET_SPECIFIC_REPLY, but eci_call_type must be set to ECI_GET_SPECIFIC_REPLY_WAIT. Return codes Same as for ECI_GET_SPECIFIC_REPLY, except that ECI_ERR_NO_REPLY cannot be returned. ═══ 7.6. ECI status block ═══ The ECI status block is used in status information calls to pass information to and from the ECI. It contains the following fields: ConnectionType An integer field specifying the type of system on which the application is running, with the following possible values: ECI_CONNECTED_NOWHERE Application is not connected to anything. ECI_CONNECTED_TO_CLIENT Application is running on a client system. ECI_CONNECTED_TO_SERVER Application is using a server implementation of the ECI. CicsServerStatus An integer field specifying the state of the CICS server, with the following possible values: ECI_SERVERSTATE_UNKNOWN The CICS server state could not be determined. ECI_SERVERSTATE_UP The CICS server is available to run programs. ECI_SERVERSTATE_DOWN The CICS server is not available to run programs. CicsClientStatus An integer field specifying the state of the client, with the following possible values: ECI_CLIENTSTATE_UNKNOWN The client state could not be determined. ECI_CLIENTSTATE_UP The client is available to receive ECI calls. ECI_CLIENTSTATE_INAPPLICABLE The application is using a server implementation of the ECI. ═══ 7.7. CICS_EciListSystems ═══ CICS_EciListSystems ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ CICS_EciListSystems │ NameSpace │ │ │ Systems │ │ │ List │ └───────────────────────────────────────┴──────────────────────────────────────┘ Purpose The CICS_EciListSystems function provides a list of CICS servers to which CICS_ExternalCall requests may be directed. There is no guarantee that a communications link exists between the client and any server in the list, or that any of the servers is available to process requests. The list of servers is returned as an array of system information structures, one element for each CICS server. The structure is called CICS_EciSystem_t, and it defines the following fields. SystemName A pointer to a null-terminated string specifying the name of a CICS server. If the name is shorter than CICS_ECI_SYSTEM_MAX, it is padded with nulls to a length of CICS_ECI_SYSTEM_MAX + 1. Description A pointer to a null-terminated string that provides a description of the system, if one is available. If the description is shorter than CICS_ECI_DESCRIPTION_MAX characters, it is padded with nulls to a length of CICS_ECI_DESCRIPTION_MAX + 1. Parameters NameSpace A pointer reserved for future use. Ensure that this is a null pointer. Systems On entry to the function, this parameter specifies the number of elements in the array provided in the List parameter. On return it contains the actual number of systems found. List An array of CICS_EciSystem_t structures that are filled in and returned by the function. The application must provide the storage for the array, and must set the Systems parameter to indicate the number of elements in the array. The first name in the list is the default server. However, the way in which the default is defined is operating system dependent. Return codes ECI_NO_ERROR The function completed successfully. The number of systems found is at least one, and does not exceed the value supplied as input in the Systems parameter. ECI_ERR_MORE_SYSTEMS There was not enough space in the List array to store the information. The supplied array has been filled, and the Systems parameter has been updated to contain the total number of systems found, so that you can reallocate an array of suitable size and try the function again. ECI_ERR_NO_SYSTEMS No CICS servers can be located. In this case, the value returned in Systems is zero. ECI_ERR_NO_CICS The client is not active. ECI_ERR_INVALID_DATA_LENGTH The value specified in the Systems parameter is so large that the length of storage for the List parameter exceeds 32767. ECI_ERR_CALL_FROM_CALLBACK The call was made from a callback routine. ECI_ERR_SYSTEM_ERROR An internal system error occurred. ═══ 8. External presentation interface ═══ This chapter provides reference information about the external presentation interface (EPI). The interface is described here in a language-independent manner, though the names chosen for the elements of the interface-functions, parameters, data structures, fields, constants, and so on-are similar to those provided for programming. For language-dependent information, see Creating ECI and EPI application programs. Any restrictions applicable to particular operating environments are identified under the functions to which they apply. The chapter is organized as follows: Overview How to use the EPI EPI constants and data structures EPI functions EPI events 3270 data streams for the EPI Microsoft Windows considerations. ═══ 8.1. Overview ═══ The EPI allows a non-CICS application program to have access to one or more CICS servers. In each CICS server, the application can establish one or more terminal resources. The application acts as the operator of these terminal resources, starting CICS transactions, and sending and receiving standard 3270 data streams associated with those transactions. The following points should be borne in mind when designing client/server implementations using the EPI. 1. A CICS transaction that sends data to an EPI application must not use the IMMEDIATE option of EXEC CICS RETURN. 2. The EPI application can use the EPI to determine the default screen size of the terminal resource definition, but not the alternate screen size. 3. The EPI application cannot use the EPI to determine whether it is to send or receive double byte character set (DBCS) data streams to or from the CICS transaction. 4. The 3270 data streams produced by CICS transactions must not contain structured fields. 5. If a CICS transaction is run with execution diagnostic facility (EDF) enabled at an EPI application's terminal resource, the events reported to the EPI application are different from those reported when EDF is not enabled. 6. If a CICS transaction uses EXEC CICS START with the DELAY option to schedule transactions to a terminal resource autoinstalled by an EPI application, the EPI application should exercise caution in deleting the terminal resource, or delayed ATI requests might be lost. You should consult your server documentation to determine the effects of deleting a terminal resource when delayed ATI requests are outstanding. The application is responsible for the presentation of the 3270 data received. The application may present the data in the normal way by emulating a 3270 terminal, or it may present a very different view. For example: o An OS/2 application may use Presentation Manager. o An application for the CICS on Opens Systems environment may use Motif. o A SunOS application may use Open Look. o An Apple application may use Macintosh Toolbox. ═══ 8.2. How to use the EPI ═══ The EPI provides a separate function name for each of its functions. ═══ 8.2.1. Initialization and termination ═══ Any application requiring to use the EPI must call the CICS_EpiInitialize function to initialize the EPI. Until this call is made, no other EPI function is allowed. The CICS_EpiInitialize function takes a parameter indicating the version of the EPI for which the application was coded. This is to ensure that existing applications continue to execute without change if the EPI is extended. Before an EPI application ends, it should call the CICS_EpiTerminate function to terminate the EPI cleanly. ═══ 8.2.2. Listing the configured servers ═══ After calling CICS_EpiInitialize successfully, the application should call CICS_EpiListSystems to check which CICS servers are configured for use by the application. ═══ 8.2.3. Adding and deleting terminal resources ═══ The primary purpose of the EPI is to allow an application to appear to a CICS server as one or more 3270 terminals. The application should make a CICS_EpiAddTerminal call for each terminal resource it needs to define. The application must specify the server in which the terminal resource is to be installed, and may specify the terminal resource to be installed by supplying one of the following: o The netname of an existing terminal resource in the server. This terminal resource should be one that is not currently in use. o The name of a model terminal definition. In this case a new terminal resource is autoinstalled. o Nothing. In this case the server generates a netname and autoinstalls a terminal resource with that name, using a default model terminal definition. Once an application has established its use of a terminal resource with CICS_EpiAddTerminal, no other application can use that terminal resource until the first application releases it with CICS_EpiDelTerminal. The CICS_EpiAddTerminal call returns a terminal index, which must be passed on subsequent EPI function calls to indicate the terminal resource to which the function is to apply. Each index identifies a combination of server and terminal resource. The terminal index supplied is the first available integer starting from 0. This allows the application to maintain a mapping between terminal indexes and terminal resource information, using array lookup. Terminal indexes are unique within an application, but not across applications, so each application gets terminal index zero for the first terminal it installs, and so on. Using terminal indexes shows an application with three terminal resources, one in one server and two in another. The application uses the terminal indexes to operate the terminal resources, sending and receiving 3270 data streams. The order of the indexes shows the order in which the terminal resources were installed with CICS_EpiAddTerminal. Using terminal indexes If a terminal resource is no longer required, it can be deleted by making a CICS_EpiDelTerminal call. This call can succeed only if the terminal resource is not currently running a transaction; if a transaction is in progress, the call returns an error code. Deleting a terminal resource is like signing off from the terminal by running the CESF transaction. When deletion is complete, the terminal index value becomes free and can be reissued by a subsequent CICS_EpiAddTerminal call. If the terminal resource was added by way of a model terminal definition, the CICS_EpiDelTerminal call also deletes the terminal resource from the server. ═══ 8.2.4. Starting transactions ═══ When an application has defined a terminal resource, it can start a transaction from that terminal resource. To the CICS server it appears as if a terminal user had typed a transaction code on the screen and pressed an AID key. To start a transaction, the CICS_EpiStartTran function is called. There are two ways of specifying the transaction to be started and the data to be associated with it. 1. Supply the transaction identifier as a parameter to the call (TransId), and supply any transaction data in the Data parameter. 2. Combine a transaction identifier and transaction data into a 3270 data stream, and supply the data stream as a parameter to the call (Data). ═══ 8.2.5. Events and callbacks ═══ When an application has defined a terminal resource, several events can happen to it because of actions in the CICS server, rather than actions of the application. The application cannot predict when those events may happen, but it is the responsibility of the application to collect and process the events as appropriate. Events are held by the EPI in a first-in-first-out queue until they are collected, one by one, by the application making calls to the CICS_EpiGetEvent function. During such a call, the EPI puts information in a CICS_EpiEventData_t structure to indicate the event that occurred and any associated data. It also indicates whether there are more events still waiting in the queue. The application can synchronize the processing of these events with its other activities in one of three ways: o Polling o Blocking o Callback notification. ═══ 8.2.5.1. Polling ═══ The CICS_EpiGetEvent call can be made in a polling mode by specifying CICS_EPI_NOWAIT for the Wait parameter. If no event is waiting to be collected, the function returns immediately with an error code. This is the mechanism that you would have to adopt in a single-user single-threaded environment, such as DOS, where the application might alternately poll the keyboard for user activity and poll the EPI for event activity. ═══ 8.2.5.2. Blocking ═══ The CICS_EpiGetEvent call can be made in a blocking mode by specifying CICS_EPI_WAIT for the Wait parameter. If no event is waiting to be collected, the function waits and does not return until an event becomes available. You could use this mechanism in a multithreaded environment, where a secondary thread could be dedicated to event processing. It could also be used after a notification by callback, because the event information is known to be available. ═══ 8.2.5.3. Callback notification ═══ When the terminal resource is defined with the CICS_EpiAddTerminal call, the optional parameter NotifyFn may be used to provide the address of a callback routine that the EPI calls whenever an event occurs against that terminal resource. Callback notification is not supported under DOS and Microsoft Windows. Under DOS and Microsoft Windows, the parameter can be specified, but it is ignored, and the application must poll for events. Note: Some compilers do not support the use of callback routines. Consult your compiler documentation for more information. An application should carry out the minimum of processing in its callback routine, and never block in the specified routine before returning to the EPI. The routine itself cannot make EPI calls. You decide what it should do when the notification is received. For example, in a multithreaded environment like OS/2, it might post a semaphore to signal another thread that an event has occurred. In a Presentation Manager environment, it might post a message to a window to indicate to the window procedure that an event has occurred. Other actions will be appropriate for other environments. In a CICS on Open Systems environment, only thread-safe facilities should be used. When the callback routine is called, it is passed a single parameter-the terminal index of the terminal resource against which the event occurred. This allows the same callback routine to be used for more than one terminal resource. ═══ 8.2.6. Processing the events ═══ On return from the CICS_EpiGetEvent function, the CICS_EpiEventData_t structure contains the details of the event that occurred. The Event field in this structure indicates the event, and can take one of the following values: o CICS_EPI_EVENT_SEND o CICS_EPI_EVENT_CONVERSE o CICS_EPI_EVENT_END_TRAN o CICS_EPI_EVENT_START_ATI o CICS_EPI_EVENT_END_TERM o CICS_EPI_EVENT_HELP. The application should attempt to process events as quickly as possible, because some events describe the state of the terminal resource. If these events are not processed, the application may receive unexpected error return codes when it tries to issue EPI functions, because the state maintained inside the EPI might not match the state maintained in the application. For example, an application can start a transaction only if the terminal resource is not currently running another transaction. The CICS_EPI_EVENT_END_TRAN event signals the end of a transaction, and so the application and the EPI enter a state in which new transactions can be started for that terminal resource. The CICS_EPI_EVENT_START_ATI event indicates that an ATI transaction has started at the terminal resource, and therefore that the terminal resource has entered a state in which the starting of transactions is no longer allowed. If the application calls CICS_EpiStartTran after the CICS_EPI_EVENT_START_ATI event has been notified, but before the event has been retrieved, the CICS_EpiStartTran call fails, even though, to the application, it may appear that it is still in a state in which it should succeed. ═══ 8.2.7. Sending and receiving data ═══ When a transaction sends data to a terminal resource, the EPI generates either a CICS_EPI_EVENT_SEND event or a CICS_EPI_EVENT_CONVERSE event. The CICS_EPI_EVENT_SEND event indicates that data was sent but that no reply is required. Typically this would result from an EXEC CICS SEND command, but in some servers it would result from an EXEC CICS CONVERSE command. (In the latter case, a CICS_EPI_EVENT_CONVERSE event occurs later to tell the application to send a data stream back to the transaction in the server.) The CICS_EPI_EVENT_CONVERSE event indicates that a reply is required, and would typically result from an EXEC CICS RECEIVE or EXEC CICS CONVERSE command. The application should respond to this event by issuing a CICS_EpiReply call to provide the response data. The CICS_EpiReply function should be issued only to respond to a CICS_EPI_EVENT_CONVERSE event; if it is issued at any other time, an error is returned. ═══ 8.2.8. Managing pseudoconversations ═══ CICS transactions can operate in a pseudoconversational mode. The conversation between a terminal resource and a server is broken up into a number of segments, each of which is a separate transaction. As each transaction ends, it provides the name of the transaction to be run to process the next input from the terminal resource. (It uses EXEC CICS RETURN with the TRANSID option to do this.) The CICS_EPI_EVENT_END_TRAN event tells the application whether the transaction just ended has specified a transaction to process the next input, and which transaction has been specified. The application must not attempt to start a different transaction, but must use CICS_EpiStartTran to start the transaction specified by the CICS_EPI_EVENT_END_TRAN event. ═══ 8.2.9. Security in the EPI ═══ The EPI has no interface for the non-CICS application to supply userids or passwords to the server. Not all CICS servers require the client to supply a userid and password for EPI calls. Some CICS servers have configuration options to decide whether the userid and password are required. You should consult the publications for the appropriate server for more information. Some client environments support the use of userids and passwords in files, so that the userid and password need not be supplied by the non-CICS application. Some client environments support the use of dialogs with the workstation operator to determine userids and passwords. You should consult the publications for the appropriate client environment for more information. In the CICS on Open Systems environment, the operator might need DCE authorization to use the EPI application, depending on the local configuration. If the EPI program runs for a long time, for example longer than thirty minutes, you must make sure that the credential lifetime and renewable lifetime of the DCE principal are long enough to cover the maximum allowed duration of the EPI program. Authorization to use protected transactions can only be achieved by using CICS_EpiStartTran for the CESN transaction, specifying userid and password. Whether userids and passwords are encrypted depends on the communications protocol being used between client and server. ═══ 8.3. EPI constants and data structures ═══ This section describes the constants and data structures that you will need to use the EPI. They are referred to in EPI functions. ═══ 8.3.1. EPI constants ═══ The following constants are referred to symbolically in the descriptions of the EPI data structures, functions, and events in this chapter. Their values are given here to help you understand the descriptions. However, your code should always use the symbolic names of EPI constants provided for the programming language you are using. Lengths of fields o CICS_EPI_SYSTEM_MAX (8) o CICS_EPI_DESCRIPTION_MAX (60) o CICS_EPI_NETNAME_MAX (8) o CICS_EPI_TRANSID_MAX (4) o CICS_EPI_ABEND_MAX (4) o CICS_EPI_DEVTYPE_MAX (16) o CICS_EPI_ERROR_MAX (60). Relating to TermIndex o CICS_EPI_TERM_INDEX_NONE 0xFFFF. Version numbers (See EPI versions) o CICS_EPI_VERSION_100 o CICS_EPI_VERSION_101. ═══ 8.3.2. EPI data structures ═══ The following data structures are available for use with the EPI. o CICS_EpiSystem_t o CICS_EpiDetails_t o CICS_EpiEventData_t o CICS_EpiSysError_t. In the descriptions of the fields in the data structures, fields described as strings are null-terminated strings. ═══ 8.3.3. CICS_EpiSystem_t ═══ CICS_EpiSystem_t Purpose The CICS_EpiSystem_t structure contains the name and description of a CICS server. An array of these structures is returned from the CICS_EpiListSystems function. Fields SystemName A string naming the CICS server. It can be passed as a parameter to the CICS_EpiAddTerminal function, to identify the CICS server in which the terminal resource should be installed. If the name is shorter than CICS_EPI_SYSTEM_MAX characters, it is padded with nulls to a length of CICS_EPI_SYSTEM_MAX + 1. Description A string giving a brief description of the server. If the description is shorter than CICS_EPI_DESCRIPTION_MAX, it is padded with nulls to a length of CICS_EPI_DESCRIPTION_MAX + 1. ═══ 8.3.4. CICS_EpiDetails_t ═══ CICS_EpiDetails_t Purpose The CICS_EpiDetails_t structure holds information about a terminal resource installed by CICS_EpiAddTerminal. Fields NetName A string specifying the VTAM-style netname of the terminal resource. If the name is shorter than CICS_EPI_NETNAME_MAX characters, it is padded with nulls to a length of CICS_EPI_NETNAME_MAX + 1. NumLines The number of rows supported by the terminal resource. NumColumns The number of columns supported by the terminal resource. MaxData The maximum possible size of the data that CICS will send to this terminal resource. ErrLastLine 1 if the terminal resource should display error messages on its last row, 0 otherwise. ErrIntensify 1 if the terminal resource should display error messages intensified, 0 otherwise. ErrColor The 3270 attribute defining the color to be used to display error messages. ErrHilight The 3270 attribute defining the highlight value to be used to display error messages. Hilight 1 if the terminal resource is defined to support extended highlighting, 0 otherwise. Color 1 if the terminal resource is defined to support color, 0 otherwise. Printer 1 if the terminal resource is defined to be a printer, 0 otherwise. ═══ 8.3.5. CICS_EpiEventData_t ═══ CICS_EpiEventData_t Purpose The CICS_EpiEventData_t structure holds details of a terminal-related event. Not all fields are valid for all events, and fields that are not valid are set to nulls. This structure is an output from CICS_EpiGetEvent. Fields TermIndex The terminal index for the terminal resource against which this event occurred. Event The event indicator; that is, one of the event codes listed in EPI events. EndReason The reason for termination, if the event is a CICS_EPI_EVENT_END_TERM event (see page CICS_EPI_EVENT_CONVERSE). TransId A string specifying a transaction name. If the name is shorter than CICS_EPI_TRANSID_MAX characters, it is padded with spaces to this length, followed by a single null character. AbendCode A string specifying an abend code. Data A pointer to a buffer that is updated with any terminal data stream associated with the event. Size The maximum size of the buffer addressed by Data. On return from the CICS_EpiGetEvent call, this contains the actual length of data returned. Note: The Data and Size fields should be set before the call to CICS_EpiGetEvent is made. ═══ 8.3.6. CICS_EpiSysError_t ═══ CICS_EpiSysError_t Purpose The CICS_EpiSysError_t structure holds system error information. It is an output of CICS_EpiGetSysError. Fields Cause A value, specific to the operating environment, indicating the cause of the last error. Value A value, specific to the operating environment, indicating the nature of the last error. Msg A text message, specific to the operating environment, describing the last error. If the message is shorter than CICS_EPI_ERROR_MAX, it is padded with nulls to a length of CICS_EPI_ERROR_MAX + 1. ═══ 8.4. EPI versions ═══ The following descriptions of EPI functions include information about two versions of the EPI. You should consult the documentation for your client or server environment to determine which versions of the EPI they provide. You establish the version of the EPI that you need by using the Version parameter on the CICS_EpiInitialize function. The function described in the following sections is the function for CICS_EPI_VERSION_101. If you initialize the EPI with CICS_EPI_VERSION_100, the following restrictions apply: o The CICS_EpiInquireSystem function is not supported. o The return codes EPI_ERR_IN_CALLBACK, EPI_ERR_NULL_PARM, and EPI_ERR_SECURITY are not supported. EPI_ERR_FAILED will be returned instead. o The System parameter of CICS_EpiAddTerminal must specify a non-null string, as the mechanism for finding a default server is not supported. (If a null string is specified, CICS_EPI_ERR_SYSTEM is returned.) ═══ 8.5. EPI functions ═══ This section describes the functions provided by the EPI that can be called from an application program: o CICS_EpiInitialize o CICS_EpiTerminate o CICS_EpiListSystems o CICS_EpiAddTerminal o CICS_EpiInquireSystem o CICS_EpiDelTerminal o CICS_EpiStartTran o CICS_EpiReply o CICS_EpiATIState o CICS_EpiSenseCode o CICS_EpiGetEvent o CICS_EpiGetSysError. Summary of EPI functions summarizes the functions of the interface, the parameters passed to each function, and the possible return codes from each function. ┌──────────────────────────────────────────────────────────────────────────────┐ │ Table 1. Summary of EPI functions │ ├───────────────────────────────┬───────────────┬──────────────────────────────┤ │ Function name │ Parameters │ Return codes: │ │ │ │ CICS_EPI_ │ ├───────────────────────────────┼───────────────┼──────────────────────────────┤ │ CICS_EpiInitialize │ Version │ ERR_FAILED │ │ │ │ ERR_IS_INIT │ │ │ │ ERR_VERSION │ │ │ │ ERR_IN_CALLBACK │ │ │ │ NORMAL │ ├───────────────────────────────┼───────────────┼──────────────────────────────┤ │ CICS_EpiTerminate │ none │ ERR_FAILED │ │ │ │ ERR_NOT_INIT │ │ │ │ ERR_IN_CALLBACK │ │ │ │ NORMAL │ ├───────────────────────────────┼───────────────┼──────────────────────────────┤ │ CICS_EpiListSystems │ NameSpace │ ERR_FAILED │ │ │ Systems │ ERR_MORE_SYSTEMS │ │ │ List │ ERR_NO_SYSTEMS │ │ │ │ ERR_NOT_INIT │ │ │ │ ERR_NULL_PARM │ │ │ │ ERR_IN_CALLBACK │ │ │ │ NORMAL │ ├───────────────────────────────┼───────────────┼──────────────────────────────┤ │ CICS_EpiAddTerminal │ NameSpace │ ERR_FAILED │ │ │ System │ ERR_MAX_TERMS │ │ │ NetName │ ERR_NOT_INIT │ │ │ DevType │ ERR_SYSTEM │ │ │ NotifyFn │ ERR_SECURITY │ │ │ Details │ ERR_NULL_PARM │ │ │ TermIndex │ ERR_IN_CALLBACK │ │ │ │ NORMAL │ ├───────────────────────────────┼───────────────┼──────────────────────────────┤ │ CICS_EpiInquireSystem │ TermIndex │ ERR_BAD_INDEX │ │ │ System │ ERR_FAILED │ │ │ │ ERR_NOT_INIT │ │ │ │ ERR_NULL_PARM │ │ │ │ ERR_IN_CALLBACK │ │ │ │ NORMAL │ ├───────────────────────────────┼───────────────┼──────────────────────────────┤ │ CICS_EpiDelTerminal │ TermIndex │ ERR_BAD_INDEX │ │ │ │ ERR_FAILED │ │ │ │ ERR_NOT_INIT │ │ │ │ ERR_TRAN_ACTIVE │ │ │ │ ERR_IN_CALLBACK │ │ │ │ NORMAL │ ├───────────────────────────────┼───────────────┼──────────────────────────────┤ │ CICS_EpiStartTran │ TermIndex │ ERR_ATI_ACTIVE │ │ │ TransId │ ERR_BAD_INDEX │ │ │ Data │ ERR_FAILED │ │ │ Size │ ERR_NO_DATA │ │ │ │ ERR_NOT_INIT │ │ │ │ ERR_TTI_ACTIVE │ │ │ │ ERR_IN_CALLBACK │ │ │ │ NORMAL │ ├───────────────────────────────┼───────────────┼──────────────────────────────┤ │ CICS_EpiReply │ TermIndex │ ERR_BAD_INDEX │ │ │ Data │ ERR_FAILED │ │ │ Size │ ERR_NO_CONVERSE │ │ │ │ ERR_NO_DATA │ │ │ │ ERR_NOT_INIT │ │ │ │ ERR_IN_CALLBACK │ │ │ │ NORMAL │ ├───────────────────────────────┼───────────────┼──────────────────────────────┤ │ CICS_EpiATIState │ TermIndex │ ERR_ATI_STATE │ │ │ ATIState │ ERR_BAD_INDEX │ │ │ │ ERR_FAILED │ │ │ │ ERR_NOT_INIT │ │ │ │ ERR_IN_CALLBACK │ │ │ │ NORMAL │ ├───────────────────────────────┼───────────────┼──────────────────────────────┤ │ CICS_EpiSenseCode │ TermIndex │ ERR_BAD_INDEX │ │ │ SenseCode │ ERR_FAILED │ │ │ │ ERR_NOT_INIT │ │ │ │ ERR_SENSE_CODE │ │ │ │ ERR_IN_CALLBACK │ │ │ │ NORMAL │ └───────────────────────────────┴───────────────┴──────────────────────────────┘ ┌──────────────────────────────────────────────────────────────────────────────┐ │ Table 1. Summary of EPI functions │ ├───────────────────────────────┬───────────────┬──────────────────────────────┤ │ CICS_EpiGetEvent │ TermIndex │ ERR_BAD_INDEX │ │ │ Wait │ ERR_FAILED │ │ │ Event │ ERR_MORE_DATA │ │ │ │ ERR_MORE_EVENTS │ │ │ │ ERR_NO_EVENT │ │ │ │ ERR_NOT_INIT │ │ │ │ ERR_WAIT │ │ │ │ ERR_NULL_PARM │ │ │ │ ERR_IN_CALLBACK │ │ │ │ NORMAL │ ├───────────────────────────────┼───────────────┼──────────────────────────────┤ │ CICS_EpiGetSysError │ TermIndex │ ERR_NOT_INIT │ │ │ SysErr │ ERR_BAD_INDEX │ │ │ │ ERR_FAILED │ │ │ │ ERR_NULL_PARM │ │ │ │ ERR_IN_CALLBACK │ │ │ │ NORMAL │ └───────────────────────────────┴───────────────┴──────────────────────────────┘ Refer to the definitions of the functions to discover the types and usage of the parameters, the data structures used by the functions, and the meanings of the return codes. ═══ 8.5.1. CICS_EpiInitialize ═══ CICS_EpiInitialize ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ CICS_EpiInitialize │ Version │ └───────────────────────────────────────┴──────────────────────────────────────┘ Purpose The CICS_EpiInitialize function initializes the EPI. All other EPI calls from this application are invalid before this call is made. Microsoft Windows only See Microsoft Windows considerations for further details of the use of this function in a Microsoft Windows environment. Parameters Version The version of the EPI for which this application is coded. This makes it possible for old applications to remain compatible with future versions of the EPI. The version described here is CICS_EPI_VERSION_101. (See EPI versions for more information.) The EPI uses this parameter only for input. Return codes CICS_EPI_ERR_FAILED The function failed for an unexpected reason. CICS_EPI_ERR_IS_INIT The EPI is already initialized. CICS_EPI_ERR_VERSION The EPI cannot support the version requested. CICS_EPI_ERR_IN_CALLBACK The function was called from a callback routine. CICS_EPI_NORMAL The function completed successfully. ═══ 8.5.2. CICS_EpiTerminate ═══ CICS_EpiTerminate ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ CICS_EpiTerminate │ │ └───────────────────────────────────────┴──────────────────────────────────────┘ Purpose The CICS_EpiTerminate function ends the application's use of the EPI, typically just before the application terminates. All other EPI calls (except for CICS_EpiInitialize) are invalid when this call has completed. The application should issue CICS_EpiDelTerminal calls before terminating, to ensure that any terminal resources are deleted. Parameters None. Return codes CICS_EPI_ERR_FAILED The function failed for an unexpected reason. CICS_EPI_ERR_NOT_INIT CICS_EpiInitialize has not been executed. CICS_EPI_ERR_IN_CALLBACK The function was called from a callback routine. CICS_EPI_NORMAL The function completed successfully. ═══ 8.5.3. CICS_EpiListSystems ═══ CICS_EpiListSystems ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ CICS_EpiListSystems │ NameSpace │ │ │ Systems │ │ │ List │ └───────────────────────────────────────┴──────────────────────────────────────┘ Purpose The CICS_EpiListSystems function returns a list of CICS servers that are candidates to act as servers for EPI requests. There is no guarantee that a communications link exists between the client and any server in the list, or that any of the servers is available to process requests. The list is returned as an array of system information structures, one element for each CICS server. See CICS_EpiSystem_t for the contents of the structure. EPI applications should call this function immediately after each CICS_EpiInitialize call made to determine which CICS servers are available. Parameters NameSpace A pointer reserved for future use. Ensure that this is a null pointer. Systems A pointer to a number. On entry to the function, this number specifies the number of elements in the array specified in the List parameter. This value should accurately reflect the amount of storage that is available to the EPI to store the result. On return, it contains the actual number of servers found. The EPI uses this parameter for both input and output. List An array of CICS_EpiSystem_t structures that are filled in and returned by the function. The application should provide the storage for the array and must set the Systems parameter to indicate the number of elements in the array. The first name in the list is the default server. However, the way in which the default is defined is operating system dependent. The EPI uses this parameter only for output. Return codes CICS_EPI_ERR_FAILED The function failed for an unexpected reason. CICS_EPI_ERR_MORE_SYSTEMS There was not enough space in the List array to store the details of all the CICS servers found. The supplied array has been filled, and the Systems parameter has been updated to contain the total number of servers found, thus allowing you to reallocate an array of suitable size and try the function again. CICS_EPI_ERR_NO_SYSTEMS No CICS servers can be located. In this case, the value returned in Systems is zero. CICS_EPI_ERR_NOT_INIT CICS_EpiInitialize has not been executed. CICS_EPI_ERR_NULL_PARM Systems is a null pointer. CICS_EPI_ERR_IN_CALLBACK The function was called from a callback routine. CICS_EPI_NORMAL The function completed successfully. The number of systems found is at least one, and does not exceed the value supplied as input in the Systems parameter. ═══ 8.5.4. CICS_EpiAddTerminal ═══ CICS_EpiAddTerminal ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ CICS_EpiAddTerminal │ NameSpace │ │ │ System │ │ │ NetName │ │ │ DevType │ │ │ NotifyFn │ │ │ Details │ │ │ TermIndex │ └───────────────────────────────────────┴──────────────────────────────────────┘ Purpose The CICS_EpiAddTerminal function installs a new terminal resource, or reserves an existing terminal resource, for the application's use. It provides a terminal index, which should be used to identify the terminal resource on all further EPI calls. It also provides the information defined in the CICS_EpiDetails_t data structure. Microsoft Windows only See Microsoft Windows considerations for further details of the use of this function in a Microsoft Windows environment. Parameters NameSpace A pointer reserved for future use. Ensure that this is a null pointer. System A pointer to a null-terminated string that specifies the name of the server in which the terminal resource is to be installed or reserved. If the name is shorter than CICS_EPI_SYSTEM_MAX characters, it must be padded with nulls to a length of CICS_EPI_SYSTEM_MAX + 1. If the string is all nulls, then a server, currently the default server, is selected by the EPI. To determine the name of the server chosen, use CICS_EpiInquireSystem. (Specifying a null string is allowed only if the EPI was initialized with EPI_VERSION_101.) The EPI uses this parameter only for input. NetName A pointer to a null-terminated string that specifies the name of the terminal resource to be installed or reserved, or null. The interpretation of this name is server-dependent. If a string is supplied that is shorter than CICS_EPI_NETNAME_MAX, it must be padded with nulls to a length of CICS_EPI_NETNAME_MAX + 1. The string is transmitted to the server without conversion to uppercase. The use of NetName is as follows: 1. If a name is supplied using the NetName, and it matches the name of an existing terminal resource in the server, the server attempts to reserve that terminal resource. 2. If a name is supplied, but it does not match the name of an existing terminal resource in the server, the processing depends on the server as follows: o In a CICS on Open Systems server, the server installs a resource using a default model terminal definition, and gives it the input name. o On other CICS servers, the server installs a terminal resource using the model terminal definition specified by the DevType parameter described below, and gives it the input name. (If DevType is a null pointer, CICS_EPI_ERR_FAILED is returned.) 3. If NetName is a null pointer, then a terminal resource is installed using the model terminal definition specified in DevType, or a default model terminal definition if DevType is a null pointer. The name of the terminal resource is returned in the NetName field of the CICS_EpiDetails_t structure. The EPI uses this parameter only for input. DevType A pointer to a null-terminated string that is used in the server to select a model terminal definition from which a terminal resource definition is generated, or a null pointer. If a string is supplied that is shorter than CICS_EPI_DEVTYPE_MAX characters, it should be padded with nulls to a length of CICS_EPI_DEVTYPE_MAX + 1. The string is transmitted to the server without conversion to uppercase. The EPI uses this parameter only for input. NotifyFn A pointer to a callback routine that is called whenever an event occurs for the terminal resource, such as the arrival of an ATI request. If a callback routine is not required, this parameter should be set to null. The EPI uses this parameter only for input. DOS and Microsoft Windows The function is ignored and never called even if specified. Details A pointer to the CICS_EpiDetails_t structure that on return contains various details about the terminal resource that was installed or reserved. The EPI uses the fields in this structure only for output. TermIndex A pointer to a terminal index for the terminal resource just installed or reserved. The returned terminal index must be used as input to all further EPI function calls to identify the terminal resource to which the function is directed. The terminal index supplied is the first available integer starting from 0. The EPI uses this parameter only for output. Return codes CICS_EPI_ERR_FAILED The function failed for an unexpected reason. CICS_EPI_ERR_MAX_TERMS The maximum number of terminal resources supported by the EPI for this process has been reached. CICS_EPI_ERR_NOT_INIT CICS_EpiInitialize has not been executed. CICS_EPI_ERR_SYSTEM The specified server is not known to the client. CICS_EPI_ERR_SECURITY The server rejected the attempt for security reasons. CICS_EPI_ERR_NULL_PARM TermIndex was a null pointer. CICS_EPI_ERR_IN_CALLBACK The function was called from a callback routine. CICS_EPI_NORMAL The function completed successfully. ═══ 8.5.5. CICS_EpiInquireSystem ═══ CICS_EpiInquireSystem ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ CICS_EpiInquireSystem │ TermIndex │ │ │ System │ └───────────────────────────────────────┴──────────────────────────────────────┘ Purpose The CICS_EpiInquireSystem function returns the name of the server on which a given terminal resource (identified by its terminal index) is installed. Parameters TermIndex The terminal index of the terminal resource whose location is to be determined. The EPI uses this parameter only for input. System A pointer to a string of length CICS_ECI_SYSTEM_MAX + 1 in which the name of the server will be returned. The EPI uses this parameter only for output. Return codes CICS_EPI_ERR_BAD_INDEX The TermIndex value is not a valid terminal index. CICS_EPI_ERR_FAILED The function failed for an unexpected reason. CICS_EPI_ERR_NOT_INIT CICS_EpiInitialize has not been executed. CICS_EPI_ERR_NULL_PARM System was a null pointer. CICS_EPI_ERR_IN_CALLBACK The function was called from a callback routine. CICS_EPI_NORMAL The function completed successfully. The name of the server is returned in the System parameter padded with nulls to a length of CICS_EPI_SYSTEM_MAX +1. ═══ 8.5.6. CICS_EpiDelTerminal ═══ CICS_EpiDelTerminal ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ CICS_EpiDelTerminal │ TermIndex │ └───────────────────────────────────────┴──────────────────────────────────────┘ Purpose The CICS_EpiDelTerminal function deletes a previously added terminal resource. The application should not consider the deletion complete until it receives the corresponding CICS_EPI_EVENT_END_TERM event. A call to this function fails if the terminal resource is currently running a transaction. To ensure that a terminal resource is deleted, the application must wait until the current transaction finishes and process all outstanding events before issuing the CICS_EpiDelTerminal call. If the terminal resource was autoinstalled, its definition is deleted from the server. When a CICS_EpiDelTerminal call has completed successfully for a terminal resource, use of the terminal index is restricted to CICS_EpiGetEvent and CICS_EpiGetSysError calls until the application has received the corresponding CICS_EPI_EVENT_END_TERM event. Parameters TermIndex The terminal index of the terminal resource to be deleted. The EPI uses this parameter only for input. Return codes CICS_EPI_ERR_BAD_INDEX The TermIndex value is not a valid terminal index. CICS_EPI_ERR_FAILED The function failed for an unexpected reason. CICS_EPI_ERR_NOT_INIT CICS_EpiInitialize has not been executed. CICS_EPI_ERR_TRAN_ACTIVE A transaction is currently running against the terminal resource, or there are unprocessed events for the terminal resource. CICS_EPI_ERR_IN_CALLBACK The function was called from a callback routine. CICS_EPI_NORMAL The function completed successfully. ═══ 8.5.7. CICS_EpiStartTran ═══ CICS_EpiStartTran ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ CICS_EpiStartTran │ TermIndex │ │ │ TransId │ │ │ Data │ │ │ Size │ └───────────────────────────────────────┴──────────────────────────────────────┘ Purpose The CICS_EpiStartTran function starts a new transaction from a terminal resource, or continues a pseudoconversation. o Starting a new transaction-do this after CICS_EpiAddTerminal, or after a CICS_EPI_EVENT_END_TRAN event indicated that the previous transaction did not specify a transaction to process the next input from the terminal resource. o Continuing a pseudoconversation-do this after a CICS_EPI_EVENT_END_TRAN event that indicated that the previous transaction specified did specify a transaction to process the next input from the terminal resource. If the call is successful, no further start requests can be issued for this terminal resource until the transaction ends; this is indicated by the CICS_EPI_EVENT_END_TRAN event. Parameters TermIndex The terminal index of the terminal resource that is to run the transaction. The EPI uses this parameter only for input. TransId A pointer to a string specifying the transaction to be run, or the null pointer. If a new transaction is being started, and this input is the null pointer, the name of the transaction is extracted from the data stream supplied in the Data parameter. If a pseudoconversation is being continued, and the pointer is not null, the string must be the name of the transaction returned in the preceding CICS_EPI_EVENT_END_TRAN event for this terminal resource. If the pointer is not null, and the string is shorter than CICS_EPI_TRANSID_MAX characters, it should be padded with spaces to this length. The EPI uses this parameter only for input. Data A pointer to the 3270 data stream to be associated with the transaction. This parameter must not be a null pointer, because the data stream must contain at least an AID byte. If a new transaction is being started, and the TransId parameter is the null pointer, the data stream must be at least 4 bytes long, must contain the name of the transaction to be started, and might contain data to be supplied to the transaction on its first EXEC CICS RECEIVE command. If a new transaction is being started, and the TransId parameter is not the null pointer, the data stream might be only one byte (an AID byte), or 3 bytes (an AID byte and a cursor address), or longer than 3 bytes (an AID byte, a cursor address, and data and SBA commands). In the last case, the data is supplied to the transaction program on the first EXEC CICS RECEIVE command. If a pseudoconversation is being continued, the data stream might be only one byte (an AID byte), or 3 bytes (an AID byte and a cursor address), or longer than 3 bytes (an AID byte, a cursor address, and data and SBA commands). In the last case the data is supplied to the transaction program on the first EXEC CICS RECEIVE command. The details of the format of 3270 data streams for CICS are described in 3270 data streams for the EPI. The EPI uses this parameter only for input. Size The size in bytes of the initial data to be passed to the transaction. The EPI uses this parameter only for input. Note: The application might expect a terminal resource to be free to start a transaction and yet get an unexpected return code of CICS_EPI_ERR_ATI_ACTIVE from a call to CICS_EpiStartTran. If this happens, it means that the EPI has started an ATI request against the terminal resource and issued the corresponding CICS_EPI_EVENT_START_ATI event, but the application has not yet retrieved the event by issuing a CICS_EpiGetEvent call. Return codes CICS_EPI_ERR_ATI_ACTIVE An ATI transaction is active for this terminal resource. CICS_EPI_ERR_BAD_INDEX The TermIndex value is not a valid terminal index. CICS_EPI_ERR_FAILED The function failed for an unexpected reason. CICS_EPI_ERR_NO_DATA No initial data was supplied. CICS_EPI_ERR_NOT_INIT CICS_EpiInitialize has not been executed. CICS_EPI_ERR_TTI_ACTIVE A transaction started from the EPI is already active for this terminal resource. CICS_EPI_ERR_IN_CALLBACK The function was called from a callback routine. CICS_EPI_NORMAL The function completed successfully. ═══ 8.5.8. CICS_EpiReply ═══ CICS_EpiReply ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ CICS_EpiReply │ TermIndex │ │ │ Data │ │ │ Size │ └───────────────────────────────────────┴──────────────────────────────────────┘ Purpose The CICS_EpiReply function sends data from a terminal resource to a CICS transaction. It should only be issued in response to a CICS_EPI_EVENT_CONVERSE event. Parameters TermIndex The terminal index of the terminal resource from which the data is being sent. The EPI uses this parameter only for input. Data A pointer to the 3270 data stream to be sent to the transaction. This parameter must not be a null pointer, because the data stream must contain at least an AID byte. The data stream might be one byte (an AID byte), 3 bytes (an AID byte and a cursor address), or more than 3 bytes (an AID byte, a cursor address, and data and SBA commands). In the last case, what follows the cursor address is supplied to the transaction program on the first EXEC CICS RECEIVE command. The EPI uses this parameter only for input. Size The size of the data in bytes. The EPI uses this parameter only for input. Return codes CICS_EPI_ERR_BAD_INDEX The TermIndex value is not a valid terminal index. CICS_EPI_ERR_FAILED The function failed for an unexpected reason. CICS_EPI_ERR_NO_CONVERSE No reply is expected by the terminal resource. CICS_EPI_ERR_NO_DATA No reply data was supplied. CICS_EPI_ERR_NOT_INIT CICS_EpiInitialize has not been executed. CICS_EPI_ERR_IN_CALLBACK The function was called from a callback routine. CICS_EPI_NORMAL The function completed successfully. ═══ 8.5.9. CICS_EpiATIState ═══ CICS_EpiATIState ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ CICS_EpiATIState │ TermIndex │ │ │ ATIState │ └───────────────────────────────────────┴──────────────────────────────────────┘ Purpose The CICS_EpiATIState function allows the calling application to query and alter the way in which ATI requests for a terminal resource are handled. If ATI requests are enabled (CICS_EPI_ATI_ON) and an ATI request is issued in the server, the request is started when the terminal resource becomes free. If ATI requests are held (CICS_EPI_ATI_HOLD), any ATI requests issued are queued, and started when ATI requests are next enabled. The state for ATI requests after a CICS_EpiAddTerminal call is CICS_EPI_ATI_HOLD. The EPI application may change the state to CICS_EPI_ATI_ON when it is ready to allow ATI requests to be processed. (The server also maintains a ATI state for terminal resources, which is independent of the ATI state maintained in the EPI. Changes to the ATI state on the server do not affect the ATI status in the EPI.) Parameters TermIndex The terminal index of the terminal resource whose ATI state is required. The EPI uses this parameter only for input. ATIState The EPI uses this parameter for both input and output depending on the input value as follows: CICS_EPI_ATI_ON Enable ATI requests, and return the previous ATI state in this parameter. CICS_EPI_ATI_HOLD Hold ATI requests until they are next enabled, and return the previous ATI state in this parameter. CICS_EPI_ATI_QUERY Do not change the ATI state; just return the current state in this parameter. Return codes CICS_EPI_ERR_ATI_STATE An invalid ATIState value was provided. CICS_EPI_ERR_BAD_INDEX The TermIndex value is not a valid terminal index. CICS_EPI_ERR_FAILED The function failed for an unexpected reason. CICS_EPI_ERR_NOT_INIT CICS_EpiInitialize has not been executed. CICS_EPI_ERR_IN_CALLBACK The function was called from a callback routine. CICS_EPI_NORMAL The function completed successfully. ═══ 8.5.10. CICS_EpiSenseCode ═══ CICS_EpiSenseCode ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ CICS_EpiSenseCode │ TermIndex │ │ │ SenseCode │ └───────────────────────────────────────┴──────────────────────────────────────┘ Purpose In the CICS on Open Systems environment, the CICS_EpiSenseCode function allows the calling application to inform the EPI of any errors in the 3270 data sent by a transaction. In other environments, the function has no effect. Parameters TermIndex The terminal index of the terminal resource for which the error is to be raised. The EPI uses this parameter only for input. SenseCode The sense code failure reason, which can be one of the following values: CICS_EPI_SENSE_OPCHECK Errors were detected in the 3270 data stream. CICS_EPI_SENSE_REJECT Invalid 3270 commands were received. The EPI uses this parameter only for input. Return codes CICS_EPI_ERR_BAD_INDEX The TermIndex value is not a valid terminal index. CICS_EPI_ERR_FAILED The function failed for an unexpected reason. CICS_EPI_ERR_NOT_INIT CICS_EpiInitialize has not been executed. CICS_EPI_ERR_SENSE_CODE An invalid sense code was provided. CICS_EPI_ERR_IN_CALLBACK The function was called from a callback routine. CICS_EPI_NORMAL The function completed successfully. ═══ 8.5.11. CICS_EpiGetEvent ═══ CICS_EpiGetEvent ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ CICS_EpiGetEvent │ TermIndex │ │ │ Wait │ │ │ Event │ └───────────────────────────────────────┴──────────────────────────────────────┘ Purpose The CICS_EpiGetEvent function obtains information about an event that has occurred for a terminal resource. Remember that this call may be attempted only from the application, not from the callback routine. Microsoft Windows only In a Microsoft Windows environment, the application should call this function after receiving a message with wParam set to CICS_EPI_WIN_EVENT. See Microsoft Windows considerations for further details of the use of this function in a Microsoft Windows environment, including the format of Windows messages posted by the EPI. Parameters TermIndex The terminal index of the terminal resource for which to obtain an event. This can be set to the constant CICS_EPI_TERM_INDEX_NONE to indicate that the next event for any terminal resource used by this application is to be returned. The application can examine the TermIndex field in the returned CICS_EpiEventData_t structure to determine the terminal resource against which the event was generated. The EPI uses this parameter for both input and output. Wait An indication of what should happen if no event has been generated for the terminal resource. One of the following values should be used: CICS_EPI_WAIT Do not return until the next event occurs. (This value should not be used in the Microsoft Windows or DOS environments.) CICS_EPI_NOWAIT Return immediately with an error code. This option is used if the application elects to poll for events. The EPI uses this parameter only for input. Event A pointer to a CICS_EpiEventData_t structure that on return contains the details of the event that occurred. The Data field in the structure should be set to point to the data buffer that is updated with any terminal data stream associated with the event. The Size field should be set to indicate the maximum size of this buffer, and is updated to contain the actual length of data returned. Return codes CICS_EPI_ERR_BAD_INDEX The TermIndex value is not a valid terminal index. CICS_EPI_ERR_FAILED The function failed for an unexpected reason. CICS_EPI_ERR_MORE_DATA The supplied data buffer was not large enough to contain the terminal data; the data has been truncated. CICS_EPI_ERR_MORE_EVENTS An event was successfully obtained, but there are more events outstanding against this terminal resource. CICS_EPI_ERR_NO_EVENT No events are outstanding for this terminal resource. CICS_EPI_ERR_NOT_INIT CICS_EpiInitialize has not been executed. CICS_EPI_ERR_WAIT The Wait parameter is not valid. CICS_EPI_ERR_NULL_PARM Event is a null pointer. CICS_EPI_ERR_IN_CALLBACK The function was called from a callback routine. CICS_EPI_NORMAL The function completed successfully, and there are no more events. ═══ 8.5.12. CICS_EpiGetSysError ═══ CICS_EpiGetSysError ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ CICS_EpiGetSysError │ TermIndex │ │ │ SysErr │ └───────────────────────────────────────┴──────────────────────────────────────┘ Purpose The CICS_EpiGetSysError function obtains detailed information describing the last error that occurred when the CICS_EPI_ERR_FAILED return code was generated. The values returned in the Cause and Value fields in the supplied SysErr parameter can be used to further qualify the return code from any other EPI function. These values are environment-dependent. You might need to consult documentation for your client environment, and the documentation for the appropriate CICS server. The Msg field in the supplied SysErr parameter may return a message, specific to the operating environment, describing the error that occurred. If no message is available, this field is set to nulls. Parameters TermIndex The terminal index of the terminal resource for which to obtain the detailed error code. This parameter may be set to the constant CICS_EPI_TERM_INDEX_NONE, if further error information associated with a CICS_EpiInitialize, CICS_EpiTerminate, CICS_EpiListSystems, or CICS_EpiAddTerminal call is required. The EPI uses this parameter only for input. SysErr A pointer to a CICS_EpiSysError_t structure that on return contains the system error information. The EPI uses the structure only for output. Return codes CICS_EPI_ERR_NOT_INIT CICS_EpiInitialize has never been called. (If a CICS_EpiInitialize call is made and fails, CICS_EpiGetSysError will still succeed.) CICS_EPI_ERR_BAD_INDEX The TermIndex value is not a valid terminal index. CICS_EPI_ERR_FAILED The function failed for an unexpected reason. CICS_EPI_ERR_NULL_PARM SysErr is a null pointer. CICS_EPI_ERR_IN_CALLBACK The function was called from a callback routine. CICS_EPI_NORMAL The function completed successfully. ═══ 8.6. EPI events ═══ EPI events occur when CICS has data to pass to the EPI application. The application can handle EPI events in a variety of ways. (See Events and callbacks.) Whichever mechanism is used, the data from CICS is obtained by calling CICS_EpiGetEvent. ═══ 8.6.1. CICS_EPI_EVENT_SEND ═══ CICS_EPI_EVENT_SEND Purpose The CICS_EPI_EVENT_SEND event indicates that a transaction has sent some 3270 data to a terminal resource, typically as a result of an EXEC CICS SEND command. No reply is expected, and none should be attempted. (The reply might be data from the transaction, or it might be messages produced by the server, including error messages. You should consult your server documentation to see what messages are possible.) Fields completed Event The CICS_EPI_EVENT_SEND event code. Data A pointer to the buffer that is updated to contain the data sent by the transaction. See 3270 data streams for the EPI for details of the data stream format. Size The length of the data in the Data buffer. ═══ 8.6.2. CICS_EPI_EVENT_CONVERSE ═══ CICS_EPI_EVENT_CONVERSE Purpose The CICS_EPI_EVENT_CONVERSE event indicates that a transaction is expecting a reply as a result of either an EXEC CICS RECEIVE command, or an EXEC CICS CONVERSE command. The application should issue a CICS_EpiReply call to return the data to CICS, as follows: o If the transaction has issued an EXEC CICS RECEIVE command without specifying the BUFFER option, the buffer might contain data sent from the transaction, or it might be empty. If there is data to process, you should deal with it before replying. The reply should be sent when the data to be sent is available. o If the transaction has issued an EXEC CICS RECEIVE BUFFER command, the data buffer contains the 3270 Read Buffer command and the Size field is set to 1. The reply should be sent immediately. Fields completed Event The CICS_EPI_EVENT_CONVERSE event code. Data A pointer to the buffer that is updated to contain the data sent by the transaction, as defined above. Size The length of the data in the buffer. This may be set to zero to indicate that no data was sent, but a reply is still expected. ═══ 8.6.3. CICS_EPI_EVENT_END_TRAN ═══ CICS_EPI_EVENT_END_TRAN Purpose The CICS_EPI_EVENT_END_TRAN event indicates the end of a transaction that was running against a terminal resource. If the transaction abended, it indicates the abend code; if the transaction completed normally, the AbendCode field is set to spaces. If the transaction was pseudoconversational, the TransId field contains the name of the next transaction required. The application should start this transaction by issuing a CICS_EpiStartTran call. Fields completed Event The CICS_EPI_EVENT_END_TRAN event code. TransId The name of the next transaction to start, if the previous transaction was pseudoconversational. This name is 4 characters long and null-terminated. If there is no next transaction, the field is set to nulls. AbendCode The abend code, if the transaction abended. This code is 4 characters long and null-terminated. If the transaction completed normally, the field is set to spaces. ═══ 8.6.4. CICS_EPI_EVENT_START_ATI ═══ CICS_EPI_EVENT_START_ATI Purpose The CICS_EPI_EVENT_START_ATI event indicates that an ATI transaction has been started against the terminal resource. If the terminal resource receives an ATI request while it is running another transaction, the request is held until the transaction ends. The transaction is then started on behalf of the terminal resource, and the CICS_EPI_EVENT_START_ATI event is generated to inform the application. Fields completed Event The CICS_EPI_EVENT_START_ATI event code. TransId The name of the transaction that was started. This name is 4 characters long and null-terminated. ═══ 8.6.5. CICS_EPI_EVENT_END_TERM ═══ CICS_EPI_EVENT_END_TERM Purpose The CICS_EPI_EVENT_END_TERM event indicates that a terminal resource no longer exists. After this event, the terminal index that was previously used for the terminal resource is not valid. If the EPI detects that a CICS server has shut down, CICS_EPI_EVENT_END_TERM events are generated for all terminal resources that the application has installed in that server and not subsequently deleted. Fields completed Event The CICS_EPI_EVENT_END_TERM event code. EndReason An indication of why the terminal resource was deleted. It can be one of the following values: CICS_EPI_END_SIGNOFF The terminal resource was signed off. This can be as a result of running the CESF transaction or of calling the CICS_EpiDelTerminal function. CICS_EPI_END_SHUTDOWN The CICS server is shutting down. CICS_EPI_END_OUTSERVICE The terminal resource has been switched out of service. CICS_EPI_END_UNKNOWN An unexpected error has occurred. CICS_EPI_END_FAILED An attempt to delete a terminal resource failed. AbendCode A string specifying the abend code for the failure, if the EndReason field is set to CICS_EPI_END_FAILED. ═══ 8.6.6. CICS_EPI_EVENT_HELP ═══ CICS_EPI_EVENT_HELP Note This event is presented only in the CICS on Open Systems environment. Purpose The CICS_EPI_EVENT_HELP event indicates that a transaction has requested that help information be displayed. It provides a text string indicating the topic corresponding to the help request. The application may be able to invoke an operating system help facility to display the help information. Fields completed Event The CICS_EPI_EVENT_HELP event code. Data A pointer to the buffer that is updated to contain a null-terminated string describing the requested help topic. Size The length of the help topic string, excluding the terminating null. ═══ 8.7. 3270 data streams for the EPI ═══ The data streams implemented for the EPI follow those defined in the 3270 Data Stream Programmer's Reference. All data flows for the EPI are in ASCII format, and structured fields are not supported. Data flows are defined under the following topics in the 3270 Data Stream Programmer's Reference: o Introduction to the 3270 data stream (excluding structured fields) o 3270 data stream commands o Character sets, orders and attributes o Keyboard and printer operations. The use of 3270 data streams within the EPI, and some nonstandard orders and attributes, are defined here. Except in the CICS on Open Systems environment, the supplied C header file CICS3270.H, COBOL copybook CICS3270.CBL, and PL/I include file CICS3270.INC contain constants and conversion tables that you will find useful in handling 3270 data streams. (These files are not supplied in the CICS on Open Systems environment.) Note that if a CICS user transaction issues EXEC CICS SEND and EXEC CICS RECEIVE commands, CICS does not process the data (after the initial control bytes) that is passed between the EPI application and the CICS transaction. In this case, the data buffer may be used to pass user-specified data between the programs. Be aware that the contents of the data buffer may be code-page converted if the buffer is passed between CICS systems, in which case the data should be limited to ASCII and EBCDIC characters. If a CICS transaction issues EXEC CICS SEND MAP and EXEC CICS RECEIVE MAP commands, CICS converts the data from the BMS structure to a 3270 data stream. In this case, the application receives 3270 data from CICS and should return valid 3270 data to be converted for the transaction. ═══ 8.7.1. Inbound data streams (EPI to CICS) ═══ ┌──────────┬──────────┬───────────────────────────┐ │ AID │ Cursor │ Data buffer │ │ (1 byte) │ address │ (variable length) │ │ │ (2 bytes)│ │ └──────────┴──────────┴───────────────────────────┘ EPI applications send 3270 data to CICS on calls to the following functions: o CICS_EpiStartTran o CICS_EpiReply. The format in both cases is the same. The data stream must be a minimum of 3 non-null bytes, representing the AID and cursor address; the sole exception to this is if the AID represents the CLEAR key or a PA key, when the data stream may consist of the AID only. These fields are passed to the CICS transaction in the EIBAID and EIBCPOSN fields of the EIB. The contents of the data buffer consist of: o ASCII displayable characters with embedded 3270 control characters, when it is passed to an EXEC CICS RECEIVE MAP command. o User-specified data, when it is passed to an EXEC CICS RECEIVE command. On starting a transaction, the transaction ID is extracted from the start of the data buffer as follows: o If a set buffer address (SBA) order is present at the start of the data buffer, the transaction ID is extracted from the 4th through 7th bytes of the buffer. o If an SBA is not present at the start of the data buffer, the transaction ID is extracted from the 1st through 4th bytes of the buffer. In either case, the transaction ID may be shorter than 4 bytes, being delimited by either another SBA, an ASCII space, or the end of the string. The contents of the data buffer passed on the start of a CICS transaction are available to the transaction in response to an initial EXEC CICS RECEIVE command. When the application replies, the contents of the data buffer are available in an unconverted form in response to an EXEC CICS RECEIVE command or converted to a BMS structure in response to an EXEC CICS RECEIVE MAP command. Note: It is the EPI programmer's responsibility in the latter case to ensure that the data is formatted correctly so that the conversion succeeds. ═══ 8.7.2. Outbound data streams (CICS to EPI) ═══ ┌─────────┬───────────────┬───────────────────────┐ │ Command │ Write control │ Data buffer │ │ (1 byte)│ character │ (variable length) │ │ │ (1 byte) │ │ └─────────┴───────────────┴───────────────────────┘ The 3270 commands are either write or read commands, instructing the EPI to process the data or to reply with data respectively. On a CICS_EPI_EVENT_SEND event, the command is one of the following 3270 write commands: o Write o Erase/Write o Erase/Write Alternate o Erase All Unprotected. The first three commands are followed by a write control character (WCC) and data. An Erase All Unprotected command has neither WCC nor data. The Write Structured Field command is not generated by CICS and is therefore not supported for the EPI. The contents of the data buffer consist of: o ASCII displayable characters with embedded 3270 control characters, when it is passed from an EXEC CICS SEND MAP command. o User-specified data, when it is passed from an EXEC CICS SEND command. A CICS_EPI_EVENT_CONVERSE event specifies a read command. The contents of the data stream vary with the source of the event, as follows: o If the event is the result of an EXEC CICS RECEIVE command, the data buffer might contain data sent by the transaction, or it might be empty. The EPI program should reply when the data to be sent is available. o If the event is the result of an EXEC CICS RECEIVE BUFFER command, the data buffer contains the 3270 Read Buffer command. This should be processed as described in the 3270 Data Stream Programmer's Reference. The Read Modified and Read Modified All commands are not generated by CICS and are therefore not supported for the EPI. ═══ 8.7.3. 3270 order codes ═══ 3270 orders are included in both inbound and outbound data streams to provide additional control function. Order codes occurring in 3270 data streams lists the order codes that may occur in 3270 data streams, and shows whether they relate to inbound or outbound data streams, or both. ┌──────────────────────────────────────────────────────────────────────────────┐ │ Table 2. Order codes occurring in 3270 data streams │ ├───────────────────────────────────────────────┬───────────────┬──────────────┤ │ Order code │ Inbound │ Outbound │ ├───────────────────────────────────────────────┼───────────────┼──────────────┤ │ Start field (SF) │ Yes │ Yes │ ├───────────────────────────────────────────────┼───────────────┼──────────────┤ │ Start field extended (SFE) │ Yes │ Yes │ ├───────────────────────────────────────────────┼───────────────┼──────────────┤ │ Set buffer address (SBA) │ Yes │ Yes │ ├───────────────────────────────────────────────┼───────────────┼──────────────┤ │ Set attribute (SA) │ Yes │ Yes │ ├───────────────────────────────────────────────┼───────────────┼──────────────┤ │ Modify field (MF) │ No │ Yes │ ├───────────────────────────────────────────────┼───────────────┼──────────────┤ │ Insert cursor (IC) │ No │ Yes │ ├───────────────────────────────────────────────┼───────────────┼──────────────┤ │ Program tab (TB) │ No │ Yes │ ├───────────────────────────────────────────────┼───────────────┼──────────────┤ │ Repeat to address (RA) │ No │ Yes │ ├───────────────────────────────────────────────┼───────────────┼──────────────┤ │ Erase unprotected to address (EUA) │ No │ Yes │ ├───────────────────────────────────────────────┼───────────────┼──────────────┤ │ Graphic escape (GE) │ No │ No │ └───────────────────────────────────────────────┴───────────────┴──────────────┘ Note: The 3270 Data Stream Programmer's Reference states that the SFE, SA, and MF orders are not supported in ASCII. However, they do occur in 3270 data streams for the EPI, where they take the following values: SFE X'10' SA X'1F' MF X'1A' MF was formerly assigned the value X'1E'. However the Field Mark format control order is assigned the same value. Without the change to X'1A', an EPI application would be unable to distinguish between MF and FM. Each of these orders is followed by one or more attribute type-value pairs. The count of attribute pairs and the attribute type are both binary values, and are thus as defined in the 3270 Data Stream Programmer's Reference. However, the contents of the attribute value field may vary from those defined in the 3270 Data Stream Programmer's Reference as follows: o If the attribute type is less than or equal to X'C0' (for example, a color), the attribute value is defined as an EBCDIC value in the 3270 Data Stream Programmer's Reference. The EPI uses the ASCII equivalent of the EBCDIC value; for example, red is defined as X'F2' in the 3270 Data Stream Programmer's Reference, and should be defined as X'32' in the EPI data stream. o If the attribute type is greater than X'C0' (for example, field outlining), the attribute value is a binary value. The EPI uses the values defined in the 3270 Data Stream Programmer's Reference. Further details of 3270 orders and other control characters are supplied in the files named in the following table. ┌─────────────────────────┬──────────────────────────┬─────────────────────────┐ │ │ CICS for AIX Version 2.1 │ Other environments │ ├─────────────────────────┼──────────────────────────┼─────────────────────────┤ │ COBOL copybook │ N/A │ CICS3270.CBL │ ├─────────────────────────┼──────────────────────────┼─────────────────────────┤ │ C header file │ cics3270.h │ CICS3270.H │ ├─────────────────────────┼──────────────────────────┼─────────────────────────┤ │ PL/I include file │ N/A │ CICS3270.INC │ └─────────────────────────┴──────────────────────────┴─────────────────────────┘ In the CICS on Open Systems environment, 3270 support files are not available before CICS for AIX Version 2.1. ═══ 8.8. Microsoft Windows considerations ═══ Note The following information applies only to the IBM CICS Client for Windows. The CICS_EpiInitialize function has two additional parameters: hWnd The handle of the Microsoft Windows window to which EPI messages will be posted. MsgId The message identifier to be used for posting EPI messages to the window specified in the hWnd parameter. The EPI application is posted a Windows message (using the hWnd and MsgId values) in any of the following situations: o The CICS_EpiInitialize call has completed. o The CICS_EpiAddTerminal call has completed. o An incoming event for a terminal resource has been received. (CICS_EpiGetEvent should be called to receive the event data.) Values are assigned to the wParam and lParam parameters within these messages as follows. In the case of lParam, the LOWORD of this parameter is used. wParam CICS_EPI_WIN_INITIALIZED CICS_EpiInitialize complete CICS_EPI_WIN_INSTALLED CICS_EpiAddTerminal complete CICS_EPI_WIN_EVENT An incoming terminal event lParam X'0000' CICS_EpiInitialize has completed. Terminal index Index number of the terminal resource installed by a successful CICS_EpiAddTerminal, or of the terminal resource to which an incoming event belongs. X'FFFF' CICS_EpiAddTerminal has completed, but terminal resource installation failed. After receiving a message with wParam set to CICS_EPI_WIN_INITIALIZED, the application should call CICS_EpiGetSysError to check for any install errors. If lParam is set to X'FFFF', CICS_EpiGetSysError should be called with the TermIndex parameter set to CICS_EPI_TERM_INDEX_NONE. (A terminal index will not have been allocated if the terminal resource install failed.) If lParam is not set to X'FFFF', CICS_EpiGetSysError should be called with the TermIndex parameter set to the lParam value. Under Microsoft Windows, the EPI functions CICS_EpiInitialize and CICS_EpiAddTerminal are asynchronous (all other functions are synchronous). This means that the application should wait for a message to be posted before continuing after each of these two calls. ═══ 9. Creating ECI and EPI application programs ═══ This chapter contains language-dependent information about the external access interfaces, and is organized as follows: Writing the non-CICS applications Making ECI calls Making EPI calls Compiling and linking applications This chapter does not deal with testing or debugging ECI and EPI applications. You should refer to the programming manuals for the environment in which you are working. These are listed in the Related publications section of the preface of this book. ═══ 9.1. Writing the non-CICS applications ═══ ECI and EPI applications are standard stand-alone programs that can be run on any of the client systems, and can use the server implementations of the ECI and EPI on CICS for OS/2 and CICS for Windows NT servers. Programs that do not make operating-system-specific calls are portable between these environments. The sample programs and associated build files for your environment illustrate much of what is discussed here. An application program may use the facilities of both ECI and EPI. Applications may be written in C (or C++), COBOL, or PL/I, though not all these languages are available in every environment. The following table shows for each programming environment o the names of the C header file, COBOL copybook, or PL/I include file for the ECI o the names of the C header file, COBOL copybook, or PL/I include file for the EPI o the names of the type definition files for either interface for C and PL/I programs. (Type definition files are not used with COBOL.) The entry N/A in the table indicates that the combination of language and interface are not supported. ┌─────────────────────────┬──────────────────────────┬─────────────────────────┐ │ Use │ CICS on Open Systems │ Other environments │ ├─────────────────────────┼──────────────────────────┼─────────────────────────┤ │ ECI: C programs │ cics_eci.h │ CICS_ECI.H │ ├─────────────────────────┼──────────────────────────┼─────────────────────────┤ │ ECI: COBOL programs │ CICS-ECI │ CICSECI.CBL │ ├─────────────────────────┼──────────────────────────┼─────────────────────────┤ │ ECI: PL/I programs │ cics_eci.inc (AIX only) │ CICS_ECI.INC │ ├─────────────────────────┼──────────────────────────┼─────────────────────────┤ │ EPI: C programs │ cics_epi.h │ CICS_EPI.H │ ├─────────────────────────┼──────────────────────────┼─────────────────────────┤ │ EPI: COBOL programs │ N/A │ CICSEPI.CBL │ ├─────────────────────────┼──────────────────────────┼─────────────────────────┤ │ EPI: PL/I programs │ N/A │ CICS_EPI.INC │ ├─────────────────────────┼──────────────────────────┼─────────────────────────┤ │ Type definitions: C │ cicstype.h │ CICSTYPE.H │ │ programs │ │ │ ├─────────────────────────┼──────────────────────────┼─────────────────────────┤ │ Type definitions: PL/I │ cicstype.inc │ CICSTYPE.INC │ │ programs │ │ │ └─────────────────────────┴──────────────────────────┴─────────────────────────┘ You should study the contents of the file appropriate to the language you intend to use. Each file contains the definitions of all the entry points, types, data structures, and constants needed for writing programs for the corresponding interface. The naming conventions for the structures, fields, and constants of the interfaces in the different languages are as follows: o PL/I and C-the names are the same as the names used earlier in this book to describe the interfaces. o COBOL-the names are upper-case versions of the names used earlier in this book to describe the interfaces with hyphens instead of underscores. There are a few exceptions to this convention, and these are noted where they occur. When compiling C programs, you may need to ensure that the structures passed to the CICS external facilities are packed. If this is necessary, the C header files will contain the #pragma pack directive, which should not be changed. ═══ 9.2. Making ECI calls ═══ ECI functions are called in the manner described below. COBOL applications must ensure that the ECI function calls are statically linked at link time by using the system linkage convention. o For IBM VisualAge for COBOL for OS/2, you should use the default CALLINTERFACE(System) linkage. o For Micro Focus Object COBOL, you should use call-convention 8 for every program call, or use the default call-convention 0 and compile using the LITLINK compiler directive. ═══ 9.2.1. CICS_ExternalCall ═══ The method of calling CICS_ExternalCall is shown here for COBOL, C, and for PL/I. The ECI parameter block (ECI-PARMS for COBOL, ECI_PARMS for C, and ECI_PARMS for PL/I) is used for passing parameters to the ECI. The format of the call and associated declarations is as follows: ═══ 9.2.1.1. For C programs: ═══ ECI_PARMS EciBlock; cics_ushort_t Response; . . . Response = CICS_ExternalCall(&EciBlock); ═══ 9.2.1.2. For COBOL programs: ═══ CALL 'CICSEXTERNALCALL' USING BY REFERENCE ECI-PARMS RETURNING ECI-RETURN-CODE. The name '_CICS_ExternalCall' may also be used with the Micro Focus Object COBOL compiler, but it is not recommended. ═══ 9.2.1.3. For PL/I programs: ═══ dcl Response fixed bin(15); dcl EciBlock type ECI_PARMS; . . . Response = CICS_ExternalCall(EciBlock); ═══ 9.2.1.4. For REXX programs: ═══ Before using CICS_ExternalCall, the REXX program must add the function for CICS_ExternalCall to its environment as follows: Call RxFuncAdd 'CICS_ExternalCall', 'cclrxeci', 'RxCICS_ExternalCall' Once the function has been added, the program may use it any number of times. The format of the call is as follows: retcode = CICS_ExternalCall('ECI_PARMS.') where ECI_PARMS is the name chosen for the REXX stem representing the ECI parameter block. Do not omit the period at the end of the name, or the single quotation marks surrounding it. The values for eci_call_type, eci_extend_mode, and eci_version in the ECI parameter block, and for ConnectionType, CicsServerStatus, and CicsClientStatus in the ECI status block are character literals that match the names used earlier in this book. The following sample assignment statement shows how, having chosen ECI_PARMS as the stem name, the eci_call_type field in the ECI parameter block is set to ECI_SYNC. ECI_PARMS.eci_call_type = 'ECI_SYNC' The return code values ECI_NO_ERROR, and so on, are defined in the file RXECI.MSG supplied with the samples. ═══ 9.2.2. Callback routines ═══ Each callback routine has only one parameter. You should consult the sample programs for examples of writing callback routines. ═══ 9.2.3. CICS_EciListSystems ═══ The format of the call in the different programming languages is as follows: ═══ 9.2.3.1. For C programs: ═══ #define MAX_SYS 5 cics_sshort_t Response; cics_ushort_t Count; CICS_EciSystem_t List[MAX_SYS]; . Count = MAX_SYS; . Response = CICS_EciListSystems(NULL, &Count, List); ═══ 9.2.3.2. For COBOL programs: ═══ The COBOL name of the system information structure is CICS-ECISYSTEM, which is contrary to the naming convention stated earlier. In the CICS on Open Systems environment, the array of CICS-ECISYSTEM structures is made part of CICS-ECISYSARRAY to comply with the requirements of the ANSI standard for COBOL. However the array can still be referred to using the name CICS-ECISYSTEM, as shown in the example below. 01 LIST-SIZE PIC 9(4) COMP-5. CALL 'CICSECILISTSYSTEMS' USING BY REFERENCE NULL-PTR BY REFERENCE LIST-SIZE BY REFERENCE CICS-ECISYSTEM RETURNING ECI-RETURN-CODE. The name '_CICS_EciListSystems' may also be used with the Micro Focus Object COBOL compiler, but it is not recommended. ═══ 9.2.3.3. For PL/I programs: ═══ dcl EciRetCode fixed bin(15); dcl count fixed bin(15); dcl list type CICS_EciSystem_t; . . . EciRetCode = CICS_EciListSystems(null(), count, list); ═══ 9.2.3.4. For REXX programs: ═══ Before using CICS_EciListSystems, the REXX program must add the function for CICS_EciListSystems to its environment as follows: Call RxFuncAdd 'CICS_EciListSystems', 'cclrxeci', 'RxCICS_EciListSystems' Once the function has been added, the program may use it any number of times. The format of the call is as follows: retcode = CICS_EciListSystems(, 'count', 'LIST.') No parameter need be supplied for NameSpace, count is the name of the REXX variable chosen for Systems, and LIST is the name chosen for the REXX stem representing List. Do not omit the period at the end of the name, or the single quotation marks surrounding it. On return from the call, the names LIST.1.SystemName, and LIST.1.Description, are used to refer to the fields in the first array element, and so on. ═══ 9.2.4. Debugging with REXX ═══ Special debugging facilities are provided for ECI applications using REXX. Setting the REXX variable DEBUG to any non-zero value will cause debug information to be sent to a log file. The path name of the file can be specified in the REXX variable DEBUGFILE, and the default is the file CCLRXECI.LOG in the directory where CCLRXECI.DLL is executing. If the file exists already, debug information is appended to it. ═══ 9.3. Making EPI calls ═══ ═══ 9.3.1. EPI functions ═══ EPI functions are called in a standard manner. Examples of calling the CICS_EpiListSystems function follow. COBOL applications must ensure that the EPI function calls are statically linked at link time by using the system linkage convention. o For IBM VisualAge for COBOL for OS/2, you should use the default CALLINTERFACE(System) linkage. o For Micro Focus Object COBOL, you should use call-convention 8 for every program call, or use the default call-convention 0 and compile using the LITLINK compiler directive. ═══ 9.3.1.1. For C programs: ═══ #define MAX_SYS 5 CICS_EpiSystem_t System; cics_ushort-t Count; cics_sshort_t Response; . Count = MAX_SYS; . Response = CICS_EpiListSystems(NULL, &Count, &System); ═══ 9.3.1.2. For COBOL programs: ═══ Except in the CICS on Open Systems environment, in which EPI calls from COBOL are not supported, the following may be used: 01 COUNT PIC 9(4) COMP-5. 01 NAMESPACE POINTER. . . . CALL 'CICSEPILISTSYSTEMS' USING BY VALUE NAMESPACE BY REFERENCE COUNT BY REFERENCE CICS-EPISYSTEM RETURNING EPI-RETURN-CODE. ═══ 9.3.1.3. For PL/I programs: ═══ Except in the CICS on Open Systems environment, in which EPI calls from PL/I are not supported, the following may be used: dcl System type CICS_EpiSystem_t, Count fixed bin(15), Response fixed bin(15); . . . Response = CICS_EpiListSystems(null(), Count, System); ═══ 9.3.1.4. For REXX programs: ═══ EPI functions are not available in REXX. ═══ 9.3.2. Callback routines ═══ Each callback routine has only one parameter. You should consult the sample programs for examples of writing callback routines. ═══ 9.4. Compiling and linking applications ═══ This section gives some examples showing how to compile and link typical ECI and EPI applications in the various client environments. These are examples only, and may refer to specific compilers and linkers. You should refer to the samples supplied with your environment for more information about compiling and linking programs. ═══ 9.4.1. IBM CICS Client for DOS ═══ For examples of programs that call the ECI and EPI, refer to the samples supplied with the client in the following libraries: o \CICSCLI\SAMPLES\C o \CICSCLI\SAMPLES\COBOL ═══ 9.4.1.1. For C programs: ═══ cl /c /DCICS_DOS program.c link program.obj,,,ccldos.lib; Notes: o Example compiler used is Microsoft C Optimizing Compiler Version 6.00A. o The constant CICS_DOS must be defined to the compiler using the /DCICS_DOS option. o Programs may use any of the standard memory models. o The application must be linked with the CCLDOS.LIB library in addition to the standard C runtime libraries. o Callback functions are not supported in DOS. ═══ 9.4.1.2. For COBOL programs: ═══ cobol program,,,, link program.obj,,,lcobol.lib+cobapi.lib+ccldos.lib; Notes: o Example compiler used is Micro Focus COBOL Version 3.0. o Programs should use the LARGE memory model. o ECI and EPI function calls should be linked using call-convention 8. o The application must be linked with the CCLDOS.LIB library and must use the COBOL static link libraries. o Callback functions are not supported in DOS or COBOL. ═══ 9.4.2. IBM CICS Client for Windows ═══ For examples of programs that call the ECI and EPI, refer to the samples supplied with the client in the following library: o \CICSCLI\SAMPLES\C ═══ 9.4.2.1. For C programs: ═══ cl /c /Gsw /DCICS_WIN program.c link program.obj,,,cclwin.lib,program.def Notes: o Example compiler used is Microsoft C/C++ Optimizing Compiler Version 7.00. o The constant CICS_WIN must be defined to the compiler using the /DCICS_WIN option. o The /Gsw options are recommended for compiling Windows programs. o Programs may use any of the standard memory models. o The application must be linked with the CCLWIN.LIB library in addition to the standard C runtime and Windows libraries. o A STACKSIZE of at least 8K is recommended in the linker .DEF file. o Callback functions must be declared using the CICSEXIT calling convention and must be created using the Windows function MakeProcInstance()-see samples for details. o The Windows resource compiler will also be required to create a functional Windows program, as normal. ═══ 9.4.3. IBM CICS Client for OS/2 ═══ For examples of programs that call the ECI and EPI, refer to the samples supplied with the client in the following libraries: o \CICSCLI\SAMPLES\C o \CICSCLI\SAMPLES\COBOL o \CICSCLI\SAMPLES\PLI ═══ 9.4.3.1. For 32-bit C programs: ═══ icc /C /Gt+ /DCICS_OS2 program.c link386 program.obj,,,cclos232.lib,program.def Notes: o Example compiler used is IBM C/Set++. o The constant CICS_OS2 must be defined to the compiler using the /DCICS_OS2 option. o The /Gt+ options is recommended to ensure any data items passed to the ECI or EPI do not span a 64K boundary. o The application must be linked with the CCLOS232.LIB library (since it is a 32-bit application) in addition to the standard C runtime and OS/2 libraries. o A STACKSIZE of at least 16K is recommended in the linker .DEF file. o Callback functions must be declared using the CICSEXIT calling convention-see samples for details. ═══ 9.4.3.2. For 16-bit C programs: ═══ cl /c /Gs /DCICS_OS2 program.c link program.obj,,,cclos2.lib,program.def Notes: o Example compiler used is Microsoft C Optimizing Compiler Version 6.00A. o The constant CICS_OS2 must be defined to the compiler using the /DCICS_OS2 option. o The /Gs option is recommended if callback functions are to be used. o The application must be linked with the CCLOS2.LIB library (since it is a 16-bit application) in addition to the standard C runtime and OS/2 libraries. o A STACKSIZE of at least 16K is recommended in the linker .DEF file. o Callback functions must be declared using the CICSEXIT calling convention-see samples for details. ═══ 9.4.3.3. For 32-bit COBOL programs: ═══ If you are using IBM VisualAge for COBOL for OS/2: cob2 -c -qapost -qnosequence -qlib. prog.cbl ilink /NOFREE /NOD /NOI /MAP prog.obj,,,OS2386 iwzrlib cclos232,prog.def If you are using Micro Focus Object COBOL: cobol prog.cbl; cblnames -mPROG -oPROG.CBJ prog link386 /NOD /NOI prog.obj prog.cbj,,,OS2386 mfrts32 cclos232,prog.def Notes: o You must resolve ECI and EPI function calls at link time using the system linkage convention. This is the default linkage for IBM VisualAge for COBOL for OS/2. If you use Micro Focus Object COBOL, you must use call-convention 8 on all ECI and EPI functions, or use the default call-convention 0 and compile using the LITLINK compiler directive. ═══ 9.4.3.4. For 16-bit COBOL programs: ═══ cobol program,,,, link program.obj,,,coblib.lib+cclos2.lib,program.def Notes: o Example compiler used is Micro Focus COBOL Version 3.0. o Programs should use the LARGE memory model. o Programs must be compiled with the LITLINK compiler directive. o The application must be linked with the CCLOS2.LIB library (since it is a 16-bit application) and may use either the COBOL static or dynamic link libraries. o A STACKSIZE of at least 16K is recommended in the linker .DEF file. o Callback functions are not supported in COBOL. ═══ 9.4.3.5. For PL/I programs: ═══ pli program link386 program.obj,,,cclos232.lib,program.def Notes: o Example compiler used is IBM PL/I for OS/2 Version 1 Release 1. o The application must be linked with the CCLOS232.LIB library (since it is a 32-bit application) in addition to the standard PL/I runtime and OS/2 libraries. o A STACKSIZE of at least 16K is recommended in the linker .DEF file. o Callback functions must be declared using the CICSEXIT calling convention-see samples for details. ═══ 9.4.4. IBM CICS Client for Macintosh ═══ For examples of programs that call the ECI and EPI, refer to the samples supplied with the client in the following library: o :CICSCLI:SAMPLES:C ═══ 9.4.4.1. For C programs: ═══ C program.c -o program.c.o -model far -i 'HD:cicscli:headers:' -d CICS_MAC Link -o program program.c.o 'HD:cicscli:lib:'cclmac.cl.o "HD:MPW:Libraries:Libraries:"Runtime.o "HD:MPW:Libraries:Libraries:"Interface.o "HD:MPW:Libraries:CLibraries:"StdCLib.o "HD:MPW:Libraries:Libraries:"LibraryManager.o -model far SetFile program -t APPL -c 'CIC1' -a B Notes: o Example compiler used is MPW C Version 3.3. o The constant CICS_MAC must be defined to the compiler using the -d CICS_MAC option. o The program must be linked with LibraryManager.o for access to the shared library. o The creator types used in the samples on the `SetFile' line (CIC1 and CIC2) match the resource file provided. The CICS Client for Macintosh product has registered with Apple the creator types CICS, CICE, CICP, and CICX for use within this product. You must not use these names for your own programs. o Callback functions must be declared using the CICSEXIT calling convention-see samples for details. ═══ 9.4.5. CICS for OS/2 Version 2.0.1 server implementation ═══ For examples of programs that call the ECI and EPI, refer to the samples supplied with the CICS product. CICS for OS/2 V2.0.1 provides C, COBOL, and PL/I source and makefile samples in the following directories: o \CICS200\SAMPLES\C\SOURCE o \CICS200\SAMPLES\COBOL\SOURCE o \CICS200\SAMPLES\PLI\SOURCE ═══ 9.4.5.1. For 32-bit C programs: ═══ icc /Gt+ prog.c faacic32.lib Notes: o ECI applications are created as shown above. o To create EPI applications you should use FAACLIB.LIB instead of FAACIC32.LIB. ═══ 9.4.5.2. For 16-bit C programs: ═══ cl prog.c /Gs /link /stack:16384 faaclib ═══ 9.4.5.3. For COBOL programs: ═══ cobol prog.cbl /CASE link /NOD prog,,,coblib+faaclib ═══ 9.4.5.4. For PL/I programs: ═══ pli prog.pli ( tiled link386 /NOD / NOI prog,,,faacic32 ibmlink ceelink os2386 Notes: o ECI applications are created as shown above. o To create EPI applications you should use FAACLIB.LIB instead of FAACIC32.LIB. ═══ 9.4.6. CICS for OS/2 Version 3 server implementation ═══ For examples of programs that call the ECI and EPI, refer to the samples supplied with the CICS product. CICS for OS/2 V3.0 provides C, COBOL, and PL/I source and makefile samples in the following directories: o \CICS300\TOOLS\C\SAMPLES\SOURCE o \CICS300\TOOLS\COBOL\SAMPLES\SOURCE o \CICS300\TOOLS\PLI\SAMPLES\SOURCE ═══ 9.4.6.1. For 32-bit C programs: ═══ icc /Gt+ prog.c faacic32.lib ═══ 9.4.6.2. For 16-bit C programs: ═══ cl prog.c /Gs /link /stack:16384 faaclib ═══ 9.4.6.3. For COBOL programs: ═══ If you are using IBM VisualAge for COBOL for OS/2: cob2 -c -qapost -qnosequence -qlib. prog.cbl ilink /NOFREE /NOD /NOI /MAP prog.obj,,,OS2386 iwzrlib cclos232,prog.def If you are using Micro Focus Object COBOL: cobol prog.cbl; cblnames -mPROG -oPROG.CBJ prog link386 /NOD /NOI prog.obj prog.cbj,,,OS2386 mfrts32 cclos232,prog.def Note: o You must resolve ECI and EPI function calls at link time using the system linkage convention. This is the default linkage for IBM VisualAge for COBOL for OS/2. If you use Micro Focus Object COBOL, you must use call-convention 8 on all ECI and EPI functions, or use the default call-convention 0 and compile using the LITLINK compiler directive. ═══ 9.4.6.4. For PL/I programs: ═══ pli prog.pli ( tiled link386 /NOD / NOI prog,,,faacic32 ibmlink ceelink os2386 ═══ 9.4.7. CICS for Windows NT server implementation ═══ For examples of programs that call the ECI and EPI, refer to the samples supplied with the CICS product. CICS for Windows NT V2.0 provides C and COBOL source and makefile samples in the following directories: o \CNT200\SAMPLES\C\SOURCE o \CNT200\SAMPLES\COBOL\SOURCE ═══ 9.4.7.1. For C programs: ═══ cl prog.c faacicnt.lib ═══ 9.4.7.2. For COBOL programs: ═══ cobol prog.cbl; cblnames -mPROG -oPRG.CBJ PROG.OBJ link prog.obj prog.cbj faacicnt.lib mfrts32.lib Note: o ECI and EPI function calls should be resolved at link time using the system linkage convention. All ECI and EPI function calls should be made using call-convention 8. If the default call-convention 0 is used, then the COBOL application should be compiled using the LITLINK compiler directive. ═══ 9.4.8. CICS on Open Systems Clients ═══ For examples of programs that call the EPI, refer to the samples supplied with the CICS product. Source code and makefiles are located in the following directories: o IBM AIX client-/usr/lpp/cics/src/samples/epi o Other clients-/opt/cics/src/samples/epi To build the sample programs and transactions: make all To build the client side only programs: make client To install the transactions: make install To remove the built applications and transactions: make clean Notes: o The region name DEFAULT should be replaced with the target region in the makefile. o Refer to the program description in the leading comment block in the sample programs for details of operation. o When compiling ECI and EPI application programs with Micro Focus COBOL, you are recommended to use the NLS complier directive, so that the locale of the server is taken from the LANG environment variable. ═══ 10. ECI extensions that are environment-dependent ═══ This chapter describes extensions to the ECI that are supported in certain environments. They are not part of CICS Family Client/Server Programming. The chapter is organized as follows: Call type extensions Time-outs Fields to support ECI extensions Reply message formats ECI return notification Summary of input parameter requirements. ═══ 10.1. Call type extensions ═══ The following call types are for asynchronous calls. For more information about the program link calls, study CICS_ExternalCall return codes - environment-dependent extensions in conjunction with ECI_ASYNC. For more information about the status information calls, study CICS_ExternalCall return codes - environment-dependent extensions in conjunction with ECI_STATE_ASYNC. ═══ 10.1.1. Asynchronous program link call, with notification by message (ECI_ASYNC_NOTIFY_MSG) ═══ This call type is available only for programs running under OS/2 Presentation Manager, Microsoft Windows, or Windows NT. The calling application gets control back when the ECI accepts the request. Note that this does not indicate that the program has started to run, merely that the parameters have been validated. The request might be queued for later processing. The ECI sends a notification message to the specified window when the response is available. (For details of the message format, see Reply message formats.) On receipt of this notification, the calling application should use ECI_GET_REPLY or ECI_GET_SPECIFIC_REPLY to receive the actual response. The following fields are required parameters for notification by message: o Either eci_async_notify.window_handle (for OS/2 Presentation Manager or Windows NT environment) or eci_async_notify.win_fields.hwnd (for Microsoft Windows environment) identifies the window to be notified. o eci_async_notify.win_fields.hinstance (for Microsoft Windows environment) indicates the hInstance of the calling program. o eci_message_id indicates the message type to be used in the notification process. eci_message_qualifier can be used as an input to provide a user-defined name for the call. It is returned as part of the notification message for the OS/2 Presentation Manager and Windows NT environments. ═══ 10.1.2. Asynchronous program link call, with notification by semaphore (ECI_ASYNC_NOTIFY_SEM) ═══ This call type is available only for programs running under OS/2 or Windows NT. The calling application gets control back when the ECI accepts the request. Note that this does not indicate that the program has started to run, merely that the parameters have been validated. The request might be queued for later processing. The ECI posts the specified semaphore when the response is available. On receipt of this notification, the calling application should use ECI_GET_REPLY or ECI_GET_SPECIFIC_REPLY to receive the actual response. eci_message_qualifier can be used as an input to provide a user-defined name for the call. The following field is a required parameter for notification by semaphore: o eci_async_notify.sem_handle refers to the semaphore. ═══ 10.1.3. Asynchronous status call, with notification by message (ECI_STATE_ASYNC_MSG) ═══ This call type is available only for programs running under OS/2 Presentation Manager, Microsoft Windows, or Windows NT. eci_message_qualifier can be used as an input to provide a user-defined name for the call. The ECI sends a notification message to the specified window when the response is available. (For details of the message format, see Reply message formats.) On receipt of this notification, the calling application should use ECI_GET_REPLY or ECI_GET_SPECIFIC_REPLY to receive the actual response. For details of the additional parameters relating to notification by message, see the description of the ECI_ASYNC_NOTIFY_MSG call type. ═══ 10.1.4. Asynchronous status call, with notification by semaphore (ECI_STATE_ASYNC_SEM) ═══ This call type is available only for programs running under OS/2 or Windows NT. eci_message_qualifier can be used as an input to provide a user-defined name for the call. The ECI posts the specified semaphore when the response is available. On receipt of this notification, the calling application should use ECI_GET_REPLY or ECI_GET_SPECIFIC_REPLY to receive the actual response. The following field is a required parameter for notification by semaphore: o eci_async_notify.sem_handle refers to the semaphore. ═══ 10.2. Time-outs ═══ Time-out support is provided in the ECI for the migration of programs from CICS/OS2 local clients, and the use of time-out facilities is not recommended in other environments. It could be used in a single-threaded environment, such as DOS, to terminate very long synchronous calls, but the results are sometimes unpredictable, as explained below. The support consists of a field eci_timeout in the ECI parameter block, and two return codes: ECI_ERR_RESPONSE_TIMEOUT and ECI_ERR_REQUEST_TIMEOUT. In the processing of timeouts, there are two cases to consider. o The time-out occurs before the request has been forwarded to the server. In this case the response is ECI_ERR_REQUEST_TIMEOUT. The requested program was not called, and no server resources have been updated. If the call was intended to start, or be the whole of, a new logical unit of work, the logical unit of work was not started, and no recoverable resources have been updated. If the call was intended to continue an existing logical unit of work, the logical unit of work was continued, but no recoverable resources were updated, and the logical unit of work is still uncommitted. If the call was intended to end an existing logical unit of work, the logical unit of work was continued, no recoverable resources were updated, and the logical unit of work is still uncommitted. o The time-out occurs after the request has been forwarded to the server. In this case the response is ECI_ERR_RESPONSE_TIMEOUT, and it could be returned to a synchronous call, or to an asynchronous call, or to the reply solicitation request that gets the reply to an asynchronous call. - If the call was intended to be the only call of a new logical unit of work, the logical unit of work was started, but it is not possible for the application to determine whether updates were performed, and whether they were committed or backed out. - If the call was intended to end an existing logical unit of work by using ECI_NO_EXTEND, the logical unit of work has ended, but it is not possible for the application to determine whether updates were performed, and whether they were committed or backed out. - If the call was intended to continue or to end an existing logical unit of work by using ECI_COMMIT, the logical unit of work persists, and changes to recoverable resources are still pending. ═══ 10.3. Fields to support ECI extensions ═══ The following fields in the ECI parameter block are to support environment-dependent extensions. eci_async_notify.window_handle (OS/2 and Windows NT environments, ECI_ASYNC_NOTIFY_MSG and ECI_STATE_ASYNC_MSG call types) The handle of the window to which the reply message will be posted. The ECI uses this field as input only. Note: eci_window_handle is a synonym for this parameter. eci_async_notify.sem_handle (OS/2 and Windows NT environments, ECI_ASYNC_NOTIFY_SEM and ECI_STATE_ASYNC_SEM call types) A reference to an OS/2 semaphore. This semaphore is cleared when the asynchronous response is ready for collection. o 16-bit OS/2 applications should pass either a system semaphore handle or the address of a RAM semaphore. o 32-bit OS/2 applications should pass an event semaphore handle. o Windows NT applications should pass an event object handle. The ECI uses this field as input only. eci_async_notify.win_fields.hwnd (Microsoft Windows environment, ECI_ASYNC_NOTIFY_MSG and ECI_STATE_ASYNC_MSG call types) The handle of the Microsoft Windows window to which the reply message will be posted. The ECI uses this field as input only. eci_async_notify.win_fields.hinstance (Microsoft Windows environment, ECI_ASYNC_NOTIFY_MSG and ECI_STATE_ASYNC_MSG call types) The Microsoft Windows hInstance of the calling program as supplied during program initialization. The ECI uses this field as input only. eci_message_id (OS/2 Presentation Manager, Microsoft Windows, and Windows NT environments, ECI_ASYNC_NOTIFY_MSG and ECI_STATE_ASYNC_MSG call types) The message identifier to be used for posting the reply message to the window specified in the relevant window handle. The ECI uses this field as input only. eci_timeout (Program link calls and status calls only) An integer field specifying the maximum time in seconds that a request from the application is allowed to take. A timeout occurs if the servicing of a request takes longer than the specified time. The value must be in the range 0 through 32767. A value of zero means that the application sets no limit on the time to service a request. The ECI uses this field as input only. eci_extend_mode There is an additional value for program link calls in CICS OS/2 Version 1.20- ECI_CANCEL. It has the same effect as ECI_COMMIT. ═══ 10.4. Reply message formats ═══ When an application makes an asynchronous call requesting notification by message, the ECI returns the result in a message to a window using the specified window handle and message identifier. For OS/2 Presentation Manager, the message is divided into two parameters, as follows: break all. MPARAM1 High-order 16 bits Specified message qualifier Low-order 16 bits Return code MPARAM2 4-character abend code, if applicable For Microsoft Windows, the message is divided into two parameters, as follows: wParam Return code lParam 4-character abend code, if applicable For Windows NT, the message is divided into two parameters, as follows: break all. wParam High-order 16 bits Specified message qualifier Low-order 16 bits Return code lParam 4-character abend code, if applicable ═══ 10.5. ECI return notification ═══ ┌──────────────────────────────────────────────────────────────────────────────┐ │ Table 3. CICS_ExternalCall return codes - environment-dependent extensions │ ├───────────────────────────────────────┬──────────────────────────────────────┤ │ Return code │ Meaning │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ ECI_ERR_NULL_WIN_HANDLE │ An asynchronous call was specified │ │ │ with the window handle set to 0. │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ ECI_ERR_NULL_MESSAGE_ID │ An asynchronous call was specified │ │ │ with the message identifier set to │ │ │ 0. │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ ECI_ERR_NULL_SEM_HANDLE │ A null semaphore handle was passed │ │ │ when a valid handle was required. │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ ECI_ERR_REQUEST_TIMEOUT │ The time-out interval expired before │ │ │ the request could be processed, or │ │ │ the specified interval was negative. │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │ ECI_ERR_RESPONSE_TIMEOUT │ The time-out interval expired while │ │ │ the program was running. │ └───────────────────────────────────────┴──────────────────────────────────────┘ ═══ 10.6. Summary of input parameter requirements ═══ Input parameters for CICS_ExternalCall - environment-dependent extensions shows the input parameters for an ECI call, and, for each call type, whether the parameters are required (`R'), optional (`O'), or not applicable (`-'). Where a parameter is shown as optional or not-applicable an initial field setting of nulls is recommended. An asterisk (*) immediately following an `R' means that further details regarding applicability are given under the description of the parameter. The following abbreviations are used in the Parameter column: AN async_notify WF win_fields Also, all named parameters have an eci_ prefix. Thus AN.WF.hwnd represents the eci_async_notify.win_fields.hwnd parameter. The following 3-character abbreviations are used for the call types in the column headings of the table: ANM ECI_ASYNC_NOTIFY_MSG ANE ECI_ASYNC_NOTIFY_SEM SAM ECI_STATE_ASYNC_MSG SAE ECI_STATE_ASYNC_SEM ┌──────────────────────────────────────────────────────────────────────────────┐ │ Table 4. Input parameters for CICS_ExternalCall - environment-dependent │ │ extensions │ ├─────────────────────────┬─────────────┬────────────┬────────────┬────────────┤ │ Parameter, eci_ │ ANM │ ANE │ SAM │ SAE │ ├─────────────────────────┼─────────────┼────────────┼────────────┼────────────┤ │ call_type │ R │ R │ R │ R │ ├─────────────────────────┼─────────────┼────────────┼────────────┼────────────┤ │ program_name │ R* │ R* │ - │ - │ ├─────────────────────────┼─────────────┼────────────┼────────────┼────────────┤ │ userid │ R │ R │ - │ - │ ├─────────────────────────┼─────────────┼────────────┼────────────┼────────────┤ │ password │ R │ R │ - │ - │ ├─────────────────────────┼─────────────┼────────────┼────────────┼────────────┤ │ transid │ O │ O │ - │ - │ ├─────────────────────────┼─────────────┼────────────┼────────────┼────────────┤ │ commarea │ O │ O │ R* │ R* │ ├─────────────────────────┼─────────────┼────────────┼────────────┼────────────┤ │ commarea_length │ O │ O │ R* │ R* │ ├─────────────────────────┼─────────────┼────────────┼────────────┼────────────┤ │ timeout │ O │ O │ O │ O │ ├─────────────────────────┼─────────────┼────────────┼────────────┼────────────┤ │ extend_mode │ R │ R │ R │ R │ ├─────────────────────────┼─────────────┼────────────┼────────────┼────────────┤ │ AN.window_handle │ R* │ - │ R* │ - │ ├─────────────────────────┼─────────────┼────────────┼────────────┼────────────┤ │ AN.sem_handle │ - │ R │ - │ R │ ├─────────────────────────┼─────────────┼────────────┼────────────┼────────────┤ │ AN.WF.hwnd │ R* │ - │ R* │ - │ ├─────────────────────────┼─────────────┼────────────┼────────────┼────────────┤ │ AN.WF.hinstance │ R* │ - │ R* │ - │ ├─────────────────────────┼─────────────┼────────────┼────────────┼────────────┤ │ message_id │ R │ - │ R │ - │ ├─────────────────────────┼─────────────┼────────────┼────────────┼────────────┤ │ message_qualifier │ O │ O │ O │ O │ ├─────────────────────────┼─────────────┼────────────┼────────────┼────────────┤ │ luw_token │ R │ R │ R* │ R* │ ├─────────────────────────┼─────────────┼────────────┼────────────┼────────────┤ │ version │ O │ O │ O │ O │ ├─────────────────────────┼─────────────┼────────────┼────────────┼────────────┤ │ system_name │ O │ O │ O │ O │ └─────────────────────────┴─────────────┴────────────┴────────────┴────────────┘ ═══ 11. CICS OS/2 Version 1.20 ECI subset ═══ The CICS OS/2 Version 1.20 ECI call types can be used only in an application running under OS/2, either in the same programmable workstation as the CICS for OS/2 system or on a client in a CICS for OS/2 client/server configuration. The use of these call types is not recommended for new applications. The type of ECI call is controlled by the setting of the ECI-CALL-TYPE parameter in the control block. For consistency with the documentation of the ECI in CICS OS/2 Version 1.20, parameter names and call type values are given here in COBOL format. This subset does not support the use of PL/I. Calls can be either single or parallel, and either synchronous or asynchronous. Several calls can be tied together in one logical unit of work by setting the ECI-EXTEND-MODE parameter to ECI-EXTENDED. ═══ 11.1. Single calls ═══ Only one single call can be made at a time from an OS/2 process. Single calls give no advantage over parallel calls; therefore, it is recommended that parallel calls are used instead. Single calls are retained so that programs written for earlier releases of CICS for OS/2 will continue to run. Single synchronous call (ECI-SYNC-CALL) The calling program makes a single call and has to wait for the reply to come back. A parallel synchronous call can be used in exactly the same way. Single asynchronous call (ECI-ASYNC-CALL) Asynchronous processing is used for Presentation Manager programs only. The called program returns an initial response code to the calling program to indicate whether it accepts the request. If it accepts, the processing is carried out in a separate thread, and a message is posted to the PM window specified in ECI-WINDOW-HANDLE when it has finished. The format and contents of this message are described in Reply message formats. ═══ 11.2. Parallel calls ═══ Parallel processing of calls allows up to 16 logical units of work to be handled simultaneously for each OS/2 process. Before making the first call of a logical unit of work, ECI-LUW-TOKEN should be set to zero. When the calling program makes the first call, ECI-LUW-TOKEN is returned with a valid token. The program must use this token as input to later calls in the logical unit of work to make the logical connection. Parallel synchronous call (ECI-SYNC-PARALLEL) Because this is a synchronous call, the calling thread is forced to wait for a reply before it can continue with another call. The returned token can then be used in extended calls. Parallel asynchronous call (ECI-ASYNC-PARALLEL) When the calling program makes the first call, ECI-LUW-TOKEN is returned with a valid token, which it uses as input to later calls in the logical unit of work to make the logical connection. Because this is an asynchronous call, the token is returned immediately and a Presentation Manager message indicating completion is posted later. A second call should not be made within this logical unit of work until the completion message is received. ═══ 11.3. Use of COMMAREA storage ═══ If you are making an asynchronous call (ECI-ASYNC-CALL or ECI-ASYNC-PARALLEL), any COMMAREA storage passed on the call should not be reused until the completion message has been posted, because CICS places the final contents of the COMMAREA in this area. ═══ 11.4. Parameters for use with V1.20 ECI call types ═══ Input parameters for CICS OS/2 Version 1.20 call types shows the input parameters for such an ECI call and, for each call type, whether the parameters are required (R), optional (O), or not applicable. Where a parameter is shown as optional, an initial field setting of nulls is expected if the caller does not wish to use the parameter. Parameter names and call type values are given in COBOL format; the corresponding C parameters are in lowercase and include underscores instead of hyphens as separators, and the corresponding C call types also have underscores instead of hyphens. ┌──────────────────────────────────────────────────────────────────────────────┐ │ Table 5. Input parameters for CICS OS/2 Version 1.20 call types │ ├─────────────────────────┬─────────────┬────────────┬────────────┬────────────┤ │ Parameter, eci- │ ECI- │ ECI- │ ECI-SYNC- │ ECI-ASYNC- │ │ │ SYNC-CALL │ ASYNC-CALL │ PARALLEL │ PARALLEL │ ├─────────────────────────┼─────────────┼────────────┼────────────┼────────────┤ │ call-type │ R │ R │ R │ R │ ├─────────────────────────┼─────────────┼────────────┼────────────┼────────────┤ │ program-name │ R, except │ R, except │ R, except │ R, except │ │ │ when com- │ when com- │ when com- │ when com- │ │ │ mitting or │ mitting or │ mitting or │ mitting or │ │ │ backing out │ backing │ backing │ backing │ │ │ │ out │ out │ out │ ├─────────────────────────┼─────────────┼────────────┼────────────┼────────────┤ │ userid │ R │ R │ R │ R │ ├─────────────────────────┼─────────────┼────────────┼────────────┼────────────┤ │ password │ R │ R │ R │ R │ ├─────────────────────────┼─────────────┼────────────┼────────────┼────────────┤ │ transid │ O │ O │ O │ O │ ├─────────────────────────┼─────────────┼────────────┼────────────┼────────────┤ │ commarea │ O │ O │ O │ O │ ├─────────────────────────┼─────────────┼────────────┼────────────┼────────────┤ │ commarea-length │ O │ O │ O │ O │ ├─────────────────────────┼─────────────┼────────────┼────────────┼────────────┤ │ timeout │ O │ O │ O │ O │ ├─────────────────────────┼─────────────┼────────────┼────────────┼────────────┤ │ extend-mode │ R │ R │ R │ R │ ├─────────────────────────┼─────────────┼────────────┼────────────┼────────────┤ │ window-handle │ - │ R │ - │ R │ ├─────────────────────────┼─────────────┼────────────┼────────────┼────────────┤ │ message-id │ - │ R │ - │ R │ ├─────────────────────────┼─────────────┼────────────┼────────────┼────────────┤ │ message-qualifier │ - │ O │ - │ O │ ├─────────────────────────┼─────────────┼────────────┼────────────┼────────────┤ │ luw-token │ - │ - │ R │ R │ └─────────────────────────┴─────────────┴────────────┴────────────┴────────────┘ ═══ 12. ECI and EPI exits (CICS on Open Systems, Version 2) ═══ This chapter describes exits you can add to the EPI and ECI in the CICS on Open Systems, Version 2 environment. The exits allow you to influence the processing of ECI and EPI calls for certain application requests. The chapter is organized as follows: Installing the exits Exit routine environment How the exit routines are described in the reference sections ECI exits reference EPI exits reference Diagnostic information ═══ 12.1. Installing the exits ═══ During ECI and EPI initialization, the client attempts to load the objects described in ECI and EPI exits from the CICS binary directory, and to call the corresponding entry points. ┌──────────────────────────────────────────────────────────────────────────────┐ │ Table 6. ECI and EPI exits │ ├──────────┬─────────────────────────────────┬─────────────────────────────────┤ │ │ Object name │ Entry point name │ ├──────────┼─────────────────────────────────┼─────────────────────────────────┤ │ ECI │ cicseciexit │ CICS_EciExitInit │ ├──────────┼─────────────────────────────────┼─────────────────────────────────┤ │ EPI │ cicsepiexit │ CICS_EpiExitInit │ └──────────┴─────────────────────────────────┴─────────────────────────────────┘ Each entry point is passed a single parameter, a pointer to a structure that contains a list of addresses. The initialization code of the program puts the addresses of all the exits into the structure, and then the exits are called at appropriate points in ECI and EPI processing. Since the exits are entered by using the addresses supplied, you may give the exits any names you please, but in this manual conventional names are used for the exits. If the objects are not found, no exit processing occurs. The following files are supplied with your CICS on Open Systems product to help with programming the exits. cicseciexit.h A header files that defines: o inputs and outputs for each ECI exit o the format of the list of addresses for calling ECI exits o data structures used by ECI exits o return code values for ECI exits. cicseciexit.c Skeleton code for cicseciexit. cicseciexit.mk A makefile to reconstruct cicseciexit. cicsepiexit.h A header files that defines: o inputs and outputs for each EPI exit o the format of the list of addresses for calling EPI exits o data structures used by EPI exits o return code values for EPI exits. cicsepiexit.c Skeleton code for cicsepiexit. cicsepiexit.mk A makefile to reconstruct cicsepiexit. ═══ 12.2. Exit routine environment ═══ In your exits: o You must not make EPI or ECI calls. o You should avoid waits or long-running code. (It is quite possible that the exit is running on the applications user interface thread, and thus any delays in returning could have a bad effect on the system's responsiveness.) o You must not register as an RPC server. o You must follow the recommendations for multithreaded processes contained in Chapter 6 of Guide to Writing DCE Applications. ═══ 12.3. How the exit routines are described in the reference sections ═══ The exit routines are described under the following headings: o Purpose-describes the kind of processing that the exit is intended to perform. o When called-describes where in ECI or EPI processing the exit is called. o Parameters-describes the parameters supplied to the exit. Parameters are classified as follows: - Input-the exit may look at it, but must not change it. - Output-the exit must not look at it, but must store a value in it. - Input-output-the exit may look at it, and may store a value in it. o Return codes-describes the possible values the exit can return to the ECI or EPI. In each case the subsequent behavior of the ECI or EPI is described. Note: The term FFST is used to denote first failure support technology. ═══ 12.4. ECI exits reference ═══ In this section the following exits are discussed: o CICS_EciInitializeExit o CICS_EciTerminateExit o CICS_EciExternalCallExit1 o CICS_EciExternalCallExit2 o CICS_EciSystemIdExit o CICS_EciDataSendExit o CICS_EciDataReturnExit Summary of ECI exits summarizes the exit names, the parameters passed to each exit, and the possible return codes. ┌──────────────────────────────────────────────────────────────────────────────┐ │ Table 7. Summary of ECI exits │ ├───────────────────────────┬───────────────┬──────────────────────────────────┤ │ Function name │ Parameters │ Return codes: │ ├───────────────────────────┼───────────────┼──────────────────────────────────┤ │ CICS_EciInitializeExit │ Version │ CICS_EXIT_OK │ │ │ Anchor │ CICS_EXIT_NO_EXIT │ │ │ │ CICS_EXIT_CANT_INIT_EXITS │ │ │ │ user-defined │ ├───────────────────────────┼───────────────┼──────────────────────────────────┤ │ CICS_EciTerminateExit │ Anchor │ CICS_EXIT_OK │ │ │ │ CICS_EXIT_BAD_ANCHOR │ │ │ │ CICS_EXIT_BAD_STORAGE │ │ │ │ user-defined │ ├───────────────────────────┼───────────────┼──────────────────────────────────┤ │ CICS_EciExternalCallExit1 │ Anchor │ CICS_EXIT_OK │ │ │ Token │ CICS_EXIT_BAD_ANCHOR │ │ │ ParmPtr │ CICS_EXIT_BAD_PARM │ │ │ │ user-defined │ ├───────────────────────────┼───────────────┼──────────────────────────────────┤ │ CICS_EciExternalCallExit2 │ Anchor │ CICS_EXIT_OK │ │ │ Token │ CICS_EXIT_BAD_ANCHOR │ │ │ ParmPtr │ CICS_EXIT_BAD_PARM │ │ │ │ user-defined │ ├───────────────────────────┼───────────────┼──────────────────────────────────┤ │ CICS_EciSystemIdExit │ Anchor │ CICS_EXIT_OK │ │ │ Token │ CICS_EXIT_BAD_ANCHOR │ │ │ ParmPtr │ CICS_EXIT_BAD_PARM │ │ │ Reason │ CICS_EXIT_GIVE_UP │ │ │ │ user_defined │ ├───────────────────────────┼───────────────┼──────────────────────────────────┤ │ CICS_EciDataSendExit │ Anchor │ CICS_EXIT_OK │ │ │ Token │ CICS_EXIT_BAD_ANCHOR │ │ │ │ CICS_EXIT_BAD_PARM │ │ │ │ user_defined │ ├───────────────────────────┼───────────────┼──────────────────────────────────┤ │ CICS_EciDataReturnExit │ Anchor │ CICS_EXIT_OK │ │ │ Token │ CICS_EXIT_BAD_ANCHOR │ │ │ ParmPtr │ CICS_EXIT_BAD_PARM │ │ │ │ user_defined │ └───────────────────────────┴───────────────┴──────────────────────────────────┘ ═══ 12.4.1. Identification token ═══ In order for the exits to be able to relate calls for the same ECI request, an identification token is passed in as a parameter to all exits except CICS_EciInitializeExit and CICS_EciTerminateExit. The token is the same for CICS_EciExternalCallExit1 and CICS_EciExternalCallExit2 that relate to the same call, and on intervening CICS_EciDataSendExit, CICS_EciDataReturnExit, and CICS_EciSystemIdExit exits. (Note that CICS_EciExternalCallExit1 and CICS_EciExternalCallExit2 are not called for a reply solicitation request.) The token is unique within the operating system that initiated the request, for the duration of the request. It may be reused once the last exit for the request has been called. In the case of an extended logical unit of work, the token may be different on different requests within the logical unit of work. (Since we allow reuse of the token, and a new program link call may not be made until the ECI_GET_REPLY request for the previous asynchronous request has completed, it may also be the same.) The token is 8 bytes long. 8 null bytes is not a valid value for the token and is not supplied to the exits. ═══ 12.4.2. Process model implementation ═══ All exits that relate to a particular request (i.e. have the same identification token) are called in the context of the application process. ═══ 12.4.3. CICS_EciInitializeExit ═══ CICS_EciInitializeExit ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ CICS_EciInitializeExit │ Version │ │ │ Anchor │ └───────────────────────────────────────┴──────────────────────────────────────┘ Purpose To allow the user to set up an exit environment. When called On the first invocation of CICS_ExternalCall, for each process, after parameter validation has occurred. Parameters Version Input parameter. The version of the ECI under which the exit is running. Anchor Output parameter. A pointer to a pointer that will be passed to the ECI exits. The second pointer is not used by the ECI; it is passed to the exits as supplied. You can acquire storage in this exit and pass its address to the other exits. Return codes CICS_EXIT_OK The ECI continues processing this request, calling the exits where appropriate. CICS_EXIT_NO_EXIT The ECI continues processing this request, but does not call any more exits. CICS_EXIT_CANT_INIT_EXITS The ECI uses FFST, and then continues processing this request, but does not call any more exits. user-defined User-defined return codes must have a value not less than CICS_EXIT_USER_BASE. The ECI uses FFST, and then continues processing this request, but does not call any more exits. ═══ 12.4.4. CICS_EciTerminateExit ═══ CICS_EciTerminateExit ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ CICS_EciTerminateExit │ Anchor │ └───────────────────────────────────────┴──────────────────────────────────────┘ Purpose To allow the user to clean up the exit environment. Any storage acquired by CICS_EciInitializeExit must be released in this exit. When called On termination of the process that issued the CICS_EciInitializeExit. Parameters Anchor Input parameter. The pointer set up by CICS_EciInitializeExit. Return codes CICS_EXIT_OK Termination continues. CICS_EXIT_BAD_ANCHOR The ECI uses FFST, and then continues with termination. CICS_EXIT_BAD_STORAGE The ECI uses FFST, and then continues with termination. user-defined User-defined return codes must have a value not less than CICS_EXIT_USER_BASE. The ECI uses FFST, and then continues with termination. ═══ 12.4.5. CICS_EciExternalCallExit1 ═══ CICS_EciExternalCallExit1 ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ CICS_EciExternalCallExit1 │ Anchor │ │ │ Token │ │ │ ParmPtr │ └───────────────────────────────────────┴──────────────────────────────────────┘ Purpose To allow the user to pick the best system to run the program. This exit is called exactly once on each program link and each status information call. It is not called on a reply solicitation call. When called On invocation of CICS_ExternalCall, for each program link call and each status information call, after the ECI has validated the parameters. Parameters Anchor Input parameter. The pointer set up by CICS_EciInitializeExit. Token Input parameter. The identification token established by the ECI for this request. ParmPtr Input parameter. A pointer to the ECI parameter block. The exit must treat all fields in the ECI parameter block as inputs, except the eci_system_name field, which it may change. Return codes CICS_EXIT_OK The ECI continues to process the request with the eci_system_name now specified in the ECI parameter block. CICS_EXIT_BAD_ANCHOR The ECI uses FFST, and then continues to process the request with the eci_system_name now specified in the ECI parameter block. CICS_EXIT_BAD_PARM The ECI uses FFST, and then continues to process the request with the eci_system_name now specified in the ECI parameter block. user-defined User-defined return codes must have a value not less than CICS_EXIT_USER_BASE. The ECI uses FFST, and then continues to process the request with the eci_system_name now specified in the ECI parameter block. ═══ 12.4.5.1. Note on selection of systems ═══ There is a limited set of conditions under which the exit may select a new system. The exit may select a system if the call is a program link or status information call, and if a new logical unit of work is being started. In other cases, the exit should return CICS_EXIT_OK. If the calling application has put binary zeros as the system name in the parameter block, then the application is expecting that the system will be dynamically selected, and the exit may safely select the system. If however the calling application has placed a system name in the parameter block, or if the application is a version 0 application, then it may not be expecting the target system to change, and application errors could result. In this case the exit would generally return without specifying a replacement system, with the result that the specified or default system name is to be used. If the exit chooses to change the selected system in this situation, then it may do so, but the following should be borne in mind. o The exit routine must be sensitive to whether or not the modification of the target system will cause errors in the ECI application running on the client. o The exit routine must maintain a knowledge base, keyed on appropriate data available to it, to enable it to determine whether this modification is acceptable to the client application. ═══ 12.4.6. CICS_EciExternalCallExit2 ═══ CICS_EciExternalCallExit2 ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ CICS_EciExternalCallExit2 │ Anchor │ │ │ Token │ │ │ ParmPtr │ └───────────────────────────────────────┴──────────────────────────────────────┘ Purpose To allow the user to see the results of synchronous ECI calls for information gathering purposes only. This exit is called exactly once on every application program link or status information call. It is not called on reply solicitation calls. When called Before the ECI call returns to the application, and after the return data is filled into the ECI parameter block. Parameters Anchor Input parameter. The pointer set up by CICS_EciInitializeExit. Token Input parameter. The identification token established by the ECI for this request. ParmPtr Input parameter. A pointer to the ECI parameter block. The exit must treat all fields in the ECI parameter block as inputs. Return codes CICS_EXIT_OK The ECI returns control to the application that issued the CICS_ExternalCall request. CICS_EXIT_BAD_ANCHOR The ECI uses FFST, and then returns control to the application that issued the CICS_ExternalCall request. CICS_EXIT_BAD_PARM The ECI uses FFST, and then returns control to the application that issued the CICS_ExternalCall request. user-defined User-defined return codes must have a value not less than CICS_EXIT_USER_BASE. The ECI uses FFST, and then returns control to the application that issued the CICS_ExternalCall request. ═══ 12.4.7. CICS_EciSystemIdExit ═══ CICS_EciSystemIdExit ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ CICS_EciSystemIdExit │ Anchor │ │ │ Token │ │ │ ParmPtr │ │ │ Reason │ └───────────────────────────────────────┴──────────────────────────────────────┘ Purpose To allow the user to supply a new system name when the name supplied in the ECI parameter block is not valid. When called This exit is called when an error occurs that may be corrected by selection of a new system, userid, or password. This is when the ECI would return a code of ECI_ERR_NO_CICS or ECI_ERR_UNKNOWN_SERVER or ECI_ERR_SECURITY_ERROR. It may be called when either when the client detects an error before data is sent to the server, or after data returns from the server. Parameters Anchor Input parameter. The pointer set up by CICS_EciInitializeExit. Token Input parameter. The identification token established by the ECI for this request. ParmPtr Input parameter. A pointer to the ECI parameter block. The exit must treat all fields in the ECI parameter block as inputs, except the following, which it may set: o eci_system_name o eci_userid o eci_password. Reason Input parameter. The reason code that explains why the application request has not so far succeeded. Return codes CICS_EXIT_OK The ECI retries the application call using the new parameters in the ECI parameter block. (The CICS program communication area supplied by the application to the CICS_ExternalCall is preserved.) The application callback routine will not be called, nor will CICS_EciExternalCallExit2. CICS_EXIT_BAD_ANCHOR The ECI uses FFST, and then returns to the application that issued the CICS_ExternalCall request. CICS_EXIT_BAD_PARM The ECI uses FFST, and then returns to the application that issued the CICS_ExternalCall request. CICS_EXIT_GIVE_UP The ECI returns to the application that issued the CICS_ExternalCall request. user-defined User-defined return codes must have a value not less than CICS_EXIT_USER_BASE. The ECI uses FFST, and then retries the application call as described for CICS_EXIT_OK. ═══ 12.4.8. CICS_EciDataSendExit ═══ CICS_EciDataSendExit ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ CICS_EciDataSendExit │ Anchor │ │ │ Token │ └───────────────────────────────────────┴──────────────────────────────────────┘ Purpose To allow the user to time calls for performance analysis. When called As close as possible to the time that the request will be sent to the server. Parameters Anchor Input parameter. The pointer set up by CICS_EciInitializeExit. Token Input parameter. The identification token established by the ECI for this request. Return codes CICS_EXIT_OK The ECI continues processing the request. CICS_EXIT_BAD_ANCHOR The ECI uses FFST, and then continues processing the request. CICS_EXIT_BAD_PARM The ECI uses FFST, and then continues processing the request. user-defined User-defined return codes must have a value not less than CICS_EXIT_USER_BASE. The ECI uses FFST, and then continues processing the request. ═══ 12.4.9. CICS_EciDataReturnExit ═══ CICS_EciDataReturnExit ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ CICS_EciDataReturnExit │ Anchor │ │ │ Token │ │ │ ParmPtr │ └───────────────────────────────────────┴──────────────────────────────────────┘ Purpose To allow the user to time calls for performance analysis. When called As close as possible to the time that the response from the server has been received, and the ECI block and commarea data for eventual return to the application has been built. It is also called if there is a timeout because of a lack of response from the server. Parameters Anchor Input parameter. The pointer set up by CICS_EciInitializeExit. Token Input parameter. The identification token established by the ECI for this request. ParmPtr Input parameter. A pointer to the ECI parameter block. The exit must treat all fields in the ECI parameter block as inputs. Return codes CICS_EXIT_OK The ECI continues processing the request. CICS_EXIT_BAD_ANCHOR The ECI uses FFST, and then continues processing the request. CICS_EXIT_BAD_PARM The ECI uses FFST, and then continues processing the request. user-defined User-defined return codes must have a value not less than CICS_EXIT_USER_BASE. The ECI uses FFST, and then continues processing the request. ═══ 12.5. EPI exits reference ═══ In this section the following exits are discussed: o CICS_EpiInitializeExit o CICS_EpiTerminateExit o CICS_EpiAddTerminalExit o CICS_EpiTermIdExit o CICS_EpiStartTranExit o CICS_EpiReplyExit o CICS_EpiDelTerminalExit o CICS_EpiGetEventExit o CICS_EpiSystemIdExit o CICS_EpiTranFailedExit Summary of EPI exits summarizes the exit names, the parameters passed to each exit, and the possible return codes. ┌──────────────────────────────────────────────────────────────────────────────┐ │ Table 8. Summary of EPI exits │ ├───────────────────────────┬───────────────┬──────────────────────────────────┤ │ Function name │ Parameters │ Return codes: │ ├───────────────────────────┼───────────────┼──────────────────────────────────┤ │ CICS_EpiInitializeExit │ Version │ CICS_EXIT_OK │ │ │ Anchor │ CICS_EXIT_NO_EXIT │ │ │ │ CICS_EXIT_CANT_INIT_EXITS │ │ │ │ user-defined │ ├───────────────────────────┼───────────────┼──────────────────────────────────┤ │ CICS_EpiTerminateExit │ Anchor │ CICS_EXIT_OK │ │ │ │ CICS_EXIT_BAD_ANCHOR │ │ │ │ CICS_EXIT_BAD_STORAGE │ │ │ │ user-defined │ ├───────────────────────────┼───────────────┼──────────────────────────────────┤ │ CICS_EpiAddTerminalExit │ Anchor │ CICS_EXIT_OK │ │ │ NameSpace │ CICS_EXIT_DONT_ADD_TERMINAL │ │ │ System │ CICS_EXIT_BAD_ANCHOR │ │ │ NetName │ CICS_EXIT_BAD_PARM │ │ │ DevType │ user-defined │ ├───────────────────────────┼───────────────┼──────────────────────────────────┤ │ CICS_EpiTermIdExit │ Anchor │ CICS_EXIT_OK │ │ │ TermIndex │ CICS_EXIT_BAD_ANCHOR │ │ │ System │ CICS_EXIT_BAD_PARM │ │ │ │ user-defined │ ├───────────────────────────┼───────────────┼──────────────────────────────────┤ │ CICS_EpiStartTranExit │ Anchor │ CICS_EXIT_OK │ │ │ TransId │ CICS_EXIT_BAD_ANCHOR │ │ │ Data │ CICS_EXIT_BAD_PARM │ │ │ Size │ user-defined │ ├───────────────────────────┼───────────────┼──────────────────────────────────┤ │ CICS_EpiReplyExit │ Anchor │ CICS_EXIT_OK │ │ │ TermIndex │ CICS_EXIT_BAD_ANCHOR │ │ │ Data │ CICS_EXIT_BAD_PARM │ │ │ Size │ user_defined │ ├───────────────────────────┼───────────────┼──────────────────────────────────┤ │ CICS_EpiDelTerminalExit │ Anchor │ CICS_EXIT_OK │ │ │ TermIndex │ CICS_EXIT_BAD_ANCHOR │ │ │ │ CICS_EXIT_BAD_PARM │ │ │ │ user_defined │ ├───────────────────────────┼───────────────┼──────────────────────────────────┤ │ CICS_EpiGetEventExit │ Anchor │ CICS_EXIT_OK │ │ │ TermIndex │ CICS_EXIT_BAD_ANCHOR │ │ │ Wait │ CICS_EXIT_BAD_PARM │ │ │ Event │ user_defined │ ├───────────────────────────┼───────────────┼──────────────────────────────────┤ │ CICS_EpiSystemIdExit │ Anchor │ CICS_EXIT_OK │ │ │ NameSpace │ CICS_EXIT_DONT_ADD_TERMINAL │ │ │ System │ CICS_EXIT_BAD_ANCHOR │ │ │ NetName │ CICS_EXIT_BAD_PARM │ │ │ DevType │ user_defined │ │ │ FailedSystem │ │ │ │ Reason │ │ │ │ SubReason │ │ │ │ UserId │ │ │ │ PassWord │ │ ├───────────────────────────┼───────────────┼──────────────────────────────────┤ │ CICS_EpiTranFailedExit │ Anchor │ CICS_EXIT_OK │ │ │ TermIndex │ CICS_EXIT_BAD_ANCHOR │ │ │ Wait │ CICS_EXIT_BAD_PARM │ │ │ Event │ user_defined │ └───────────────────────────┴───────────────┴──────────────────────────────────┘ ═══ 12.5.1. CICS_EpiInitializeExit ═══ CICS_EpiInitializeExit ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ CICS_EpiInitializeExit │ Version │ │ │ Anchor │ └───────────────────────────────────────┴──────────────────────────────────────┘ Purpose To allow the user to set up an exit environment. When called On each invocation of CICS_EpiInitialize, after the EPI has validated the parameters. Parameters Version Input parameter. The version of the EPI under which the exit is running. Anchor Output parameter. A pointer to a pointer that will be passed to the EPI exits. The second pointer is not used by the EPI; it is passed to the exits as supplied. You can acquire storage in this exit and pass its address to the other exits. Return codes CICS_EXIT_OK The EPI continues processing this request, calling the exits where appropriate. CICS_EXIT_NO_EXIT The EPI continues processing this request, but does not call any more exits. CICS_EXIT_CANT_INIT_EXITS The EPI uses FFST, and then continues processing this request, but does not call any more exits. user-defined User-defined return codes must have a value not less than CICS_EXIT_USER_BASE. The EPI uses FFST, and then continues processing this request, but does not call any more exits. ═══ 12.5.2. CICS_EpiTerminateExit ═══ CICS_EpiTerminateExit ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ CICS_EpiTerminateExit │ Anchor │ └───────────────────────────────────────┴──────────────────────────────────────┘ Purpose To allow the user to clean up the exit environment. Any storage acquired by CICS_EpiInitializeExit must be released in this exit. When called On each invocation of CICS_EpiTerminate, after the EPI has validated the parameters. Parameters Anchor Input parameter. The pointer set up by CICS_EpiInitializeExit. Return codes CICS_EXIT_OK Termination continues. CICS_EXIT_BAD_ANCHOR The EPI uses FFST, and then continues with termination. CICS_EXIT_BAD_STORAGE The EPI uses FFST, and then continues with termination. user-defined User-defined return codes must have a value not less than CICS_EXIT_USER_BASE. The EPI uses FFST, and then continues with termination. ═══ 12.5.3. CICS_EpiAddTerminalExit ═══ CICS_EpiAddTerminalExit ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ CICS_EpiAddTerminalExit │ Anchor │ │ │ NameSpace │ │ │ System │ │ │ NetName │ │ │ DevType │ └───────────────────────────────────────┴──────────────────────────────────────┘ Purpose To allow the user to select a server, or override the one passed to CICS_EpiAddTerminal in the System parameter. When called On each invocation of CICS_EpiAddTerminal, after the EPI has validated the parameters. Parameters Anchor Input parameter. The pointer storage set up by CICS_EpiInitializeExit. NameSpace Input-output parameter. On input, its value depends on the value supplied for the NameSpace parameter of the CICS_EpiAddTerminal call to which this exit relates: o If a null pointer was supplied, this input is a pointer to a null string. o If a non-null pointer was supplied, this input is that pointer. On output, it will be used by the EPI in the same way as the value specified on the call would have been used. System Input-output parameter. On input, it is the value supplied for the System parameter of the CICS_EpiAddTerminal call to which this exit relates. On output, it will be used by the EPI in the same way as the value specified on the call would have been used. NetName Input-output parameter. On input, it is the value supplied for the NetName parameter of the CICS_EpiAddTerminal call to which this exit relates. On output, it will be used by the EPI in the same way as the value specified on the call would have been used. DevType Input-output parameter. On input, it is the value supplied for the DevType parameter of the CICS_EpiAddTerminal call to which this exit relates. On output, it will be used by the EPI in the same way as the value specified on the call would have been used. Return codes CICS_EXIT_OK Processing continues with the output values of NameSpace, System, NetName, and DevType. CICS_EXIT_DONT_ADD_TERMINAL The CICS_EpiAddTerminal is ended with a return code of CICS_EPI_ERR_FAILED. If the application uses CICS_EpiGetSysError, the value 5 is returned in the Value field of the CICS_EpiSysError_t structure. CICS_EXIT_BAD_ANCHOR The EPI uses FFST, and then continues as for CICS_EXIT_OK. CICS_EXIT_BAD_PARM The EPI uses FFST, and then continues as for CICS_EXIT_OK. user-defined User-defined return codes must have a value not less than CICS_EXIT_USER_BASE. The EPI uses FFST, and then continues as for CICS_EXIT_OK. ═══ 12.5.3.1. Note on selection of systems ═══ If the calling application does not specify system name in its parameter list, then it is expecting that the system will be dynamically selected, and the exit may safely select the system. If however the calling application specifies a system name, then it may not be expecting the target system to change and application errors could result. In this case the exit would generally not specify a replacement system, with the result that the specified or default system name, device type, etc. is to be used. If the exit chooses to change the selected system in this situation, then it may do so, but the following should be borne in mind. o The exit routine must be sensitive to whether or not the modification of the target system will cause errors in the EPI application running on the client. o The exit routine must maintain a knowledge base, keyed on appropriate data available to it, to enable it to determine whether this modification is acceptable to the client application. ═══ 12.5.3.2. CICS_EpiAddTerminalExit and CICS_EpiSystemIdExit ═══ The relationship between these exits is as follows. The exits will get multiple chances to make a selection of the system. The first chance will always occur on the CICS_EpiAddTerminalExit. This exit will only receive the parameters passed by the application to CICS_EpiAddTerminal. If an error occurs when CICS tries to add the terminal (whether or not the exit has made a selection) then CICS_EpiSystemIdExit will be called. CICS_EpiSystemIdExit will additionally be passed the error that occurred on the attempt to add the terminal, and will get a chance to correct the error. This continues to occur until either a terminal is successfully added, or until CICS_EpiSystemIdExit signals to give up. If no error occurs on the attempt to add the terminal, then CICS_EpiSystemIdExit will not be called. ═══ 12.5.4. CICS_EpiTermIdExit ═══ CICS_EpiTermIdExit ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ CICS_EpiTermIdExit │ Anchor │ │ │ TermIndex │ │ │ System │ └───────────────────────────────────────┴──────────────────────────────────────┘ Purpose To allow the user to know the terminal index allocated after a successfull call to CICS_EpiAddTerminal. When called On each invocation of CICS_EpiAddTerminal, after the server has allocated the terminal. Parameters Anchor Input parameter. The pointer storage set up by CICS_EpiInitializeExit. TermIndex Input parameter. A pointer to the terminal index for the terminal resource just reserved or installed. System Input parameter. A pointer to a null-terminated string that specifies the name of the server in which the terminal resource has been reserved or installed. Return codes CICS_EXIT_OK Processing continues. CICS_EXIT_BAD_ANCHOR The EPI uses FFST, and then continues as for CICS_EXIT_OK. CICS_EXIT_BAD_PARM The EPI uses FFST, and then continues as for CICS_EXIT_OK. user-defined User-defined return codes must have a value not less than CICS_EXIT_USER_BASE. The EPI uses FFST, and then continues as for CICS_EXIT_OK. ═══ 12.5.5. CICS_EpiStartTranExit ═══ CICS_EpiStartTranExit ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ CICS_EpiStartTranExit │ Anchor │ │ │ TransId │ │ │ Data │ │ │ Size │ └───────────────────────────────────────┴──────────────────────────────────────┘ Purpose To allow the user to see when a transaction is started, for information gathering purposes. This exit will not select a system, and has no return data. When called On invocation of CICS_EpiStartTran, after the EPI has validated the parameters. Parameters Anchor Input parameter. The pointer set up by CICS_EpiInitializeExit. TransId Input parameter. The value supplied for the TransId parameter of the CICS_EpiStartTran call to which this exit relates. Data Input parameter. The value supplied for the Data parameter of the CICS_EpiStartTran call to which this exit relates. Size Input parameter. The value supplied for the Size parameter of the CICS_EpiStartTran call to which this exit relates. Return codes CICS_EXIT_OK Processing of the CICS_EpiStartTran call continues. CICS_EXIT_BAD_ANCHOR The EPI uses FFST, and then processing of the CICS_EpiStartTran call continues. CICS_EXIT_BAD_PARM The EPI uses FFST, and then processing of the CICS_EpiStartTran call continues. user-defined User-defined return codes must have a value not less than CICS_EXIT_USER_BASE. The EPI uses FFST, and then processing of the CICS_EpiStartTran call continues. ═══ 12.5.6. CICS_EpiReplyExit ═══ CICS_EpiReplyExit ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ CICS_EpiReplyExit │ Anchor │ │ │ TermIndex │ │ │ Data │ │ │ Size │ └───────────────────────────────────────┴──────────────────────────────────────┘ Purpose To allow the user to see when a transaction is replied to, for information gathering purposes. When called On invocation of CICS_EpiReply, after the EPI has validated the parameters. Parameters Anchor Input parameter. The pointer set up by CICS_EpiInitializeExit. TermIndex Input parameter. The value supplied for the TermIndex parameter of the CICS_EpiReply call to which this exit relates. Data Input parameter. The value supplied for the Data parameter of the CICS_EpiReply call to which this exit relates. Size Input parameter. The value supplied for the Size parameter of the CICS_EpiReply call to which this exit relates. Return codes CICS_EXIT_OK Processing of the CICS_EpiReply call continues. CICS_EXIT_BAD_ANCHOR The EPI uses FFST, and then processing of the CICS_EpiReply call continues. CICS_EXIT_BAD_PARM The EPI uses FFST, and then processing of the CICS_EpiReply call continues. user-defined User-defined return codes must have a value not less than CICS_EXIT_USER_BASE. The EPI uses FFST, and then processing of the CICS_EpiReply call continues. ═══ 12.5.7. CICS_EpiDelTerminalExit ═══ CICS_EpiDelTerminalExit ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ CICS_EpiDelTerminalExit │ Anchor │ │ │ TermIndex │ └───────────────────────────────────────┴──────────────────────────────────────┘ Purpose To allow the user to clean up any terminal-related data structures. When called On invocation of CICS_EpiDelTerminal, after the EPI has validated the parameters. Parameters Anchor Input parameter. The pointer set up by CICS_EpiInitializeExit. TermIndex Input parameter. The value supplied for the TermIndex parameter of the CICS_EpiDelTerminal call to which this exit relates. Return codes CICS_EXIT_OK Processing of the CICS_EpiDelTerminal call continues. CICS_EXIT_BAD_ANCHOR The EPI uses FFST, and then processing of the CICS_EpiDelTerminal call continues. CICS_EXIT_BAD_PARM The EPI uses FFST, and then processing of the CICS_EpiDelTerminal call continues. user-defined User-defined return codes must have a value not less than CICS_EXIT_USER_BASE. The EPI uses FFST, and then processing of the CICS_EpiDelTerminal call continues. ═══ 12.5.8. CICS_EpiGetEventExit ═══ CICS_EpiGetEventExit ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ CICS_EpiGetEventExit │ Anchor │ │ │ TermIndex │ │ │ Wait │ │ │ Event │ └───────────────────────────────────────┴──────────────────────────────────────┘ Purpose To allow the user to collect data relating to the event that has arrived. When called Immediately before CICS_EpiGetEvent returns to the caller. The exit can then examine the data returned, time the response from the system, etc. Parameters Anchor Input parameter. The pointer set up by CICS_EpiInitializeExit. TermIndex Input parameter. The value to be returned to the application in the TermIndex parameter of the CICS_EpiGetEvent call to which this exit relates. Wait Input parameter. The value supplied for the Wait parameter of the CICS_EpiGetEvent call to which this exit relates. Event Input parameter. The value to be returned to the application in the Event parameter of the CICS_EpiGetEvent call to which this exit relates. Return codes CICS_EXIT_OK Processing of the CICS_EpiGetEvent call continues. CICS_EXIT_BAD_ANCHOR The EPI uses FFST, and then processing of the CICS_EpiGetEvent call continues. CICS_EXIT_BAD_PARM The EPI uses FFST, and then processing of the CICS_EpiGetEvent call continues. user-defined User-defined return codes must have a value not less than CICS_EXIT_USER_BASE. The EPI uses FFST, and then processing of the CICS_EpiGetEvent call continues. ═══ 12.5.9. CICS_EpiSystemIdExit ═══ CICS_EpiSystemIdExit ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ CICS_EpiSystemIdExit │ Anchor │ │ │ NameSpace │ │ │ System │ │ │ NetName │ │ │ DevType │ │ │ FailedSystem │ │ │ Reason │ │ │ SubReason │ │ │ UserId │ │ │ PassWord │ └───────────────────────────────────────┴──────────────────────────────────────┘ Purpose To allow the user to supply a new system name when the value supplied for CICS_Epi_AddTerminal was invalid. When called Immediately before CICS_EpiAddTerminal returns to the application when an error occurred while trying to add the terminal. The error can be CICS_EPI_ERR_SYSTEM or CICS_EPI_ERR_FAILED. It occurs whether or not CICS_EpiAddTerminalExit has been called previously. Note: On some systems the completion of CICS_EpiAddTerminal is returned to the application asynchronously, and in this case this exit will be called asynchronously. Parameters Anchor Input parameter. The pointer set up by CICS_EpiInitializeExit. NameSpace Input-output parameter. The NameSpace parameter used in the failed CICS_EpiAddTerminal. System Input-output parameter. The System parameter used in the failed CICS_EpiAddTerminal. NetName Input-output parameter. The NetName parameter used in the failed CICS_EpiAddTerminal. DevType Input-output parameter. The DevType parameter used in the failed CICS_EpiAddTerminal. FailedSystem Input parameter. The identifier of the system on which the failure occurred. Reason Input parameter. The reason for the failure:. CICS_EPI_ERR_SYSTEM or CICS_EPI_ERR_FAILED. SubReason Input parameter. More about the failure. If the reason is CICS_EPI_ERR_FAILED, this is the value that appears in the Cause field of the CICS_EpiSysError_t structure. UserId Output parameter. Not used. PassWord Output parameter. Not used. Return codes CICS_EXIT_OK The EPI will retry the CICS_EpiAddTerminal call using the values specified as output of this exit. Note that in this case the considerations described in CICS_EpiAddTerminalExit apply. CICS_EXIT_DONT_ADD_TERMINAL The CICS_EpiAddTerminal is ended with a return code of CICS_EPI_ERR_FAILED. If the application uses CICS_EpiGetSysError, the value 5 is returned in the Value field of the CICS_EpiSysError_t structure. CICS_EXIT_BAD_ANCHOR The EPI uses FFST, and then the error that caused the exit to be called is returned to the application. CICS_EXIT_BAD_PARM The EPI uses FFST, and then the error that caused the exit to be called is returned to the application. user-defined User-defined return codes must have a value not less than CICS_EXIT_USER_BASE. The EPI uses FFST, and then the error that caused the exit to be called is returned to the application. Retry the CICS_EpiAddTerminal call using the system specified as output of this exit. Note that in this case the considerations described in CICS_EpiAddTerminalExit apply. ═══ 12.5.10. CICS_EpiTranFailedExit ═══ CICS_EpiTranFailedExit ┌───────────────────────────────────────┬──────────────────────────────────────┐ │ CICS_EpiTranFailedExit │ Anchor │ │ │ TermIndex │ │ │ Wait │ │ │ Event │ └───────────────────────────────────────┴──────────────────────────────────────┘ Purpose To allow the user to collect data when a transaction abends or a terminal fails. When called Immediately before CICS_EpiGetEvent returns to the caller, with or without GetEventExit, when the event is CICS_EPI_EVENT_END_TRAN, and the AbendCode field is not blank. Note that there are some failures on remote systems that can occur and will simply cause the presentation of a 3270 data stream with an error message and no abend code in the CICS_EPI_EVENT_END_TRAN. This error message may not even occur on the same event as the CICS_EPI_EVENT_END_TRAN. If the exit requires to handle this situation, it may monitor it through CICS_EpiGetEventExit and scan the appropriate 3270 data streams. Parameters Anchor Input parameter. The pointer set up by CICS_EpiInitializeExit. TermIndex Input parameter. The value to be returned to the application in the TermIndex parameter of the CICS_EpiGetEvent call to which this exit relates. Wait Input parameter. The value supplied for the Wait parameter of the CICS_EpiGetEvent call to which this exit relates. Event Input parameter. The value to be returned to the application in the Event parameter of the CICS_EpiGetEvent call to which this exit relates. Return codes CICS_EXIT_OK Processing of the CICS_EpiGetEvent call continues. CICS_EXIT_BAD_ANCHOR The EPI uses FFST, and then processing of the CICS_EpiGetEvent call continues. CICS_EXIT_BAD_PARM The EPI uses FFST, and then processing of the CICS_EpiGetEvent call continues. user-defined User-defined return codes must have a value not less than CICS_EXIT_USER_BASE. The EPI uses FFST, and then processing of the CICS_EpiGetEvent call continues. ═══ 12.6. Diagnostic information ═══ CICS will trace the input parameters to the exits immediately before they are called, and the output of the exit when the exit returns. CICS tracing will not be available for use within the exit. ═══ 13. Sending your comments to IBM ═══ If you especially like or dislike anything about this book, please use one of the methods listed below to send your comments to IBM. Feel free to comment on what you regard as specific errors or omissions, and on the accuracy, organization, subject matter, or completeness of this book. Please limit your comments to the information in this book and the way in which the information is presented. To request additional publications, or to ask questions or make comments about the functions of IBM products or systems, you should talk to your IBM representative or to your IBM authorized remarketer. When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in any way it believes appropriate, without incurring any obligation to you. You can send your comments to IBM in any of the following ways: o By fax: - From outside the U.K., after your international access code use 44 1962 870229 - From within the U.K., use 01962 870229 o Electronically, use the appropriate network ID: - IBM Mail Exchange: GBIBM2Q9 at IBMMAIL - IBMLink: WINVMD(IDRCF) - Internet: idrcf@winvmd.vnet.ibm.com Whichever you use, ensure that you include: o The publication number and title o The page number or topic to which your comment applies o Your name and address/telephone number/fax number/network ID.