Overview of commit mode processing

Commit mode refers to the type of commit processing performed by IMS™. The Java™ client specifies the commit mode protocol to be used when it submits a transaction request to IMS.

There are two types of commit mode processing supported by IMS Connect and IMS: commit mode 0 (commit-then-send) where IMS commits the IMS database changes and then sends the output to the client and commit mode 1 (send-then-commit) where IMS sends the output to the client and then commits the database changes.

Associated with the commit mode protocols, IMS Connect and IMS also support three synchronization level (Synch Levels): NONE, CONFIRM, and SYNCPT. All three Synch Levels can be used with commit mode 1. CONFIRM can only be used with commit mode 0. However, IMS Connector for Java does not currently support synch level CONFIRM with commit mode 1.

Currently, the synchronization level is not set by the Java client. IMS Connector for Java automatically provides the synchronization level when communicating with IMS Connect.

IMS Connector for Java supports the following combinations:

The synchronization level is not set by the Java client. IMS Connector for Java automatically provides the synchronization level when communicating with IMS Connect.

If the Java client submits a transaction request with commit mode 1 Synch Level NONE, IMS Connector for Java passes the request through IMS Connect to IMS. IMS processes this transaction and attempts to send the output message to the Java client. The Java client may receive the output message from the transaction or may receive an exception. In either case, IMS will have already committed the changes to the database and discarded the output message of the IMS transaction.

Similarly, if the Java client sends a transaction with commit mode 0 Synch Level CONFIRM, the Java client may receive the output message from the transaction or may receive an exception. However, if the Java client receives an exception when commit mode 0 is used, the output may or may not be queued for later retrieval. Whether or not the output message that was not delivered to a Java client will be queued depends on the type of socket connection the Java client uses for the commit mode 0 interaction.

The type of exception also determines whether or not an output message is available for retrieval. For example, if the Java client receives an IMSDFSMessageException indicating that the transaction is stopped, the application was not run; therefore, there is no output message available for retrieval. However, if the transaction runs but the executionTimeout value expires before the output message is returned to IMS Connect, the Java client will receive an EISSystemException that an execution timeout has occurred. In this case, the output message will be queued to the appropriate IMS OTMA Asynchronous Output Queue or TPIPE for later retrieval.

Note: In IMS/OTMA terminology, a transaction pipe (TPIPE) is a logical connection between a client (IMS Connect) and the server (IMS/OTMA). For commit mode 0 interactions, the TPIPE is identified by the clientID used for the interaction. Each clientID used for a commit mode 0 transaction will have its own TPIPE. For commit mode 1 interactions, the TPIPE is identified by the IMS Connect port number used for the interaction. Therefore, each port will have a TPIPE which will be used for all clients running commit mode 1 interactions on that port.

Regardless of whether your Java client is running an IMS transaction with commit mode 1 or commit mode 0, the Java client specifies a value for the interactionVerb property of IMSInteractionSpec. If a commit mode 0 interaction is specified, the Java client may also have to provide a value for the clientID property of IMSConnectionSpec. clientID is a property of IMSConnectionSpec and identifies the IMS OTMA Asynchronous Output Queue or TPIPE where the recoverable output messages are placed. Whether or not a Java client provides a clientID for a commit mode 0 interaction depends on the type of socket connection being used by the Java client.

To retrieve output messages from a TPIPE, the Java client submits a request in which it specifies one of the values SYNC_RECEIVE_ASYNCOUTPUT, SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT, or SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT for the interactionVerb property of IMSInteractionSpec and a value for the clientID property of IMSConnectionSpec. For more information about asynchronous output support, see Chapter 9: Protocols in IMS Connect Guide and Reference.

In general, the SYNC_RECEIVE_ASYNCOUTPUT, SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT, or SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT interactions can be used to retrieve output messages queued for any clientID, regardless of how those messages were queued to the associated clientID - either as a result of a failed commit mode 0 transaction or from an IMS application that issued an insert to an ALTPCB (Alternate Program Communication Block). In the case of retrieving an output message from a failed commit mode 0 transaction, the clientID provided in the IMSConnectionSpec for retrieval request must match the clientID that was specified on the failed commit mode 0 transaction.

If there is nothing in the OTMA Asynchronous Output Queue for that particular clientID, you will receive an execution timeout exception. The timeout exception can mean either that there are no messages in the queue or that the timeout value did not provide enough time for IMS Connect to retrieve the message from the queue. For both SYNC_RECEIVE_ASYNCOUTPUT, SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT, or SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT, as well as SYNC_SEND_RECEIVE interactions, executionTimeout is the length of time IMS Connect will wait for a response from IMS. If you do not specify an executionTime value for a retrieval request, the default execution timeout value will be used. The default Timeout value is the IMS Connect configuration member TIMEOUT value. The user may need to experiment with the executionTimeout value, to ensure that output messages are returned for all types of interactions

Commit mode processing and socket connections

All socket connections created by the IMS resource adapter are persistent. In other words, the same socket connection between IMS Connector for Java and IMS Connect can be serially reused for multiple interactions with IMS Connect. The socket connection will not be closed and reopened between interactions. There are two types of persistent sockets, shareable and dedicated.

Shareable Persistent Socket

The shareable persistent socket can be shared (serially reused) by multiple applications executing either commit mode 1 or commit mode 0 interactions. For an application executing a commit mode 0 interaction on a shareable persistent socket, the IMS resource adapter automatically generates a clientID with the prefix "HWS". This clientID represents and identifies the socket connection as well as the associated OTMA TPIPE. For this type of socket, only clientIDs generated by the IMS resource adapter are allowed. A user-specified clientID is not allowed with shareable persistent socket support.

Note: IMS application programs that insert messages to an alternate PCB must not use names beginning with "HWS" for the alternate PCBs.

Any output message that cannot be delivered to a Java client executing a commit mode 0 interaction on a shareable persistent socket can be queued for later retrieval. Also, any commit mode 1 interaction on a shareable persistent socket that spawns a program-to-program switch which invokes another commit mode 0 interaction resulting in secondary output, can be requeued for later retrieval. SYNC_RECEIVE_ASYNCOUTPUT, SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT, and SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT interactions are supported on shareable persistent sockets. To retrieve undelivered output messages that are queued in the IMS OTMA Asynchronous Hold Queue or TPIPE, the interaction verbs must be invoked within the same client application, because the same generated client ID that identifies the shareable socket connection and the associated OTMA TPIPE must be used.

On shareable persistent sockets, the undelivered output messages can be either purged or rerouted to another destination other than the associated TPIPE of the generated clientID. To purge undelivered output messages, you must set the IMSInteractionSpec property, purgeAsyncOutput, to TRUE. This input property determines if IMS Connect purges the undelivered I/O PCB output. The purgeAsyncOutput property is only valid with the SYNC_SEND_RECEIVE interaction verb. If the property is not specified on SYNC_SEND_RECEIVE, the default is TRUE.

Another option of handling undelivered output messages on shareable persistent sockets and rerouting the messages to another destination. You can reroute the undelivered output message to different destination by setting the IMSInteractionSpec property, reRoute, to TRUE. This property is only valid for SYNC_SEND_RECEIVE interaction verb. If reRoute is set to TRUE, the undelivered output message is queued to a named destination provided by the client application, which is specified on the reRouteName IMSInteractionSpec property. If the reRoute property is set to TRUE and no reRouteName is provided, the value of the reRouteName property is the value specified in the IMS Connect configuration file. If no value is specified in the IMS Connect configuration file, the default value HWSDEF is used.

Shareable persistent socket connections are created by an IMS Connection Factory with values for at least the following custom properties:
  • Host name = TCP/IP host name of machine running IMS Connect
  • Port number = associated port number
  • Datastore name = name of target IMS
  • CM0Dedicated = FALSE
FALSE is the default value for the CM0Dedicated property and ensures that the connection factory will create shareable persistent socket connections.

Dedicated persistent socket

A dedicated persistent socket is used for Java applications executing commit mode 0 interactions only. It can be shared (serially reused) by multiple applications with the same user-specified clientID. For this type of socket, only interactions with user-specified clientIDs are allowed. A valid user-specified clientID:
  • Must be a string of 1 to 8 alphanumeric (A-Z, 0-9) or special (@,#,$) characters.
  • Must not start with the character string, "HWS"; except HWSDEF which is the default reRouteName.
  • Must not be an IMS Connect port number.
  • If lowercase letters are provided, the letters will be changed to uppercase

A dedicated persistent socket means the socket connection is assigned to a specific clientID and will remain dedicated to that particular clientID until it is disconnected. SYNC_SEND_RECEIVE, SYNC_SEND, SYNC_RECEIVE_ASYNCOUTPUT, SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT, and SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT interactions are supported on dedicated persistent sockets.

SYNC_RECEIVE_ASYNCOUTPUT, SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT, and SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT interactions on dedicated persistent sockets enable client applications to retrieve messages that were placed on an IMS OTMA Asynchronous Output Queue as a result of a failed commit mode 0 interaction, from an IMS application that issued an insert to an ALTPCB (Alternate Program Communication Block), or from a reRoute of a transaction that was executed on a shareable connection factory. To retrieve the messages, the client application must provide the clientID, which represents the TPIPE that has asynchronous output messages queued. Interactions on dedicated persistent sockets that have undelivered output messages cannot be rerouted or purged.

Dedicated persistent socket connections are created by an IMS Connection Factory with values for at least the following custom properties:
  • Host name = TCP/IP host name of machine running IMS Connect
  • Port number = associated port number
  • Datastore name = name of target IMS
  • CM0Dedicated = TRUE

A value of TRUE for the CM0Dedicated property ensures that the connection factory will create dedicated persistent socket connections.

Note: If you have more than one connection factory configured to create dedicated persistent sockets to the same IMS Connect instance, only one connection factory can dedicate a socket to a particular clientID at one time. For example, if the first connection factory successfully creates a socket connection dedicated to clientID, CLIENT01; the second connection factory will receive the following exception if it tries to create a socket connection dedicated to CLIENT01 while the socket connection created by the first connection factory is still connected to IMS Connect:
javax.resource.spi.EISSystemException: ICO0001E:
com.ibm.connector2.ims.ico.IMSTCPIPManagedConnection@23766050.processOutputOTMAMsg(byte [], InteractionSpec,Record) error. IMS Connect returned error: RETCODE=[8], REASONCODE=[DUPECLNT]. 
Duplicate client ID was used;  the client ID is currently in use. 

If you are running on z/OS with a sysplex distributor environment or running on Windows with a Workload Management WebSphere Application Server clones environment, dedicated persistent socket connection is not recommended.

Releasing Persistent Sockets

A TCP/IP connection between IMS Connector for Java and IMS Connect is persistent; in other words it remains open as long as IMS Connector for Java or IMS Connect does not disconnect it due to an error. This is the case for both a shareable persistent socket connection and a dedicated persistent socket connection. However, in the case of a dedicated persistent socket connection, the socket connection can only be used by interactions that have the same clientID that was used to establish the connection. The number of socket connections will increase as new clientIDs are used for interactions on dedicated persistent socket connections.

If you have the Max connections property set to a non-zero value and you also have a non-zero value for the Connection timeout property, when the MaxConnections is reached and all the connections are in use, the application will get a ConnectionWaitTimeoutException after the seconds specified in Connection timeout have elapsed. This is standard behavior for WebSphere® Application Server. The ConnectionWaitTimeoutException applies to both dedicated persistent sockets and shareable persistent sockets.

However, if MaxConnections has been reached and one of the persistent socket connections is currently not in use, then WebSphere Application Server will disconnect that socket in order to respond to the request to create a new persistent socket connection. This also is standard behavior for the WebSphere Application Server and applies to both dedicated and shareable persistent sockets.

Related concepts
SYNC_SEND programming model
SYNC_SEND_RECEIVE programming model
Retrieving asynchronous output
Related tasks
Displaying output message counts
Terms of use | Feedback
(C) Copyright IBM Corporation 2000, 2005. All Rights Reserved.