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 whether 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.
It is important that the Eci parameter blocks of outstanding ECI_ASYNC calls are not modified before the results of the call are received. Results will be incorrect if these blocks are modified before this stage.
Must be set to ECI_ASYNC.
An 8-character field containing the name of the program to be called. Pad unused characters with spaces. This field is transmitted to the server without conversion to uppercase.
The characters used are translated from the client’s code page to an EBCDIC code page before transmission. If the server uses an ASCII code page, they will be retranslated. The only characters guaranteed to be invariant under these translations are the uppercase characters A to Z, and the numeric characters 0 to 9. Some EBCDIC servers (Katakana and Hebrew character set A) do not use the standard representations of the lowercase alphabetic characters; use them with care when communicating with such servers.
An 8-character field containing a user ID. Pad unused characters with spaces.
Consult the documentation for the CICS® Transaction Gateway and the server to check whether this field is converted to upper case before being transmitted to the server. (If a user ID or password longer than 8 characters is required, set eci_userid and eci_password to nulls, and use eci_userid2 and eci_password2 instead.)
If a user ID is supplied, the server uses the user ID and any supplied password to authenticate the user. The supplied user ID and password are used in subsequent security checking in the server.
An 8-character field containing a password. Pad unused characters with spaces.
Consult the documentation for the CICS Transaction Gateway and the server to check whether this field is converted to upper case before being transmitted to the server. (If a user ID or password longer than 8 characters is required, set eci_userid and eci_password to nulls, and use eci_userid2 and eci_password2 instead.)
A 4-character field optionally containing the ID of a CICS transaction. Pad unused characters with spaces. The parameter is ignored if eci_tpn is used (set to any value other than nulls). The use of this parameter depends on the client from which the request is sent. The value of eci_transid is converted from ASCII to EBCDIC, with no upper case translation, and stored in EIBTRNID for the duration of the LINK to the program specified in the eci_program_name.
The called program runs under the mirror transaction CPMI, but is linked to under the eci_transid transaction name. This name is available to the called program for querying the transaction ID. Some servers use the transaction ID to determine security and performance attributes for the called program. In those servers, use this parameter to control the processing of your called programs.
If the ECI request is extended (see eci_extend_mode), the eci_transid parameter has a meaning only for the first call in the unit of work.
If the field is all nulls, and eci_tpn is not specified, the default server transaction ID is used.
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, use CICS-supplied resource conversion capabilities, such as the DFHCNV macro definitions.
The length of the COMMAREA in bytes. This value may not exceed 32 500. (Some client/server combinations may allow larger COMMAREAs, but this is not guaranteed to work.)
If no COMMAREA is required, set this field to zero and supply a null pointer in eci_commarea.
If timeout occurs, the conversation is abended.
This field was previously eci_system_ return_code. In the CICS Transaction Gateway Version 3.1, and higher, this field is reserved for compatibility with earlier versions. No information is returned in this field; all system errors are written to the error log.
An integer field determining whether a logical unit of work is terminated at the end of this call. (See the Logical units of work in ECI table in CICS Transaction Gateway: Programming Guide for more details.)
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.
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 the Logical units of work in ECI table in CICS Transaction Gateway: Programming Guide for more details.)
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.
Reserved for future use, but this field should be initialized with nulls before the start of each logical unit of work.
The version of the ECI for which the application is coded. Use the value ECI_VERSION_1A.
An 8-character field that specifies the name of the server to which the ECI request is to be directed. Pad unused characters 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, 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, eci_system_name in those requests must identify that server by name.)
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.)
If the eci_userid field is set to nulls, the eci_userid2 field specifies the user ID (if any) to be used at the server for any authority validation. The user ID can be up to 16 characters.
See the description of the eci_userid field for information about how the user ID is used.
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.
See the description of the eci_password field for information about how the password is used.
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 CPMI is used.
If the ECI request is extended (see the description of eci_extend_mode), this parameter has a meaning only for the first request.
If this field is used, the contents of eci_transid are ignored.
See also the general list of return codes for CICS_ExternalCall in CICS_ExternalCall ECI_Parms.