WebSphere® MQ message formats

In order that a receiving system can best interpret the received payload, WebSphere® MQ can indicate the format of user data. User data can contain one or more blocks that can be chained together. Each block includes the format of the next item in the chain. The last block is the user data.

Note: WebSphere® MQ 7.1 and later support message properties, which are used to add optional fields to a message. Categories of optional fields are as follows: JMS optional header fields, application-specific properties, and provider-specific properties. When used with WebSphere® MQ 7.1 and later, HCL DevOps Test Integrations and APIs (Test Integrations and APIs) also supports message properties and exposes them as header fields in messaging actions. (For more information about message properties, refer to WebSphere® MQ documentation.

For example, most publish and subscribe messages that are generated by the JMS support in WebSphere® MQ contain a version one and version two Rules and Formatting Header, followed by the message payload.

In Test Integrations and APIs, the blocks are chained together by including the optional blocks as part of the message payload. These blocks appear as optional fields on the root of the message when the WebSphere® MQ formatter is selected.

Similar to the format, the code page and encoding settings for the header and RF headers must follow a similar pattern. This means that the setting in the message header must match the first header, and the setting in each RFH must match the settings of the data that immediately follows the particular RFH. However, this setting is left to the control of the user.

RFH1 and RFH2 content blocks

The following section explains RFH1 and RFH2 content blocks.

A Rules and Formatting Header is an optional data block that gives the receiving application information about the format of the message data. There are two versions of the header:

  • Version 1 (RFH1)
  • Version 2 (RFH2)
Notes:
  • In messages, an RFH2 content block cannot be used after an RFH1 content block.
  • In WebSphere® MQ 6.0 or earlier, RFH2 headers are used to store MQ JMS properties. However, in WebSphere® MQ 7.1 and later, properties are added as MQ properties to each message instead of adding an RFH2 block. In addition, all MQ JMS properties are stored as a property. For more information about how WebSphere® MQ 6.0 (or earlier), 7.1 and later handle RFH2 blocks, see the WebSphere® MQ documentation.
  • To keep the older behavior with a separate RFH2 header, configure the physical WebSphere® MQ transport options section to include the MQGMO_PROPERTIES_FORCE_MQRFH2 value in the Get/Take and Browse values. This change can be done by adding 33554432 to the existing values, resulting in the following new default values:
    • Reading Options - Get/Take Message: 33562624
    • Browsing Options - Browse First: 33562640
    • Browsing Options - Browse Next: 33562656
  • Beginning in version 10.0.0, Test Integrations and APIs also captures attributes within user-defined folders in the RFH2 header. The attributes appear in the Recording Studio together with other contents of the folders. Within Test Integrations and APIs, attribute names begin with the @ character.
  • When you run tests that were created prior to version 10.0.0, the new capability to capture attributes might result in the following message: The field found in the received message was unexpected (Action = "Validate Message Children"). To correct this problem, you can either edit the Receive Reply test step, select the folder within the MQRFH2, and select the Ignore additional fields in received message check box, or you can recreate the test.

Each block contains a fixed portion of data followed by an optional, variable portion. The fixed data identifies and describes the Rules and Formatting Header itself, while the variable portion contains optional data fields.

In the fixed portion of the block, the version, length, and format fields are automatically calculated within Test Integrations and APIs. The CCSID field, which is present only in the version 2 format, denotes the code page that is used for the variable portion of the header. CCSID can be one of four values (1200, 1208, 13488, 17584), and must be set to code page 1208 in most cases.

The variable portion of a version one header contains these things:
  • Name-value pairs that can define the format of the user data (the application group and format name)
  • Fields that are related to publish and subscribe requests
These are interpreted by Test Integrations and APIs as a plain string of data.

The variable portion of a version two headers is divided into a number of XML folders:

  • The mcd folder contains up to four fields that define the data type and format (that is, message domain, set, type, and format). The domain indicates the parser that processes the message data, while the parser determines the meaning of the other three fields.
  • The jms folder contains several fields that are populated by the WebSphere® MQ implementation of JMS.
  • The variable portion can also contain folders that are related to publish and subscribe, user data, and other miscellaneous, user-defined folders.
  • All folders are optional, and more than one folder can be present in the same RF Header.
For more information about how WebSphere® MQ handles RFH blocks, see the MQRFH - Rules and formatting header. For more information about how WebSphere® MQ handles RFH2 blocks, see the MQRFH2 - Rules and formatting header 2.

CIHv1 and CIHv2 content blocks

The following section explains CIHv1 and CIHv2 content blocks.

The MQCIH structure describes the header information for a message sent to CICS across the CICS-MQ bridge. For more information about the CICS bridge, see The CICS-WebSphere MQ bridge.

The current version of the MQCIH structure is version 2. To differentiate the two versions, Test Integrations and APIs treats each version as a separate block:

  • Version 1 (CIHv1)
  • Version 2 (CIHv2)

Each block contains a single, fixed portion of data. The CIH block should be followed by the application message data (not another header block). In the CIH block, the structure ID, version and structure length fields are automatically calculated within Test Integrations and APIs.

For more information about how WebSphere® MQ handles CIH blocks, see MQCIH - CICS bridge header.

IMS and IMSVS content blocks

IMS and IMSVS content blocks are also supported by Test Integrations and APIs. For more information about how WebSphere® MQ handles IMS blocks, see the MQIIH - IMS information header.

Other content blocks

Other folder types (such as Dead Letter) are not supported explicitly by Test Integrations and APIs, but they are processed as a content block that contains a byte array. Since Test Integrations and APIs is unaware of the length of these blocks, all of the remaining data from the body of the message is included as part of this header.

The Unknown header element from the message schema can be used to send these blocks. In such a case, the name of the container is used to populate the format field in the preceding block, or in the message header if it is the first.

Message headers and WebSphere® MQ messages

For information about adding headers to a WebSphere® MQ message, see Messages send request.