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.