ECI_SYNC call type

Environment

The ECI_SYNC call type is available in all environments.

Purpose

The ECI_SYNC call type provides a synchronous program link call to start, continue, or end a logical unit of work. The calling application does not get control back until the called CICS® program has run to completion.

ECI parameter block fields

The ECI parameter block should be set to nulls before setting the input parameter fields.
eci_call_type
Required input parameter, which must be set to ECI_SYNC.
eci_program_name
Input parameter, required except when eci_extend_mode is ECI_COMMIT or ECI_BACKOUT. (See the Logical units of work in ECI table in CICS Transaction Gateway: Programming Guide for more details.)

An 8-character field containing the name of the program to be called. Pad unused characters with spaces. This field is transmitted to the server without conversion to uppercase.

The characters used are translated from the client’s code page to an EBCDIC code page before transmission. If the server uses an ASCII code page, they will be retranslated. The only characters guaranteed to be invariant under these translations are the uppercase characters A to Z, and the numeric characters 0 to 9. Some EBCDIC servers (Katakana and Hebrew character set A) do not use the standard representations of the lowercase alphabetic characters; use them with care when communicating with such servers.

eci_userid
Required input parameter.

An 8-character field containing a user ID. Pad unused characters with spaces.

Consult the documentation for the CICS Transaction Gateway and the server to check whether this field is converted to upper case before being transmitted to the server. If a user ID or password longer than 8 characters is required, set eci_userid and eci_password to nulls, and use fields eci_userid2 and eci_password2 instead.

If a user ID is supplied, the server uses the user ID and any supplied password to authenticate the user. The supplied user ID and password are used in subsequent security checking in the server.

eci_password
Required input parameter.

An 8-character field containing a password. Pad unused characters with spaces.

Consult the documentation for the CICS Transaction Gateway and the server to check whether this field is converted to upper case before being transmitted to the server. If a user ID or password longer than 8 characters is required, set this field and eci_userid to nulls, and use fields eci_userid2 and eci_password2 instead.

eci_transid
Optional input parameter

A 4-character field optionally containing the ID of a CICS transaction. Pad unused characters with spaces. The parameter is ignored if eci_tpn is used (set to any value other than nulls). The use of this parameter depends on the client from which the request is sent. The value of eci_transid is converted from ASCII to EBCDIC, with no upper case translation, and stored in EIBTRNID for the duration of the LINK to the program specified in the eci_program_name.

The called program runs under the mirror transaction CPMI, but is linked to under the eci_transid transaction name. This name is available to the called program for querying the transaction ID. Some servers use the transaction ID to determine security and performance attributes for the called program. In those servers, use this parameter to control the processing of your called programs.

If the ECI request is extended (see the description of eci_extend_mode), the eci_transid parameter has a meaning only for the first call in the unit of work.

If the field is all nulls, and eci_tpn is not specified, the default server transaction ID is used.

eci_abend_code
Output parameter.

A 4-character field in which a CICS abend code is returned if the transaction that executes the called program abends. Unused characters are padded with spaces.

eci_commarea
Optional input parameter.

A pointer to the data to be passed to the called CICS program as its COMMAREA. The COMMAREA will be used by the called program to return information to the application.

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
Optional 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_timeout
The time in seconds to wait for a response from the CICS server. A value of 0 means that no limit is set.

If timeout occurs, the conversation is abended.

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 CICS Transaction Gateway's error log.

eci_extend_mode
Required input parameter.

An integer field determining whether a logical unit of work is terminated at the end of this call.) (See the Logical units of work in ECI table in CICS Transaction Gateway: Programming Guide for more details.)

The values for this field (shown by their symbolic names) are as follows:
ECI_NO_EXTEND
  1. If the input eci_luw_token field is zero, this is the only call for a logical unit of work.
  2. If the input eci_luw_token field is not zero, this is the last call for the specified logical unit of work.

In either case, changes to recoverable resources are committed by a CICS end-of-task syncpoint, and the logical unit of work ends.

If you set eci_extend_mode to ECI_NO_EXTEND and eci_luw_token to 0, you will observe one request flowing from client to server and one reply flowing from server to client. The server sends the reply after the program specified in eci_program_name has been invoked and the changes made by that program have been committed.

ECI_EXTENDED
  1. If the input eci_luw_token field is zero, this is the first call for a logical unit of work that is to be continued.
  2. If the input eci_luw_token field is not zero, this call is intended to continue the specified logical unit of work.
In either case the logical unit of work continues after the called program completes successfully, and changes to recoverable resources remain uncommitted.
ECI_COMMIT
Terminate the current logical unit of work, identified by the input eci_luw_token field, and commit all changes made to recoverable resources.
ECI_BACKOUT
Terminate the logical unit of work identified by the input eci_luw_token field, and back out all changes made to recoverable resources.
eci_luw_token
Required input and output parameter.

An integer field used for identifying the logical unit of work to which a call belongs. It must be set to zero at the start of a logical unit of work (regardless of whether the logical unit of work is going to be extended). If the logical unit of work is to be extended, the ECI updates eci_luw_token with a valid value on the first call of the logical unit of work, and this value should be used as input to all later calls related to the same logical unit of work. (See the Logical units of work in ECI table in CICS Transaction Gateway: Programming Guide for more details.)

If the return code is not ECI_NO_ERROR, and the call was continuing or ending an existing logical unit of work, this field is used as output to report the condition of the logical unit of work. If it is set to zero, the logical unit of work has ended, and its updates have been backed out. If it is nonzero, it is the same as the input value, the logical unit of work is continuing, and its updates are still pending.

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.

eci_system_name
Optional input parameter.

An 8-character field that specifies the name of the server to which the ECI request is to be directed. Pad unused characters with spaces. If supplied, it should be one of the server names returned by CICS_EciListSystems. The value may be supplied whenever eci_luw_token is set to zero. (If it is supplied when eci_luw_token is not zero, it is ignored, because the server was established at the start of the logical unit of work.)

If the field is set to nulls, the default server is selected; the name of the chosen server is returned in this field, and must be used in subsequent related ECI requests. If ECI requests made in different logical units of work must be directed to the same server, eci_system_name must identify that server by name.

eci_userid2
Optional input parameter.

If the eci_userid field is set to nulls, the eci_userid2 field specifies the user ID (if any) to be used at the server for any authority validation. The user ID can be up to 16 characters.

See the description of the eci_userid field for information about how the user ID is used.

eci_password2
Optional input parameter.

If the eci_password field is set to nulls, the eci_password2 field specifies the password (if any) to be used at the server for any authority validation. The password can be up to 16 characters.

See the description of the eci_password field for information about how the password is used.

eci_tpn
Optional input parameter.

A 4-character field that specifies the transaction ID of the transaction that will be used in the server to process the ECI request. This transaction must be defined in the server as a CICS mirror transaction. If the field is not set, the default mirror transaction CPMI is used.

If the ECI request is extended (see the description of eci_extend_mode), this parameter has a meaning only for the first request.

If this field is used, the contents of eci_transid are ignored.

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_NO_CICS
The CICS Transaction Gateway is unavailable, or the server implementation is unavailable, or a logical unit of work was to be begun, but the CICS server specified in eci_system_name is not available. No resources have been updated.
ECI_ERR_CICS_DIED
A logical unit of work was to be begun or continued, 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_TRANSACTION_ABEND
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_LUW_TOKEN
The value supplied in eci_luw_token is invalid.
ECI_ERR_ALREADY_ACTIVE
An attempt was made to continue an existing logical unit of work, but there was an outstanding asynchronous call for the same logical unit of work.
ECI_ERR_RESOURCE_SHORTAGE
The server implementation or the Client daemon did not have enough resources to complete the request.
ECI_ERR_NO_SESSIONS
A new logical unit of work was being created, but the application already has as many outstanding logical units of work as the configuration will support.
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
An attempt was made 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 requested server could not be located. Only servers returned by CICS_EciListSystems are acceptable.
ECI_ERR_MAX_SESSIONS
This is returned if the MAXREQUESTS limit, as defined in your configuration file, was exceeded.
ECI_ERR_MAX_SYSTEMS
You tried 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.