The MQRFH2 header and JMS

This collection of topics describes the MQRFH Version 2 header, which carries JMS-specific data that is associated with the message content. The MQRFH Version 2 header is extensible, and can also carry additional information that is not directly associated with JMS. However, this section covers only its use by JMS. For a full description see MQRFH2 - Rules and formatting header 2.
There are two parts of the header, a fixed portion and a variable portion.
Fixed portion
The fixed portion is modeled on the standard IBM® MQ header pattern and consists of the following fields:
StrucId (MQCHAR4)
Structure identifier.

Must be MQRFH_STRUC_ID (value: RFH ) (initial value).

MQRFH_STRUC_ID_ARRAY (value: R, F, H, ) is also defined.

Version (MQLONG)
Structure version number.

Must be MQRFH_VERSION_2 (value: 2) (initial value).

StrucLength (MQLONG)
Total length of MQRFH2, including the NameValueData fields.

The value set into StrucLength must be a multiple of 4 (the data in the NameValueData fields can be padded with space characters to achieve this).

Encoding (MQLONG)
Data encoding.

Encoding of any numeric data in the portion of the message following the MQRFH2 (the next header, or the message data following this header).

CodedCharSetId (MQLONG)
Coded character set identifier.

Representation of any character data in the portion of the message following the MQRFH2 (the next header, or the message data following this header).

Format (MQCHAR8)
Format name.

Format name for the portion of the message following the MQRFH2.

Flags (MQLONG)
Flags.

MQRFH_NO_FLAGS =0. No flags set.

NameValueCCSID (MQLONG)
The coded character set identifier (CCSID) for the NameValueData character strings contained in this header. The NameValueData can be coded in a character set that differs from the other character strings that are contained in the header (StrucID and Format).

If the NameValueCCSID is a 2 byte Unicode CCSID (1200, 13488, or 17584), the byte order of the Unicode is the same as the byte ordering of the numeric fields in the MQRFH2. (For example, Version, StrucLength, and NameValueCCSID itself.)

Table 1. Possible values for NameValueCCSID field
CCSID Meaning
1200 UTF-16, most recent Unicode version supported
13488 UTF-16, Unicode version 2.0 subset
17584 UTF-16, Unicode version 3.0 subset (includes the Euro symbol)
1208 UTF-8, most recent Unicode version supported
Variable portion
The variable portion follows the fixed portion. The variable portion contains a variable number of MQRFH2 folders. Each folder contains a variable number of elements or properties. Folders group related properties. The MQRFH2 headers created by JMS can contain any of the following folders:
The mcd folder

mcd contains properties that describe the format of the message. For example, the message service domain Msd property identifies a JMS message as being JMSTextMessage, JMSBytesMessage, JMSStreamMessage, JMSMapMessage, JMSObjectMessage, or null.

The mcd folder is always present in a JMS message containing an MQRFH2.

It is always present in a message containing an MQRFH2 sent from IBM Integration Bus. It describes the domain, format, type, and message set of a message.

Table 2. mcd property name, synonym, data type, and folder
Property synonym Property name Data type Folder
mcd.Msd string <mcd><Msd>messageDomain</Msd></mcd>
mcd.Set string <mcd><Set>messageDomain</Set></mcd>
mcd.Type string <mcd><Type>messageDomain</Type></mcd>
mcd.Fmt string <mcd><Fmt>messageDomain</Fmt></mcd>

Do not add your own properties in the mcd folder.

The jms folder

jms contains JMS header fields, and JMSX properties that cannot be fully expressed in the MQMD. The jms folder is always present in a JMS MQRFH2.

The usr folder

usr contains application-defined JMS properties associated with the message. The usr folder is present only if an application has set an application-defined property.

The mqext folder
mqext contains the following types of property:
  • Properties that are used only by WebSphere® Application Server.
  • Properties relating to delayed delivery of messages.
The folder is present if the application has either set at least one of the IBM defined properties or used delivery delay.
Table 3. mqext property name, synonym, data type, and folder
Property synonym Property name Data type Folder
JMSArmCorrelator mqext.Arm string <mqext><Arm>armCorrelator</Arm></mqext>
JMSRMCorrelator mqext.Wrm string <mqext><Wrm>wrmCorrelator</Wrm></mqext>
JMSDeliveryTime mqext.Dlt i8 <mqext><Dlt>DeliveryTime</Dlt></mqext>
JMSDeliveryDelay mqext.Dly i8 <mqext><Dly>DeliveryTime</Dly></mqext>

Do not add your own properties in the mqext folder.

The mqps folder

mqps contains properties that are used only by IBM MQ publish/subscribe. The folder is present only if the application has set at least one of the integrated publish/subscribe properties.

Table 4. mqps property name, synonym, data type, and folder
Property synonym Property name Data type Folder
MQTopicString mqps.Top string <mqps><Top>topicString</Top></mqps>
MQSubUserData mqps.Sud string <mqps><Sud>subscriberUserData...</Sud></mqps>
MQIsRetained mqps.Ret boolean <mqps><Ret>isRetained</Ret></mqps>
MQPubOptions mqps.Pub i8 <mqps><Pub>publicationOptions</Pub></mqps>
MQPubLevel mqps.Pbl i8 <mqps><Pbl>publicationLevel</Pbl></mqps>
MQPubTime mqpse.Pts string <mqps><Pts>publicationTime</Pts></mqps>
MQPubSeqNum mqpse.Seq i8 <mqps><Seq>publicationSequenceNumber</Seq></mqps>
MQPubStrIntData mqpse.Sid string <mqps><Sid>publicationData</Sid></mqps>
MQPubFormat mqpse.Pfmt i8 <mqps><Pfmt>messageFormat</Pfmt></mqps>

Do not add your own properties in the mqps folder.

Table 5 shows a full list of property names.
Table 5. MQRFH2 folders and properties used by JMS
JMS field name Java type MQRFH2 folder name Property name Type/values
JMSDestination Destination jms Dst string
JMSExpiration long jms Exp i8
JMSPriority int jms Pri i4
JMSDeliveryMode int jms Dlv i4
JMSCorrelationID String jms Cid string
JMSReplyTo Destination jms Rto string
JMSTimestamp long jms Tms i8
JMSType String mcd Type, Set, Fmt string
JMSXGroupID String jms Gid string
JMSXGroupSeq int jms Seq i4
xxx (user defined) Any usr xxx any
    mcd Msd
jms_none
jms_text
jms_bytes
jms_map
jms_stream
jms_object
NameValueLength (MQLONG)
Length in bytes of the NameValueData string that immediately follows this length field (it does not include its own length).
NameValueData (MQCHARn)
A single character string, whose length in bytes is given by the preceding NameValueLength field. It contains a folder holding a sequence of properties. Each property is a name/type/value triplet, contained within an XML element whose name is the folder name, as follows: 
<foldername>
triplet1 triplet2 .....  tripletn </foldername>
The closing </foldername> tag can be followed by spaces as padding characters. Each triplet is encoded using an XML-like syntax: 
<name dt='datatype'>value</name>
The dt='datatype' element is optional and is omitted for many properties, because the data type is predefined. If it is included, one or more space characters must be included before the dt= tag.
name
is the name of the property; see Table 5.
datatype
must match, after folding, one of the data types listed in Table 6.
value
is a string representation of the value to be conveyed, using the definitions in Table 6.
A null value is encoded using the following syntax: 
<name dt='datatype' xsi:nil='true'></name>
Do not use xsi:nil='false'.
Table 6. Property data types
Data type Definition
string Any sequence of characters excluding < and &
boolean The character 0 or 1 ( 0 = false, 1 = true)
bin.hex Hexadecimal digits representing octets
i1 A number, expressed using digits 0..9, with optional sign (no fractions or exponent). Must lie in the range -128 to 127 inclusive
i2 A number, expressed using digits 0..9, with optional sign (no fractions or exponent). Must lie in the range -32768 to 32767 inclusive
i4 A number, expressed using digits 0..9, with optional sign (no fractions or exponent). Must lie in the range -2147483648 to 2147483647 inclusive
i8 A number, expressed using digits 0..9, with optional sign (no fractions or exponent). Must lie in the range -9223372036854775808 to 92233720368547750807 inclusive
int A number, expressed using digits 0..9, with optional sign (no fractions or exponent). Must lie in the same range as i8. This can be used in place of one of the i* types if the sender does not want to associate a particular precision with the property
r4 Floating point number, magnitude <= 3.40282347E+38,>= 1.175E-37 expressed using digits 0..9, optional sign, optional fractional digits, optional exponent
r8 Floating point number, magnitude <= 1.7976931348623E+308,>= 2.225E-307 expressed using digits 0..9, optional sign, optional fractional digits, optional exponent
A string value can contain spaces. You must use the following escape sequences in a string value:
  • &amp; for the & character
  • &lt; for the < character
You can use the following escape sequences, but they are not required:
  • &gt; for the > character
  • &apos; for the ' character
  • &quot; for the " character