IMSInteractionSpec properties

When you define a Java method for a J2C Java Bean, you must provide values for properties that describe the interaction with IMS™ that will be performed by the Java method. These are values of the input properties of IMSInteractionSpec. The following list describes all output properties as well as input properties of IMSInteractionSpec, including those that are not set by the application component:

asyncOutputAvailable
This is an output only property. It can be used by a Java™ application, on return from a commit mode 0 interaction on a dedicated or shareable persistent socket, to determine if there is queued output for the associated clientID. clientID is a property of IMSConnectionSpec and can be a user-specified value or an IMS Connector for Java generated value. The value of asyncOutputAvailable is true if there are messages in the queue. The asyncOutputAvailable property is not set on input by the application component. Note: If your Java application uses this property, it must be exposed as an output property of IMSInteractionSpec.
convEnded
This is an output only property. It can be used by a Java application to determine if a conversation has ended (true). The convEnded property is not set on input by the application component. Note: If your Java application uses this property, it must be exposed as an output property of IMSInteractionSpec.
commitMode
Used by the IMS resource adapter to indicate the type of commit mode processing to be performed for an IMS transaction. See Overview of commit mode processing for more information. The commitMode property can be set to 0 or 1 when interactionVerb is set to SYNC_SEND_RECEIVE. When interactionVerb is set to SYNC_RECEIVE_ASYNCOUTPUT, SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT, SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT, or SYNC_SEND, IMS Connector for Java uses commitMode 0. commitMode 1 is required when interactionVerb is set to SYNC_END_CONVERSATION. If commitMode is 0 and a dedicated persistent socket is used for the interaction, the clientID property of the IMSConnectionSpec must be provided for the interaction. If commitMode is 0 and a shareable persistent socket is used for the interaction, the clientID must not be specified. If commitMode 0 or 1 is specified for an interaction on a shareable persistent socket, the output message from a transaction can be purged or rerouted. The output message is recoverable by using a subsequent interaction within the same application with interactionVerb set to SYNC_RECEIVE_ASYNCOUTPUT, SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT, or SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT. If a dedicated persistent socket is used for a commitMode 0 interaction, the output message from a transaction cannot be purged or rerouted, but the output message is recoverable using a subsequent interaction with interactionVerb set to SYNC_RECEIVE_ASYNCOUTPUT, SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT, or SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT.
socketTimeout
The maximum amount of time IMS Connector for Java will wait for a response from IMS Connect before disconnecting the socket and returning an exception to the client application. The socketTimeout value is represented in milliseconds. To use socket timeout, the value must be greater than zero. If a socket timeout is not specified for an interaction or it is supplied with a socket timeout value of zero milliseconds, this will result in no socket timeout or an infinite wait. For more information see Socket timeout and Setting socket timeout values.
executionTimeout
The maximum amount of time allowed for IMS Connect to send a message to IMS and receive a response. The executionTimeout value is represented in milliseconds and must be a decimal integer that is either -1 or between 1 and 3,600,000, inclusively. That is, the executionTimeout value must be greater than zero and less than or equal to one hour. If a -1 value is set for this property, the interaction will run without a time limit. For more information, see Execution timeout, Setting execution timeout values, and Valid execution timeout values.
imsRequestType
Indicates the type of IMS request and determines how output from the request is handled by the IMS resource adapter. Integer values are:
Value Named constant in IMSInteractionSpecProperties Description
1 IMS_REQUEST_TYPE_IMS_TRANSACTION The request is an IMS transaction. Normal transaction output returned by IMS is used to populate the application's output message. If IMS returns a "DFS" message, the IMS resource adapter throws an IMSDFSMessageException.

This value for imsRequestType is used for applications that are not generated using WebSphere® Studio MFS support.

2 IMS_REQUEST_TYPE_IMS_COMMAND The request is an IMS command. Command output returned by IMS, including "DFS" messages, is used to populate the application's output message. The IMSDFSMessageException is not thrown.

This value for imsRequestType is used for applications that submit IMS commands.

3 IMS_REQUEST_TYPE_MFS_TRANSACTION This value for imsRequestType is reserved for applications that are generated using WebSphere Studio MFS support.

Normal transaction output returned by IMS, as well as "DFS" messages, are used to populate the application's output message. The IMSDFSMessageException is not thrown.

interactionVerb
The mode of interaction between the Java application and IMS. The value currently supported by the IMS resource adapter are:
Value Named constant in IMSInteractionSpecProperties Description
0 SYNC_SEND The IMS resource adapter sends the client request to IMS through IMS Connect and does not expect a response from IMS. With a SYNC_SEND interaction, the client does not need to synchronously receive a response from IMS. SYNC_SEND is supported on both shareable and dedicated persistent socket connections and is only allowed with commitMode 0 interactions. If the interactionVerb is set to SYNC_SEND, execution timeout and socket timeout values are ignored. Note: imsRequest type 2 is not allowed with SYNC_SEND and will generate an exception.
1 SYNC_SEND_RECEIVE The execution of an IMS Interaction sends a request to IMS and receives a response synchronously. A typical SYNC_SEND_RECEIVE interaction is the running of a non-conversational IMS transaction in which an input record (the IMS transaction input message) is sent to IMS and an output record (the IMS transaction output message) is returned by IMS. SYNC_SEND_RECEIVE interactions are also used for the iterations of a conversational IMS transaction. A conversational transaction requires commitMode 1. A non-conversational transaction can run using either commitMode 1 or commitMode 0. If commitMode 0 is used on a dedicated persistent socket, a value for the clientID property of IMSConnectionSpec must be provided. If commitMode 0 is used on a shareable persistent socket, a value for the clientID property of IMSConnectionSpec must not be provided.
3 SYNC_END_CONVERSATION If the application executes an interaction with interactionVerb set to SYNC_END_CONVERSATION, the IMS resource adapter sends a message to force the end of an IMS conversational transaction.

For SYNC_END_CONVERSATION, commitMode 1 is required. The clientID is not allowed.

4 SYNC_RECEIVE_ASYNCOUTPUT interactionVerb SYNC_RECEIVE_ASYNCOUTPUT is valid on both shareable persistent and dedicated persistent socket connections. SYNC_RECEIVE_ASYNCOUTPUT is used to retrieve asynchronous output that was not delivered. When SYNC_RECEIVE_ASYNCOUTPUT is used on a dedicated persistent socket, a value must be provided for the clientID property of IMSConnectionSpec.

With this type of interaction, the Java client can only receive a single message. If there are no messages in the IMS OTMA Asynchronous Queue for the clientID when the request is made, no further attempts are made to retreive the message. No message is returned and a timeout will occur after the length of time specified in the executionTimeout property of the SYNC_RECEIVE_ASYNCOUTPUT interaction.

5 SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT interactionVerb SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT is valid on both shareable and dedicated persistent socket connections. It is used to retrieve asynchronous output.

With this type of interaction, the Java client can only receive one single message. If there are no messages in the IMS OTMA Asynchronous Queue for the clientID when the request is made, no further attempts will be made to retrieve the message. No message will be returned and a timeout will occur after the length of time specified in the executionTimeout property of the SYNC_RECEIVE_ASYNCOUTPUT_SINLE_NOWAIT interaction.

Note: The interactionVerbs, SYNC_RECEIVE_ASYNCOUTPUT and SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT, perform the same function. However, it is recommended to use SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT with Rational Application Developer 6.0.0.2 with the IMS resource adapter 9.1.0.1.1 or 9.1.0.2.

6 SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT interactionVerb SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT is used to retrieve asynchronous output. It is valid on both shareable and dedicated persistent socket connections.

With this type of interaction, the Java client can only receive one single message. If there are no messages in the IMS OTMA Asynchronous Queue for the clientID when the request is made, IMS Connect waits for OTMA to return a message. IMS Connect waits the length of time specified in the executionTimeout property of the SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT interaction before returning an exception.

The J2EE Connection Architecture (JCA) values SYNC_RECEIVE (2) is not currently supported.

ltermName
The LTERM name used to override the value in the LTERM field of the IMS application program's I/O PCB. See the IMS Connect User's Guide and Reference (SC27-0946-23) for a description of how to use the LTERM override.

The value of this property can be set if the client application wants to provide an LTERM override name. This name will be in the IMS application program's I/O PCB, with the intent that the IMS application will make logic decisions based on this override value.

mapName
The mapName field typically contains the name of a Message Format Service (MFS) control block. MFS is the component of IMS that performs online formatting of transaction input and output messages. Since IMS Connect uses IMS OTMA to access IMS, MFS online formatting is bypassed. However, the mapName field can still be used by a Java application to input the name of an MFS control block to an IMS application program or to retrieve the name of an MFS control block provided by an IMS application program.

On input, typically the value of the mapName property is the name of an MFS Message Output Descriptor, or "MOD". The MOD name will be provided to the IMS application program in the I/O PCB.

On output, the value of the mapName property is the name of an MFS Message Output Descriptor, or "MOD". This is the MOD name that the IMS application program specified when inserting the transaction output message to the I/O PCB.

Note: The mapName field should not be used by Java applications that use an enterprise service whose input and output messages are generated by WebSphere Studio MFS support.

purgeAsyncOutput
This is an input property. This property determines whether or not IMS Connect purges undelivered output.

This property is only valid for interactions on shareable persistent socket connections that use IMS interaction verb SYNC_SEND_RECEIVE. It is not valid for any interactions on dedicated persistent socket connections. It applies to commit mode 0 interactions. It does not apply to commit mode 1 interactions. However, if a commit mode 1 interaction executes a program-to-program switch, the spawned program will run commit mode 0 and therefore the property will apply.

If the purgeAsyncOutput property is not specified on a SYNC_SEND_RECEIVE interaction on a shareable persistent socket connection, the default is TRUE. If this property is set to TRUE, the following output messages are purged:
  • Undelivered output message inserted to the I/O PCB by the primary IMS application program.
  • Output messages inserted to the I/O PCB by secondary IMS application programs invoked by a program to program switch.
reRoute
This is an input property.

This property is only valid for SYNC_SEND_RECEIVE interactions on shareable persistent socket connections with either commit mode 0 or a commit mode 1 interaction that spawns a program-to-program switch which invokes another commit mode 0 interaction and results in undeliverable secondary output. This property determines if undelivered output is to be rerouted to a named destination specified in the reRouteName field. If reRoute is TRUE, the asynchronous output is not queued to the TPIPE of the generated clientID. Instead, the asynchronous output is queued to the destination specified in the reRouteName field. The default value for reRoute is FALSE.

If both reRoute and purgeAsyncOutput are set to TRUE, an exception is thrown.

reRouteName
This property provides the name of the destination to which asynchronous output is queued. If reRoute is TRUE, this property provides the named destination. If reRoute is FALSE, the reRouteName property is ignored.
If the reRoute property is set to TRUE, and no reRouteName is provided, the value for the reRouteName property is:
  1. The value specified in the IMS Connect configuration file.
  2. If no value is specified in the IMS Connect configuration file, the value "HWS$DEF" is used.
The property, reRouteName, is only valid for SYNC_SEND_RECEIVE interactions on shareable persistent socket connections. It is not valid for any interactions on dedicated persistent socket connections.
Related concepts
Execution timeout
Socket timeout
Related tasks
Setting execution timeout values
Setting the Socket Timeout Value
Related reference
Valid execution timeout values
Connection properties
Terms of use | Feedback
(C) Copyright IBM Corporation 2000, 2005. All Rights Reserved.