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 |
| 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.