Mapping from property names to MQRFH2 folder and element names

Overview of the differences between property names and element names in the MQRFH2 header.

When using any of the defined APIs that ultimately generate MQRFH2 headers, in order to specify message properties (for example, MQ JMS), the property name is not necessarily the element name in the MQRFH2 folder.

Therefore, a mapping occurs from the property name to the MQRFH2 element, and in the reverse way, taking into account both the folder name that contains the element, and the element name. Some examples from IBM® MQ classes for JMS are already documented in Using IBM MQ classes for Java.
Table 1. Property names mapped to MQRFH2 folder and element names
Property name MQRFH2 folder name MQRFH2 element name
JMSDestination jms Dst
JMSType mcd Type, Set, Fmt
xxx (user defined, where xxx does not begin with JMS) usr xxx
Therefore, when a JMS application accesses the JMSDestination property this maps to the Dst element in the <jms> folder.
When specifying properties as MQRFH2 elements, IBM MQ defines its elements as follows:
Table 2. Property names mapped to MQRFH2 folder, group, and element names
Property name MQRFH2 folder name MQRFH2 group name MQRFH2 element name
<Property> <usr> n/a <Property>
<folder>. <Property> <folder> n/a <Property>
<folder>. <group>. <Property> <folder> <group> <Property>

For example, when an IBM MQ application attempts to access the Property1 property, this maps to the Property1 element in the <usr> folder. The wmq.Property2 property maps to the Property2 property in the <wmq> folder.

If the property name contains more than one . character, the MQRFH2 element name used is the one following the final . character, and MQRFH2 groups are used to form a hierarchy; nested MQRFH2 groups are permitted.

The JMS header and provider-specific properties that are contained in an MQRFH2 in the <mcd>, <jms>, and <mqext> folders are accessed by an IBM MQ application using the short names defined in Using IBM MQ classes for Java .

JMS user-defined properties are accessed from the <usr> folder. An IBM MQ application can use the <usr> folder for its application properties if it is acceptable for the property to appear to JMS applications as one of its user-defined properties.

If it is not acceptable, choose another folder; the <wmq_usr> folder is provided as a standard location for such non-JMS properties.

Your applications can specify and use any MQRFH2 folder with a well-defined use, not documented in Properties specified as MQRFH2 elements if you note the following:
  1. The folder might already be in use, or might be used in the future, by another application providing undefined access to properties contained inside it; see Property names for the suggested naming convention for property names.
  2. The properties are not accessible to previous versions of the IBM MQ classes for JMS or XMS client that can only access the <usr> folder for user-defined properties
  3. The folder must be marked with the attribute content with the value set to properties, for example, content='properties'.

    MQSETMP - Set message property automatically adds this attribute as required. This attribute must not be added to any of the IBM-defined folders, for example, <jms> and <usr>. Doing so, causes the message to be rejected by the IBM MQ classes for JMS client before IBM WebSphere® MQ 7.0. with a MessageFormatException.

Because the <usr> folder is the default location for properties of the <Property> syntax, an IBM MQ application and a JMS application to access the same user-defined property value using the same name.

Reserved folder names

There are several reserved folder names. You cannot use such names as your folder prefixes; for example, Root.Property1 does not access a valid property because Root is reserved. The following list contains reserved folder names:
  • Root
  • Body
  • Properties
  • Environment
  • LocalEnvironment
  • DestinationList
  • ExceptionList
  • InputBody
  • InputRoot
  • InputProperties
  • InputLocalEnvironment
  • InputDestinationList
  • InputExceptionList
  • OutputRoot
  • OutputLocalEnvironment
  • OutputDestinationList
  • OutputExceptionList