OTMA User Data Formatting exit routine (DFSYDRU0)
The OTMA User Data Formatting exit routine can determine and change the final destination of OTMA messages. The DFSYDRU0 exit routine can also format the User Prefix section of an OTMA asynchronous output message.
The DFSYDRU0 exit routine can change the final destination of OTMA messages by specifying OTMA member names, transaction pipe (Tpipe) names, or names of remote IMS™ systems.
You can specify OTMA C/I to use the
HOLDQ when asynchronous output is created before the OTMA C/I client
has established via client-bid. This is optional, as any queued output
is moved by OTMA to the HOLDQ once the OTMA C/I client has connected
and specified it is HOLDQ capable.
You can use the OTMA destination descriptor to avoid coding this user exit. See DFSYDTx in IMS Version 13 System Definition for full details on specifying OTMA descriptors.
Subsections:
About this routine
The following rules apply for this exit routine:
- This routine is optional.
- This routine is not called if the destination is an IMS scheduler message block (SMB) name.
- This routine cannot override the originating LTERM name.
- This routine can only set the final destination once.
If output is routed from one OTMA client to another, that client cannot use its own Destination Resolution exit routine to set a different final destination.
An OTMA client should not use a transaction name as a transaction pipe name (or routing key) because of potential conflict with the SMB name.
In a single IMS, multiple OTMA Destination Resolution exit routines are allowed. To display the DFSYDRU0 exit routine associated with an OTMA client, issue the /DISPLAY TMEMBER command.
IMS identifies the OTMA User Data Formatting exit routine for an OTMA client by searching, in the order listed, the following:
- The exit routine specified on the client-bid call
- The OTMA client descriptor
- The default exit routine name, DFSYDRU0, if it exists
The exit routine specified on the client-bid call overrides the OTMA descriptor. The OTMA descriptor overrides the default exit routine name. If the default exit routine name does not exist, the OTMA User Data Formatting exit routine is not used.
The following table shows the attributes of the OTMA User Data Formatting exit routine.
Attribute | Description |
---|---|
IMS environments | DB/DC, DCCTL. |
Naming convention | Different clients can have different exit routine names, or the clients can all use the default exit routine name of DFSYDRU0. |
Binding | The OTMA User Data Formatting exit routine must be reentrant. The OTMA User Data Formatting exit routine must be included in an authorized library in the JOBLIB, STEPLIB, or LINKLIST library concatenated in front of the IMS.SDFSRESL. This exit routine is optional. |
Including the routine | No special steps are required to include this routine. |
IMS callable services | This exit routine is eligible to use IMS callable services. |
Sample routine location | IMS.ADFSSMPL (member name DFSYDRU0). |
Communicating with IMS
IMS uses the entry and exit registers, as well as parameter lists, to communicate with the exit routine.
Contents of registers at entry
Register | Contents |
---|---|
R1 | Address of the IMS standard user exit parameter list |
R13 | Save area address (points to a single SAVEAREA, not a SAVEAREA chain) |
R14 | Return address |
R15 | Entry point address |
This exit routine uses the Version 6 standard exit parameter list. The address of the work area that is passed to this exit routine in SXPLAWRK can be different each time that this exit routine is called.
The following table describes the contents of the OTMA User Data Formatting exit routine parameter list. The address of this parameter list is in the standard exit parameter list field SXPLFSPL.
Offset (decimal) | Contents | |
---|---|---|
+0 | Name of the originating LTERM or OTMA transaction pipe. | |
+8 | Destination
name. If the destination is for OTMA and no Tpipe name is specified
in the output area, this field is used as the name of the Tpipe to
queue and deliver the output message.
|
|
+16 | Transaction name or program name. | |
+24 | Flag byte:
|
|
+25 | Synchronization level. | |
+26 | Destination
type flag:
|
|
+27 | A 1-byte field
that indicates the version of the exit routine parameter list:
|
|
+28 | User ID. | |
+36 | Group name. | |
+44 | The 16-byte
name of the destination OTMA client.
|
|
+60 | Address of the PST block. | |
+64 | Name of the originating OTMA client, if the message originated from an OTMA client; otherwise zeros. | |
+80 | Address of
the input Message Control Information prefix section of the OTMA message.
|
|
+84 | Address of
the input State Data prefix section of the OTMA message. Check the prefix flag in the Message Control Information section to determine the specific type of State Data section specified.
|
|
+88 | Address of
the input User Data prefix section of the OTMA message. The area is also used to return new or modified user data, up to a maximum of 1024 bytes. |
|
+92 | Address of the SCD block. | |
+96 | Address of the output parameter list. This parameter list is used to return information to IMS. The contents of the output parameter list are shown in the following table. | |
![]() ![]() |
![]() See the TMAMICON_DESCRIPTOR DSECT mapping for the layout of the routing information for an IMS Connect destination. See the TMAMMQS_DESCRIPTOR DSECT mapping for the layout of the routing information for an IBM MQ destination. ![]() |
|
![]() ![]() |
![]() ![]() |
Contents of the output parameter list
The following table shows the contents of the output parameters list.
Offset (decimal) | Contents |
---|---|
+0 | The 16-byte client override name, if any. This field is used when the destination is a different OTMA client. A return code of 8 must also be set. |
+16 | Output flag.
|
+17 | Reserved (3 bytes). |
+20 | The 8-byte Tpipe name, if any. This field specifies the name of the Tpipe that is used for queuing and transmitting the output message. If it contains all blanks, the destination name is used for the Tpipe name. (This field is valid only when the return code is 0.) |
+28 | The 4-byte super member name. This field specifies the name of the super member and is used only in the following scenario: In the shared queues back-end IMS, the first call to DRU exit is to process a message from a non-OTMA client instead of an OTMA hold queue capable client. And, the output is destined to a hold queue capable client which supports super member. This field is valid only when the return code of DRU exit is set to 0 and the output flag byte is set to X'20'. |
Contents of registers at exit
Before returning to IMS, the exit routine must restore all registers, except register 15, which must contain one of the following return codes:
Return code | Meaning |
---|---|
X'00' | Destination is the OTMA TPIPE.
|
X'04' | Destination is a non-OTMA LTERM. |
X'08' | Destination is a different OTMA client (need to
specify). The new client DRU0 exit will be invoked. Note:
![]() ![]() |
X'0C' | Destination is invalid. AL status on CHNG call. Can also be used to indicate any error in module processing. |
![]() ![]() |
![]() ![]() |
![]() ![]() |
![]() ![]() |
![]() ![]() |
![]() ![]() |
Any other return code causes IMS to generate a DFS2370I message.
Error conditions
An A1 status code will be returned to the application program when the following errors occur:
- Incorrect 16-byte OTMA client override name is specified. The client name cannot contain all blanks or zeroes. If the client name is shorter than 16 bytes, it must be padded with blanks.
- The length of modified OTMA user data is over 1K.
- Incorrect return code is specified for the exit.