ECI_STATE_SYNC call type

The ECI_STATE_SYNC call type is available in all environments.

Purpose

The ECI_STATE_SYNC call type provides a synchronous call that gives information about the status of the server.

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_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. 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 as soon as 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 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, 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 required. 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; the name of the chosen server is returned in this field.

Return codes

See also the general list of return codes for CICS_ExternalCall in CICS_ExternalCall (ECI_Parms).
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.

Reference Reference

Feedback


Timestamp icon Last updated: Tuesday, 19 November 2013


https://ut-ilnx-r4.hursley.ibm.com/tg_latest/help/topic/com.ibm.cics.tg.doc//proref/ess.html