This topic describes how service integration processes the message header fields and properties when converting messages between WebSphere® MQ format and service integration format.
In general, you do not need to be aware of conversion between message formats to exchange JMS messages between service integration and WebSphere MQ. However, you might need 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 WebSphere MQ programs.
If your service integration applications exchange MapMessage objects with WebSphere MQ applications, you might need to specify a non-default map message encoding format. For more information, see Setting the WebSphere MQ encoding format for JMS Map entries.
WebSphere MQ messages contain message properties in the message descriptor (MQMD) and in the rules and formatting header 2 (MQRFH2).
When service integration converts a message to WebSphere 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 WebSphere MQ format, it sets the service integration message header fields and properties from the MQMD and the MQRFH2 in the WebSphere MQ message.
Similarly, service integration might receive messages from WebSphere 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 WebSphere MQ Application Programming Reference. For details of WebSphere MQ JMS support, including details of how WebSphere MQ stores JMS message properties and header fields in the MQMD and the MQRFH2, see WebSphere MQ Using Java.
The following table shows how service integration maps JMS header fields to and from MQMD and MQRFH2 fields when converting messages to and from WebSphere MQ format.
The table shows the MQRFH2 field as folder.field, where folder is the name of the MQRFH2 folder which 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 WebSphere MQ format, it sets both the MQMD and the MQRFH2 fields; when service integration is converting messages from WebSphere MQ format, it sets the JMS header field from the MQRFH2 field if it is available, otherwise from the MQMD field.
JMS header field | MQMD field | MQRFH2 field | Notes® |
---|---|---|---|
JMSCorrelationID | CorrelId | jms.Cid | The MQMD CorrelId field can hold a standard WebSphere 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 WebSphere 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. |
JMSDeliveryMode | Persistence | jms.Dlv | |
JMSDestination | jms.Dst | ||
JMSExpiration | Expiry | jms.Exp | |
JMSMessageID | MsgId | ||
JMSPriority | Priority | WebSphere 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. | |
JMSRedelivered | BackoutCount | Service integration sets the JMSRedelivered indicator for a message it receives form WebSphere 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. | |
JMSReplyTo | ReplyToQ and ReplyToQMgr | jms.Rto | |
JMSTimestamp | PutDate and PutTime | jms.Tms | |
JMSType | mcd.Type |
The following table shows how service integration maps JMS defined properties to and from MQMD and MQRFH2 fields when converting messages to and from WebSphere MQ format.
The table shows the MQRFH2 field as folder.field, where folder is the name of the MQRFH2 folder which 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 WebSphere MQ format, it sets both the MQMD and the MQRFH2 fields; when service integration is converting messages from WebSphere MQ format, it sets the JMS defined property from the MQRFH2 field if it is available, otherwise from the MQMD field.
JMS defined property | MQMD field | MQRFH2 field | Notes |
---|---|---|---|
JMSXAppID | PutApplName | ||
JMSXDeliveryCount | BackoutCount | ||
JMSXGroupID | GroupId | jms.Gid | The MQMD GroupId field
can hold a standard WebSphere 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 WebSphere 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. When service integration is converting messages to WebSphere 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 WebSphere MQ message properties: JMS provider-specific properties). |
JMSXGroupSeq | MsgSeqNumber | jms.Seq | |
JMSXUserID | UserIdentifier |
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.
The table shows the MQRFH2 field as folder.field, where folder is the name of the MQRFH2 folder which contains the field, and field is the name of the field within the MQRFH2 folder.
JMS provider-specific property | MQMD field | MQRFH2 field | Notes |
---|---|---|---|
JMS_IBM_Character_Set | CodedCharacterSetId | CodedCharacterSetId | Note 1: The JMS_IBM_Character_Set, JMS_IBM_Encoding,
and JMS_IBM_Format properties contain information
about the WebSphere MQ
message payload; that is, the part of the WebSphere MQ message that follows the MQRFH2
(if there is one) or the whole WebSphere MQ
message, excluding the MQMD, if there is no MQRFH2. For more information
about these properties and how to use them, see How service integration converts the message body to and from WebSphere MQ format.
|
JMS_IBM_Encoding | Encoding | Encoding | See Note 1. |
JMS_IBM_Feedback | Feedback | ||
JMS_IBM_Format | Format | Format | See Note 1. |
JMS_IBM_Last_Msg_In_Group | MQMF_LAST_MSG_IN_GROUP | Note 2: MQMF_LAST_MSG_IN_GROUP is
one of the flags in the MsgFlags field of the
MQMD.
|
|
JMS_IBM_MsgType | MsgType | ||
JMS_IBM_PutDate | PutDate | ||
JMS_IBM_PutTime | PutTime | ||
JMS_IBM_Report_* | Report | Note 3: For a
list of the JMS_IBM_Report_* properties, see Mapping of MQMD Report fields to JMS provider-specific properties.
|