OTMA destination descriptor syntax and parameters

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.

SMEM=NO | YES

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

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

SYNTIMER=value

An optional parameter to specify the time to wait in 100th of a second for the synchronous callout process to finish.

This parameter is ignored when TYPE=NONOTMA or TYPE=MQSERIES, or when the descriptor is used to route a non-synchronous callout message.

The valid range is 0 - 999999. If SYNTIMER is set to 0, a system default of 10 seconds is used instead. If a value larger than 999999 (more than 6 characters) is specified, a DFS2385E error message is generated and no default value is set.

The AIBRSFLD parameter in the DL/I ICAL SENDRECV call that is used to issue a synchronous callout request can override this value. If the AIBRSFLD parameter is not set or set to 0, the timeout value that is specified in the OTMA destination descriptor is used. If no timer is specified in either the AIBRSFLD parameter of the ICAL SENDRECV call or the OTMA destination descriptor, the system default is 10 seconds. If the timeout value is specified both on the OTMA destination descriptor and on the ICAL call, OTMA uses the smaller value of the two.

• If AIBRSFLD is set to 0, the SYNTIMER timeout value from the OTMA destination descriptor is used.
• If values are specified for both AIBRSFLD and SYNTIMER, the smaller value is used.
• If AIBRSFLD is blank and the OTMA destination descriptor does not have a value for SYNTIMER, the timeout value is set to 10 seconds.

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

TMEMBER=name

A 1- to 16-character OTMA TMEMBER name. When SMEM=YES, TMEMBER is the 1- to 4-character supermember 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=IMSCON and TYPE=MQSERIES, the destination is used for the TPIPE if this parameter is omitted.
• 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.

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= and MQRTQMGR= parameters are 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.