The MQRFH2 header

 

This section describes the MQRFH V2 header, which carries JMS-specific data that is associated with the message content. The MQRFH2 V2 is an extensible header, and can also carry additional information that is not directly associated with JMS. However, this section covers only its use by JMS.

There are two parts of the header, a fixed portion and a variable portion.

Fixed portion

The fixed portion is modelled on the standard WebSphere 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 in the usual way.

V(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.)

The NameValueCCSID takes values from the following table:

Possible values for NameValueCCSID field
Value Meaning
1200 UCS2 open-ended
1208 UTF8
13488 UCS2 2.0 subset
17584 UCS2 2.1 subset (includes Euro symbol)

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 together related properties. The MQRFH2 headers created by JMS can contain up to three folders:

The <mcd> folder

This contains properties that describe the shape or format of the message. For example, the Msd property identifies the message as being Text, Bytes, Stream, Map, Object, or null. This folder is always present in a JMS MQRFH2.

The <jms> folder

This is used to transport JMS header fields, and JMSX properties that cannot be fully expressed in the MQMD. This folder is always present in a JMS MQRFH2.

The <usr> folder

This is used to transport any application-defined properties associated with the message. This folder is present only if the application has set some application-defined properties.

The <mqext> folder

This is used to transport IBM defined properties that are used only by WebSphere Application Server. This folder is present only if the application has set at least one of these properties.

Table 2 shows a full list of property names.

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

The syntax used to express the properties in the variable portion is as follows:

NameValueLength (MQLONG)

Length in bytes of the NameValueData string that immediately follows this length field (it does not include its own length). The value set into NameValueLength is always a multiple of 4 (the NameValueData field is padded with space characters to achieve this).

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 2.

datatype

must match, after folding, one of the data types listed in Table 3.

value

is a string representation of the value to be conveyed, using the definitions in Table 3.

A null value is encoded using the following syntax: 

<name dt='datatype' xsi:nil='true'></name>
Do not use xsi:nil='false'.

Property data types
Data type Definition
string Any sequence of characters excluding < and &
boolean The character 0 or 1 (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

We can use the following escape sequences, but they are not required:

  • &gt; for the > character

  • &apos; for the ' character

  • &quot; for the " character


uj25440_