ECI_ASYNC call type

Environment

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 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.

Note: Some compilers do not support the use of callback routines. Consult your compiler documentation for more information.

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.

When the callback routine is called, it is passed a single parameter—the value specified in eci_message_qualifier. This enables the callback routine to identify the asynchronous call that is completing. Follow these guidelines when using 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, the callback routine might post a semaphore to signal another thread that an event has occurred.
  4. The application, not the callback routine, must use a reply solicitation call to receive the actual response.

ECI parameter block fields

Set the ECI parameter block to nulls before you set 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 the Logical units of work in ECI table in CICS Transaction Gateway: Programming Guide 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 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.

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 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.)

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 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.

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. 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.

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 is abended.

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 the Logical units of work in ECI table in CICS Transaction Gateway: Programming Guide for more details.)

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 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.

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. 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 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.)

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 16 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 16 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.

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.

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.