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.