Shareable persistent socket processing model

Shareable persistent socket connections are connections that can be used for commit mode 1 and commit mode 0 interactions. The following scenarios describe the SYNC_SEND_RECEIVE interaction on a shareable persistent socket during normal processing, error processing, and execution timeout.

Normal processing scenario

The IMS TM resource adapter, with the application server, obtains either an available connection from the connection pool or creates a new connection. The IMS TM resource adapter, as part of initializing a new connection, generates a client ID for the connection. The generated client ID identifies the socket connection, and for commit mode 0 interactions, the tpipe and associated OTMA asynchronous hold queue.

The IMS TM resource adapter ensures that a socket is associated with the connection and sends the request with input data to IMS Connect by using that socket. IMS Connect then sends the message to IMS, where IMS runs the transaction and returns the output message.

For commit mode 0 interactions, when it receives the output message, the IMS TM resource adapter sends an ACK message to IMS, which signals IMS to discard the output from the IMS queue. When the client application closes the connection or terminates, the connection is returned to the connection pool for reuse by other commit mode 0 or commit mode 1 interactions.

Error processing scenario

All errors result in a resource exception being thrown to the client application. In addition, some errors result in the socket being disconnected by IMS Connect. For commit mode 0 interactions, an exception means that the output message cannot be delivered to the client application. However, following the exceptions, undelivered output messages for commit mode 0 interactions on shareable persistent socket connections can be retrieved if the SYNC_SEND_RECEIVE interaction specifies that undelivered output is to be rerouted to a specific destination. To have an undelivered output message rerouted to a specific destination, the following additional properties must be specified in the IMSInteractionSpec object that is passed on the SYNC_SEND_RECEIVE interaction:
  • Set the purgeAsyncOutput property to false so that undelivered output is not purged.
  • Set the reRoute property to true, and specify a reroute destination in the RouteName property.

To retrieve undelivered output from a reroute destination, a separate client application issues a SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT or SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT interaction on a dedicated persistent socket connection. The client application provides the reroute destination as the client ID of the interaction.

Alternatively, to retrieve undelivered output from a reroute destination, a separate client application issues a SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT, or SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT interaction on a shareable persistent socket connection by specifying the alternate client ID. Using the alternate client ID, a client application can retrieve undelivered asynchronous output messages from any tpipe.

The default value of the purgeAsyncOutput property is true. When the value of the purgeAsyncOutput property is true, the following output messages are purged:
  • Undelivered output message inserted to the I/O Program Communications Block (I/O PCB) by the primary IMS application program
  • Output messages inserted to the I/O PCB by secondary IMS application programs invoked by program-to-program switches
When the purgeAsyncOutput property is set to false, the reroute destination must be specified.

Execution timeout scenario

If an execution timeout occurs, the socket connection remains open but the output message is not delivered to the client application. However, following an execution timeout exception, undelivered output messages for commit mode 0 interactions on shareable persistent socket connections can be retrieved in either of the following two ways:
  • The same client application that issued the SYNC_SEND_RECEIVE interaction can issue a SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT or SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT interaction.
  • The undelivered output message can be rerouted to a specific destination as described in the error processing scenario.

When the client application closes the connection or terminates, the connection is returned to the connection pool so it can be reused by other commit mode 0 or commit mode 1 interactions.