Supported MQRFH2 folders

Overview of the use of message descriptor fields as properties.

The folders <jms>, <mcd>, <mqext>, and <usr> are described in The MQRFH2 header and JMS. The <usr> folder is used to transport any JMS application-defined properties that are associated with a message. Groups are not allowed in the <usr> folder.

The MQRFH2 header and JMS supports the following additional folders:
  • <mq>

    This folder is used and reserved for MQ-defined properties that are used by IBM® MQ.

  • <mq_usr>

    This folder can be used to transport any application-defined properties that are not exposed as JMS user-defined properties, as the properties might not meet the requirements of a JMS property. This folder can contain groups that the <usr> folder cannot.

  • Any folder marked with the content='properties' attribute.

    Such a folder is equivalent to the <mq_usr> folder in content.

  • <mqps>

    This folder is used for IBM MQ publish/subscribe properties.

IBM MQ also supports the following folders that are already in use by WAS/SIB:
  • <sib>

    This folder is used and reserved for WAS/SIB system message properties that are not exposed as JMS properties, or are mapped to JMS_IBM_* properties, but are exposed to WAS/SIB applications; these include forward and reverse routing paths properties.

    At least some cannot be exposed as JMS properties, because they are byte arrays. If your application adds properties to this folder, the value is either ignored or removed.

  • <sib_usr>

    This folder is used and reserved for WAS/SIB user message properties that cannot be exposed as JMS user properties because they are not of supported types; they are exposed to WAS/SIB applications.

    These are user properties, that you can get or set through the SIMessage interface, but the content of the byte array is mapped to the required property value.

    If your IBM MQ application writes an arbitrary bin.hex element to the folder, the application probably receives an IOException, as it is not of the format expected to restore. If you add anything other than a bin.hex element you receive a ClassCastException.

    Do not attempt to make properties available to WAS/SIB by using this folder; instead user the <usr> folder for that purpose.

  • <sib_context>

    This folder is used for WAS/SIB system message properties that are not exposed to WAS/SIB user applications or as JMS properties. These include security and transactional properties that are used for web services and similar.

    Your application must not add properties to this folder.

  • <mqema>

    This folder was used by WAS/SIB instead of the <mqext> folder.

MQRFH2 folder names are case-sensitive.
The following folders are reserved, in any mixture of lowercase or uppercase characters:
  • Any folder prefixed by mq or wmq ; reserved for use by IBM MQ.
  • Any folder prefixed by sib ; reserved for use by WAS/SIB.
  • <Root> and <Body> folders; reserved but not used.
The following folders are not recognized as containing message properties:
  • <psc>

    Used by IBM Integration Bus to convey publish/subscribe command messages to the broker.

  • <pscr>

    Used by IBM Integration Bus to contain information from the broker, in response to publish/subscribe command messages.

  • Any folder not defined by IBM, that is not marked with the content='properties' attribute.

Do not specify content='properties' on the <psc> or <pscr> folders. If you do so, these folders are treated as properties and IBM Integration Bus is likely to stop functioning as expected.

If your application is building messages with properties, in MQRFH2 headers to be recognized as an MQRFH2 header containing properties, the header must be in the list of headers that can be chained at the head of the message.

The MQRFH2 can be preceded by any number of MQH standard headers, or an MQCIH, an MQDLH, an MQIIH, an MQTM, an MQTMC2, or an MQXQH. A string or an MQCFH ends parsing because they cannot be chained.

It is possible for a message to contain multiple MQRFH2 headers all carrying message properties. Folders with the same name can coexist in different headers unless otherwise restricted, for example by WAS/SIB. The folders are treated as one logical folder, if they are all in significant headers.

While folders from the significant headers cannot be merged with those folders in nonsignificant headers, folders with the same name within the significant headers can be merged, removing any conflicting properties. Your applications must not depend on the layout of properties within their message.

MQRFH2 groups are parsed for properties in user-defined folders, that is, not the <wmq>, <jms>, <mcd>, <usr>, <mqext>, <sib>, <sib_usr>, <sib_context>, and <mqema> folders.

Groups in the IBM-defined properties folders, except for the <wmq> and <mq> folders, are parsed for properties.

An MQRFH2 folder cannot contain mixed content; a folder or group can contain either groups or properties, or a value, but not both.

A segment of a message, either the first or a subsequent segment, cannot contain IBM MQ -defined properties other than those properties in the message descriptor. Therefore putting a message containing such properties with either MQMF_SEGMENT or MQMF_SEGMENTATION_ALLOWED set causes the put to fail with MQRC_SEGMENTATION_NOT_ALLOWED.

However, message groups can contain IBM MQ -defined properties.