Shareable persistent sockets

A shareable persistent socket is a socket that can be shared (serially reused) by multiple applications that execute either commit mode 1 (CM1) or commit mode 0 (CM0) interactions.

For an application that executes a commit mode 0 interaction on a shareable persistent socket, the IMS TM resource adapter automatically generates a client ID with the prefix HWS. This client ID represents and identifies the socket connection and the associated OTMA tpipe. For this type of socket, only client IDs that are generated by the IMS TM resource adapter are allowed. If you specify a client ID for a connection that has not been defined as CM0 on a shareable persistent socket, an exception is thrown and returned to the client.

Restriction: IMS application programs that insert messages to an alternate PCB must not use names that begin with HWS for the alternate PCBs. IMS TM resource adapter cannot retrieve HWS messages.

Tip: Client IDs are different from alternate client IDs. The alternate client ID is a property of the IMSInteractionSpec class. Alternate client IDs are used to retrieve asynchronous output messages from OTMA hold queues (tpipes).

Supported commit mode and interaction

A shareable persistent socket can be used for Java™ applications that execute either commit mode 1 or commit mode 0 interactions.

Table 1. Supported commit modes, interaction verbs, and sync levels by socket type
Commit mode	Socket type	Interaction verb	Client ID	Sync level
CM1	Shareable persistent	SYNC_END_CONVERSATION (for conversational transactions) SYNC_SEND_RECEIVE	Automatically generated and managed	None or Confirm
CM0	Shareable persistent	SYNC_SEND SYNC_SEND_RECEIVE SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT SYNC_RECEIVE_CALLOUT (for non-managed callout programming model)	Automatically generated and managed	Confirm
CM0	Dedicated persistent	SYNC_SEND SYNC_SEND_RECEIVE SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT	Specified by client applications (the clientID property)	Confirm

Table 2. Supported commit modes, interaction verbs, and sync levels by socket type
Commit mode	Socket type	Interaction verb	Client ID	Sync level
CM1	Shareable persistent	SYNC_END_CONVERSATION (for conversational transactions) SYNC_SEND_RECEIVE	Automatically generated and managed	None or Confirm
CM0	Shareable persistent	SYNC_SEND SYNC_SEND_RECEIVE SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT SYNC_RECEIVE_CALLOUT (for non-managed callout programming model)	Automatically generated and managed	Confirm
CM0	Dedicated persistent	SYNC_SEND SYNC_SEND_RECEIVE SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT	Specified by client applications (the clientID property)	Confirm

The SYNC_RECEIVE_ASYNCOUTPUT interaction verb is deprecated and replaced by the SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT interaction verb.

Message retrieval

Any output message that cannot be delivered to a Java client that executes a CM0 interaction on a shareable persistent socket can be queued for later retrieval. Secondary output is always treated as CM0 output and can be requeued for subsequent retrieval.

Consider the situation in which a CM1 or CM0 interaction on a shareable persistent socket executes a program-to-program switch. If both programs return output, the second output message returned is treated as a CM0 output. It can be queued again and then retrieved later.

If a CM1 or CM0 interaction on a shareable persistent socket creates a program-to-program switch that invokes another CM0 interaction that results in secondary output (which is always CM0), the output can be queued again for later retrieval.

If undelivered output messages that are queued in the IMS OTMA asynchronous hold queue or tpipe are not retrieved by using the alternate client ID, the original interaction and the retrieval must be invoked within the same client application by using the same socket connection. The same generated client ID that identifies the shareable socket connection and the associated OTMA tpipe must be used for both the original interaction and the retrieval of any asynchronous output from that interaction.

On shareable persistent sockets, undelivered output messages can be handled in several ways:

Retrieve undeliverable output by specifying the OTMA hold queue name that has the asynchronous output messages as the alternate client ID property value of the IMSInteractionSpec object.
Purge the undelivered output. To purge undelivered output messages, the value of the IMSInteractionSpec purgeAsyncOutput property must be set to true. This input property determines if IMS Connect purges the undelivered I/O PCB output. The purgeAsyncOutput property is valid with the SYNC_SEND_RECEIVE interaction verb only. If the property is not specified on SYNC_SEND_RECEIVE, the default is true.
Reroute the messages to another destination. You can reroute the undelivered output message to a different destination by setting the IMSInteractionSpec reRoute property to true. This property is valid only for the SYNC_SEND_RECEIVE and SYNC_SEND interaction verbs. If the reRoute property is set to true, the undelivered output message is queued to a named destination that is usually provided by the client application. This destination is specified in the IMSInteractionSpec reRouteName 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

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 the system that is running IMS Connect
Port number: associated port number
Data store name: name of the target IMS
CM0 dedicated: false

The default value for the CM0Dedicated property is false, which ensures that the connection factory creates a shareable persistent socket connection unless the CM0Dedicated property has been explicitly set to true.