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.

Start of change 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. End of change

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
Communicating with IMS
Error conditions

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.

Recommendation: Within a shared-queues group, ensure that the DFSYDRU0 exit routine is the same for both front-end and back-end IMS systems. If these exit routines differ on one or more back-end IMS systems, asynchronous output might be sent to different destinations, depending on which back-end IMS system processed the input.

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.

Table 1. OTMA User Data Formatting exit routine attributes
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

At entry, the exit routine must save all registers using the provided save area. The registers contain the following information:

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.

Table 2. Contents of the OTMA User Data Formatting exit routine parameter list
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. When a matching destination descriptor with EXIT=YES is found and the DFSYPRX0 exit routine either sets RC=100 or does not exist, this field contains the TPIPE name that is specified in the destination descriptor.
+16	Transaction name or program name.
+24	Flag byte: X'80' An OTMA prefix exists. X'40' The exit routine can override the client name. X'20' OTMA message submitted by OTMA client with super member support. The OTMA state data pointed to by the input parameter list has the 1-4 bytes super member name at offset x'E' from the beginning of the state data. X'10' The exit routine is called to process a late response to a synchronous program switch request. If the X'80' flag is also set, the LTERM or TPIPE name and input client member name in the parameter list are propagated from the original OTMA transaction that initiated the ICAL call. X'08' The destination name matches an entry in the OTMA destination descriptor for IMS Connect. X'04' The destination name matches an entry in the OTMA destination descriptor for IBM® MQ. X'02' The destination name matches an entry in the OTMA destination descriptor for a non-OTMA destination.
+25	Synchronization level.
+26	Destination type flag: X'80' Transaction pipe exists for the client. X'40' LTERM exists in IMS (non-maintenenced versions). X'20' LU 6.2 descriptor exists. X'10' ETO is available. X'08' Client is active. X'04' Tpipe trace is active.
+27	A 1-byte field that indicates the version of the exit routine parameter list: X'80' If set, indicates that at offset +100, the parameter list includes the address of the information from the OTMA destination descriptor for IBM MQ or IMS Connect. X'40' If set, indicates that at offset +104, the parameter list includes the original CHNG call value.
+28	User ID.
+36	Group name.
+44	The 16-byte name of the destination OTMA client. When a matching descriptor with EXIT=YES is found and the DFSYPRX0 exit routine either sets RC=100 or does not exist, this field contains the tmember name that is specified in the destination descriptor.
+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. If the exit is called to process a synchronous program switch response and the original transaction is from OTMA, this message control information is generated by IMS. The original message prefix from the OTMA client is not propagated to the exit routine. However, the LTERM or TPIPE name and the input client member name in this parameter list are from the original 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. If the OTMA super member feature is used, the super member name is located at offset +14 from the beginning of the state data. See the TMAMSPNM field of the DFSYMSG macro. If the exit is called to process a synchronous program switch response and the original transaction is from OTMA, this state data information is generated by IMS. The state data prefix from the OTMA client is not propagated to the exit routine. However, the correlator field (TMAMHCOR), the LTERM or TPIPE name, and the input client member name in this parameter list are from the original OTMA message.
+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.
+100	Address of the routing information defined in the OTMA destination descriptor for IBM MQ and IMS Connect. If the destination name matches a non-OTMA destination descriptor, or the name does not match any entry in the OTMA destination descriptor, this field contains 0. 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.
+104	The 8-byte destination name from the original CHNG call. If the name is less than 8-bytes, it is left-justified and padded with blanks. This is an entry parameter only.

Contents of the output parameter list

The following table shows the contents of the output parameters list.

Table 3. Contents of the output parameter 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. X'80' If this flag is set, a synchronized transaction pipe must be created. However, if the OTMASP initialization parameter is set to Y in the DFSPBxxx PROCLIB member, the synchronized transaction pipe is always created. This flag can be set only if the return code is 0. X'40' If this flag is set, the message is persistent and a recoverable sequence number must be set. This flag is valid only if a synchronized transaction pipe is specified. X'20' If this flag is set, this ALT_PCB output is for an OTMA hold queue capable client, such as IMS Connect. This is an optional flag that 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. If this flag is set, OTMA ensures that the output is always saved in a hold queue. However, without this flag set in this scenario, the output is stored in the regular tpipe queue instead of in the hold queue. X'10' If set, indicates that this ALT-PCB output message is to be sent to a remote IMS system for processing by way of an IMS Connect to IMS Connect TCP/IP connection. You must build a user data prefix that includes at least the names of both the destination remote IMS system and the remote IMS Connect that supports the remote IMS system.
+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. When the destination client name is from a matching destination descriptor with EXIT=YES, the descriptor defines the default destination for output message. However, if any value in the output parameter list is set, the user exit then determines the output destination instead of the descriptor.
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: The OTMA Destination Resolution user exit (OTMAYPRX) can make all routing decisions by setting OTMAMD=Y in the DFSPBXXX PROCLIB member.
X'0C'	Destination is invalid. AL status on CHNG call. Can also be used to indicate any error in module processing.
X'64'	Use the routing information from the destination descriptor without modification.
X'100'	The matching OTMA destination descriptor determines both the destination and the user data prefix in the output message. This return code is accepted when EXIT=YES is specified in the matching OTMA destination descriptor.
X'101'	The matching OTMA destination descriptor determines the destination only. The DFSYDRU0 exit routine determines the user data prefix in the output message. Any value in the output parameter list are ignored.

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.