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.