Mapping the message header fields and properties to and from IBM MQ format

When service integration converts a message to IBM MQ format, it sets fields in the MQMD and the MQRFH2 based on the service integration message header fields and properties; these include JMS message header fields and properties applicable to the message. When service integration converts a message from IBM MQ format, it sets the service integration message header fields and properties from the MQMD and the MQRFH2 in the IBM MQ message.

Exchanging messages between JMS programs through service integration and IBM MQ

Usually, you do not have to be aware of conversion between message formats to exchange JMS messages between service integration and IBM MQ, because service integration performs the appropriate conversion automatically, including character and numeric encoding. However, you might have to learn about message conversion if your JMS applications do not behave as expected, or if your service integration configuration includes JMS programs or mediations that process messages to or from non-JMS IBM MQ programs.

If your service integration applications exchange MapMessage objects with IBM MQ applications, you might have to specify a non-default map message encoding format.

IBM MQ message properties: the MQMD and the MQRFH2

WebSphere MQ messages contain message properties in the message descriptor (MQMD) and in the rules and formatting header 2 (MQRFH2). The IBM MQ message always includes an MQMD, but the MQRFH2 is optional because some WebSphere MQ applications cannot process messages that contain an MQRFH2. To simplify interoperation, you can configure service integration to omit the MQRFH2 from messages for applications that cannot process the MQRFH2. When service integration omits the MQRFH2, it discards the corresponding service integration header fields and properties.
Note: A small amount of the MQRFH2 information is also stored in MQMD fields. However, these MQMD fields are not exact equivalents, tend to be less specific, and cannot be relied upon to provide an adequate substitute for the MQRFH2 information. Therefore if the receiving application can accept an MQRFH2 header, you should always provide one.

Similarly, service integration might receive messages from IBM MQ applications that generate messages with no MQRFH2. When service integration receives a message with no MQRFH2, it creates a best guess service integration header, by getting as much information as it can from the MQMD, and using default values for the other fields.

For detailed information about the contents of the message descriptor and the message headers, see the IBM MQ Application programming reference. For details of IBM MQ JMS support, including details of how IBM MQ stores JMS message properties and header fields in the MQMD and the MQRFH2, see Using WebSphere MQ classes for JMS.

IBM MQ message properties: JMS header fields

The following table shows how service integration maps JMS header fields to and from MQMD and MQRFH2 fields when converting messages to and from IBM MQ format.

The table shows the MQRFH2 field as folder.field, where folder is the name of the MQRFH2 folder that contains the field, and field is the name of the field within the MQRFH2 folder.

For several JMS header fields, there is both an MQMD field and an MQRFH2 field. When service integration is converting messages to IBM MQ format, it sets both the MQMD and the MQRFH2 fields. When service integration is converting messages from IBM MQ format, it sets the JMS header field from the MQRFH2 field if it is available, otherwise from the MQMD field.

Table 1. JMS, MQMD and MQRFH2 header fields. The first column of this table lists the JMS header fields, and the second column shows the MQMD fields that relate to the JMS header fields in the first column. The third column shows the MQRFH2 fields that relate to the JMS header fields in the first column. The fourth column provides links, where required, to the footnotes that appear after the table.
JMS header field MQMD field MQRFH2 field Notes
JMSCorrelationID CorrelId jms.Cid See Note 1.
JMSDeliveryMode Persistence jms.Dlv See Note 15.
JMSDestination   jms.Dst See Note 16.
JMSExpiration Expiry jms.Exp  
JMSMessageID MsgId    
JMSPriority Priority   See Note 2.
JMSRedelivered BackoutCount   See Note 3.
JMSReplyTo ReplyToQ and ReplyToQMgr jms.Rto See Note 16.
JMSTimestamp PutDate and PutTime jms.Tms  
JMSType   mcd.Type  
Note 1: The MQMD CorrelId field can hold a standard IBM MQ Correlation ID of 48 hexadecimal digits (24 bytes). The JMSCorrelationID can be a byte[] value, a string value containing hexadecimal characters and prefixed with ID:, or an arbitrary string value not beginning ID:. The first two of these represent a standard IBM MQ Correlation ID and map directly to or from the MQMD CorrelId field (truncated or padded with zeros as applicable); they do not use the MQRFH2 jms.Cid field. The third (arbitrary string) uses the MQRFH2 jms.Cid field; the first 24 bytes of the string, in UTF-8 format, are written into the MQMD CorrelID.
Note 2: IBM MQ stores the JMSPriority value in the MQRFH2 jms.Pri field but does not use any value already in that field. Service integration does not check or set the MQRFH2 jms.Pri field.
Note 3: Service integration sets the JMSRedelivered indicator for a message it receives from IBM MQ based on the BackoutCount field of the MQMD; a non-zero BackoutCount value indicates that a previous receive for the message was rolled back.

IBM MQ message properties: JMS defined properties

The following table shows how service integration maps JMS defined properties to and from MQMD and MQRFH2 fields when converting messages to and from IBM MQ format.

The table shows the MQRFH2 field as folder.field, where folder is the name of the MQRFH2 folder that contains the field, and field is the name of the field within the MQRFH2 folder.

For several JMS-defined properties, there is both an MQMD field and an MQRFH2 field. When service integration is converting messages to IBM MQ format, it sets both the MQMD and the MQRFH2 fields. When service integration is converting messages from IBM MQ format, it sets the JMS defined property from the MQRFH2 field if it is available, otherwise from the MQMD field.

Table 2. JMS properties with MQMD and MQRFH2 fields. The first column of this table lists the JMS defined properties, and the second column shows the MQMD fields that relate to the JMS defined properties in the first column. The third column shows the MQRFH2 fields that relate to the JMS defined properties in the first column. The fourth column provides links, where required, to the footnotes that appear after the table.
JMS defined property MQMD field MQRFH2 field Notes
JMSXAppID PutApplName    
JMSXDeliveryCount BackoutCount    
JMSXGroupID GroupId jms.Gid See Notes 4 and 5.
JMSXGroupSeq MsgSeqNumber jms.Seq  
JMSXUserID UserIdentifier    
Note 4: The MQMD GroupId field can hold a standard IBM MQ GroupId of 48 hexadecimal digits (24 bytes). The JMSXGroupID is a string value containing hexadecimal characters and prefixed with ID: or an arbitrary string value not beginning ID:. The first of these represents a standard IBM MQ GroupId and maps directly to or from the MQMD GroupId field (truncated or padded with zeros as applicable). The second (arbitrary string) uses the MQRFH2 jms.Gid field; the first 24 bytes of the string, in UTF-8 format, are written into the MQMD GroupId.
Note 5: When service integration is converting messages to IBM MQ format, if the JMSXGroupID has been set then service integration also sets the MQMF_MSG_IN_GROUP flag in the MsgFlags field of the MQMD. Note that when sending group messages, the sending JMS application must ensure that the MQMF_LAST_MSG_IN_GROUP flag is set as required (see IBM MQ message properties: JMS provider-specific properties).

IBM MQ message properties: JMS provider-specific properties

The following table shows how service integration maps JMS provider-specific properties to and from MQMD and MQRFH2 fields when converting messages to and from WebSphere MQ format. Typically you use these properties to satisfy special requirements in the receiving application, so you should consult the developer or administrator of the receiving application for details of the required property values.

Table 3. JSM provider-specific properties with MQMD and MQRFH2 fields. The first column of this table lists the JMS provider-specific properties, and the second column shows the MQMD fields that relate to the JMS provider-specific properties in the first column. The third column shows the MQRFH2 fields that relate to the JMS provider-specific properties in the first column. The fourth column provides links, where required, to the footnotes that appear after the table.
JMS provider-specific property MQMD field MQRFH2 field Notes
JMS_IBM_ArmCorrelator   mqext.Arm See Note 6.
JMS_IBM_Character_Set CodedCharacterSetId CodedCharacterSetId See Note 7.
JMS_IBM_Encoding Encoding Encoding See Note 7.
JMS_IBM_Feedback Feedback    
JMS_IBM_Format Format Format See Note 7.
JMS_IBM_Last_Msg_In_Group MQMF_LAST_MSG_IN_GROUP   See Note 8.
JMS_IBM_MQMD_CorrelId CorrelId   See Notes 9 and 10.
JMS_IBM_MQMD_MsgId MsgId   See Notes 9 and 11.
JMS_IBM_MQMD_Persistence Persistence   See Notes 9, 12, and 15.
JMS_IBM_MQMD_ReplyToQ ReplyToQ   See Notes 9, 13, and 16.
JMS_IBM_MQMD_ReplyToQMgr ReplyToQMgr   See Notes 9, 13, and 16.
JMS_IBM_MsgType MsgType    
JMS_IBM_PutDate PutDate    
JMS_IBM_PutTime PutTime    
JMS_IBM_Report_* Report   See Note 14.
JMS_IBM_RMCorrelator   mqext.Wrm  
JMS_TOG_ARM_Correlator   mqext.Arm See Note 6.
Note 6: You should use the name JMS_TOG_ARM_Correlator for the ARM correlator. The name JMS_IBM_ArmCorrelator is available for compatibility with some existing JMS programs.
Note 7: The JMS_IBM_Character_Set, JMS_IBM_Encoding, and JMS_IBM_Format properties contain information about the IBM MQ message payload; that is, the part of the IBM MQ message that follows the MQRFH2 (if there is one) or the whole IBM MQ message, excluding the MQMD, if there is no MQRFH2. For more information about these properties and how to use them, see Mapping the message body to and from IBM MQ format.
Note 8: MQMF_LAST_MSG_IN_GROUP is one of the flags in the MsgFlags field of the MQMD.
Note 9: The JMS_IBM_MQMD_CorrelId, JMS_IBM_MQMD_MsgId, JMS_IBM_MQMD_Persistence, JMS_IBM_MQMD_ReplyToQ, and JMS_IBM_MQMD_ReplyToQMgr properties allow JMS applications to override the service integration default processing of IBM MQ MQMD fields. When service integration converts messages to IBM MQ format, service integration sets the corresponding MQMD field for each of these properties if, and only if, that property has been explicitly set by the application (using setObjectProperty() or setNonNullProperty()).

Service integration sets each of these properties from the corresponding MQMD field when it converts a message from IBM MQ format.

Note 10: The JMS_IBM_MQMD_CorrelId property overrides the default processing of the JMSCorrelationID property. When service integration converts messages to IBM MQ format, service integration sets the MQMD CorrelId field to the value (byte[]) if explicitly set of the JMS_IBM_MQMD_CorrelId property, regardless of the value (if any) of the JMSCorrelationID property. Setting the JMS_IBM_MQMD_CorrelId property does not affect the value of the MQRFH2 jms.Cid field.

When service integration converts messages from IBM MQ format, service integration sets the JMS_IBM_MQMD_CorrelId property to the value (byte[]) of the MQMD CorrelId field, regardless of the value (if any) of the MQRFH2 jms.Cid field.

Note 11: The JMS_IBM_MQMD_MsgId property overrides the JMS default processing of the JMSMessageID property. When service integration converts messages to IBM MQ format, service integration checks whether the JMS_IBM_MQMD_MsgId property has been explicitly set. If so, service integration sets the MQMD MsgId field to this value (byte[]) , and replaces the unique value of the JMSMessageID that JMS allocates to the message.

When service integration converts messages from IBM MQ format, service integration sets the JMS_IBM_MQMD_MsgId property to the value (byte[]) of the MQMD MsgId field.

Note 12: The JMS_IBM_MQMD_Persistence property overrides the default processing of the JMSDeliveryMode property. When service integration converts messages to IBM MQ format, service integration sets the MQMD Persistence field to the value (integer) if explicitly set of the JMS_IBM_MQMD_Persistence property, regardless of the value (if any) of the JMSDeliveryMode property. Setting the JMS_IBM_MQMD_Persistence property does not affect the value of the MQRFH2 jms.Dlv field.

When service integration converts messages from IBM MQ format, service integration sets the JMS_IBM_MQMD_Persistence property to the value (integer) of the MQMD Persistence field, regardless of the value (if any) of the MQRFH2 jms.Dlv field.

Note 13: The JMS_IBM_MQMD_ReplyToQ and JMS_IBM_MQMD_ReplyToQMgr properties override the default processing of the JMSReplyTo property. When service integration converts messages to IBM MQ format, service integration sets the MQMD ReplyToQ field to the value (string) if explicitly set of the JMS_IBM_MQMD_ReplyToQ property and the MQMD ReplyToQMgr field to the value (string) if explicitly set of the JMS_IBM_MQMD_ReplyToQMgr property, regardless of the value (if any) of the JMSReplyTo property. Setting the JMS_IBM_MQMD_ReplyToQ or JMS_IBM_MQMD_ReplyToQMgr field does not affect the value of the MQRFH2 jms.Rto field.

When service integration converts messages from IBM MQ format, service integration sets the JMS_IBM_MQMD_ReplyToQ and JMS_IBM_MQMD_ReplyToQMgr property to the values (string) of the MQMD ReplyToQ and ReplyToQMgr fields, regardless of the value (if any) of the MQRFH2 jms.Rto field.

Note 14: For a list of the JMS_IBM_Report_* properties, see Mapping MQMD Report fields to JMS provider-specific properties.
Note 15: For more information see Mapping the JMS delivery option and message reliability to and from the IBM MQ persistence value.
Note 16: For more information see Mapping destinations to and from IBM MQ queues, topics, and destinations.