CICS® Transaction Gateway Programming Reference V3.1

com.ibm.ctg.client
Class ECIRequest

java.lang.Object
  |
  +--com.ibm.ctg.client.GatewayRequest
        |
        +--com.ibm.ctg.client.ECIRequest

public class ECIRequest
extends GatewayRequest

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

See Also:
GatewayRequest

Field Summary
 java.lang.String Abend_Code
          CICS transaction abend code
 int Call_Type
          CICS ECI Call Type
static int CICS_EciListSystems
          List CICS servers
 int Cics_Rc
          CICS ECI return code
 int CicsClientStatus
          After getStatus() shows status of CICS client
 int CicsServerStatus
          After getStatus() shows status of CICS server
 byte[] Commarea
          COMMAREA to be passed to CICS Program
 int Commarea_Length
          length of COMMAREA
 int ConnectionType
          After getStatus() shows type of CICS system
static int ECI_ASYNC
          Asynchronous call
static int ECI_ASYNC_TPN
          Asynchronous call with eci_tpn.
static int ECI_BACKOUT
          End LUW and backout changes
static int ECI_CANCEL
          End LUW and commit changes
static short ECI_CLIENTSTATE_INAPPLICABLE
          Return value from a getStatus() call
static short ECI_CLIENTSTATE_UNKNOWN
          Return value from a getStatus() call
static short ECI_CLIENTSTATE_UP
          Return value from a getStatus() call
static int ECI_COMMIT
          End LUW and commit changes
static short ECI_CONNECTED_NOWHERE
          Return value from a getStatus() call
static short ECI_CONNECTED_TO_CLIENT
          Return value from a getStatus() call
static short ECI_CONNECTED_TO_SERVER
          Return value from a getStatus() call
static int 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
static int ECI_ERR_CALL_FROM_CALLBACK
          On the CICS client, the call was made from a callback routine
static int ECI_ERR_CICS_DIED
          The Specified server is no longer available
static int ECI_ERR_EXEC_NOT_RESIDENT
           
static int ECI_ERR_INVALID_CALL_TYPE
          The call type was not valid
static int ECI_ERR_INVALID_DATA_AREA
           
static int ECI_ERR_INVALID_DATA_LENGTH
          The commarea length is not consistent with the commarea supplied
static int ECI_ERR_INVALID_EXTEND_MODE
          The extend mode field is invalid
static int ECI_ERR_INVALID_TRANSID
          A logical unit of work was being extended, but the value supplied for the transid differed from the value used when the logical unit of work was created
static int ECI_ERR_INVALID_VERSION
           
static int ECI_ERR_LUW_TOKEN
          The value in Luw_Token is incorrect
static int ECI_ERR_MAX_SESSIONS
          Not enough communication resources to satisfy request
static int ECI_ERR_MAX_SYSTEMS
          Reached limit on maxmimum number of systems
static int ECI_ERR_MORE_SYSTEMS
          Insufficient space for Server list
static int ECI_ERR_NO_CICS
          No CICS system Available
static int ECI_ERR_NO_REPLY
           
static int ECI_ERR_NO_SESSIONS
           
static int ECI_ERR_NO_SYSTEMS
          No CICS Servers can be located
static int ECI_ERR_NULL_MESSAGE_ID
           
static int ECI_ERR_NULL_SEM_HANDLE
           
static int ECI_ERR_NULL_WIN_HANDLE
           
static int ECI_ERR_REQUEST_TIMEOUT
          The value supplied for timeout is negative
static int ECI_ERR_RESOURCE_SHORTAGE
          Not enough resource to complete the request
static int ECI_ERR_RESPONSE_TIMEOUT
          The ECI Call timed out
static int 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
static int ECI_ERR_SECURITY_ERROR
          you did not supply a valid combination of userid and password
static int ECI_ERR_SYSTEM_ERROR
          An internal System Error Occurred
static int ECI_ERR_THREAD_CREATE_ERROR
           
static int ECI_ERR_TRANSACTION_ABEND
          The CICS Transaction abended.
static int ECI_ERR_UNKNOWN_SERVER
          The requested Server could not be located
static int ECI_EXTENDED
          This request is part of an Extended Logical Unit of Work
static int ECI_GET_REPLY
          WARNING: this Call_Type will be removed in a future release
static int ECI_GET_REPLY_WAIT
          WARNING: this Call_Type will be removed in a future release
static int ECI_GET_SPECIFIC_REPLY
          Get a specific asynchronous reply
static int ECI_GET_SPECIFIC_REPLY_WAIT
          Await a specific asynchronous reply
static int ECI_LUW_NEW
          New LUW
static int ECI_NO_ERROR
          The function completed normally
static int ECI_NO_EXTEND
          Non-extended LUW call, or the last call in a LUW
static short ECI_SERVERSTATE_DOWN
          Return value from a getStatus() call
static short ECI_SERVERSTATE_UNKNOWN
          Return value from a getStatus() call
static short ECI_SERVERSTATE_UP
          Return value from a getStatus() call
static int ECI_STATE_ASYNC
          Asynchronous request for status
static int ECI_STATE_ASYNC_JAVA
          Asynchronous request for status information as Java values i.e.
static int ECI_STATE_CANCEL
          Cancel an ECI_STATE_CHANGED request
static int ECI_STATE_CHANGED
          If status changes then send reply
static int ECI_STATE_IMMEDIATE
          Return state information immediately
static int ECI_STATE_SYNC
          Synchronous request for status information
static int ECI_STATE_SYNC_JAVA
          Synchronous request for status information as Java values i.e.
static int ECI_STATUS_LENGTH
          Length of COMMAREA needed for status information
static int ECI_SYNC
          Synchronous call
static int ECI_SYNC_TPN
          Synchronous call with eci_tpn.
 int Extend_Mode
          Extend mode of request
 int Luw_Token
          Extended Logical Unit of Work token
 int maxNumServers
          Maximum number of CICS Servers about which information is to be returned (see listSystems() )
 int Message_Qualifier
          User supplied message identifier
 int numServersKnown
          Number of CICS Servers which are defined (output from listSystems() flow)
 int numServersReturned
          Number of CICS Servers about which information has been returned (output from listSystems() flow)
 java.lang.String Password
          Password for CICS server
 java.lang.String Program
          Program to invoke on CICS server
 java.lang.String Server
          CICS Server to direct request to
 java.util.Vector SystemList
          List of known systesm and system descriptions following a listSystems call.
 java.lang.String Transid
          Transaction id to run CICS program under
 java.lang.String Userid
          Userid for CICS server
 
Fields inherited from class com.ibm.ctg.client.GatewayRequest
ERROR_CONNECTION_FAILED, ERROR_GATEWAY_CLOSED, ERROR_REPLY_MISMATCH, ERROR_UNKNOWN_REQUEST_TYPE, ERROR_WORK_WAS_REFUSED
 
Constructor Summary
ECIRequest()
          Default constructor, which leaves all the values set to their defaults.
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)
          Basic constructor.
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)
          Extended constructor.
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 calBack)
          Full constructor.
ECIRequest(java.lang.String strServer, java.lang.String strUserid, java.lang.String strPassword, java.lang.String strProgram, byte[] abytCommarea, int iExtendMode, int iLuwToken)
          Beta style constructor, which takes the relevant parameters for a simple synchronous call, and sets the contents of the object.
 
Method Summary
(package private) static void ()
          The purpose of this static initializer is to get the appropriate ResourceBundle class.
 int getCallType()
          This method returns the Call_Type field of this ECIRequest object.
 java.lang.String getCallTypeString()
          This method returns a String representing the Call_Type field of this ECIRequest object.
 int getCicsRc()
          Gets the CICS return code set in this object.
 java.lang.String getCicsRcString()
          Gets the CICS return code set in this object and returns it as a String.
 java.lang.String getClientStatusString()
          This method returns a String describing the CicsClientStatus field of this ECIRequest object.
 int getCommareaInboundLength()
          This method returns an int, which is the Commarea inbound length.
 int getCommareaOutboundLength()
          This method returns an int, which is the Commarea outbound length.
 java.lang.String getConnectionTypeString()
          This method returns a String describing the ConnectionType field of this ECIRequest object.
 short getECITimeout()
          This method returns a short.
 int getExtendMode()
          This method returns the Extend_Mode field of this ECIRequest object.
 java.lang.String getExtendModeString()
          This method returns a String describing the Extend_Mode field of this ECIRequest object.
 int getRc()
          Gets the return code set in this object.
 java.lang.String getServerStatusString()
          This method returns a String describing the CicsServerStatus field of this ECIRequest object.
 ECIRequest getStatus(java.lang.String strServer)
          This method sets the values of an ECIRequest object for an ECI_STATE_SYNC_JAVA call on the CICS Transaction Gateway.
 ECIRequest getStatus(java.lang.String strServer, int iMessageQualifier, Callbackable calBack)
          This method sets the values of an ECIRequest object for an ECI_STATE_ASYNC_JAVA call on the CICS Transaction Gateway.
 boolean isCallback()
          This method returns a boolean indicating whether there is a Callbackable object associated with this ECIRequest object.
 boolean isCommareaInboundLength()
          This method returns a boolean indicating whether the Commarea inbound length is valid.
 boolean isCommareaOutboundLength()
          This method returns a boolean indicating whether the Commarea outbound length is valid.
 boolean isTPNTransid()
          Returns a boolean indicating whether the Transid field is interpreted as an eci_tpn transid, (if supported), by the CICS client.
static ECIRequest listSystems(int iNumOfSys)
          This method returns a new ECIRequest object which can be used to effect an CICS_EciListSystems on the CICS Transaction Gateway.
 void setCallback(Callbackable calBack)
          Sets the Callbackable object associated with this ECIRequest object.
 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.
 void setCommareaInboundLength(int iIn)
          This method controls how much of the Commarea, (associated with this ECIRequest object), will be flowed from the CICS Transaction Gateway.
 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.
 void setCommareaOutboundLength(int iOut)
          This method controls how much of the Commarea, (associated with this ECIRequest object), will be flowed to the CICS Transaction Gateway.
 void setECITimeout(short sTimeout)
          This method controls whether there will be an eci_timeout value associated with this ECIRequest object.
 java.lang.String stringClientStatus(int iCicsClientStatus)
          This method takes an int representing the status of the Client i.e.
 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.
 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.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ECI_SYNC

public static final int ECI_SYNC
Synchronous call

ECI_ASYNC

public static final int ECI_ASYNC
Asynchronous call

ECI_GET_REPLY

public static final int ECI_GET_REPLY
WARNING: this Call_Type will be removed in a future release

ECI_GET_REPLY_WAIT

public static final int ECI_GET_REPLY_WAIT
WARNING: this Call_Type will be removed in a future release

ECI_GET_SPECIFIC_REPLY

public static final int ECI_GET_SPECIFIC_REPLY
Get a specific asynchronous reply

ECI_GET_SPECIFIC_REPLY_WAIT

public static final int ECI_GET_SPECIFIC_REPLY_WAIT
Await a specific asynchronous reply

ECI_STATE_SYNC

public static final int ECI_STATE_SYNC
Synchronous request for status information

ECI_STATE_ASYNC

public static final int ECI_STATE_ASYNC
Asynchronous request for status

CICS_EciListSystems

public static final int CICS_EciListSystems
List CICS servers

ECI_STATE_SYNC_JAVA

public static final int ECI_STATE_SYNC_JAVA
Synchronous request for status information as Java values i.e. platform independent data

ECI_STATE_ASYNC_JAVA

public static final int ECI_STATE_ASYNC_JAVA
Asynchronous request for status information as Java values i.e. platform independent data

ECI_SYNC_TPN

public static final int ECI_SYNC_TPN
Synchronous call with eci_tpn.

Synchronous call with the Transid field representing eci_tpn on the CICS client. eci_tpn Transids are not valid for CICS on Open System Clients. Refer to the CICS client/server documentation for more information on the difference between eci_transid and eci_tpn.


ECI_ASYNC_TPN

public static final int ECI_ASYNC_TPN
Asynchronous call with eci_tpn.

Asynchronous call with the Transid field representing eci_tpn on the CICS client. eci_tpn Transids are not valid for CICS on Open System Clients. Refer to the CICS client/server documentation for more information on the difference between eci_transid and eci_tpn.


ECI_NO_EXTEND

public static final int ECI_NO_EXTEND
Non-extended LUW call, or the last call in a LUW

ECI_EXTENDED

public static final int ECI_EXTENDED
This request is part of an Extended Logical Unit of Work

ECI_COMMIT

public static final int ECI_COMMIT
End LUW and commit changes

ECI_CANCEL

public static final int ECI_CANCEL
End LUW and commit changes

ECI_BACKOUT

public static final int ECI_BACKOUT
End LUW and backout changes

ECI_STATE_IMMEDIATE

public static final int ECI_STATE_IMMEDIATE
Return state information immediately

ECI_STATE_CHANGED

public static final int ECI_STATE_CHANGED
If status changes then send reply

ECI_STATE_CANCEL

public static final int ECI_STATE_CANCEL
Cancel an ECI_STATE_CHANGED request

ECI_LUW_NEW

public static final int ECI_LUW_NEW
New LUW

ECI_STATUS_LENGTH

public static final int ECI_STATUS_LENGTH
Length of COMMAREA needed for status information

ECI_NO_ERROR

public static final int ECI_NO_ERROR
The function completed normally

ECI_ERR_INVALID_DATA_LENGTH

public static final int ECI_ERR_INVALID_DATA_LENGTH
The commarea length is not consistent with the commarea supplied

ECI_ERR_INVALID_EXTEND_MODE

public static final int ECI_ERR_INVALID_EXTEND_MODE
The extend mode field is invalid

ECI_ERR_NO_CICS

public static final int ECI_ERR_NO_CICS
No CICS system Available

ECI_ERR_CICS_DIED

public static final int ECI_ERR_CICS_DIED
The Specified server is no longer available

ECI_ERR_REQUEST_TIMEOUT

public static final int ECI_ERR_REQUEST_TIMEOUT
The value supplied for timeout is negative

ECI_ERR_NO_REPLY

public static final int ECI_ERR_NO_REPLY

ECI_ERR_RESPONSE_TIMEOUT

public static final int ECI_ERR_RESPONSE_TIMEOUT
The ECI Call timed out

ECI_ERR_TRANSACTION_ABEND

public static final int ECI_ERR_TRANSACTION_ABEND
The CICS Transaction abended.

ECI_ERR_EXEC_NOT_RESIDENT

public static final int ECI_ERR_EXEC_NOT_RESIDENT

ECI_ERR_LUW_TOKEN

public static final int ECI_ERR_LUW_TOKEN
The value in Luw_Token is incorrect

ECI_ERR_SYSTEM_ERROR

public static final int ECI_ERR_SYSTEM_ERROR
An internal System Error Occurred

ECI_ERR_NULL_WIN_HANDLE

public static final int ECI_ERR_NULL_WIN_HANDLE

ECI_ERR_NULL_MESSAGE_ID

public static final int ECI_ERR_NULL_MESSAGE_ID

ECI_ERR_THREAD_CREATE_ERROR

public static final int ECI_ERR_THREAD_CREATE_ERROR

ECI_ERR_INVALID_CALL_TYPE

public static final int ECI_ERR_INVALID_CALL_TYPE
The call type was not valid

ECI_ERR_ALREADY_ACTIVE

public static final int 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

public static final int ECI_ERR_RESOURCE_SHORTAGE
Not enough resource to complete the request

ECI_ERR_NO_SESSIONS

public static final int ECI_ERR_NO_SESSIONS

ECI_ERR_NULL_SEM_HANDLE

public static final int ECI_ERR_NULL_SEM_HANDLE

ECI_ERR_INVALID_DATA_AREA

public static final int ECI_ERR_INVALID_DATA_AREA

ECI_ERR_INVALID_VERSION

public static final int ECI_ERR_INVALID_VERSION

ECI_ERR_UNKNOWN_SERVER

public static final int ECI_ERR_UNKNOWN_SERVER
The requested Server could not be located

ECI_ERR_CALL_FROM_CALLBACK

public static final int ECI_ERR_CALL_FROM_CALLBACK
On the CICS client, the call was made from a callback routine

ECI_ERR_INVALID_TRANSID

public static final int ECI_ERR_INVALID_TRANSID
A logical unit of work was being extended, but the value supplied for the transid differed from the value used when the logical unit of work was created

ECI_ERR_MORE_SYSTEMS

public static final int ECI_ERR_MORE_SYSTEMS
Insufficient space for Server list

ECI_ERR_NO_SYSTEMS

public static final int ECI_ERR_NO_SYSTEMS
No CICS Servers can be located

ECI_ERR_SECURITY_ERROR

public static final int ECI_ERR_SECURITY_ERROR
you did not supply a valid combination of userid and password

ECI_ERR_MAX_SYSTEMS

public static final int ECI_ERR_MAX_SYSTEMS
Reached limit on maxmimum number of systems

ECI_ERR_MAX_SESSIONS

public static final int ECI_ERR_MAX_SESSIONS
Not enough communication resources to satisfy request

ECI_ERR_ROLLEDBACK

public static final int 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_CONNECTED_NOWHERE

public static final short ECI_CONNECTED_NOWHERE
Return value from a getStatus() call

ECI_CONNECTED_TO_SERVER

public static final short ECI_CONNECTED_TO_SERVER
Return value from a getStatus() call

ECI_CONNECTED_TO_CLIENT

public static final short ECI_CONNECTED_TO_CLIENT
Return value from a getStatus() call

ECI_SERVERSTATE_UNKNOWN

public static final short ECI_SERVERSTATE_UNKNOWN
Return value from a getStatus() call

ECI_SERVERSTATE_UP

public static final short ECI_SERVERSTATE_UP
Return value from a getStatus() call

ECI_SERVERSTATE_DOWN

public static final short ECI_SERVERSTATE_DOWN
Return value from a getStatus() call

ECI_CLIENTSTATE_UNKNOWN

public static final short ECI_CLIENTSTATE_UNKNOWN
Return value from a getStatus() call

ECI_CLIENTSTATE_UP

public static final short ECI_CLIENTSTATE_UP
Return value from a getStatus() call

ECI_CLIENTSTATE_INAPPLICABLE

public static final short ECI_CLIENTSTATE_INAPPLICABLE
Return value from a getStatus() call

Call_Type

public int Call_Type
CICS ECI Call Type

Extend_Mode

public int Extend_Mode
Extend mode of request

Luw_Token

public int Luw_Token
Extended Logical Unit of Work token

Message_Qualifier

public int Message_Qualifier
User supplied message identifier

Server

public java.lang.String Server
CICS Server to direct request to

Userid

public java.lang.String Userid
Userid for CICS server

Password

public java.lang.String Password
Password for CICS server

Program

public java.lang.String Program
Program to invoke on CICS server

Transid

public java.lang.String Transid
Transaction id to run CICS program under

Commarea_Length

public int Commarea_Length
length of COMMAREA

Commarea

public byte[] Commarea
COMMAREA to be passed to CICS Program

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 SystemList
List of known systesm and system descriptions following a listSystems 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 CICS client

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)
Constructor Detail

ECIRequest

public ECIRequest()
Default constructor, which leaves all the values set to their defaults.

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)
Beta style constructor, which 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
strUserid - CICS userid to use
strPassword - CICS password 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)
Basic constructor. 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
strUserid - CICS userid to use
strPassword - CICS password 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)
Extended constructor. This constructor expands on the basic constructor to take the additional parameters required to make 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
strUserid - CICS userid to use
strPassword - CICS password 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 calBack)
Full constructor. This constructor takes all the supported ECI parameters and sets them in the object.

It is the only constructor which allows the direct construction of an object which can be used for ECI asynchronous call types.

Parameters:
iCallType - ECI call type
strServer - CICS server name to make request to
strUserid - CICS userid to use
strPassword - CICS password 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
calBack - ECI Callbackable object. This may be null if no callback is required.
Method Detail

static void ()
The purpose of this static initializer is to get the appropriate ResourceBundle class. Client-side resource bundles (for CICS requests) have the naming format: CicsResourceBundle.java This class is the highest level resource bundle and the messages are in US English. If the language associated with the default locale is not US English then the specific resource bundle (if it exists) will have the format: CicsResourceBundle_fr.java (or CicsResourceBundle_fr_FR.java). The 'getBundle()' method of the ResourceBundle class looks for the most specific (appropriate) resource bundle first and if it does not find this works its way up to the least specific resource bundle i.e. CicsResourceBundle.java. So, messages will appear in US English if there are no appropriate resource bundles.

listSystems

public static ECIRequest listSystems(int iNumOfSys)
This method returns a new ECIRequest object which can be used to effect an CICS_EciListSystems on the CICS Transaction Gateway. The returned object should be flowed to the Gateway as is.

Upon return for the flow call, the public data Vector ECIRequest.SystemsList will contain the returned system names and descriptions.

Upon return from the flow call, numServersKnown and numServersReturned will also have been updated.

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 sets the values of an ECIRequest object for an ECI_STATE_SYNC_JAVA call on the CICS Transaction Gateway. The Extend_mode is set to ECI_STATE_IMMEDIATE i.e. a reply will be sent immediately it is available.

Upon return from the flow call, the fields: ConnectionType , CicsServerStatus and CicsClientStatus will have been updated with any information the server has supplied. This data is platform independent.

You are advised not to set an Extend_Mode of ECI_STATE_CHANGE or ECI_STATE_CANCEL, since these are not fully supported by the CICS Transaction Gateway.

Parameters:
strServer - CICS server name to make request to (optional value)
Returns:
ECIRequest this ECIRequest object

getStatus

public ECIRequest getStatus(java.lang.String strServer,
                            int iMessageQualifier,
                            Callbackable calBack)
This method sets the values of an ECIRequest object for an ECI_STATE_ASYNC_JAVA call on the CICS Transaction Gateway. The Extend_mode is set to ECI_STATE_IMMEDIATE i.e. a reply will be sent immediately it is available.

Since this call is asynchronous, 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.

You are advised not to set an Extend_Mode of ECI_STATE_CHANGE or ECI_STATE_CANCEL, since these are not fully supported by the CICS Transaction Gateway.

Parameters:
strServer - CICS server name to make request to (optional value)
iMessageQualifier - Application provided identifier (optional value)
calBack - ECI Callbackable object. This may be null if no callback is required.
Returns:
ECIRequest this ECIRequest object

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 occured.
Returns:
int 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 two concatenated Strings are: ECI_ERR_REQUEST_TIMEOUT_OR_ERR_NO_REPLY and ECI_ERR_EXEC_NOT_RESIDENT_OR_ERR_LUW_TOKEN

Returns:
String The return code

setCallback

public void setCallback(Callbackable calBack)
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:
calBack - EPI 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

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 there is no valid Commarea inbound length, then the Commarea_Length value will be used to determine the amount of data to flow. NOTE: Commarea_Length still specifes 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 there is no valid Commarea inbound length, then the Commarea_Length value will be used to determine the amount of data to flow. NOTE: Commarea_Length still specifes 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 indicating whether the Commarea inbound length is valid.
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

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 the CICS Client. An eci_timeout value greater than zero indicates that this ECIRequest may be timed out by the CICS Client.

NOTE: The eci_timeout option is not recommended unless you have fully read and understood the advice given in the CICS Client/Server documentation. The main concern with the eci_timeout is that the Java client program using it may not know whether a unit of work has been backed out or committed. This is particularly an issue when using logical units of work which are not extended.

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 the CICS Client. An eci_timeout value greater than zero indicates that this ECIRequest may be timed out by the CICS Client.

NOTE: This option is not recommended unless you have fully read and understood the advice given in the CICS Client/Server documentation. The main concern with the eci_timeout is that the Java client program using it may not know whether a unit of work has been backed out or committed. This is particularly an issue when using logical units of work which are not extended.

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), by the CICS client.

This method returns true if the Call_Type is ECI_SYNC_TPN or ECI_ASYNC_TPN, it does not reflect the actual CICS Client capability.

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 client/server documentation. 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

© Copyright IBM Corp. 1994, 1999