Overview

Purpose: The MQRMH structure defines the format of a reference message header. This header is used in conjunction 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: FMRMH.

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 ENNAT for the C programming language.

The character set and encoding of the MQRMH must be set into the MDCSI and MDENC 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 the message is read from the transmission queue by a message channel agent (MCA), 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 should exist. When a reference message is received, the exit should 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 will 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:

A reference message should not be sent as a segmented message, because the message exit cannot process it correctly.

Data conversion: For data conversion purposes, conversion of the MQRMH structure includes conversion of the source environment data, source object name, destination environment data, and destination object name. Any other bytes within RMLEN bytes of the start of the structure are either discarded or have undefined values after data conversion. The bulk data will be converted provided that all of the following are true:

• The bulk data is present in the message when the data conversion is performed.

• The RMFMT field in MQRMH has a value other than FMNONE.

• 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 will not be converted by the GMCONV option.