Format of fixed portion of IRM in messages sent to IMS Connect

The IMS request message (IRM) header contains a 28-byte fixed-format section that is common to all messages from all IMS Connect client applications that communicate with IMS TM.

The following table shows the fixed format preceding the input message sent to IMS Connect from clients. It includes the message field, the field length, and a brief explanation of the message.

The llll field tells IMS Connect how long the message is, and the IRM provides additional information, such as the specific user exit to which the data is to be passed.

Table 1. Fixed portion of IRM prefix
Field Length Offsets Meaning
Dec Hex
llll 4 bytes 0 0 Length of the total message read as a binary number.

The total message length includes the length of the llll field (four bytes), the IRM (variable length, depending on your requirements), the length of the message, and the end of message indicator X'00040000' (four bytes).

The minimum length for all messages is X'58'. For IMS TM Resource Adapter, the maximum length is X'00989680' (10,000,000 bytes). For user-written client applications, the maximum length is X'7FFFFFFF'.
The following fields are for the 28 (decimal) byte IRM prefix.
IRM_LEN 2 bytes 4 4 Length of the IRM structure. The minimum size of the IRM for user written exits is X'24' or binary '00100100'. HWSSMPL0 has a minimum IRM length of X'50' or binary '01010000'.
IRM_ARCH 1 byte 6 6 Specifies the architectural level of the IRM prefix in messages received by IMS Connect from the client.
  • X'00' Specifies IRM_ARCH0, the base architectural structure of the user portion of the IRM prefix.
  • X'01' Specifies IRM_ARCH1, the architectural structure of the user portion of the IRM prefix that includes space for:
    • The IRM_REROUT_NM field
    • The IRM_RT_ALTCID field
  • X'02' Specifies IRM_ARCH2, the architectural structure of the user portion of the IRM prefix that includes space for:
    • The IRM_REROUT_NM field
    • The IRM_RT_ALTCID field
    • The IRM_TAG_ADAPT field
    • The IRM_TAG_MAP field
  • X'03' Specifies IRM_ARCH3, the architectural structure of the user portion of the IRM prefix that includes space for all of the fields included in IRM_ARCH2 and the following additional fields:
    • The synchronous callout correlation token fields
    • The IRM_MODNAME field for MFS MOD names
  • X'04' Specifies IRM_ARCH4, the architectural structure of the user portion of the IRM prefix that includes space for all of the fields included in IRM_ARCH3 and the field IRM_SESTKN for session tokens for IMS-to-IMS connections.
  • X'05' Specifies IRM_ARCH5, the architectural structure of the user portion of the IRM prefix that includes space for all of the fields included in IRM_ARCH4 and the following additional fields:
    • The IRM_EXTN_OFF field
    • A 2-byte reserved field
IRM_F0 1 byte 7 7
  • X'80' Specifies IRM_F0_SYNONLY: This is a resume tpipe call that retrieves only synchronous callout messages from IMS application programs running in IMS dependent regions.
  • X'40' Specifies IRM_F0_SYNASYN: This is a resume tpipe call that retrieves both synchronous callout messages from IMS application programs and asynchronous messages.
  • X'20' Specifies IRM_F0_SYNCNAK: This is a NAK message from the IMS Connect client that directs OTMA to keep the message that triggered the NAK on the tpipe queue.
  • X'10' Specifies IRM_F0_NAKRSN: This is a NAK message that includes a reason code for the NAK response.
  • X'04' Specifies IRM_F0_EXTENS, which indicates that the message contains one or more IRM Extensions.
  • X'01' Specifies IRM_F0_XMLTD, which indicates a request from an IMS Enterprise Suite SOAP Gateway client to convert an XML tagged message that contains both a transaction code and data into the format expected by the IMS application program.
  • X'02' Specifies IRM_F0_XML_D, which indicates a request from an SOAP Gateway client to convert an XML tagged message that contains data only into the format expected by the IMS application program.
IRM_ID 8 bytes 8 8 Character string. Specifies the identifier of the user exit that is to be driven after the complete message has been received. Additionally, IMS Connect reads this field to determine whether the incoming message is in ASCII or EBCDIC.
The IMS Connect-supplied user message exits reserve and use these IDs:
  • *HWSCSL*-- for HWSCSLO0
  • *HWSJAV*-- for HWSJAVA0
  • *HWSOA1*-- for HWSSOAP1
  • *SAMPL1*-- for HWSSMPL1
  • *SAMPLE*-- for HWSSMPL0
IRM_NAK_RSNCDE 2 bytes 16 10 Optional reason code for a NAK response.
IRM_RES1 2 bytes 18 12 Reserved for future use. Initialize to binary zeros.
IRM_F5 1 byte 20 X'14' Input message type.
X'80'
OTMA headers built by client.
X'40'
Translation done by client.
X'20'
The client application that issues resume tpipe supports control data in the ICAL callout message.
X'10'
Single message with wait option. Only one message returned following the RESUME TPIPE call. If no message is present, OTMA waits for a message to arrive and then sends that single message to IMS Connect. The timer set on the RESUME TPIPE call can expire before a message is returned to IMS Connect. If that occurs, IMS Connect issues a NAK response to the message when received.
X'04'
No auto flow of messages. All current messages are returned one at a time.

Use the no auto flow option only if the client is a dedicated output client. This value is similar to Auto, except that the IRM_TIMER will cause the last receive to terminate.

Set the IRM_TIMER to a small value. Each ACK sent by the client resets the IRM_TIMER value. The IRM_TIMER value set by the RESUME_TPIPE only applies to the first receive state.

X'02'
Auto flow of messages. All current messages are returned one at a time. Use the auto flow option only if the client is a dedicated output client.

Set the IRM_TIMER to a large value. Each ACK sent by the client resets the IRM_TIMER value. The IRM_TIMER value set by the RESUME_TPIPE only applies to the first receive state.

X'01'
Single message. Only one message returned following the RESUME TPIPE call. If no message is present, OTMA does not wait for a message and the IMS Connect timer causes a timeout to occur based on the timeout value specified.
X'08'
IRM_F5_XID The message includes an X/Open identifier (XID).
X'00'
No option flow of messages (see meaning for X'04'). This is the default if no value is specified.
IRM_TIMER 1 byte 21 X'15'

Time delay that IMS Connect will wait for IMS to return data to IMS Connect which, in turn, will be sent to the client. The following functions support the IRM_TIMER settings:

  • TCP/IP SEND of a RESUME TPIPE call
  • TCP/IP SEND of an ACK or NAK message
  • TCP/IP SEND of data
  • PC SEND of a RESUME TPIPE call
  • PC SEND of an ACK or NAK message
  • PC SEND of data
IRM_SOCT 1 byte 22 X'16' Socket connection type. The client can set this value as follows:
X'00'
Transaction socket. The socket connection lasts across a single transaction.
X'10'
Persistent socket. The socket connection lasts across multiple transactions.
X'40'
Non-persistent socket. The socket connection lasts for a single exchange consisting of one input and one output. Recommendation: Do not use this socket type if you plan on implementing conversational transactions, because multiple connects and disconnects will occur.
IRM_ES 1 byte 23 X'17' Unicode encoding schema. Initialize to binary zeros.
X'01'
UTF8 encoding schema.
X'02'
UCS2 encoding schema.
X'02'
UTF16 encoding schema.
IRM_CLIENTID 8 bytes 24 X'18' A string of 1 to 8 uppercase alphanumeric (A through Z, 0 to 9) or special (@, #, $) characters, left justified, and padded with blanks. IRM_CLIENTID specifies the name of the client ID that is used by IMS Connect. If this string is not supplied by the client, then the user exit must generate it.

The client ID is returned to IMS Connect from the exit in the EXIT PARMLIST field, EXPREA_CLID.