com.ibm.ctg.client
Class ECIRequest

java.lang.Object
  com.ibm.ctg.client.GatewayRequest
      com.ibm.ctg.client.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 Summary

java.lang.String	Abend_Code CICS transaction abend code.
int	Call_Type CICS ECI call type.
Channel	channel The Channel to be passed to the CICS program.
static int	CICS_EciListSystems List CICS servers.
int	Cics_Rc CICS ECI return code.
int	CicsClientStatus After getStatus(), shows status of the Client daemon.
int	CicsServerStatus After getStatus(), shows status of CICS server.
byte[]	Commarea COMMAREA to be passed to the 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 Deprecated. End LUW and commit changes, exactly the same as ECI_COMMIT.
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_EXTENDED This request is part of an Extended Logical Unit of Work.
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_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 Deprecated. The getStatus(String,int,Callbackable) method of ECIRequest should be used to retrieve immediate asynchronous status information about a CICS server.
static int	ECI_STATE_CANCEL Cancel a previous request to be alerted on a state change
static int	ECI_STATE_CHANGED Return state information when the CICS Server changes state e.g.
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 Deprecated. The getStatus(String) method of ECIRequest should be used to retrieve immediate synchronous status information about a CICS server.
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 Deprecated. setMessageQualifier() and getMessageQualifier() methods should now be used.
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 or password phrase 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<java.lang.String>	SystemList List of known systems and system descriptions following a listSystems(int) call.
java.lang.String	Transid Transaction ID to run CICS program under.
java.lang.String	Userid User ID for CICS server.

Fields inherited from interface com.ibm.ctg.client.ECIReturnCodes

astrCics_Rc, astrCics_Rc2, ECI_ERR_ALREADY_ACTIVE, ECI_ERR_CALL_FROM_CALLBACK, ECI_ERR_CICS_DIED, ECI_ERR_EXEC_NOT_RESIDENT, ECI_ERR_INVALID_CALL_TYPE, ECI_ERR_INVALID_DATA_AREA, ECI_ERR_INVALID_DATA_LENGTH, ECI_ERR_INVALID_EXTEND_MODE, ECI_ERR_INVALID_VERSION, ECI_ERR_LUW_TOKEN, ECI_ERR_MAX_SESSIONS, ECI_ERR_MAX_SYSTEMS, ECI_ERR_MORE_SYSTEMS, ECI_ERR_MSG_QUAL_IN_USE, ECI_ERR_NO_CICS, ECI_ERR_NO_MSG_QUALS, ECI_ERR_NO_REPLY, ECI_ERR_NO_SESSIONS, ECI_ERR_NO_SYSTEMS, ECI_ERR_NULL_MESSAGE_ID, ECI_ERR_NULL_SEM_HANDLE, ECI_ERR_NULL_WIN_HANDLE, ECI_ERR_REQUEST_TIMEOUT, ECI_ERR_RESOURCE_SHORTAGE, ECI_ERR_RESPONSE_TIMEOUT, ECI_ERR_ROLLEDBACK, ECI_ERR_SECURITY_ERROR, ECI_ERR_SYSTEM_ERROR, ECI_ERR_THREAD_CREATE_ERROR, ECI_ERR_TRANSACTION_ABEND, ECI_ERR_UNKNOWN_SERVER, ECI_ERR_XID_INVALID, ECI_NO_ERROR

Fields inherited from interface com.ibm.ctg.client.GatewayReturnCodes

astrGateway_Rc, ERROR_BASE, ERROR_CONNECTION_FAILED, ERROR_EXIT_RETRY_INVALID, ERROR_GATEWAY_BACK_LEVEL, ERROR_GATEWAY_CLOSED, ERROR_GATEWAY_EXCEPTION, ERROR_INVALID_REQUEST_TYPE, ERROR_NOT_AUTHORIZED, ERROR_NOT_SUPPORTED, ERROR_REPLY_MISMATCH, ERROR_UNKNOWN_REQUEST_TYPE, ERROR_WORK_WAS_REFUSED, ERROR_XA_SUPPORT_NOT_ENABLED, strINVALID_GATEWAY_RC

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)
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, Channel channel, 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, Channel channel, int iExtendMode, int iLuwToken, int iMessageQualifier, Callbackable calBack)
Extended constructor.

ECIRequest(java.lang.String strServer, java.lang.String strUserid, java.lang.String strPassword, java.lang.String strProgram, byte[] abytCommarea, int iExtendMode, int iLuwToken)
Extended constructor, which takes the relevant parameters for a simple synchronous call, and sets the contents of the object.

ECIRequest(java.lang.String strServer, java.lang.String strUserid, java.lang.String strPassword, java.lang.String strProgram, Channel channel, int iExtendMode, int iLuwToken)
Extended constructor, which takes the relevant parameters for a simple synchronous call, and sets the contents of the object.

Method Summary

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.
Channel	getChannel() Gets the Channel associated with the request.
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	getInboundDataLength() This method returns an integer, which is the inbound data length.
int	getMessageQualifier() Returns the Message Qualifier associated with this request.
int	getRc() Gets the return code set in this object.
java.lang.String	getRcString() Gets the return code set in this object and return it as a string.
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 creates an ECIRequest object which can be used to find the current status of a CICS system.
ECIRequest	getStatus(java.lang.String strServer, int iMessageQualifier, Callbackable calBack) This method creates an ECIRequest object which can be used to find the current status of a CICS system.
boolean	hasChannel() Gets a value indicating whether the request has an associated Channel.
boolean	isAutoMsgQual() Returns whether Automatic Message Qualifier generation is on or not.
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 value which indicates that setCommareaInboundLength was called with a valid value.
boolean	isCommareaOutboundLength() This method returns a boolean indicating whether the Commarea outbound length is valid.
boolean	isInboundDataLength() This method returns a boolean indicating whether automatic null stripping took place.
boolean	isTPNTransid() Returns a boolean indicating whether the Transid field is interpreted as an eci_tpn transid (if supported).
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.
void	setAutoMsgQual(boolean newFlag) Allows you to turn on or off the Automatic Message Qualifier generation facility.
void	setCallback(Callbackable calBack) Sets the Callbackable object associated with this ECIRequest object.
void	setChannel(Channel channel) Sets the Channel associated with the request.
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.
void	setMessageQualifier(int newMsgQual) Sets the Message Qualifier associated with this request.
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 com.ibm.ctg.client.GatewayRequest

getGatewayRc, getGatewayRcString

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ECI_SYNC

public static final int ECI_SYNC

Synchronous call.

See Also:

Constant Field Values

ECI_ASYNC

public static final int ECI_ASYNC

Asynchronous 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_LUW_NEW

public static final int ECI_LUW_NEW

New LUW.

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.

Message_Qualifier

@Deprecated
public int Message_Qualifier

Deprecated. setMessageQualifier() and getMessageQualifier() methods should now be used.

The Message Qualifier to be associated with an ASYNC type call that does not use callbacks. This value MUST be unique within the Local Gateway or within the remote gateway you are flowing the request to.

Although defined as an int, valid range for this property is -32767 to 32767. The default value is 0.

Refer to the method setAutoMsgQual for safe message qualifier generation.

See Also:

setAutoMsgQual(boolean), setMessageQualifier(int), getMessageQualifier()

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)

Extended 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 (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)

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

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 (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 calBack)

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

calBack - ECI Callbackable object. This may be null if no callback is required.

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)

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 Channel 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

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 calBack)

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

calBack - 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)

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

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 calBack)

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 calBack 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)

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

NOTE: The eci_timeout option is not recommended unless you have fully read and understood the advice given in the CICS Transaction Gateway Information Center. 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 Client daemon. An eci_timeout value greater than zero indicates that this ECIRequest may be timed out by the Client daemon.

NOTE: This option is not recommended unless you have fully read and understood the advice given in the CICS Transaction Gateway Information Center. 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).

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.