CTG_ECI_PARMS Struct Reference

#include <ctgclient_eci.h>

Detailed Description

The Version 2 External Call Interface (ECI) parameter block.

The CTG_ECI_PARMS structure is the parameter block used when communicating with a CICS server. The parameter block fields are used for input and output. To communicate with the CICS server through the Gateway daemon use the CTG_ECI_Execute() or CTG_ECI_Execute_Channel() function.

Set the ECI parameter block to nulls before setting the input parameter fields.

Guidance on how to use the ECI to manage logical units of work can be found in the CICS Transaction Gateway Information Center, search for "Managing logical units of work".

The ECI parameter block is transmitted to the Gateway daemon without any code page conversion. For more information on managing code pages refer to the CICS Transaction Gateway Information Center, search for title "Data conversion".

Note
Text strings are NOT null-terminated.

Definition at line 92 of file ctgclient_eci.h.

Field Documentation

Channel token for use with CTG_ECI_ExecuteChannel().

An input parameter for an ECI request invoking a CICS channel program, specify the channel token obtained from ECI_createChannel(). For reply solicitation calls this is an output parameter, used to return the channel token for the returned channel. For an ECI request invoking a CICS COMMAREA program this value is ignored.

Definition at line 426 of file ctgclient_eci.h.

Maximum data length to receive from the Gateway daemon.

If the commarea_inbound_length is set to 0 or is greater than eci_commarea_length, the value of eci_commarea_length is used instead of commarea_inbound_length.

Definition at line 418 of file ctgclient_eci.h.

Maximum data length to send to the Gateway daemon.

If commarea_outbound_length is set to 0 or is greater than eci_commarea_length, the value of eci_commarea_length is used instead of commarea_outbound_length.

Definition at line 412 of file ctgclient_eci.h.

CICS abend code.

An output parameter, a 4 character field in which a CICS abend code is returned. If the transaction that executes the called program does not abend, the field contains space characters on return.

Definition at line 221 of file ctgclient_eci.h.

Identifies the type of ECI flow.

A required input parameter. The call type identifies the type of the ECI flow. Asynchronous call types require the eci_version field to be set to ECI_VERSION_2A. The valid values are:

  • ECI_SYNC
    The ECI_SYNC call type provides a synchronous program link call to start, continue, or complete a logical unit of work. Control is returned to the application once the called CICS program has run to completion.
  • ECI_ASYNC
    The ECI_ASYNC call type provides and asynchronous program link call to start, continue, or complete a logical unit of work. Control is returned to the application once the ECI request has been sent to the Gateway daemon.
  • ECI_GET_REPLY
    The ECI_GET_REPLY call type provides a reply solicitation call that returns one of the available replies. If there is no reply available, ECI_ERR_NO_REPLY is returned.
  • ECI_GET_REPLY_WAIT
    The ECI_GET_REPLY_WAIT call type provides a reply solicitation call that returns one of the available replies. If there is no reply available, the call waits until a reply is available.
  • ECI_GET_SPECIFIC_REPLY
    The ECI_GET_SPECIFIC_REPLY call type provides a reply solicitation call that returns the reply for the asynchronous request identified by eci_message_qualifier. If there is no reply available, ECI_ERR_NO_REPLY is returned.
  • ECI_GET_SPECIFIC_REPLY_WAIT
    The ECI_GET_SPECIFIC_REPLY_WAIT call type provides a reply solicitation call that returns the reply for the asynchronous request identified by eci_message_qualifier. If there is no reply available, the call waits until the reply is available.

Definition at line 156 of file ctgclient_eci.h.

The COMMAREA data passed to and returned from the CICS program.

An optional input parameter, a pointer to the data to be passed in the COMMAREA to the CICS program identified by eci_program_name. If no COMMAREA is required, supply a null pointer and set eci_commarea_length to zero. The COMMAREA is also an output field, it can be used by the called program to return information to the application. A COMMAREA can only be returned from the called program, if one was sent.

Definition at line 231 of file ctgclient_eci.h.

The length of the COMMAREA.

The maximum length of the COMMAREA in bytes. The COMMAREA lengths for sending and receiving data can be defined using the commarea_outbound_length and commarea_inbound_length parameters.

Use a maximum size of 32500 bytes, as this is guaranteed to be flowed successfully across all protocols. COMMAREA sizes greater than this may generate an ECI_ERR_INVALID_DATA_LENGTH error.

Definition at line 242 of file ctgclient_eci.h.

Extend mode defines the behaviour of the ECI flow.

A required input parameter that defines how a logical unit of work is processed.

The valid values are:

  • ECI_NO_EXTEND

    1. If the eci_luw_token is zero, this call is the only call for the logical unit of work.
    2. If the eci_luw_token is not zero, this call is the last call for the specified logical unit of work.

    In each case, if no error occurs, changes to recoverable resources are committed by a CICS end-of-task sync point, and the logical unit of work ends. If an error occurs, changes to recoverable resources are backed out and the logical unit of work ends.

  • ECI_EXTENDED

    1. If the eci_luw_token is zero, this call is the first call for a logical unit of work that is to be continued.
    2. If the eci_luw_token is not zero, this call continues the specified logical unit of work.

    In each case, the logical unit of work continues and changes to recoverable resources remain uncommitted.

  • ECI_COMMIT
    Terminates the logical unit of work, identified by the eci_luw_token, and commits all changes made to recoverable resources.

  • ECI_BACKOUT
    Terminates the logical unit of work, identified by the eci_luw_token, and backs out all changes made to recoverable resources.

For guidance on how to use the ECI to manage logical units of work, refer to the CICS Transaction Gateway Information Center, search for "Managing logical units of work".

Definition at line 320 of file ctgclient_eci.h.

The token identifies the logical unit of work to which the ECI request is associated.

An integer field used for identifying the logical unit of work to which a call belongs. The eci_luw_token must be set to ECI_LUW_NEW 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, the returned value must be used as the input value for all subsequent calls that are part of the same logical unit of work.

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. The LUW token must be set to zero when eci_extend_mode is ECI_NO_EXTEND

Definition at line 346 of file ctgclient_eci.h.

Identifier for an asynchronous request reply.

For ECI_ASYNC calls, this field is an output parameter containing the identifier that can be used to get the response to this specific request.

For ECI_GET_SPECIFIC_REPLY and ECI_GET_SPECIFIC_REPLY_WAIT calls, this field is an input parameter specifying the identifier of the asynchronous response to be returned.

For other call types, this field is not used.

Definition at line 457 of file ctgclient_eci.h.

Password field provided for compatibility with existing applications.

For new applications, use the eci_password_ptr field; this supports password phrases longer than 16 characters.

Definition at line 190 of file ctgclient_eci.h.

Pointer to a null terminated string containing a password or password phrase.

To use this field, set eci_version to ECI_VERSION_2A.

Set this field to null if a password or password phrase is not required. The maximum field length depends on the CICS server version and communications protocol type. For more information see your CICS server documentation.

Definition at line 443 of file ctgclient_eci.h.

The CICS program to run.

An input parameter, the CICS program name is required except when eci_extend_mode is ECI_COMMIT or ECI_BACKOUT.

An 8 character field containing the name of the program to be called. Pad unused characters with spaces or nulls. To avoid code page conversion issues it is recommended to use uppercase characters A to Z, and the numeric characters 0 to 9. For more information on managing code pages refer to the CICS Transaction Gateway Information Center, search for the title "Data conversion".

Definition at line 172 of file ctgclient_eci.h.

Server name.

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 or nulls. Set the server name for each request that starts a new logical unit of work. The server name is ignored for subsequent requests in an extended LUW, as all requests for an extended LUW must be sent to the same server.

To use a default CICS server, set eci_system_name to nulls.

Definition at line 386 of file ctgclient_eci.h.

The ECI request timeout.

The time in seconds to wait for a response from the CICS server. A value of zero means that no time limit is set.

An ECI timeout value of zero indicates that this ECI request will not be timed out by CICS Transaction Gateway. An ECI timeout value greater than zero indicates that this ECI request might be timed out by CICS Transaction Gateway. When an ECI timeout expires, the associated unit of work in CICS might have already completed or might have been backed out. This information is not available to the client application.

If using remote mode IPIC connections, this value can be overridden by the ECITIMEOUT parameter on the IPIC server definition in the CICS Transaction Gateway configuration file.

Definition at line 259 of file ctgclient_eci.h.

A transaction identifier for the mirror transaction.

Optional input parameter. A 4-character field that specifies the transaction ID 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 CICS mirror transaction is used.

If the ECI request is extended (see the description of eci_extend_mode), this parameter is used only for the first request. Subsequent requests within the same unit of work will use the transaction specified on the first request.

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

Definition at line 406 of file ctgclient_eci.h.

A CICS transaction identifier.

A 4 character field optionally containing the ID of a CICS transaction. Pad unused characters with spaces or nulls. The parameter is ignored if eci_tpn is used. The value of eci_transid is stored in the CICS server EIBTRNID field for the duration of the LINK to the program specified in the eci_program_name.

The called program runs under the default CICS mirror transaction, 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.

Definition at line 210 of file ctgclient_eci.h.

User ID field provided for compatibility with existing applications.

For new applications, use the eci_userid_ptr field; this supports user IDs longer than 16 characters.

Definition at line 181 of file ctgclient_eci.h.

Pointer to a null terminated string containing a user ID.

To use this field, set eci_version to ECI_VERSION_2A.

Set this field to null if a user ID is not required. The maximum supported field length depends on the CICS server version. For more information see your CICS server documentation.

Definition at line 434 of file ctgclient_eci.h.

ECI version identifier.

A required input parameter that identifies the version of the ECI, for which the application is coded, to CICS Transaction Gateway. This field must be set to ECI_VERSION_2 or ECI_VERSION_2A. ECI_VERSION_2 is provided for compatibility with existing applications that use the ECI_SYNC call type and the eci_userid and eci_password fields. ECI_VERSION_2A must be used for asynchronous call support.

Definition at line 370 of file ctgclient_eci.h.