The asynchronous output programming model

This programming model allows you to retrieve output that has been queued by IMS™.

Your application may need to retrieve output that has been queued at some earlier point in time - hence the term asynchronous output. Asynchronous output can be the result of a number of situations. For example, undelivered output from commitMode 0 interactions, output from program-to-program switches, output from ISRTs to an alternate PCB, output from an IMS application that returns multiple output messages.

To retrieve asynchronous output, your Java™ application executes a SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT or SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT interaction. Your application provides the value for the interactionVerb property and a value of 0 for the commitMode property of the IMSInteractionSpec object used by the execute method of the interaction.

There are two types of socket connections, shareable persistent socket and dedicated persistent socket, that can be used to retrieve asynchronous output. The way to retrieve asynchronous output messages is different depending on the type of socket connection used. The interactionVerb property values that can be used to retrieve asynchronous output are: SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT, and SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT (along with the older SYNC_RECEIVE_ASYNCOUTPUT).

Note: There is no difference in function between SYNC_RECEIVE_ASYNCOUTPUT and SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT. However, it is recommended that you use the new name SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT with V9.1.0.1 and later deliverables of the IMS TM resource adapter. Only the new name, SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT, will be used in the rest of this document.

The difference between SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT and SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT determines how IMS Connect checks for output on the IMS OTMA Asynchronous Hold Queue. For SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT or SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT interactions, if there is no asynchronous output in the IMS OTMA Asynchronous Hold Queue when the retrieve request is made, IMS Connect will return an execution timeout notification as soon as the execution timeout value specified by the client application has passed. For this reason, the shortest possible execution timeout value, 10, is recommended for SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT interactions.

For a SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT interaction, if there is no asynchronous output in the IMS OTMA Asynchronous Hold Queue when the retrieve request is made, IMS Connect will wait up to the length of time specified in the executionTimeout property of the interaction for OTMA to return a message. If there is still no asynchronous output in the hold queue when the execution timeout has passed, IMS Connect will return an execution timeout error. For a SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT interaction, you should select an appropriate execution timeout value, rather than the shortest possible value.

All three interactionVerb property values require commit mode 0 and can be used on both shareable persistent socket and dedicated persistent socket connections. In addition, IMSInteractionSpec properties purgeAsycOutput, reRoute and reRouteName do not apply to interactions which use these three interactionVerbs and are ignored by the IMS TM resource adapter. The way that interactionVerb properties are invoked on dedicated and shareable persistent socket connections is different. In addition, asynchronous output may be retrieved from shareable persistent socket connections using two methods:: using alternate client ID or reRouteName in the same

Retrieving asynchronous output on dedicated persistent socket connections

To retrieve the queued output message on a dedicated persistent socket, the client application must execute a commit mode 0 interaction with the interactionVerb property of IMSInteractionSpec set to SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT, or SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT.

In addition to executing a commit mode 0 interaction on a dedicated persistent socket connection with the appropriate interactionVerb property of IMSInteractionSpec, the client application must also provide a value for the clientID property of IMSConnectionSpec. The clientID is required because it determines the TPIPE from which the asynchronous output will be retrieved. To retrieve output messages from a commit mode 0 interaction on a dedicated persistent socket, the clientID specified on the SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT/NOWAIT interaction must match the value specified for the original commit mode 0 interaction. To retrieve output messages sent to an alternate PCB, the clientID specified on the SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT/NOWAIT interaction must match the name of the alternate PCB. To retrieve output messages which were rerouted to a reRouteName destination, the clientID on the SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT/NOWAIT interaction must be set to that destination indicated by the reRouteName property.

Retrieving asynchronous output with an alternate client ID on shareable persistent socket connections

A client application can retrieve asynchronous output messages that are either rerouted or non-rerouted from any OTMA TPIPE using an alternate client ID. This alternate client ID is specified using the altClientID property of the IMSInteractionSpec object used by the execute method of the interaction. The alternate client ID will correspond with the name of the OTMA TPIPE that has the asynchronous output messages. A client application cannot specify a rerouteName and the alternate client ID in the same interaction.

Alternate client ID is supported when a client application uses all of the following:

Retrieving asynchronous output without an alternate client ID on shareable persistent socket connections

The client application can retrieve only non-rerouted asynchronous output messages resulting from an interaction on a shareable persistent socket connection without using alternate client ID by executing a SYNC_RECEIVE_ASYNCOUTPUT or SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT or SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT interaction on the same shareable persistent socket connection in the same application that invoked the interaction that led to the asynchronous output being queued.

The following table shows the behavior of the 'retrieval of asynchronous output message' (resumeTpipe) interaction when different property values are specified.
Table 1. Behavior of resumeTpipe interactions when IMSConnectSpec property values are specified
Interaction Socket clientID reRouteName altClientID Comments
resumeTPIPE, without specifying altClientID Shareable null null null Retrieval of asynchronous output must be done on the same connection as the previous interaction. Otherwise, the asynchronous output cannot be retrieved. If the retrieval failed, the message will be lost.
resumeTPIPE, without specifying altClientID Shareable null myRR null Retrieval of asynchronous messages must be done on the same connection as the previous interaction. If the retrieval failed, the message will be rerouted to myRR.
resumeTPIPE, specifying altClientID Shareable null N/A myTPIPE Retrieval of asynchronous messages from TPIPE "myTPIPE" reRouteName and altClientID are mutually exclusive and may not be used at the same time.
resumeTPIPE Dedicated myCID N/A N/A Retrieval of asynchronous messages from TPIPE "myCID"
Note: For shareable persistent socket connections, the commit mode for a SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT/NOWAIT interaction will automatically be set to 0 internally by the IMS TM resource adapter regardless of the value that is set in the IMSInteractionSpec for that interaction. This behavior is different from the behavior for SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT/NOWAIT interactions on dedicated persistent socket connections. For dedicated socket connections, the commit mode must be explicitly set to 0.

Feedback