Overview for MQRMH

Availability: The MQRMH structure is available on the following platforms:

  • AIX
  • IBM i
  • Linux
  • Windows

and for IBM MQ clients connected to these systems.

Purpose: The MQRMH structure defines the format of a reference message header. This header is used with user-written message channel exits to send extremely large amounts of data (called bulk data ) from one queue manager to another. The difference compared to normal messaging is that the bulk data is not stored on a queue; instead, only a reference to the bulk data is stored on the queue. This reduces the possibility of MQ resources being exhausted by a small number of extremely large messages.

Format name: MQFMT_REF_MSG_HEADER.

Character set and encoding: Character data in MQRMH, and the strings addressed by the offset fields, must be in the character set of the local queue manager; this is given by the CodedCharSetId queue manager attribute. Numeric data in MQRMH must be in the native machine encoding; this is given by the value of MQENC_NATIVE for the C programming language.

Set the character set and encoding of the MQRMH into the CodedCharSetId and Encoding fields in:

  • The MQMD (if the MQRMH structure is at the start of the message data), or
  • The header structure that precedes the MQRMH structure (all other cases).

Usage: An application puts a message consisting of an MQRMH, but omitting the bulk data. When a message channel agent (MCA) reads the message from the transmission queue, a user-supplied message exit is invoked to process the reference message header. The exit can append to the reference message the bulk data identified by the MQRMH structure, before the MCA sends the message through the channel to the next queue manager.

At the receiving end, a message exit that waits for reference messages must exist. When a reference message is received, the exit must create the object from the bulk data that follows the MQRMH in the message, and then pass on the reference message without the bulk data. The reference message can later be retrieved by an application reading the reference message (without the bulk data) from a queue.

Normally, the MQRMH structure is all that is in the message. However, if the message is on a transmission queue, one or more additional headers precede the MQRMH structure.

A reference message can also be sent to a distribution list. In this case, the MQDH structure and its related records precede the MQRMH structure when the message is on a transmission queue.

Note: Do not send a reference message as a segmented message, because the message exit cannot process it correctly. Data conversion: For data conversion purposes, converting the MQRMH structure includes conversion of the source environment data, source object name, destination environment data, and destination object name. Any other bytes within StrucLength bytes of the start of the structure are either discarded or have undefined values after data conversion. The bulk data is converted provided that all the following statements are true:

  • The bulk data is present in the message when the data conversion is performed.
  • The Format field in MQRMH has a value other than MQFMT_NONE.
  • A user-written data-conversion exit exists with the format name specified.

Be aware, however, that usually the bulk data is not present in the message when the message is on a queue, and that as a result the bulk data is converted by the MQGMO_CONVERT option. Parent topic: MQRMH - Reference message header