OTMA destination descriptor syntax and parameters

If the SENDALTP function is activated, and the message switches destination from the ALT IOPCB is the IMS Connect client that initiates a commit-then-send send-receive call, the ALT IOPCB output message will be delivered back to the IMS Connect client through the incoming TPIPE. The output message will not be queued to a TPIPE hold queue. This behavior applies to IMS Connect clients that use super member.

Subsections:

• Creating and modifying destination descriptors
• Destination descriptor format
• Common parameters
• IMS Connect parameters
• IMS synchronous program switch parameters
• IBM MQ parameters
• Example
• IBM MQ example

Creating and modifying destination descriptors

The OTMA destination descriptors are specified in the OTMA DFSYDTx member of the IMS.PROCLIB data set. You can use them to externalize message switch definitions that would otherwise be coded in the OTMA routing exit routines OTMAYPRX and DFSYDRU0. The OTMA destination descriptors can be used instead of the OTMAYPRX and DFSYDRU0 exit routines or in addition to them.

Destination descriptors are loaded from the DFSYDTx member of the IMS.PROCLIB data set during IMS cold start or /ERESTART COLDCOMM processing, or from the X'4035' checkpoint log records during IMS restart by the /NRESTART or /ERESTART command.

Alternatively, you can dynamically add, update, or delete OTMA destination descriptors with the following type-2 commands:

• CREATE OTMADESC
• UPDATE OTMADESC
• DELETE OTMADESC

A restart of IMS is not required; in addition, any changes that you make with these type-2 commands persist across warm and emergency restarts, when the changes are read from the IMS logs.

Use the QUERY OTMADESC command to display the characteristics of a specific destination routing descriptor.

For callout requests to IMS Connect clients, you can use the OTMA destination descriptors to specify adapter and converter names for XML message conversion.

For IMS-to-IMS TCP/IP communications, you can use the OTMA destination descriptor to route ALTPCB output to a remote IMS system over a TCP/IP connection that is managed by IMS Connect. You can optionally specify the transaction to run on the remote IMS system.

A descriptor that matches the destination sets the default routing as either IMS Connect, IBM MQ, or non-OTMA, as coded on the descriptor. OTMA routing exits are not called if they exist. The OTMA routing descriptors override the exits unless EXIT=Y is specified for the descriptor.

Unless you change the limit, you can specify a maximum of 510 OTMA destination descriptors in the DFSYDTx member of the IMS PROCLIB data set. You can increase the maximum number up to 4095 by creating a DFSOTMA descriptor and specifying a new maximum on the DDESCMAX parameter. Increasing the number of OTMA destination descriptors increases the amount of ECSA storage that is used.

Destination descriptor format

Up to 50 lines can be used in the specification of a descriptor. Columns 1 - 10 must be the same for each line.

Common parameters

You can specify the following parameters on the OTMA destination descriptor:

EXIT=NO | YES

For descriptors with a TYPE= value other than IMSTRAN, this optional parameter specifies whether the OTMA routing exits (OTMAYPRX and DFSYDRU0) can override the descriptor routing information of the message switch destination from the ALT IOPCB. The valid values are YES and NO. The default is NO.

For TYPE=IMSTRAN descriptors, this parameter specifies whether the IMS user exit (DFSCMUX0) can override the descriptor routing information for late or redundant response messages.

If you specify EXIT=YES when TYPE=IMSCON is specified and the return code of the DRU exit is set to 0, the SENDALTP flag in the output parameter list of the DRU exit, if set, can be used to override the SENDALTP parameter of the destination descriptor.

SMEM=NO | YES

Specifies whether this destination is a super member. This parameter is optional and the default is SMEM=NO. When SMEM=YES, TMEMBER is the 1- to 4-character super member name.

If you specify this parameter when TYPE=NONOTMA or TYPE=MQSERIES, it is ignored.

Because the SENDALTP function applies to IMS Connect clients that use super members, if you enable this parameter when TYPE=IMSCON and the SENDALTP function is activated, the ALTPCB output message that is triggered by an IMS Connect commit-then-send Send-Receive call is sent back to the input client TMEMBER.

SYNTIMER=value

An optional parameter that specifies the timeout value for a synchronous callout process. When the timeout value is reached, the IMS application that issues the synchronous callout request receives a X'100' return code and a X'104' reason code. The message is discarded.

If TYPE=NONOTMA or TYPE=MQSERIES is specified in the OTMA destination descriptor, or when the descriptor is used to route a non-synchronous callout message, this parameter is ignored. If TYPE=IMSTRAN is specified, this parameter is the timeout value for synchronous program switch ICAL calls.

The value of this parameter should be expressed in 100th of the timeout value in seconds. The valid range is 0–999999. The system default is 10 seconds. If you specify a value that is not within the valid range:

• If SYNTIMER=0, the system default is used.
• If the SYNTIMER value is larger than 999999, you’ll receive error message DFS2385E. No default value is set.

The AIBRSFLD parameter in the DL/I ICAL SENDRECV call can override the SYNTIMER value when specified. Depending on the specification of the two parameters, the timeout value might vary:

• When the AIBRSFLD parameter is set:
  • If the SYNTIMER parameter is set, the smaller value is used.
  • If the SYNTIMER parameter is not set or is invalid, the AIBRSFLD value is used.
• When the AIBRSFLD parameter is not set or is invalid:
  • If the SYNTIMER parameter is set, the value of this parameter is used.
  • If the SYNTIMER parameter is not set or is invalid, the system default 10 seconds is used.

For more information about the usage of the AIBRSFLD parameter, see ICAL call.

TMEMBER=name

A 1- to 16-character OTMA TMEMBER name. When SMEM=YES, TMEMBER is the 1- to 4-character super member name.

• For TYPE=IMSCON and TYPE=MQSERIES, this parameter is required.
• For TYPE=IMSTRAN, this parameter is optional. It can be used with the TPIPE parameter to queue a late response from a synchronous program switch to the specified OTMA TMEMBER.
• For TYPE=NONOTMA, this parameter is ignored.

TPIPE=name

A 1- to 8-character TPIPE name. The default is the destination name.

• For TYPE=MQSERIES, the destination is used for the TPIPE if this parameter is omitted.
• For TYPE=IMSCON, this parameter is omitted if the SENDALTP function is activated for an ALTPCB output message that is triggered by an IMS Connect commit-then-send send-receive call. When the SENDALTP function is activated, the ALTPCB output message is sent back to the input client TPIPE of the originated commit-then-send send-receive call.
• For TYPE=IMSTRAN, this parameter is optional. It can be used with the TMEMBER parameter to queue a late response from a synchronous program switch to the specified OTMA TMEMBER.
• For TYPE=NONOTMA, this parameter is ignored.

TYPE=type

Specifies what type of destination the descriptor is for. This parameter is required. The valid values are:

IMSTRAN

IMS transaction for synchronous program switch

IMSCON

IMS Connect client

NONOTMA

Non-OTMA destination

MQSERIES

IBM MQ

USERID=user_ID

A 1- to 8-character user ID used for security checking by the remote IMS system that is specified in the RMTIMS parameter. If not specified, the user ID from the IMS application that issued the ISRT call is used.

This is an optional parameter for TYPE=IMSCON and TYPE=MQSERIES descriptors. It is ignored for other descriptor types.

When TYPE=MQSERIES is set for the descriptor, this parameter specifies the MQMD_USERIDENTIFIER value. This field allows the descriptor to override the default user ID in the MQ message descriptor structure. You can specify the value *USERID* to use the IMS user ID from the program specification table (PST).

IMS Connect parameters

The TMEMBER, TPIPE,SMEM, SYNTIMER, EXIT, and USERID parameters are valid for IMS Connect descriptors (TYPE=IMSCON), as well as the following additional parameters:

ADAPTER=

A 1- to 8-character name of the adapter that identifies the IMS Connect adapter to be used on these messages. For example, you can specify an adapter for XML transformation. This parameter is optional. If you specify this parameter, CONVRTR= is also required.

CONVRTR=

A 1- to 8-character name of the converter to be used by the adapter specified on ADAPTER=. This parameter is required when TYPE=IMSCON if the ADAPTER parameter is specified.

RMTIMS=

A 1- to 8-character name of the remote IMS system to which messages routed to this descriptor are sent. This value is the same value specified on the ID parameter of a DATASTORE statement in the HWSCFGxx member of the IMS PROCLIB data set of a remote IMS Connect instance. If specified, the RMTIMSCON parameter must also be specified.

RMTIMSCON=

A 1- to 8-character name of a connection to a remote IMS Connect instance. This value must match the value specified on the ID parameter of an RMTIMSCON statement in the HWSCFGxx member of the IMS PROCLIB data set of a local IMS Connect instance. If specified, the RMTIMS parameter must also be specified.

RMTSEC=F | C | N

An optional parameter that sets the security flag in an OTMA ALTPCB output message that is sent to a remote IMS system through IMS-to-IMS TCP/IP communications. The remote IMS system uses this security flag setting in the output message only if the input message does not have a security flag and the remote IMS OTMA security is set to PROFILE. The default is RMTSEC(F).

F

OTMA RACF® security is set to FULL.

C

OTMA RACF security is set to CHECK.

N

OTMA RACF security is set to NONE.

RMTTRAN=

A 1- to 8-character name of the transaction to use at the remote IMS. This is an optional parameter. If not specified, the transaction in the start of the message is used.

When the RMTTRAN is specified, OTMA passes the transaction code to IMS Connect. IMS Connect inserts the transaction code into the message immediately before the application data. Any transaction code that is specified by the sending application program is retained by OTMA in the application data section of the message.

For example, if the message received from the application program is LLZZMSGDATA, OTMA inserts 8 bytes between LLZZ and MSGDATA to hold the transaction code specified on the RMTTRAN parameter, so that the message sent by OTMA to the remote IMS system is LLZZTRANCODEMSGDATA.

If a transaction code is specified by both the OTMA destination descriptor and the sending application program, both transaction codes must be accounted for at the receiving IMS system.

SENDALTP=NO | YES

Specifies whether or not an ALTPCB output that is triggered by an IMS Connect commit-then-send send-receive call needs to be sent back to the originated IMS Connect client.

When SENDALTP=YES is specified, the ALTPCB output is delivered back to the client that initiates the call. When SENDALTP=NO is specified, the ALTPCB output for IMS Connect is kept in a TPIPE hold queue so that a Resume TPIPE request can retrieve it later.

If the SENDALTP function is activated at the member or datastore level, when IMS processes an ALTPCB output with SENDALTP=NO specified in the destination descriptor, the message level setting through OTMA destination descriptor overrides the member or datastore level setting. The ALTPCB output is saved in a TPIPE hold queue.

This parameter is optional and has no default value. Note that this parameter is ignored for non-IMS Connect clients.

IMS synchronous program switch parameters

The TMEMBER, TPIPE, SMEM, SYNTIMER, and EXIT parameters are valid for IMS synchronous program switch descriptors (TYPE=IMSTRAN). The following additional parameters are available for descriptors with TYPE=IMSTRAN:

LTERMOVR

Specifies a logical terminal name used to override the name specified in the I/O PCB of the IMS application program. This parameter is optional.

IMS attempts to get a logical terminal name for the target transaction from the following locations in the following order:

1. From the AIB.
2. From the OTMA destination descriptor.
3. If an LTERM name is not specified in the descriptor or in the AIB, the IMS application terminal symbolic (PSTSYMBO) is used as the default value.

REPLYCHK=YES | NO

Specifies whether the IMS detects when the target IMS application replies to the I/O PCB. When REPLYCHK=YES is specified and the target application does not reply to the I/O PCB (or issue an ICAL request for synchronous program switch to a third application), IMS gives the return code X'0100' with reason code X'0110' and extended reason code X'0061' instead of a timeout to the ICAL call. This parameter is optional and the default is YES.

Also, if there are multiple responses to the ICAL (redundant messages), the response that is sent as a CM1 message is returned to the application that issued the ICAL call. Other responses that use CM0 are dequeued or rerouted to the late message tpipe.

When REPLYCHK=NO is specified, no check is done to see if the target application replies to the I/O PCB or if it issues a synchronous program switch to another transaction. If there are multiple response messages, the first response (CM1 or CM0) is returned to the application that issued the ICAL call. All other responses are dequeued or rerouted.

SYNCTP=NO | YES

Specifies whether the destination TPIPE for the late messages needs to be created as a synchronized TPIPE. This parameter is optional and the default is NO.

IBM MQ parameters

The TMEMBER, TPIPE, USERID, and EXIT parameters are valid for IBM MQ descriptors, as well as the following additional parameters. The MQRTQ= parameter is required for TYPE=MQSERIES descriptors.

SYNCTP=NO | YES

Specifies whether a SYNC TPIPE must be created for this message. This parameter is optional and the default is NO.

MQPERST=NO | YES

Specifies whether this message is persistent on a SYNC TPIPE. This parameter is optional and the default is NO.

MQCOPYMD=YES | NO

Specifies whether the original input MQMD structure values from the MQ IMS bridge must be copied to this output message. This parameter is optional and the default is YES.

MQREPORT=COPYMTOC | NEWMSGID | PASSCORR | PASSMSGI | NONE

Specifies the MQMD_REPORT value:

COPYMTOC

MQ report option: MQRO_COPY_MSG_ID_TO_CORREL_ID

NEWMSGID

MQ report option: MQRO_NEW_MSG_ID

PASSCORR

MQ report option: MQRO_PASS_CORREL_ID

PASSMSGI

MQ report option: MQRO_PASS_MSG_ID

NONE

MQ report option: MQRO_NONE

This parameter is optional and the default is COPYMTOC.

MQFORMAT=MQIMSVS | MQIMS | MQSTR | NONE

Specifies the MQMD_FORMAT value:

MQIMS

MQ format option: MQFMT_IMS

MQIMSVS

MQ format option: MQFMT_IMS_VAR_STRING

NONE

MQ format option: MQFMT_NONE

MQSTR

MQ format option: MQFMT_STRING

This parameter is optional and the default is MQIMSVS.

MQMSGID=0 | mqmd_mqmsgid

Specifies the MQMD_MSGID name. This is a 1- to 24-character value that is passed to the receiving MQ application based on the value of the MQMD_REPORT field. This parameter is optional and the default is 0.

MQCORREL=0 | mqmd_mqcorrelid

Specifies the MQMD_CORRELID name. This is a 1- to 24-character value that is passed to the receiving MQ application based on the value of the MQMD_REPORT field. This parameter is optional and the default is 0.

MQRTQ=mqmd_mqrtq

Specifies the 1- to 48-character MQMD_REPLYTOQ value. This parameter is required when TYPE=MQSERIES is specified for the descriptor.

MQRTQMGR=mqmd_replytoqmgr

Specifies the 1- to 48-character MQMD_REPLYTOQMGR value. This value is the queue manager name. This parameter is optional and if not specified then MQSeries® will use the local QManager.

MQAPPLID=mqmd_applidentitydata

Specifies the 1- to 32-character MQMD_APPLIDENTITYDATA value. You can use this value to pass data to the receiving MQ application. This parameter is optional and the default is blanks.

MQRTF=mq_replytoformat

Specifies the 1- to 8-character RepyToFormat value. This value is not part of the MQMD data structure, but it is submitted to MQ by OTMA at the same time. IBM MQ uses the value of this parameter for the MQIIH_ReplyToFormat field when the value of MQMD_FORMAT is MQIMS. This parameter is optional and the default is binary zeroes.