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.
Exchanging messages between JMS programs through service integration and WebSphere MQ
Usually, you do not have to be aware of conversion between message formats to exchange JMS messages between service integration and WebSphere 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 WebSphere MQ programs.
If your service integration applications exchange MapMessage objects with WebSphere MQ applications, you might have to specify a non-default map message encoding format.
WebSphere 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
WebSphere 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 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.
WebSphere 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 WebSphere 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 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.
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 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.
Note 2: 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.
Note 3: Service integration sets
the JMSRedelivered indicator for a message it
receives from 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.
WebSphere 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 WebSphere 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 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.
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 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.
Note 5: 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).
WebSphere 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
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
Mapping the message body to and from WebSphere 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
WebSphere MQ MQMD fields. When
service integration converts messages to
WebSphere 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 WebSphere MQ format.
Note 10: The
JMS_IBM_MQMD_CorrelId property
overrides the default processing of the
JMSCorrelationID property.
When service integration converts messages to
WebSphere 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 WebSphere 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
WebSphere 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 WebSphere 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
WebSphere 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 WebSphere 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
WebSphere 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 WebSphere 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.