Commit mode and sync level processing

The commit mode you choose determines the type of commit processing performed by IMS™.

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 levels (synch levels): NONE, CONFIRM, and SYNCPT. All three synch levels can be used with commit mode 1. Only CONFIRM can be used with commit mode 0.

While IMS Connector for Java automatically provides the synchronization level when communicating with IMS Connect, the synchronization level may be set explicitly by the Java client using the setSyncLevel(int) method to NONE or CONFIRM. Currently the Java client cannot explicitly set the synch level to SYNCPT. For commit mode 1 interactions, the default synch level is NONE. It will suffice to set the Interaction Verb to SYNC_SEND_RECEIVE only without setting synch level. For commit mode 0 interactions, the default synch level is CONFIRM. It will suffice to set the Interaction Verb to SYNC_SEND_RECEIVE and the commit mode to 0 only without setting synch level. If any other numeric value besides 0 or 1 is passed to the setSyncLevel(int) method, an error will be thrown.

IMS Connector for Java supports the following combinations:

If the Java client submits a transaction request with commit mode 1 synch level CONFIRM, 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 through IMS Connector for Java. IMS Connector for Java sends a positive acknowledgement on behalf of the Java client to IMS. IMS will send a return code to IMS Connector for Java indicating whether or not the changes were committed. If they were, IMS Connector for Java will send the output to the Java client. If not, the Java client will receive an exception. If any errors occur during this process, the Java client will receive an exception.

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 execution timeout 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 execution timeout 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 TM Resource Adapter are persistent. In other words, the same socket connection between IMS Connector for Java and IMS Connect can be serially re-usedfor 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 TM Resource Adapter are allowed. A user-specified clientID is not allowed with shareable persistent socket support.

Note: This clientID should not be confused with the alternate clientID, a property of IMSInteractionSpec that deals with the retrieval of asynchronous output messages from any OTMA hold queue (TPIPE).
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 or commit mode 0 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. If the alternate client ID is not used, 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, undelivered output messages can be handled in more than one way. Undeliverable output can be retrieved by specifying the OTMA hold queue name that has the asynchronous output messages as the alternate client ID property value of the IMSInteractionSpec object. Alternatively, the undelivered output may be purged. To purge undelivered output messages, you must ensure the IMSInteractionSpec property purgeAsyncOutput is 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.

You can reroute the undelivered output message to a different destination by setting the IMSInteractionSpec property, reRoute, to TRUE. This property is only valid for the 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 HWS$DEF is used.

Shareable persistent socket connections are created by an IMS Connection Factory with required values for 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".
  • 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 the reroute of the output from 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. 

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.


Feedback