ECI_STATE_ASYNC call type

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.

Purpose

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.

Note: It is important that the ECI parameter blocks of outstanding ECI_STATE_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. Note the following guidelines on the use of the callback routine:

Perform the minimum possible processing within the callback routine.
ECI functions cannot be invoked from within the callback routine.
The callback routine 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.
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 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. Area size must not exceed 32,500 bytes

If no COMMAREA is required, set this field to zero and supply a null pointer in eci_commarea.

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 further qualifying the call type. 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, for more details.
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 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 for which status information is requested. Pad unused characters with spaces. If supplied, it is one of the server names returned by CICS_EciListSystems. The value might be supplied whenever eci_luw_token is set to zero.

If the field is set to nulls, the default CICS 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 (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 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.