The ECI_SYNC call type is available in all environments.
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.
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.
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 uppercase 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.
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 uppercase 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.
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 uppercase 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 field is all nulls, and eci_tpn is not specified, the default server transaction ID is used.
A 4-character field in which a CICS abend code is returned if the transaction that executes the called program ends abnormally. Unused characters are padded with spaces.
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.
The length of the COMMAREA in bytes. Application developers are advised to use a maximum size of 32,500 bytes because this is guaranteed to be flowed successfully across all protocols. COMMAREA sizes greater than this might cause an ECI_ERR_INVALID_DATA_LENGTH return code to be generated.
If no COMMAREA is required, set this field to zero and supply a null pointer in eci_commarea.
If timeout occurs, the conversation ends abnormally.
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.
An integer field determining whether a logical unit of work is terminated at the end of this call. (See Managing logical units of work for more details.)
In each case, changes to recoverable resources are committed by a CICS end-of-task sync point, 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.
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 is used as input to all later calls related to the same logical unit of work. (See Managing logical units of work 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.
Reserved for future use, but initialize this field with nulls before the start of each logical unit of work.
The version of the ECI for which the application is coded. Use the value ECI_VERSION_1A.
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 is one of the server names returned by CICS_EciListSystems. The value can 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 CICS 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.
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.
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.
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 in the unit of work. Subsequent requests within the same unit of work will use the mirror transaction specified on the first request.
If this field is used, the contents of eci_transid are ignored.