com.ibm.ctg.client

Class ECIRequest

  • All Implemented Interfaces:
    ECIReturnCodes, GatewayReturnCodes


    public class ECIRequest
    extends GatewayRequest
    implements ECIReturnCodes
    This class contains the details of an ECI request to the CICS Transaction Gateway. To execute the request, the ECIRequest object should be flowed to the Gateway using the JavaGateway.flow method
    To reduce the amount of data transmitted from the gateway daemon to the user application, the Gateway uses a process known as "null stripping" to remove trailing zeros from the COMMAREA automatically so that they are not transmitted over the network. Alternatively, you can use the setCommareaInboundLength method to reduce the amount of data transmitted. The Gateway does not strip trailing zeros if the setCommareaInboundLength method is used. See the CICS Transaction Gateway Programming Guide for more information about null stripping.

    Data contained within the COMMAREA cannot be assumed to remain unchanged between calls, for example, after a call to commit a transaction.

    The maximum COMMAREA size that can be flowed successfully to CICS depends upon various factors, including the server communication protocol being used and the amount of non-zero data in the COMMAREA. 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.
    See Also:
    GatewayRequest
    • Field Detail

      • ECI_GET_REPLY

        public static final int ECI_GET_REPLY
        In local mode, use this call type to get any reply to an asynchronous call. In remote mode, requests that use this call type return ECI_ERR_INVALID_CALL_TYPE.

        If a call of this type fails because the COMMAREA is too small, CICS TG sets Commarea_Length to the minimum size needed to store the reply. Interrogate the Commarea_Length integer to find out how big the COMMAREA needs to be, create a new COMMAREA of the right size and reissue the call.

        See Also:
        Constant Field Values
      • ECI_GET_REPLY_WAIT

        public static final int ECI_GET_REPLY_WAIT
        In local mode, use this call type to await any reply to an asynchronous call. In remote mode, requests that use this call type return ECI_ERR_INVALID_CALL_TYPE.

        If a call of this type fails because the COMMAREA is too small, CICS TG sets Commarea_Length to the minimum size needed to store the reply. Interrogate the Commarea_Length integer to find out how big the COMMAREA needs to be, create a new COMMAREA of the right size and reissue the call.

        See Also:
        Constant Field Values
      • ECI_GET_SPECIFIC_REPLY

        public static final int ECI_GET_SPECIFIC_REPLY
        Get a specific asynchronous reply.

        If a call of this type fails because the COMMAREA is too small, CICS TG sets Commarea_Length to the minimum size needed to store the reply. Interrogate the Commarea_Length integer to find out how big the COMMAREA needs to be, create a new COMMAREA of the right size and reissue the call.

        See Also:
        Constant Field Values
      • ECI_GET_SPECIFIC_REPLY_WAIT

        public static final int ECI_GET_SPECIFIC_REPLY_WAIT
        Await a specific asynchronous reply.

        If a call of this type fails because the COMMAREA is too small, CICS TG sets Commarea_Length to the minimum size needed to store the reply. Interrogate the Commarea_Length integer to find out how big the COMMAREA needs to be, create a new COMMAREA of the right size and reissue the call.

        See Also:
        Constant Field Values
      • ECI_STATE_SYNC

        public static final int ECI_STATE_SYNC
        Synchronous request for status information.
        See Also:
        Constant Field Values
      • ECI_STATE_ASYNC

        public static final int ECI_STATE_ASYNC
        Asynchronous request for status.
        See Also:
        Constant Field Values
      • CICS_EciListSystems

        public static final int CICS_EciListSystems
        List CICS servers.
        See Also:
        Constant Field Values
      • ECI_STATE_SYNC_JAVA

        @Deprecated
        public static final int ECI_STATE_SYNC_JAVA
        Deprecated. The getStatus(String) method of ECIRequest should be used to retrieve immediate synchronous status information about a CICS server.
        See Also:
        Constant Field Values
      • ECI_STATE_ASYNC_JAVA

        @Deprecated
        public static final int ECI_STATE_ASYNC_JAVA
        Deprecated. The getStatus(String,int,Callbackable) method of ECIRequest should be used to retrieve immediate asynchronous status information about a CICS server.
        See Also:
        Constant Field Values
      • ECI_SYNC_TPN

        public static final int ECI_SYNC_TPN
        Synchronous call with eci_tpn.

        Synchronous call with the Transid field representing eci_tpn. Refer to the CICS Transaction Gateway Information Center for more information on the difference between eci_transid and eci_tpn.

        See Also:
        Constant Field Values
      • ECI_ASYNC_TPN

        public static final int ECI_ASYNC_TPN
        Asynchronous call with eci_tpn.

        Asynchronous call with the Transid field representing eci_tpn. Refer to the CICS Transaction Gateway Information Center for more information on the difference between eci_transid and eci_tpn.

        See Also:
        Constant Field Values
      • ECI_NO_EXTEND

        public static final int ECI_NO_EXTEND
        Non-extended LUW call, or the last call in a LUW.
        See Also:
        Constant Field Values
      • ECI_EXTENDED

        public static final int ECI_EXTENDED
        This request is part of an Extended Logical Unit of Work.
        See Also:
        Constant Field Values
      • ECI_COMMIT

        public static final int ECI_COMMIT
        End LUW and commit changes.
        See Also:
        Constant Field Values
      • ECI_CANCEL

        @Deprecated
        public static final int ECI_CANCEL
        Deprecated. End LUW and commit changes, exactly the same as ECI_COMMIT.
        See Also:
        Constant Field Values
      • ECI_BACKOUT

        public static final int ECI_BACKOUT
        End LUW and backout changes.
        See Also:
        Constant Field Values
      • ECI_STATE_IMMEDIATE

        public static final int ECI_STATE_IMMEDIATE
        Return state information immediately.
        See Also:
        Constant Field Values
      • ECI_STATE_CHANGED

        public static final int ECI_STATE_CHANGED
        Return state information when the CICS Server changes state e.g. up to down or vica verca.
        See Also:
        Constant Field Values
      • ECI_STATE_CANCEL

        public static final int ECI_STATE_CANCEL
        Cancel a previous request to be alerted on a state change
        See Also:
        Constant Field Values
      • ECI_STATUS_LENGTH

        public static final int ECI_STATUS_LENGTH
        Length of COMMAREA needed for status information.
        See Also:
        Constant Field Values
      • ECI_CONNECTED_NOWHERE

        public static final short ECI_CONNECTED_NOWHERE
        Return value from a getStatus() call.
        See Also:
        Constant Field Values
      • ECI_CONNECTED_TO_SERVER

        public static final short ECI_CONNECTED_TO_SERVER
        Return value from a getStatus() call.
        See Also:
        Constant Field Values
      • ECI_CONNECTED_TO_CLIENT

        public static final short ECI_CONNECTED_TO_CLIENT
        Return value from a getStatus() call.
        See Also:
        Constant Field Values
      • ECI_SERVERSTATE_UNKNOWN

        public static final short ECI_SERVERSTATE_UNKNOWN
        Return value from a getStatus() call.
        See Also:
        Constant Field Values
      • ECI_SERVERSTATE_UP

        public static final short ECI_SERVERSTATE_UP
        Return value from a getStatus() call.
        See Also:
        Constant Field Values
      • ECI_SERVERSTATE_DOWN

        public static final short ECI_SERVERSTATE_DOWN
        Return value from a getStatus() call.
        See Also:
        Constant Field Values
      • ECI_CLIENTSTATE_UNKNOWN

        public static final short ECI_CLIENTSTATE_UNKNOWN
        Return value from a getStatus() call.
        See Also:
        Constant Field Values
      • ECI_CLIENTSTATE_UP

        public static final short ECI_CLIENTSTATE_UP
        Return value from a getStatus() call.
        See Also:
        Constant Field Values
      • ECI_CLIENTSTATE_INAPPLICABLE

        public static final short ECI_CLIENTSTATE_INAPPLICABLE
        Return value from a getStatus() call.
        See Also:
        Constant Field Values
      • Call_Type

        public int Call_Type
        CICS ECI call type. The default value is ECI_SYNC.
      • Extend_Mode

        public int Extend_Mode
        Extend mode of request. The default value is ECI_NO_EXTEND.
      • Luw_Token

        public int Luw_Token
        Extended Logical Unit of Work token. The default value is ECI_LUW_NEW.
      • Server

        public java.lang.String Server
        CICS server to direct request to. The default value is null. If this is left unset, the default server defined in the gateway is used.
      • Userid

        public java.lang.String Userid
        User ID for CICS server. The default value is null.
      • Password

        public java.lang.String Password

        Password or password phrase for CICS server. The maximum supported password or password phrase length varies by CICS server and communication protocol. Refer to your CICS server documentation for details.

        The default value is null.

      • Program

        public java.lang.String Program
        Program to invoke on CICS server. The default value is null.
      • Transid

        public java.lang.String Transid
        Transaction ID to run CICS program under. The default value is null.

        If Call_Type is set to ECI_SYNC_TPN or ECI_ASYNC_TPN, this field specifies the mirror transaction that the called program runs under. If the request is extended, this field has a meaning only for the first request within a logic unit of work. Subsequent requests within the same unit of work will use the mirror transaction specified on the first request.

        If Call_Type is set to ECI_SYNC or ECI_ASYNC, the called program runs under the default CICS mirror transaction but is linked to under the transaction specified in this field. The transaction identifier is stored in EIBTRNID for the duration of the LINK to the CICS program, so it is available to the called program. Some servers use the transaction identifier to determine security and performance attributes for the called program. In those servers, use this property to control the processing of called programs.

      • Commarea_Length

        public int Commarea_Length
        Length of COMMAREA. The default value is 0.
      • Commarea

        public byte[] Commarea
        COMMAREA to be passed to the CICS program. The default value is null.
      • Cics_Rc

        public int Cics_Rc
        CICS ECI return code.
      • Abend_Code

        public java.lang.String Abend_Code
        CICS transaction abend code.
      • SystemList

        public java.util.Vector<java.lang.String> SystemList
        List of known systems and system descriptions following a listSystems(int) call.

        On return from a CICS_EciListSystems call, this vector is filled with Strings containing system names and system descriptions. Entries with even indices contain system names, and those with odd indices contain system descriptions.

      • ConnectionType

        public int ConnectionType
        After getStatus(), shows type of CICS system.
      • CicsServerStatus

        public int CicsServerStatus
        After getStatus(), shows status of CICS server.
      • CicsClientStatus

        public int CicsClientStatus
        After getStatus(), shows status of the Client daemon.
      • maxNumServers

        public int maxNumServers
        Maximum number of CICS servers about which information is to be returned (see listSystems()).
      • numServersKnown

        public int numServersKnown
        Number of CICS servers which are defined (output from listSystems() flow).
      • numServersReturned

        public int numServersReturned
        Number of CICS servers about which information has been returned (output from listSystems() flow).
      • channel

        public Channel channel
        The Channel to be passed to the CICS program. The default value is null.
    • Constructor Detail

      • ECIRequest

        public ECIRequest()
        Default constructor, which leaves all the values set to their defaults. The defaults are: Server = null, Userid = null, Password = null, Program = null, commarea = null, extend mode = ECI_NO_EXTEND, luw token = ECI_LUW_NEW, call type = ECI_SYNC, transaction id = null.

        Since all the valid ECIRequest parameters are public data members you can set them by hand if required.

      • ECIRequest

        public ECIRequest(java.lang.String strServer,
                  java.lang.String strUserid,
                  java.lang.String strPassword,
                  java.lang.String strProgram,
                  byte[] abytCommarea,
                  int iExtendMode,
                  int iLuwToken)
        Creates an ECIRequest object with commarea for a simple synchronous call. It takes the relevant parameters for a simple synchronous call, and sets the contents of the object.
        Parameters:
        strServer - CICS server name to make request to (default used if not set)
        strUserid - CICS userid to use
        strPassword - CICS password or password phrase to use
        strProgram - CICS program to be run on the server
        abytCommarea - Byte array containing the COMMAREA to pass to CICS
        iExtendMode - ECI extend mode
        iLuwToken - ECI LUW token
      • ECIRequest

        public ECIRequest(int iCallType,
                  java.lang.String strServer,
                  java.lang.String strUserid,
                  java.lang.String strPassword,
                  java.lang.String strProgram,
                  java.lang.String strTransid,
                  byte[] abytCommarea)
        Creates an ECIRequest object with commarea for a basic request using the most commonly used ECI parameters. This constructor takes the most commonly used ECI parameters and sets the contents of the object.

        The length of the COMMAREA is assumed to be the length of the byte array passed in via the abytCommarea parameter.

        Parameters:
        iCallType - ECI call type
        strServer - CICS server name to make request to (default used if not set)
        strUserid - CICS userid to use
        strPassword - CICS password or password phrase to use
        strProgram - CICS program to be run on the server
        strTransid - CICS transid to be run on the server
        abytCommarea - Byte array containing the COMMAREA to pass to CICS
      • ECIRequest

        public ECIRequest(int iCallType,
                  java.lang.String strServer,
                  java.lang.String strUserid,
                  java.lang.String strPassword,
                  java.lang.String strProgram,
                  java.lang.String strTransid,
                  byte[] abytCommarea,
                  int iCommareaLength,
                  int iExtendMode,
                  int iLuwToken)
        Creates an ECIRequest object with commarea which expands on the basic values to allow Extended Logical Unit-of-Work requests.

        It also accepts a COMMAREA length parameter. This should be set to less than or equal to the length of the byte array passed in via the abytCommarea parameter.

        Parameters:
        iCallType - ECI call type
        strServer - CICS server name to make request to (default used if not set)
        strUserid - CICS userid to use
        strPassword - CICS password or password phrase to use
        strProgram - CICS program to be run on the server
        strTransid - CICS transid to be run on the server
        abytCommarea - Byte array containing the COMMAREA to pass to CICS
        iCommareaLength - COMMAREA length
        iExtendMode - ECI extend mode
        iLuwToken - ECI LUW token
      • ECIRequest

        public ECIRequest(int iCallType,
                  java.lang.String strServer,
                  java.lang.String strUserid,
                  java.lang.String strPassword,
                  java.lang.String strProgram,
                  java.lang.String strTransid,
                  byte[] abytCommarea,
                  int iCommareaLength,
                  int iExtendMode,
                  int iLuwToken,
                  int iMessageQualifier,
                  Callbackable callBack)
        Creates an ECIRequest object with commarea for ECI asynchronous call types.
        Parameters:
        iCallType - ECI call type
        strServer - CICS server name to make request to (default used if not set)
        strUserid - CICS userid to use
        strPassword - CICS password or password phrase to use
        strProgram - CICS program to be run on the server
        strTransid - CICS transid to be run on the server
        abytCommarea - Byte array containing the COMMAREA to pass to CICS
        iCommareaLength - COMMAREA length
        iExtendMode - ECI extend mode
        iLuwToken - ECI LUW token
        iMessageQualifier - Application provided identifier
        callBack - ECI Callbackable object. This may be null if no callback is required.
      • ECIRequest

        public ECIRequest(java.lang.String strServer,
                  java.lang.String strUserid,
                  java.lang.String strPassword,
                  java.lang.String strProgram,
                  Channel channel,
                  int iExtendMode,
                  int iLuwToken)
        Creates an ECIRequest object with a Channel using the most commonly used ECI parameters. This constructor takes the most commonly used ECI parameters and sets the contents of the object.
        Parameters:
        strServer - CICS server name to make request to (default used if not set)
        strUserid - CICS userid to use
        strPassword - CICS password or password phrase to use
        strProgram - CICS program to be run on the server
        channel - Channel with containers to pass to CICS
        iExtendMode - ECI extend mode
        iLuwToken - ECI LUW token
      • ECIRequest

        public ECIRequest(int iCallType,
                  java.lang.String strServer,
                  java.lang.String strUserid,
                  java.lang.String strPassword,
                  java.lang.String strProgram,
                  java.lang.String strTransid,
                  Channel channel,
                  int iExtendMode,
                  int iLuwToken)
        Creates an ECIRequest object with a Channel to make Extended Logical Unit-of-Work requests.

        It takes a Channel parameter instead of commarea.

        Parameters:
        iCallType - ECI call type
        strServer - CICS server name to make request to (default used if not set)
        strUserid - CICS userid to use
        strPassword - CICS password or password phrase to use
        strProgram - CICS program to be run on the server
        strTransid - CICS transid to be run on the server
        channel - Channel with containers to pass to CICS
        iExtendMode - ECI extend mode
        iLuwToken - ECI LUW token
      • ECIRequest

        public ECIRequest(int iCallType,
                  java.lang.String strServer,
                  java.lang.String strUserid,
                  java.lang.String strPassword,
                  java.lang.String strProgram,
                  java.lang.String strTransid,
                  Channel channel,
                  int iExtendMode,
                  int iLuwToken,
                  int iMessageQualifier,
                  Callbackable callBack)
        Creates an ECIRequest object with a Channel for ECI asynchronous call types.

        It takes a Channel parameter instead of commarea.

        Parameters:
        iCallType - ECI call type
        strServer - CICS server name to make request to (default used if not set)
        strUserid - CICS userid to use
        strPassword - CICS password or password phrase to use
        strProgram - CICS program to be run on the server
        strTransid - CICS transid to be run on the server
        channel - Channel with containers to pass to CICS
        iExtendMode - ECI extend mode
        iLuwToken - ECI LUW token
        iMessageQualifier - Application provided identifier
        callBack - ECI Callbackable object. This may be null if no callback is required.
    • Method Detail

      • listSystems

        public static ECIRequest listSystems(int iNumOfSys)
        This method returns an ECIRequest object which can be flowed to a CICS Transaction Gateway to retrieve the defined CICS servers.

        If the flow call is successful, the Vector ECIRequest.SystemsList contains all the CICS servers defined to the CICS Transaction Gateway. If the connected Gateway is running on z/OS then any logical CICS servers are included. Logical CICS servers can be identified by a prefix of (LS) in the description.

        There is no guarantee that a communications link exists between the CICS Transaction Gateway and any server in the list, or that any of the CICS servers are available.

        Parameters:
        iNumOfSys - Maximum number of systems to request information on
        Returns:
        ECIRequest new ECIRequest object
      • getStatus

        public ECIRequest getStatus(java.lang.String strServer)
        This method creates an ECIRequest object which can be used to find the current status of a CICS system. Following a successful flow of the ECIRequest, the fields: ConnectionType, CicsServerStatus and CicsClientStatus will have been updated with any information the server has supplied.
        Parameters:
        strServer - CICS server name to make request to. If null is specified the default server defined in the gateway is used.
        Returns:
        ECIRequest An ECIRequest object which can be flowed to discover the current status of the CICS server defined by strServer.
      • getStatus

        public ECIRequest getStatus(java.lang.String strServer,
                           int iMessageQualifier,
                           Callbackable callBack)
        This method creates an ECIRequest object which can be used to find the current status of a CICS system. The call will be performed asynchronously and one of the following two methods must be used to retrieve the reply:

        If the parameter callBack is specified, a reply will be sent to the Callback routine when the status information is available. When the Callback routine is invoked the fields: ConnectionType, CicsServerStatus and CicsClientStatus will have been updated with any information the server has supplied. This data is platform independent.

        If a Callbackable object is not supplied, then an ECI_GET_SPECIFIC_REPLY with a Message_Qualifier must be done to receive the status information. This is not the recommended way of obtaining status information since the reply will be in platform specific bytes returned in the Commarea and not in the ConnectionType, CicsServerStatus and CicsClientStatus fields.

        Parameters:
        strServer - CICS server name to make request to. If null is specified the default server defined in the gateway is used.
        iMessageQualifier - Application provided identifier (optional value)
        callBack - ECI Callbackable object. This may be null if no callback is required.
        Returns:
        ECIRequest An ECIRequest object which can be flowed to discover the current status of the CICS server defined by strServer.
      • getCallType

        public int getCallType()
        This method returns the Call_Type field of this ECIRequest object.
        Returns:
        int The Call_Type
      • getCallTypeString

        public java.lang.String getCallTypeString()
        This method returns a String representing the Call_Type field of this ECIRequest object.

        The String returned is the name of the appropriate Java constant for example if the Call_Type is ECI_SYNC, then the String returned will be "ECI_SYNC". If the Call_Type is unknown then the String returned will be "ECI_UNKNOWN_CALL_TYPE".

        Returns:
        String The Call_Type as a String
      • getExtendMode

        public int getExtendMode()
        This method returns the Extend_Mode field of this ECIRequest object.
        Returns:
        int The Extend_Mode
      • getExtendModeString

        public java.lang.String getExtendModeString()
        This method returns a String describing the Extend_Mode field of this ECIRequest object.

        The String returned is the name of the appropriate Java constant, for example, if the Extend_Mode is ECI_NO_EXTEND, then the String returned will be "ECI_NO_EXTEND". If the Extend_Mode is unknown then the String returned will be "ECI_UNKNOWN_EXTEND_MODE".

        Returns:
        String The Extend_Mode as a String
      • getConnectionTypeString

        public java.lang.String getConnectionTypeString()
        This method returns a String describing the ConnectionType field of this ECIRequest object.

        The String returned is the name of the appropriate Java constant, for example, if the ConnectionType is ECI_CONNECTED_TO_CLIENT, then the String returned will be "ECI_CONNECTED_TO_CLIENT". If the ConnectionType is unknown then the String returned will be "ECI_UNKNOWN_CONNECTION_TYPE".

        Returns:
        String The Connection Type as a String
      • stringConnectionType

        public java.lang.String stringConnectionType(int iConnectionType)
        This method takes an int representing the status of the Connection, that is, the ConnectionType, and returns a String describing the ConnectionType.

        NOTE: the String returned is not the same as the name of the appropriate Java constant e.g. if the ConnectionType is ECI_CONNECTED_TO_CLIENT, the String returned is "ECI connected to client".

        Parameters:
        iConnectionType - int representing the Connection Type
        Returns:
        String The Connection Type as a String
      • getServerStatusString

        public java.lang.String getServerStatusString()
        This method returns a String describing the CicsServerStatus field of this ECIRequest object.

        The String returned is the name of the appropriate Java constant, for example, if the CicsServerStatus is ECI_SERVERSTATE_UP, then the String returned will be "ECI_SERVERSTATE_UP". If the CicsServerStatus is unknown then the String returned will be "ECI_UNKNOWN_SERVER_STATE".

        Returns:
        String The Server Status as a String
      • stringServerStatus

        public java.lang.String stringServerStatus(int iCicsServerStatus)
        This method takes an int representing the status of the Server, this is, the CicsServerStatus, and returns a String describing the ServerStatus.

        NOTE: the String returned is not the same as the name of the appropriate Java constant e.g. if the CicsServerStatus is ECI_SERVERSTATE_UP, the String returned is "ECI server state up".

        Parameters:
        iCicsServerStatus - int representing the Server Status
        Returns:
        String The Server Status as a String
      • getClientStatusString

        public java.lang.String getClientStatusString()
        This method returns a String describing the CicsClientStatus field of this ECIRequest object.

        The String returned is the name of the appropriate Java constant, for example, if the CicsClientStatus is ECI_CLIENTSTATE_UP, then the String returned will be "ECI_CLIENTSTATE_UP". If the CicsClientStatus is unknown then the String returned will be "ECI_UNKNOWN_CLIENT_STATE".

        Returns:
        String The Client Status as a String
      • stringClientStatus

        public java.lang.String stringClientStatus(int iCicsClientStatus)
        This method takes an int representing the status of the Client i.e. the CicsClientStatus, and returns a String describing the CicsClientStatus.

        NOTE: the String returned is not the same as the name of the appropriate Java constant e.g. if the CicsClientStatus is ECI_CLIENTSTATE_UP, the String returned is "ECI client state up".

        Parameters:
        iCicsClientStatus - int representing the Client Status
        Returns:
        String The Client Status as a String
      • getRc

        public int getRc()
        Gets the return code set in this object. If a Gateway error code is set this is returned. However if there is no Gateway error code, then any CICS return code is returned. If this method returns zero, it can be assumed that no errors have occurred.
        Returns:
        int The return code
      • getRcString

        public java.lang.String getRcString()
        Gets the return code set in this object and return it as a string. If a Gateway error code is set the string equivalent is returned. However if there is no Gateway error code, then any CICS return code string is returned. If there is no error then the string ECI_NO_ERROR will be returned.
        Returns:
        String The return code
      • getCicsRc

        public int getCicsRc()
        Gets the CICS return code set in this object.
        Returns:
        int The return code
      • getCicsRcString

        public java.lang.String getCicsRcString()
        Gets the CICS return code set in this object and returns it as a String.

        The String returned is the name of the appropriate Java constant, for example, if the Cics_Rc is ECI_NO_ERROR, then the String returned will be "ECI_NO_ERROR". If the Cics_Rc is unknown then the String returned will be "ECI_UNKNOWN_CICS_RC".

        NOTE: for CICS return codes that may have more than one meaning the String returned is a concatenation of the return codes. The only concatenated String is: ECI_ERR_REQUEST_TIMEOUT_OR_ERR_NO_REPLY

        Returns:
        String The return code
      • setCallback

        public void setCallback(Callbackable callBack)
        Sets the Callbackable object associated with this ECIRequest object.

        If null is passed to this method then it is assumed that no Callbackable object is required.

        Parameters:
        callBack - ECI Callbackable object.
      • isCallback

        public boolean isCallback()
        This method returns a boolean indicating whether there is a Callbackable object associated with this ECIRequest object.
        Returns:
        boolean indicating whether there is a Callbackable object
      • setCommareaOutboundLength

        public void setCommareaOutboundLength(boolean bOut)
        This method controls how much of the Commarea, (associated with this ECIRequest object), will be flowed to the CICS Transaction Gateway. If there is no valid Commarea outbound length then the Commarea_Length value will be used to determine the amount of data to flow. NOTE: Commarea_Length still specifies the size of the Commarea that will be given to CICS, and should be set to the maximum value that the CICS application will require. This method takes one parameter: a boolean, indicating whether the Commarea outbound length is valid. Generally, this method would only be used to set the Commarea outbound length to "false".
        Parameters:
        bOut - boolean indicated whether there is valid Commarea outbound length
      • setCommareaOutboundLength

        public void setCommareaOutboundLength(int iOut)
                                       throws java.lang.IllegalArgumentException
        This method controls how much of the Commarea, (associated with this ECIRequest object), will be flowed to the CICS Transaction Gateway. If there is no valid Commarea outbound length then the Commarea_Length value will be used to determine the amount of data to flow. NOTE: Commarea_Length still specifies the size of the Commarea that will be given to CICS, and should be set to the maximum value that the CICS application will require. This method takes one parameter: an int, representing the amount of Commarea to be sent. If this value is negative then an IllegalArgumentException will be thrown; and the current values associated with the Commarea outbound length will not be changed. If this value is positive then this will be used to set a valid outbound length (after which a call to "isCommareaOutboundLength()" would return "true").
        Parameters:
        iOut - int representing amount of Commarea to be sent
        Throws:
        java.lang.IllegalArgumentException - if the parameter value is negative or greater than the maximum commarea length
      • isCommareaOutboundLength

        public boolean isCommareaOutboundLength()
        This method returns a boolean indicating whether the Commarea outbound length is valid.
        Returns:
        boolean indicating whether there is a valid Commarea outbound length
      • getCommareaOutboundLength

        public int getCommareaOutboundLength()
        This method returns an int, which is the Commarea outbound length. NOTE: it is necessary to check whether the Commarea outbound length is valid, (using "isCommareaOutboundLength()"), before checking the value of the Commarea outbound length.
        Returns:
        int which is the Commarea outbound length
      • setCommareaInboundLength

        public void setCommareaInboundLength(boolean bIn)
        This method controls how much of the Commarea, (associated with this ECIRequest object), will be returned by the CICS Transaction Gateway. If bIn is set to "false" or the method is not called, the CICS Transaction Gateway automatically strips zeros from the incoming data. See the CICS Transaction Gateway Programming Guide for a description of null stripping. If the data does not contain any trailing zeros the value of Commarea_Length is used to determine the amount of data to be transmitted.

        NOTE: Commarea_Length still specifies the size of the Commarea that will be given to CICS, and should be set to the maximum value that the CICS application will require. This method takes one parameter: a boolean, indicating whether the Commarea inbound length is valid. Generally, this method would only be used to set the Commarea inbound length to "false".

        Parameters:
        bIn - boolean indicating whether there is valid Commarea inbound length
      • setCommareaInboundLength

        public void setCommareaInboundLength(int iIn)
                                      throws java.lang.IllegalArgumentException
        This method controls how much of the Commarea, (associated with this ECIRequest object), will be flowed from the CICS Transaction Gateway. If no inbound length is set, the CICS Transaction Gateway automatically strips zeros from the incoming data. See the CICS Transaction Gateway Programming Guide for a description of null stripping. If the data does not contain any trailing zeros the value of Commarea_Length is used to determine the amount of data to be transmitted.

        NOTE: Commarea_Length still specifies the size of the Commarea that will be given to CICS, and should be set to the maximum value that the CICS application will require. This method takes one parameter: an int, representing the amount of Commarea to be returned. If this value is negative then an IllegalArgumentException will be thrown; and the current values associated with the Commarea inbound length will not be changed. If this value is positive then this will be used to set a valid inbound length (after which a call to "isCommareaInboundLength()" would return "true").

        Parameters:
        iIn - int representing amount of Commarea to be received
        Throws:
        java.lang.IllegalArgumentException - if the parameter value is negative
      • isCommareaInboundLength

        public boolean isCommareaInboundLength()
        This method returns a boolean value which indicates that setCommareaInboundLength was called with a valid value. In this case the inbound data is truncated to the value specified by Commarea_Length and null stripping is not used.
        Returns:
        boolean indicating whether there is a valid Commarea inbound length
      • getCommareaInboundLength

        public int getCommareaInboundLength()
        This method returns an int, which is the Commarea inbound length.

        NOTE: it is necessary to check whether the Commarea inbound length is valid, (using "isCommareaInboundLength()"), before checking the value of the Commarea inbound length.

        Returns:
        int which is the Commarea inbound length
      • isInboundDataLength

        public boolean isInboundDataLength()
        This method returns a boolean indicating whether automatic null stripping took place. Null stripping takes place if the data flow from the CICS server contained trailing 0x00's. It does not happen for list systems, ESI requests or status requests. It does not happen for ECI_COMMIT or ECI_BACKOUT requests, since these requests do not require a commarea. If you used setCommareaInboundLength to specify a data truncation length then no null stripping takes place. If this function returns false the value returned by getInboundDataLength is invalid.
        Returns:
        boolean indicating whether there is a valid inbound data length
      • getInboundDataLength

        public int getInboundDataLength()
        This method returns an integer, which is the inbound data length. Check whether the inbound data length is valid, (using "isInboundDataLength()"), before checking the value of the inbound data length. If null stripping took place this value represents the length of the commarea after any trailing 0x00's have been removed. This is the length of commarea data that will be sent from CICS TG to the client application. It is not necessarily the same as the amount of data that the CICS transaction returned, since trailing nulls in the transaction data may also be null stripped.
        Returns:
        int which is the inbound data length
      • getECITimeout

        public short getECITimeout()
        This method returns a short. This is the value, in seconds, of the ECI timeout for the current ECIRequest.

        An ECI timeout value of zero indicates that this ECIRequest will not be timed out by CICS Transaction Gateway. An ECI timeout value greater than zero indicates that this ECIRequest may be timed out by CICS Transaction Gateway. ECI timeout can expire before a response is received from CICS. This means that the client does not receive the confirmation from CICS that a unit of work has been backed out or committed.

        For remote mode IPIC, this value can be overridden by the ECITIMEOUT property on the IPIC server definition.

        NOTE: This option is not used when issuing a CICS_EciListSystems request.

        Returns:
        short which is the ECI timeout value
      • setECITimeout

        public void setECITimeout(short sTimeout)
                           throws java.lang.IllegalArgumentException
        This method controls whether there will be an ECI timeout value associated with this ECIRequest object.

        This method takes one parameter: a short. If this value is positive then it will be used as the ECI timeout value (in seconds). If this value is negative then an IllegalArgumentException will be thrown; and the current value of the ECI timeout will remain unchanged. note that if you want to use explicit numbers you need to cast them to a short first or Java will complain. eg ECIRequest.setECITimeout((short)10);.

        An ECI timeout value of zero indicates that this ECIRequest will not be timed out by CICS Transaction Gateway. An ECI timeout value greater than zero indicates that this ECIRequest may be timed out by CICS Transaction Gateway. ECI timeout can expire before a response is received from CICS. This means that the client does not receive the confirmation from CICS that a unit of work has been backed out or committed.

        For remote mode IPIC, this value can be overridden by the ECITIMEOUT property on the IPIC server definition.

        NOTE: This option is not used when issuing a CICS_EciListSystems request.

        Parameters:
        sTimeout - short representing the ECI timeout value
        Throws:
        java.lang.IllegalArgumentException - if the parameter value is negative
      • isTPNTransid

        public boolean isTPNTransid()
        Returns a boolean indicating whether the Transid field is interpreted as an eci_tpn transid (if supported).

        This method returns true if the Call_Type is ECI_SYNC_TPN or ECI_ASYNC_TPN.

        In order to understand the difference between a Transid field interpreted as an eci_transid, and one interpreted as an eci_tpn, you should refer to CICS Transaction Gateway Information Center. If you do not specify a Transid then the default CICS server transid is used.

        Returns:
        boolean indicating whether Transid is treated as an eci_tpn transid.
      • setAutoMsgQual

        public void setAutoMsgQual(boolean newFlag)
        Allows you to turn on or off the Automatic Message Qualifier generation facility. By default this is off.

        If set to true, you do not need to supply a message qualifier for ASYNC type calls which do not provide a callback object. A valid value which won't conflict with any other application (which could occur if you are communicating to a remote gateway server) will be returned from the call You then retrieve this value and use it on GET_SPECIFIC_REPLY and GET_SPECIFIC_REPLY_WAIT requests.

        Parameters:
        newFlag - true = turn Auto Message Qualifier generation on.
      • isAutoMsgQual

        public boolean isAutoMsgQual()
        Returns whether Automatic Message Qualifier generation is on or not.
        Returns:
        flag to say if generation is on or not.
      • getMessageQualifier

        public int getMessageQualifier()
        Returns the Message Qualifier associated with this request. If you have AutoMsgQual set to true, this value if the message qualifier assigned to the object after a successful ASYNC call without callback is made. You use this value in a get_specific_reply and get_specific_reply_wait to retrieve the appropriate response.
        Returns:
        The Message Qualifier associated with this object
      • setMessageQualifier

        public void setMessageQualifier(int newMsgQual)
                                 throws java.lang.IllegalArgumentException
        Sets the Message Qualifier associated with this request. If you have AutoMsgQual set to true, the value used here is only applicable if you are doing a GET_SPECIFIC_REPLY or GET_SPECIFIC_REPLY_WAIT it will not be used at any other time.

        Valid range is -32767 to 32767. If a value outside of this range is passed then an IllegalArgumentException will be thrown.

        Parameters:
        newMsgQual - The Message Qualifier to be used for this request
        Throws:
        illegalArgumentException - Thrown if outside of the valid range
        java.lang.IllegalArgumentException
        See Also:
        getMessageQualifier(), setAutoMsgQual(boolean)
      • setChannel

        public void setChannel(Channel channel)
        Sets the Channel associated with the request.
      • getChannel

        public Channel getChannel()
        Gets the Channel associated with the request.
        Returns:
        The Channel
      • hasChannel

        public boolean hasChannel()
        Gets a value indicating whether the request has an associated Channel.
        Returns:
        true if the request has an associated Channel; false otherwise.
©Copyright IBM Corp. 1994, 2012
Legal