CTG Classes

This chapter describes how to use CTG classes.

1. Overview

The following are classes used to develop J2EE ECI applications and exception-related classes.

2. CCILocalTransaction

Controls the ECI Connector transaction status. This class can be accessed only through the ECIConnection.getLocalTransaction() method.

  • Package

    com.tmax.ofctg.connector.cics

  • Declaration

    public class CCILocalTransaction
implements javax.resource.cci.LocalTransaction
Methods

The following are relevant methods.

Method Description

public void begin()

Begins a new local transaction.

  • Exception

    • ResourceException: thrown if this method fails.

public void commit()

Commits a current local transaction.

  • Exception

    • ResourceException: thrown if this method fails.

public void rollback()

Rolls back a current local transaction.

  • Exception

    • ResourceException: thrown if this method fails.

3. CICSConnection

Currently cannot be used alone. For more information, refer to ECIConnection.

4. CICSConnectionFactory

Currently cannot be used alone. For more information, refer to ECIConnectionFactory.

5. CICSConnectionSpec

Currently cannot be used alone. For more information, refer to ECIConnectionSpec.

  • Package

    com.tmax.ofctg.connector.cics

  • Declaration

    public class CICSConnectionSpec
implements javax.resource.cci.ConnectionSpec
Methods

The following are relevant methods.

Method Description

public void setUserName(java.lang.String newUser)

Sets a user name.

public java.lang.String getUserName()

Gets a user name.

public void setPassword(java.lang.String newPass)

Sets a password.

public java.lang.String getPassword()

Gets a password.

String getHost()

Gets the IP address of the OSC server’s host.

void setHost(String host)

Sets the IP address of the OSC server’s host.

int getHost_port()

Gets the port number of the OSC server’s host.

void setHost_port(Integer host_port)

Sets the port number of the OSC server’s host.

String getBackup()

Gets the IP address of the OSC server’s backup host.

void setBackup(String backup)

Sets the IP address of the OSC server’s backup host.

int getBackup_port()

Gets the port number of the OSC server’s backup host.

void setBackup_port(Integer backup_port)

Sets the port number of the OSC server’s backup host.

int getConnectTimeout()

Gets the OSC server connection timeout. (Unit: seconds)

void setConnectTimeout(Integer connectTimeout)

Sets the OSC server connection timeout. (Unit: seconds)

6. CICSInteraction

Represents interactions with a CICS server. This class has information about connections used to communicate with the CICS server. Currently cannot be used alone. For more information, refer to ECIInteraction.

  • Package

    com.tmax.ofctg.connector.cics

  • Declaration

    public class CICSInteractionSpec
implements javax.resource.cci.Interaction
Methods

The following are relevant methods.

Method Description

public Connection getConnection()

Gets the instance of the ECIConnectinon class that creates its own instance (CICSInteraction).

public ResourceWarning getWarnings()

Gets the CICSResourceException class that includes information about an error that occurred while the execute() method is performed for the interaction. If no error occurs, null is returned.

  • Exception

    • ResourceException: thrown if this method fails.

public void clearWarnings()

Clears ResourceWarning information saved for the interaction.

  • Exception

    • ResourceException: thrown if this method fails.

public boolean execute(InteractionSpec aspec, Record sndRecord, Record rcvRecord)

Do not call this method directly. To call this method, use the ECIInteraction class.

  • Exception

    • ResourceException: thrown if an error occurs when communicating with the CICS server.

public void close()

Closes the ECIConnection connection for the interaction.

  • Exception

    • ResourceException: thrown if this method fails.

7. CICSInteractionSpec

Currently cannot be used alone. For more information, refer to ECIInteractionSpec.

  • Package

    com.tmax.ofctg.connector.cics

  • Declaration

    public class CICSInteractionSpec
implements javax.resource.cci.InteractionSpec
Methods

The following are relevant methods.

Method Description

public int getInteractionVerb()

Gets an interactionVerb (which indicates what type of interaction is used) that is saved for the instance. One of the following is returned.

  • SYNC_SEND: currently not supported.

  • SYNC_RECEIVE: currently not supported.

  • SYNC_SEND_RECEIVE: send requests and receive responses in DPL mode.

public void setInteractionVerb(int newVerb)

Sets a new interactionVerb, which indicates what type of interaction is used.

  • newVerb: SYNC_SEND, SYNC_RECEIVE, or SYNC_SEND_RECEIVE. Currently, only SYNC_SEND_RECEIVE is supported.

public void addPropertyChangeListener (PropertyChangeListener pcl)

Adds a PropertyChangeListener.

public void removePropertyChangeListener (PropertyChangeListener pcl)

Removes a PropertyChangeListener.

8. CICSManagedConnectionFactory

Currently cannot be used alone. For more information, refer to ECIManagedConnectionFactory. Method-related default values are the same as the values set in a resource adapter.

  • Package

    com.tmax.ofctg.connector.cics

  • Declaration

    public class CICSManagedConnectionFactory
implements com.tmax.ofctg.connector.cics.CICSLogTraceLevels,
    java.io.Serializable,
    javax.resource.spi.ManagedConnectionFactory,
    javax.resource.spi.ResourceAdapterAssociation,
    javax.resource.spi.ValidatingManagedConnectionFactory

9. CICSResourceException

Includes exception information about errors that occur when handling requests with ECIInteraction.

You can get information about the first exception by using getWarnings() of the ECIInteraction class, and additional information such as abend code for exceptions that occur when executing execute() of the ECIInteraction class.

  • Package

    com.tmax.ofctg.connector.cics

  • Declaration

    public class CICSResourceException
extends javax.resource.cci.ResourceWarning
Methods

The following are relevant methods.

Method Description

public String getAbendCode()

Gets an abend code if an abend occurs when handling requests. If an abend code does not exist, null is returned.

public int getCicsRespCode()

Gets a response code constant defined in the ECIResourceAdapterRc class. For more information about errors, refer to ECIResourceAdapterRc.

public int getCicsServerStatus()

Gets a server status constant defined in the ECIResourceAdapterRc class. For more information about errors, refer to ECIResourceAdapterRc.

10. ECIConnection

Represents a connection to an OSC server. Its object is used to create an interaction for communication with CICS. The object is created through getConnection() of the ECIConnectionFactory class.

  • Package

    com.tmax.ofctg.connector.cics

  • Declaration

    public class ECIConnection
extends CICSConnection
implements javax.resource.cci.Connection
Methods

The following are relevant methods.

Method Description

public void close()

Closes a connection.

  • Exception

    • ResourceException: thrown if this method fails.

public Interaction createInteraction()

Creates ECIInteraction to execute through a connection.

  • Exception

    • ResourceException: thrown if this method fails.

public LocalTransaction getLocalTransaction()

Gets a local transaction object used to control transaction status of the connection.

  • Exception

    • ResourceException: thrown if this method fails.

11. ECIConnectionFactory

Gets an ECI connection, to which settings for a resource adapter or settings in connection specifications are applied, through getConnection(). You can look up this class through the settings for a resource adapter.

  • Package

    com.tmax.ofctg.connector.cics

  • Declaration

    public class ECIConnectionFactory
extends com.tmax.ofctg.connector.cics.CICSConnectionFactory
Methods

The following are relevant methods.

Method Description

public Connection getConnection(ConnectionSpec connectionSpec)

Gets a local transaction object used to control the transaction status of the connection.

  • Parameters

    • connectionSpec: specifications to apply to the connection.

      When creating a connection, property values set in Factory are used by default. If this parameter is set to non-null and the host, host_port, backup, backup_port, and connectionTimeout properties are set, their values set in connection specifications are used. An ECIConnectionSpec object is created and passed as an argument

  • Exception

    • ResourceException: thrown if an error occurs during a connection creation.

12. ECIConnectionSpec

Defines ECI connection specifications. When you call getConnection(), the specifications defined in this class are used.

  • Package

    com.tmax.ofctg.connector.cics

  • Declaration

    public class ECIConnectionSpec
extends com.tmax.ofctg.connector.cics.CICSConnectionSpec
Constructors
Constructor Description

public ECIConnectionSpec()

Creates an ECIConnectionSpec object.

public ECIConnectionSpec(java.lang.String user, java.lang.String pass)

Creates a new ECIConnectionSpec object by using a user name and password.
Methods

For more information, refer to CICSConnectionSpec.

13. ECIInteraction

Represents interactions with an OSC Region server through an ECI connection. This class has connection information, and the information is used for interactions with an OSC Region server. The object is created through createInteraction() of the ECIConnection class.

  • Package

    com.tmax.ofctg.connector.cics

  • Declaration

    public class ECIInteraction
extends com.tmax.ofctg.connector.cics.CICSInteraction
Methods

The following are relevant methods.

Method Description

public Connection getConnection()

Gets the instance of the ECIConnection class that creates its own instance (ECIInteraction).

public ResourceWarning getWarnings()

Gets the CICSResourceException class that includes information about an error that occurred while the execute() method is performed for the interaction. If no error occurs, null is returned.

  • Exception

    • ResourceException: thrown if this method fails.

public void close()

Closes the ECIConnection connection corresponding to the interaction.

  • Exception

    • ResourceException: thrown if this method fails.

public boolean execute(InteractionSpec aspec, Record sndRecord, Record rcvRecord)

  • Parameters

    • aspec: InteractionSpec corresponding to the interaction to execute.

    • sndRecord: record object that has data to send.

    • rcvRecord: record object that will have data to receive.

      [Note]

      A record interface inherits the serializable interface, which is not appropriate when sending a Java object data to a non-JVM environment. Therefore, you must write code to send record instance data appropriate for the COMMAREA format by implementing both a record interface and the javax.resource.cci.Streamable interface. execute() generates CICSResourceException as an exception if a record object does not include Streamable.

  • Return value

    • true: this method succeeds.

    • false: this method fails.

  • Exception

    • CICSResourceException: thrown if this method fails. You can check a CICS abend code depending on error cases.

    • ResourceException: thrown if this method fails.

14. ECIInteractionSpec

Defines specifications about communication between ECI connections and CICS servers. ECIInteraction uses the specifications defined in this class for communication with a CICS server.

  • Package

    com.tmax.ofctg.connector.cics

  • Declaration

    public class ECIInteractionSpec
implements java.io.Serializable,
    javax.resource.cci.InteractionSpec
Constructors
Constructor Description

public ECIInteractionSpec()

Creates an ECIInteractionSpec class object. Set the following.

  • InteractionVerb: SYNC_SEND_RECEIVE

  • UserID, Password: not used. Can be modified through setUserID() and setPassword().

  • Commarea Length: 5000 bytes. Can be modified through setCommareaLength().

public ECIInteractionSpec(int verb, String prog)

Creates an ECIInteractionSpec class object. For information about default values, refer to the ECIInteractionSpec() constructor.

  • Parameters

    • verb: one of the following interaction verbs: SYNC_SEND, SYNC_RECEIVE, and SYNC_SEND_RECEIVE. Currently, only SYNC_SEND_RECEIVE is supported.

    • prog: name of the program to execute. Can be modified through setFunctionName().

public ECIInteractionSpec(int verb, String prog, int timeout, int commLen, int repLen)

Creates an ECIInteractionSpec class object. For information about default values, refer to the ECIInteractionSpec() constructor.

  • Parameters

    • verb: one of the following interaction verbs: SYNC_SEND, SYNC_RECEIVE, and SYNC_SEND_RECEIVE. Currently, only SYNC_SEND_RECEIVE is supported.

    • prog: name of the program to execute. Can be modified through setFunctionName().

    • timeout: response timeout (currently not supported).

    • commLen: COMMAREA length.

    • repLen: response data length. Currently, all response data is received regardless of this value.
Methods

The following are relevant methods.

Method Description

public int getCommareaLength()

Gets the length of COMMAREA.

public int getExecuteTimeout()

Gets the execution timeout for the execute() method of the ECIInteraction class.

public int getInteractionVerb()

Gets one of the following InteractionVerbs defined in the InteractionSpec class: SYNC_SEND, SYNC_RECEIVE, and SYNC_SEND_RECEIVE.

public String getFunctionName()

Gets the program name.

public String getPassword()

Gets the password.

public int getReplyLength()

Gets the response data length. Currently, all response data is received regardless of this value.

public String getTPNName()

Gets the TP name.

public String getTranName()

Gets the Tran name.

public String getUserID()

Gets the user ID.

public void setCommareaLength(int length)

Sets the length of COMMAREA.

public void setExecuteTimeout(int time)

Sets the execution timeout for the execute method of the ECIInteraction class. If this method is not called, the value of Resource Adaptor is used by default.

public void setFunctionName(String name)

Sets the program name to call.

public void setInteractionVerb(int verb)

Sets InteractionVerb. (Currently only SYNC_SEND_RECEIVE is supported)

public void setUserID(String password)

Sets the ID for TACF authentication. If specified, the value of this method takes precedence over the setUserName() method of the ECIConnectionSpec class.

public void setPassword(String password)

Sets the password for TACF authentication. If specified, the value of this method takes precedence over the setPassword() method of the ECIConnectionSpec class.

public void setReplyLength(int length)

Sets the reply data length. Currently, all data entered in reply are received regardless of the value of this method.

public void setTPNName(String newTPNName)

Sets the mirror transaction name to execute through an ECI call. If both TPNName and TranName are not specified, the default value "CPMI" is used. If both are specified, TPNName takes precedence.

public void setTranName(java.lang.String newTranName)

Sets the mirror transaction name to execute through an ECI call. If both TPNName and TranName are not specified, the default value "CPMI" is used. If TPNName is not specified, and TranName is specified, the default value "CPMI" is used and OSC’s EIBTRNID is specified as TranName.

15. ECIManagedConnectionFactory

Used to create ECI Connections. This class has all the information about connections to CICS servers. The information is set in ra.xml for resource adapters. You can check a sample ra.xml in Resource Adapter Configuration File.

You cannot use this class directly, and can get and use ECIConnectionFactory created through createConnectionFactory by looking up the name set in a resource adapter. For more information about resource adapter properties, refer to CICSManagedConnectionFactory.

  • Package

    com.tmax.ofctg.connector.cics

  • Declaration

    public final class ECIManagedConnectionFactory
extends com.tmax.ofctg.connector.cics.CICSManagedConnectionFactory
implements javax.resource.spi.ManagedConnectionFactory,
    javax.resource.spi.TransactionSupport

16. ECIResourceAdapterRc

Includes constants about CICSResourceException class errors that occur in an OSC server.

  • Package

    com.tmax.ofctg.connector.cics

  • Declaration

    public class ECIResourceAdapterRc
Methods

The following are relevant methods.

Method Description

public static String getErrorMessage(int cicsRespCode)

Gets a string about error constants.

  • Response Code

    • ECI_NO_ERROR

    • ECI_ERR_INVALID_DATA_LENGTH

    • ECI_ERR_INVALID_EXTEND_MODE

    • ECI_ERR_NO_CICS

    • ECI_ERR_CICS_DIED

    • ECI_ERR_RESPONSE_TIMEOUT

    • ECI_ERR_TRANSACTION_ABEND

    • ECI_ERR_LUW_TOKEN

    • ECI_ERR_SYSTEM_ERROR

    • ECI_ERR_THREAD_CREATE_ERROR

    • ECI_ERR_INVALID_DATA_AREA

    • ECI_ERR_UNKNOWN_SERVER

    • ECI_ERR_INVALID_TRANSID

    • ECI_ERR_SECURITY_ERROR

  • Server Status

    • ECI_SERVERSTATE_DOWN

    • ECI_SERVERSTATE_UNKNOWN

    • ECI_SERVERSTATE_UP

For more information about each code, refer to "ECIResourceAdapterRc Class Constants".

The following response codes are not supported: ECI_ERR_NO_REPLY, ECI_ERR_REQUEST_TIMEOUT, ECI_ERR_EXEC_NOT_RESIDENT, ECI_ERR_NULL_WIN_HANDLE, ECI_ERR_NULL_MESSAGE_ID, ECI_ERR_ALREADY_ACTIVE, ECI_ERR_RESOURCE_SHORTAGE, ECI_ERR_NO_SESSIONS, ECI_ERR_NULL_SEM_HANDLE, ECI_ERR_INVALID_VERSION, ECI_ERR_MORE_SYSTEMS, ECI_ERR_CALL_FROM_CALLBACK, ECI_ERR_NO_SYSTEMS, ECI_ERR_MAX_SYSTEMS, ECI_ERR_MAX_SESSIONS, ECI_ERR_ROLLEDBACK, ECI_ERR_XID_INVALID.
ECIResourceAdapterRc Class Constants

The following are the ECIResourceAdapterRc class constants.

Name Value Description

public static final short ECI_CLIENTSTATE_UNKNOWN

0

Client status is unknown.

public static final short ECI_CLIENTSTATE_UP

1

The client is available.

public static final int ECI_ERR_CICS_DIED

-4

The region server is terminated during communication.

public static final int ECI_ERR_INVALID_CALL_TYPE

-14

The specified value is neither ECI_SYNC nor ECI_SYNC_TPN.

public static final int ECI_ERR_INVALID_DATA_AREA

-19

The COMMAREA length and the data length are not the same.

public static final int ECI_ERR_INVALID_DATA_LENGTH

-1

The COMMAREA length is invalid.

public static final int ECI_ERR_INVALID_EXTEND_MODE

-2

The extend mode is not ECI_NO_EXTEND.

public static final int ECI_ERR_INVALID_TRANSID

-24

An undefined transaction is called.

public static final int ECI_ERR_LUW_TOKEN

-8

Unknown LUW token.

public static final int ECI_ERR_NO_CICS

-3

The region server is not started.

public static final int ECI_ERR_RESPONSE_TIMEOUT

-6

A response timeout occurs.

public static final int ECI_ERR_SECURITY_ERROR

-27

The user ID and password combination is invalid.

public static final int ECI_ERR_SYSTEM_ERROR

-9

Unknown internal error.

public static final int ECI_ERR_TRANSACTION_ABEND

-7

A transaction abend occurs.

public static final int ECI_ERR_UNKNOWN_SERVER

-22

Unknown region server.

public static final int ECI_EXTENDED

2

The extend mode is EXTENDED.

public static final int ECI_NO_ERROR

0

Normally terminated.

public static final int ECI_NO_EXTEND

1

The extend mode is NO_EXTEND.

public static final short ECI_SERVERSTATE_DOWN

2

The server is not started.

public static final short ECI_SERVERSTATE_UNKNOWN

0

Unknown server state.

public static final short ECI_SERVERSTATE_UP

1

The server status is normal.

public static final int ECI_SYNC

1

The call type is SYNC.

public static final int ECI_SYNC_TPN

2

The call type is SYNC_TPN.