CTG_ECI_PARMS Struct Reference

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

#include <ctgclient_eci.h>

Data Fields


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() 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: Programming Guide, 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 Information Center: Programming Guide, search for title "Data conversion".

Note:
Text strings are NOT null-terminated.

Definition at line 72 of file ctgclient_eci.h.


Field Documentation

signed short commarea_inbound_length
 

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 346 of file ctgclient_eci.h.

signed short commarea_outbound_length
 

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 338 of file ctgclient_eci.h.

char eci_abend_code[4]
 

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 spaces are returned.

Definition at line 169 of file ctgclient_eci.h.

signed short eci_call_type
 

Identifies the type of ECI flow.

A required input parameter. The call type identifies the type of the ECI flow. 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. The calling application does not get control back until 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, then 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, then 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, then 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 114 of file ctgclient_eci.h.

void* eci_commarea
 

The data passed to and returned from the CICS program.

An optional input parameter, a pointer to the data to be passed as the COMMAREA of the CICS program identified by eci_program_name. If no COMMAREA is required, supply a null pointer and set the 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 program, if one was sent

Definition at line 180 of file ctgclient_eci.h.

signed short eci_commarea_length
 

The length of the eci_commarea.

The length of the COMMAREA in bytes. This is used by the interface as the maximum length of the eci_commarea. The COMMAREA lengths for sending and receiving data should be defined by commarea_outbound_length and commarea_inbound_length.

Application developers are advised to 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 return code.

Definition at line 194 of file ctgclient_eci.h.

signed short eci_extend_mode
 

Extend mode defines the behaviour of the ECI flow.

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

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 it is the only call for a logical unit of work.
    2. If the input eci_luw_token field is not zero it is the last call for the specified logical unit of work.
    In each case, changes to recoverable resources are committed by a CICS end-of-task sync point, and the logical unit of work ends.

  • ECI_EXTENDED
    1. If the input eci_luw_token field is zero, it 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 each 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.

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

Definition at line 256 of file ctgclient_eci.h.

signed int eci_luw_token
 

This token identifies the logical unit of work to which the ECI flow is associated.

An integer field is used for identifying the logical unit of work to which a call belongs. The eci_luw_token must be set to ECI_LUW_NEW or 0 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 0, 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 eci_luw_token field must be set to 0 when eci_extend_mode is ECI_NO_EXTEND

Definition at line 282 of file ctgclient_eci.h.

signed int eci_message_qualifier
 

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 361 of file ctgclient_eci.h.

char eci_password[16]
 

Password for security checking.

The eci_password has a maximum length of 16 characters.

Definition at line 140 of file ctgclient_eci.h.

char eci_program_name[8]
 

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 Information Center: Programming Guide, search for title "Data conversion".

Definition at line 128 of file ctgclient_eci.h.

char eci_system_name[8]
 

Server name.

An optional input parameter.

An 8 character field that specifies the name of the server to which the ECI request is to be directed. If supplied, it must be one of the server names returned by CTG_listSystems, with the exception that, if connected to a z/OS gateway, it is possible to pass the APPLID of a CICS region which the gateway then communicates with using EXCI. Pad unused characters with spaces or nulls. If the server name is supplied when eci_luw_token is not zero, the server name is ignored, as all requests within a logical unit of work must be sent to the same server.

If the field is set to nulls, the default server defined in the Gateway daemon is used.

Definition at line 314 of file ctgclient_eci.h.

signed short eci_timeout
 

Timeout in seconds.

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

If timeout occurs, the conversation is abended.

Definition at line 202 of file ctgclient_eci.h.

char eci_tpn[4]
 

A transaction identifier for the mirror transaction.

Optional input parameter. A 4-character field that specifies the transaction ID that is used by 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 set, the contents of eci_transid are ignored.

Definition at line 331 of file ctgclient_eci.h.

char eci_transid[4]
 

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 (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.

Definition at line 161 of file ctgclient_eci.h.

char eci_userid[16]
 

Userid for security checking.

The eci_userid has a maximum length of 16 characters.

Definition at line 134 of file ctgclient_eci.h.

signed short eci_version
 

ECI version identifier.

A required input parameter that identifies the version of the ECI for which the application is coded. This field must be set to ECI_VERSION_2 or ECI_VERSION_S1. ECI_VERSION_2 is provided for compatibility with existing applications that use only the ECI_SYNC call type. ECI_VERSION_S1 must be used for asynchronous call support.

Definition at line 296 of file ctgclient_eci.h.

void* reserved1
 

Definition at line 364 of file ctgclient_eci.h.


© Copyright IBM Corporation 2011, 2012. All rights reserved.
For legal information, see http://www.ibm.com/legal/copytrade.shtml