IMSInteractionSpec property configuration

You must provide a configured IMSInteractionSpec object to interact with IMS™.

When your Java™ application interacts with IMS it must provide a configured IMSInteractionSpec object. The values of the properties of the IMSInteractionSpec object describe the interaction with IMS. Values for the properties of IMSInteractionSpec can be provided directly via set methods by an application that uses the Common Client Interface, or they can be provided to a wizard of an IDE that generates code for the application. Some of the properties are input only properties, some are input and output properties, and some are output only properties. Output only properties are interrogated by the Java application (also called application component) to determine additional information about the interaction.

The following list describes all the properties of IMSInteractionSpec:

altClientID
This is an input only property and is used to provide the name of an alternate client ID. This name will be used as a TPIPE from which asynchronous output will be retrieved on a shareable persistent socket connection.
This property is supported with the following criteria:
  • TCP/IP connection with shareable persistent socket
  • Valid Interaction Verbs for retrieval of asynchronous output messages (resumeTpipe request): SYNC_RECEIVE_ASYNCOUTPUT, SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT, and SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_WAIT
  • Commit Mode 0 interaction - Cannot be used with Local Option
  • Cannot be used with Dedicated socket connection
  • The reroute name and the alternate clientID are mutually exclusive and cannot be specified at the same time
asyncOutputAvailable
This is an output only property. It can be used by a Java application to determine if there is queued output for the TPIPE associated with the connection used for a commitMode 0 interaction. For dedicated persistent socket connections, the name of the TPIPE is the value in the clientID property of IMSConnectionSpec. For shareable persistent socket connections, the name of the TPIPE is generated by IMS Connector for Java. 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 TM 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 shareable persistent socket is used for the interaction, the clientID must not be specified. If commitMode 0 is specified for an interaction on a shareable persistent socket, the output message from a transaction can be purged or rerouted. The undelivered secondary output from a program to program switch can also be purged or rerouted.
If a dedicated persistent socket connection is used for an interaction, the commitMode must be 0 and the clientID property of the IMSConnectionSpec used for the connection must be provided. If a dedicated persistent socket is used for a commitMode 0 interaction, undelivered output messages are always recoverable and cannot be purged or rerouted.
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 TM 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 containing the "DFS" message.

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 values currently supported by the IMS TM resource adapter are:
Value Named constant in IMSInteractionSpecProperties Description
0 SYNC_SEND The IMS TM 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 TM resource adapter sends a message to force the end of an IMS conversational transaction.

The IMSInteractionSpec property, commitMode, and the IMSConnectionSpec property, clientID, do not apply when SYNC_END_CONVERSATION is provided for interactionVerb.

4 SYNC_RECEIVE_ASYNCOUTPUT interactionVerb SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT 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.

A SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT interaction on a shareable persistent socket connection must be in the same application as the original SYNC_SEND or SYNC_SEND_RECEIVE interaction and must use the same shareable persistent connection. This primarily occurs following execution timeout.

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

SYNC_RECEIVE_ASYNCOUTPUT_
SINGLE_NOWAIT

interaction on a shareable persistent socket connection must be in the same application as the original SYNC_SEND or SYNC_SEND_RECEIVE interaction and must use the same shareable persistent connection. This primarily occurs following execution timeout.
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_
SINGLE_NOWAIT

interaction.
Note: The interactionVerbs, SYNC_RECEIVE_ASYNCOUTPUT_SINGLE_NOWAIT and

SYNC_RECEIVE_ASYNCOUTPUT_
SINGLE_NOWAIT

, perform the same function. However, it is recommended to use

SYNC_RECEIVE_ASYNCOUTPUT_
SINGLE_NOWAIT

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

SYNC_RECEIVE_ASYNCOUTPUT_
SINGLE_WAIT

interaction on a shareable persistent socket connection must be in the same application as the original SYNC_SEND or SYNC_SEND_RECEIVE interaction and must use the same shareable persistent connection. This primarily occurs following execution timeout.
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.

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.

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.

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 and 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 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. 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.
Valid values for the reRouteName property:
  • Must be a string of 1 to 8 alphanumeric (A-Z, 0-9) or special (@,#,$) characters.
  • Must not start with the character string, "HWS".
  • Must not be an IMS Connect port number.
  • If lowercase letters are provided, the letters will be changed to uppercase.

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.

syncLevel
This is an input property. syncLevel is the synchronization level of the interaction between IMS Connector for Java and IMS OTMA. Valid synch level values are 0 (NONE) and 1 (CONFIRM). The syncLevel property only applies for values SYNC_SEND_RECEIVE and SYNC_SEND of the interactionVerb property and is used in combination with the commitMode property. It applies to both conversational and non-conversational applications.
Commit Mode 1
Sync Levels 0 and 1 are valid.  0 is the default value. For example, if the interactionVerb property is set to SYNC_SEND_RECEIVE and the commitMode property is set to 1, then it is not necessary to set the syncLevel property. If any other value besides 0 or 1 is passed to the setSyncLevel(int) method, an exception will be thrown.  
Commit Mode 0
Sync Level 1 is the only valid value. It is not necessary to set the Sync Level with this Commit Mode. If any other value besides 1 is passed to the setSyncLevel(int) method, an exception will be thrown.
Programs triggered by a program-to-program switch will always be processed as Commit Mode 0, regardless of the Sync Level of the originating program. For this reason, secondary output from these programs can be put onto the reroute queue or purged according to the setting of the reRoute and purgeNotDeliverable properties in on the original interaction.

Feedback