Format of user portion of IRM for HWSSMPL0, HWSSMPL1, and user-written message exit routines

Following the 4-byte length field and the 28-byte fixed portion of the IMS request message (IRM) header in IMS Connect client input messages, user-written client applications supported by HWSSMPL0, HWSSMPL1, or user-written message exits can include a user-defined section in the IRM.

Messages submitted by the IMS Connect client might or might not include application or IMS data after the IRM depending on the type of message. For example, the following message types, which are specified in the IRM_F4 field, do not contain a data element after the IRM:

ACK (A)
CANCEL TIMER (C)
DEALLOCATE (D)
NAK (N)
RESUME TPIPE (R)

Message types that do contain application data after the IRM include the following types, which are also specified in the IRM_F4 field:

SENDONLY (S)
SENDONLYA (K)
SNDONLYE (J)
Send-receive (X'40')
Synchronous callout response with ACK (L)
Synchronous callout response (M)

The data that follows the user portion of the IRM must be in the format of LLZZDATA, where LL is the total length of message segment (including the LL field), ZZ is binary zeros, and DATA is the IMS transaction code followed by the transaction data.

Restriction: If you are using IMS Connect client applications such as IMS TM Resource Adapter, IMS Enterprise Suite SOAP Gateway, or IBM® Management Console for IMS and Db2 for z/OS®, you cannot include a user-defined portion in the IRM.

The following table shows the format of the user portion of the IRM used by HWSSMPL0, HWSSMPL1, and other user-written user message exits.

This topic contains Product-sensitive Programming Interface information.

Table 1. User portion of IRM for HWSSMPL0, HWSSMPL1, and user-written user message exits
Field	Length	Offsets		Meaning
Field	Length	Dec	Hex	Meaning
llll	4 bytes	0	X'00'	Length of entire message including the IRM, application data, end of message indicator, and this length field
Fixed-format IRM	28 bytes	4	X'04'	The common, fixed portion of the IRM prefix.
IRM_MAP	0 bytes	32	X'20'	Position of the XID map when it is present.
IRM_F1	1 byte	32	X'20'	The purpose of this field differs depending on its value. X'80' - IRM_F1_MFSREQ The user requests that IMS return an MFS MOD name. X'40' - IRM_F1_CIDREQ The user requests that IMS Connect returns the client_id. X'20' - IRM_F1_UC This is a Unicode message. X'10' - IRM_F1_UCTC This is a Unicode transaction code. X'04' - IRM_F1_SOARSP No message text is returned with ACK for send-only with ACK requests X'02' - IRM_F1_NOWAIT This CM0 send-and-receive message uses the NOWAIT option for the expected ACK or NAK response. X'01' - IRM_F1_TRNEXP The user requests that IMS Connect set the expiration time for the input transaction. X'00' The user requests that no MFS MOD name to be returned. If this value is not supplied by the client, the user exit must use a default value. The MFS MOD name flag is returned to IMS Connect from the exit in the EXIT PARMLIST field, EXPREA_UFLAG1. The Unicode encoding schema (UTF8, UCS2, UTF16) is identified in the IRM_ES field of the fixed portion of the IRM.
IRM_F2	1 byte	33	X'21'	Specifies the commit mode. X'40' - commit mode '0' (CM0), also known as commit-then-send X'20' - commit mode '1' (CM1), also known as send-then-commit X'02' - specifies the SENDALTP message level activation for a commit-then-send send-receive transaction. X'01' - specifies to IMS Connect to generate a unique client_ID to prevent a duplicate client_ID error condition. If this value is not supplied from the client, the user exit must use a default value. The commit mode flag is returned to IMS Connect from the exit in the OTMA header field, OMHDRSYN.
IRM_F3	1 byte	34	X'22'	Depending on the value, this field specifies the sync level, the purge or reroute option for CM0 output, or the serial delivery option for send-only input. X'00' - sync level is 'NONE' X'01' - sync level is 'CONFIRM' X'02' - sync level is 'SYNCPT' X'04' - purge undeliverable CM0 output (IRM_F3_PURGE) X'08' - reroute undeliverable CM0 output (IRM_F3_REROUT) X'10' - send-only with serial delivery (IRM_F3_ORDER). IRM_F3_ORDER invokes the serial (ordered) delivery option for a send-only transaction X'20' - for multi-segment CM0 output messages, ignore the DL/I PURG call to the TP PCB (IRM_F3_IPURG) until all segments of the output message have been inserted to the TP PCB. This option is useful only if the IMS application issues a PURG call for each segment of a multi-segment message that it inserts to the TP PCB. X'40' - for OTMA CM0 input messages, regardless of the transaction response mode, to receive a DFS2082 message (IRM_F3_DFS2082) if the IMS application does not reply to the IOPCB or complete a message switch to another transaction. This DFS2082 message for a CM0 input message applies only to the original input transaction and does not support a program-to-program switch. X'80' - cancel duplicate client ID (IRM_F3_CANCID). On the first request of a new session, if an existing session is using the same client ID as the new session, IRM_F3_CANCID terminates the existing session to allow the new session to proceed. For CM0, the sync level must be set to confirm. If the synch level is not supplied from the client, the user exit must use a default value. The sync level flag is returned to IMS Connect from the exit in the OTMA header field, OMHDRSLV. The purge not deliverable flag is returned to IMS Connect from the user message exit in the OTMA header field, OMHDRCFL, with the setting of OMHDRPND X'10'. If the reroute flag is set, the IRM_REROUT_NM field is optional. You cannot specify the purge not deliverable function and the reroute function at the same time. If both functions are specified, the output messages are not purged or rerouted and OTMA issues message DFS2407W.
IRM_F4	1 byte	35	X'23'	The IRM_F4 flag identifies the type of message being sent by the client. Message types are specified by an ASCII or EBCDIC character value. The value is sent to IMS Connect , passed to the user exit, the exit builds the appropriate OTMA structure and returns it to IMS Connect to be forwarded to IMS. The valid values and the message types that they indicate are as follows: A ACK (IRM_F4_ACK) - An ACK response to output received from IMS Connect. ACK is used by a client to indicate the acceptance of either: A synchronous callout request message issued by an IMS application program An output message when the original input message from the client specifies a SYNC level of CONFIRM C Cancel IRM timer (IRM_F4_CANTIMER) - A request to cancel the IRM timer for another connection on which the client, using the same client ID, is waiting for output data. D Deallocate (IRM_F4_DEALLOC) - A request to deallocate the conversation. J Send-only with error (IRM_F4_SNDONLYE) - A send-only error message that returns any IMS Connect error back to the client. Errors that occur in IMS will not be returned to the client. The SNDONLYE interaction must use CM0. K Send only requires ACK (IRM_F4_SNDONLYA) - A send-only transaction message that requires an ACK response from IMS Connect. L Synchronous callout response message requiring ACK (IRM_F4_SYNRESPA) - A synchronous callout response message that uses the send-only protocol and requires an acknowledgement from IMS Connect. M Synchronous callout response message (IRM_F4_SYNRESP) - A synchronous callout response message that uses the send-only protocol. N NAK (IRM_F4_NACK) - A NAK response from the client that indicates the rejection of one of the following types of output from IMS Connect : A synchronous callout request message issued by an IMS application program An output message when the original input message from the client specifies a SYNC level of CONFIRM R RESUME TPIPE (IRM_F4_RESUMET) - A RESUME TPIPE call for asynchronous output data from IMS. A RESUME TPIPE call must execute on a transaction or persistent socket using CM0.
IRM_F4 (cont'd)	1 byte	35	X'23'	S Send only (IRM_F4_SENDONLY) - A send only transaction message that starts a send-only interaction for a non-response mode, non-conversational transaction. If the host application terminates without issuing an ISRT to the IO PCB, no DFS2082 messages are returned to the client. The SENDONLY interaction must use CM0. blank (X'40') A send-receive interaction for a conversational or non-conversational response mode transaction.
IRM_TRNCOD	8 bytes	36	X'24'	Character string. It specifies the IMS transaction code.
IRM_IMSDESTID	8 bytes	44	X'2C'	Character string. It specifies the data store name (IMS destination ID). This field must be specified by the client. The data store name is returned to IMS Connect from the exit in the OTMA header field, OMUSR_DESTID.
IRM_LTERM	8 bytes	52	X'34'	Character string. It specifies the IMS logical terminal (LTERM) override name. This field can be set to a valid name or to blanks. The LTERM override name is returned to IMS Connect from the exit in the OTMA header field, OMHDRLM. For IMS host applications, the value for this field is set by the user message exit, which either moves this value to the OTMA field OMHDRLTM or sets OMHDRLTM with a predetermined value. If you have specified an LTERM override value, OTMA places that value in the IOPCB LTERM field. If you do not specify an LTERM override value, OTMA instead places the IMS Connect-defined tpipe name in the IOPCB LTERM field. The tpipe name is set to the CLIENT ID if the commit mode is zero; it is set to the PORT ID if the commit mode is one. If you use the LTERM value in the IOPCB to make logic decisions, be aware of the naming conventions of the IOPCB LTERM name. If you need to use the LTERM override name for calling IBM Workload Manager for input transactions, you must specify WLMLTRM=YES in the DFSOTMA descriptor.
IRM_RACF_USERID	8 bytes	60	X'3C'	Character string. It specifies the RACF® user ID. The client must provide it if RACF is to be used. The RACF user ID name is returned to IMS Connect from the exit in the OTMA header field, OMSECUID.
IRM_RACF_GRNAME	8 bytes	68	X'44'	Character string. It specifies the RACF group name. The RACF group name is returned to IMS Connect from the exit in the OTMA header field, OMSECGRP. To preserve the expected offset of this field, when you specify IRM_RACF_GRNAME, you must also specify the following fields with valid values or blanks: IRM_RACF_USERID
IRM_RACF_PW	8 bytes	76	X'4C'	Character string. It specifies the RACF PassTicket or password. The client must provide it if RACF is to be used. The PassTicket or password value is returned to IMS Connect from the user message exit, in the OTMA header field, OMUSR_PASSTICK. To preserve the expected offset of this field, when you specify IRM_RACF_PW, you must also specify the following fields with valid values or blanks: IRM_RACF_USERID IRM_RACF_GRNAME The RACF password can contain any of the following special characters. IMS Connect uses EBCDIC page 037 to validate password characters. The symbols shown are for EBCDIC code page 1047 and 037. . (Hex value is 4B) < (Hex value is 4C) + (Hex value is 4E) \| (Hex value is 4F) & (Hex value is 50) ! (Hex value is 5A) * (Hex value is 5C) - (Hex value is 60) % (Hex value is 6C) _ (Hex value is 6D) > (Hex value is 6E) ? (Hex value is 6F) : (Hex value is 7A) = (Hex value is 7E) The RACF password can also contain the following national characters: $ (Hex value is 5B) # (Hex value is 7B) @ (Hex value is 7C)
IRM_APPL_NM	8 bytes	84	X'54'	Character string. It specifies the RACF APPL name, that was defined to RACF on the PTKTDATA definition. If this field is not included or is blank, the RACF APPL name is taken from the APPL parameter of the DATASTORE configuration statement. To preserve the expected offset of this field, when you specify IRM_APPL_NM, you must also specify the following fields with valid values or blanks: IRM_RACF_USERID IRM_RACF_GRNAME IRM_RACF_PW
IRM_REROUT_NM	8 bytes	92	X'5C'	Character string (A through Z, 0 - 9, or special characters, such as @, #, $). The reroute tpipe name of the client reroute request. This field is optional. Recommendation: Use blanks for the default value. When you specify the IRM_REROUT_NM field, you must also specify: IRM_F3_REROUT in the IRM_F3 field in the user portion of the IRM IRM_ARCH1 or IRM_ARCH2 in the IRM_ARCH field in the common fixed portion of the IRM To preserve the expected offset of this field, when you specify IRM_REROUT_NM, you must also specify the following fields with valid values or blanks: IRM_RACF_USERID IRM_RACF_GRNAME IRM_RACF_PW IRM_APPL_NM IRM_REROUT_NM and IRM_RT_ALTCID use the same offset. Both cannot be specified on the same message.
IRM_RT_ALTCID	8 bytes	92	X'5C'	Alternate client ID for a RESUME TPIPE call. This is an optional field. If the alternate client ID is provided, the IRM_ARCH field must be set to IRM_ARCH1. To preserve the expected offset of this field, when you specify IRM_RT_ALTCID, you must also specify the following fields with valid values or blanks: IRM_RACF_USERID IRM_RACF_GRNAME IRM_RACF_PW IRM_APPL_NM
IRM_TAG_ADAPT	8 bytes	100	X'64'	Name of the adapter that IMS Connect calls to convert XML messages to and from select programming languages. To preserve the expected offset of this field, when you include the IRM_TAG_ADAPT field, you must also specify the following fields with valid values or blanks: IRM_RACF_USERID IRM_RACF_GRNAME IRM_RACF_PW IRM_APPL_NM IRM_REROUT_NM or IRM_RT_ALTCID
IRM_TAG_MAP	8 bytes	108	X'6C'	Name of the converter the XML adapter calls to perform that actual conversion of XML messages to and from select programming languages. To preserve the expected offset of this field, when you include the IRM_TAG_MAP field, you must also specify the following fields with valid values or blanks: IRM_RACF_USERID IRM_RACF_GRNAME IRM_RACF_PW IRM_APPL_NM IRM_REROUT_NM or IRM_RT_ALTCID IRM_TAG_ADAPT
IRM_MODNAME	8	116	74	The MFS MOD name for input messages.
IRM_CORTKN	0XL40			The correlation token for a synchronous callout message. The correlation token includes information that correlates a reply to a synchronous callout request with the IMS system and IMS application program that issued the request.
IRM_CT_LEN	2	124	7C	The length of the correlation token.
IRM_CT_RESV1	2	126	7E	Reserved.
IRM_CT_IMSID	4	128	80	The IMSID of the IMS system that scheduled the IMS application that issued the synchronous callout request.
IRM_CT_MEMTK	8	132	84	The OTMA TMEMBER token.
IRM_CT_AWETK	8	140	8C	OTMA message token.
IRM_CT_TPIPE	8	148	94	OTMA TPIPE name.
IRM_CT_USERID	8	156	9C	The user ID specified in the ICAL call.
IRM_SESTKN	8	164	A4	Session token value used for IMS Connect-to-IMS Connect connections.
IRM_EXTN_OFF	2	172	AC	Offset value from the start of the IRM to the first IRM extension.
IRM_F6	1	174	AE	The purpose of this flag depends on its value. X'80' - IRM_F6_NWSE Valid for RESUME TPIPE requests. The user-written client application supports output messages from IMS that include network security segments containing distributed network security credentials. Network security segments include the NETSID segment, which contains a network session ID, and the NETUID segment, which contains a network user ID.
IRM_RESERVED1	1	175	AF	Reserved.
		ORG IRM_MAP
IRM_XID	XL140	32	20	The IRM_XID field is used for two-phase commit protocol messages. The IRM_XID field is only valid for IMS TMRA messages with IRM_ARCH less than 5. For IRM_ARCH = 5 and greater, you must use the value in the IRM_LEN field to determine the location of the XID in the input buffer. This must be done because the IRMMASK has been extended to support variable length IRM extensions. The IRM extensions are included as part of the IRMMASK and they contribute to the total length specified in IRM_LEN. Thus, the XID will start at the byte following the end of the now larger IRMMASK, which might also contain IRM extensions. For IRM_ARCH = 5 and greater, the message might look as follows: `LLLL \| IRM + IRM EXTENSION(S)\| XID \| OTMA HEADERS...`
		ORG IRM_MAP: Remapping of offsets 32-35.
IRM_TMRA_EXTN_OFF	2	32	20	Offset value from the start of the IRM to the first IRM extension in IMS TMRA messages with IRM architecture level, IRM_ARCH, equal to or greater than 5.
IRM_TMRA_SRVD1	2	34	22	Reserved for IMS Connect.
IRM_TMRA_EXTN_START	X	36	24	Denotes the start of the first IRM extension for IMS TMRA messages.
*IRM_XID_ARCH5	XL140	X	X	This field represents the size of the XID for IMS TMRA messages that use IRM_ARCH equal to or greater than 5. The location of this field in memory varies depending on the number of IRM extensions and their sizes. Therefore, the value in IRM_LEN must be used to determine the actual location of the XID. For more information, see the Meaning column for IRM_XID.