ECI_GET_REPLY call type

Purpose

The ECI_GET_REPLY call type provides a reply solicitation call to return information appropriate to any outstanding reply for any asynchronous request. 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.)

Note: It is important that the Eci parameter blocks of outstanding ECI_ASYNC calls are not modified before the results of the call are received (for example using this get reply call). Results will be incorrect if these blocks are modified before this stage.

ECI parameter block fields

The ECI parameter block should be set 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:
  1. 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.
  2. The eci_message_qualifier value supplied as input to the asynchronous request to which this reply relates is restored.
  3. Any inputs that are not updated become undefined, except the pointer to the COMMAREA. Do not use the contents of these fields again.
eci_call_type
Required input parameter.

Must be set to ECI_GET_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 when eci_extend_mode has the value ECI_STATE_CANCEL, it is a COMMAREA containing status information. See Status information calls, in the External call interface chapter, in CICS Transaction Gateway: Programming Guide, and ECI status block, for more details.

If no COMMAREA is required, supply a null pointer and set the length (specified in eci_commarea_length) to zero.

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 may not exceed 32 500. (Some client/server combinations may allow larger COMMAREAs, but this is not guaranteed to work.)

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

eci_sysid
Required input parameter.

Reserved for future use, but this field should be initialized 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 asynchronous request to which this reply relates 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 use the output eci_message_qualifier (if it identifies the asynchronous request uniquely) with an ECI_GET_SPECIFIC_REPLY call type to retrieve the reply.
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.
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 abended. The abend code will be found 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 call to which this reply relates.
ECI_ERR_RESOURCE_SHORTAGE
The server implementation 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 communication resources to satisfy the asynchronous request to which this reply relates. Consult the documentation for your CICS Transaction Gateway or server to see how to control communication resources.
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 userid and password on the asynchronous request to which this reply relates.