ECI_ASYNC call type
The ECI_ASYNC call type provides an asynchronous program link call to start, continue, or end a logical unit of work.
Purpose
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.
- Perform the minimum possible processing within the callback routine.
- ECI functions cannot be invoked from within the callback routine.
- The callback routine indicates 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, the callback routine might post a semaphore to signal another thread that an event has occurred.
- The application, not the callback routine, must use a reply solicitation call to receive the actual response.
ECI parameter block 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 Managing
logical units of work
for more details.)
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.
- eci_userid
- Required input parameter.
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 uppercase 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.
- eci_password
- Required input parameter.
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 uppercase 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.)
- eci_transid
- Optional input parameter
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 uppercase 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 field is all nulls, and eci_tpn is not specified, 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, use CICS-supplied resource conversion capabilities, such as the DFHCNV macro definitions.
- eci_commarea_length
- Required input parameter.
The length of the COMMAREA in bytes. Application developers are advised to use a maximum size of 32,500 bytes, as this is guaranteed to be flowed successfully across all protocols. COMMAREA sizes greater than this may generate an ECI_ERR_INVALID_DATA_LENGTH return code.
If no COMMAREA is required, set this field to zero and supply a null pointer in eci_commarea.
- eci_timeout
- The time in seconds to wait for a response from the CICS server.
A value of 0 means that no limit is set.
If timeout occurs, the conversation ends abnormally.
- reserved1
- Output parameter.
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.
- 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 Managing logical units of work for more details.)
Values (shown by their symbolic names) for this field are as follows:- ECI_NO_EXTEND
-
- If the input eci_luw_token field is zero, this is the only call for a logical unit of work.
- If the input eci_luw_token field is not zero, this is the last call for the specified logical unit of work.
- ECI_EXTENDED
-
- 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.
- If the input eci_luw_token field is not zero, this call is intended to continue the specified logical unit of work.
- 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, use this as input to all later calls related to the same logical unit of work. (See Managing logical units of work 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.
- eci_sysid
- Required input parameter.
Reserved for future use, but initialize this field 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. Use the value ECI_VERSION_1A.
- 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. Pad unused characters with spaces. The value might 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 CICS 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.)
- 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, 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 10 characters.
See the description of the eci_userid field for information about how the user ID 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 10 characters.
See the description of the eci_password field for information about how the password is used.
- eci_tpn
- Optional input parameter.
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 in the unit of work. Subsequent requests within the same unit of work will use the mirror transaction specified on the first request.
If this field is used, the contents of eci_transid are ignored.
Return codes
See also the general list of return codes for CICS_ExternalCall in CICS_ExternalCall (ECI_Parms).
- 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.