The ECI_GET_SPECIFIC_REPLY call type provides a reply solicitation
call to return information appropriate to any outstanding reply that
matches the eci_message_qualifier input. If there is no such
reply, ECI_ERR_NO_REPLY is returned. (To cause the application to
wait until a reply is available, use call type ECI_GET_REPLY_WAIT
instead.)
Purpose
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.
ECI parameter block fields
Set the ECI parameter
block to nulls before setting the input parameter fields.
The
following fields are the fields of the ECI parameter block that might
be supplied as input.
In the course of an ECI_GET_REPLY call,
the ECI parameter block is updated as follows:
- All the outputs from the reply, some of which overwrite input
fields, are added. These fields are those that are output from the
corresponding synchronous version of the asynchronous request.
- Any inputs that are not updated become undefined, except the pointer
to the COMMAREA and the input eci_message_qualifier. Do not
use the contents of these fields again.
- eci_call_type
- Required input parameter.
Must be set to ECI_GET_SPECIFIC_REPLY.
- eci_commarea
- Optional input parameter.
A pointer to the area of storage
where the application receives the returned COMMAREA. The contents
of the returned commarea depend on the type of asynchronous call to
which a reply is being sought. For a program link call, it is the
COMMAREA expected to be returned from the called program, if any.
For a status information call, except one in which eci_extend_mode had
the value ECI_STATE_CANCEL, it is a COMMAREA containing status information.
See Status information calls
and ECI status block, for more details.
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 must not exceed 32,500.
(Some client/server combinations might allow larger COMMAREAs, but
this is not guaranteed to work.)
- eci_message_qualifier
- Required input parameter.
An
integer field that identifies the asynchronous call for which a reply
is being solicited.
- 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.
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 unacceptable for one of the following reasons:
- It is outside the valid range.
- It 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.
- It is not large enough for the output COMMAREA from the asynchronous
request to which this reply relates.
In the last case, you can use the output eci_commarea_length to
allocate more storage for the COMMAREA, and then retry the ECI_GET_SPECIFIC_REPLY
call.
- ECI_ERR_NO_CICS
- The CICS® server
specified in eci_system_name in the asynchronous request to
which this reply relates is not available. No resources have been
updated.
- ECI_ERR_CICS_DIED
- A logical unit of work
was to be begun or continued by the asynchronous request to which
this reply relates, but the CICS server was no longer available.
If eci_extend_mode was ECI_EXTENDED, the changes are backed
out, and the logical unit of work ends. If eci_extend_mode was
ECI_NO_EXTEND, ECI_COMMIT, or ECI_BACKOUT, the application cannot
determine whether the changes have been committed or backed out, and
must log this condition to aid future manual recovery.
- ECI_ERR_NO_REPLY
- There was no outstanding
reply that matched the input eci_message_qualifier.
- ECI_ERR_TRANSACTION_ABEND
- The asynchronous
request to which this reply relates caused a program to be executed
in the server, but the CICS transaction that executed
the requested program ended abnormally. The abend code is in eci_abend_code.
For information about abend codes and their meaning, consult the documentation
for the server system to which the request was directed.
- ECI_ERR_THREAD_CREATE_ERROR
- The CICS server
or CICS Transaction Gateway failed
to create the thread to process the asynchronous request to which
this reply relates.
- ECI_ERR_RESOURCE_SHORTAGE
- The CICS server
or CICS Transaction Gateway did
not have enough resources to complete the asynchronous request to
which this reply relates.
- 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_ROLLEDBACK
- The asynchronous request
to which this reply relates attempted to commit a logical unit of
work, but the server was unable to commit the changes, and backed
them out instead.
- ECI_ERR_UNKNOWN_SERVER
- The asynchronous
request to which this reply relates specified a server that could
not be located. Only servers returned by CICS_EciListSystems are
acceptable.
- ECI_ERR_MAX_SESSIONS
- There were not enough
resources to satisfy the asynchronous request to which this reply
relates. The maximum number of concurrent requests handled by the
Client daemon, as defined by the configuration parameter maxrequests in
the configuration file, has been reached.
- ECI_ERR_MAX_SYSTEMS
- The asynchronous request
to which this reply relates attempted to start requests to more servers
than your configuration allows. Consult the documentation for your CICS Transaction Gateway or server
to see how to control the number of servers you can use.
- ECI_ERR_SECURITY_ERROR
- You did not supply
a valid combination of user ID and password on the asynchronous request
to which this reply relates.