MQRMH (Reference message header) on IBM i
The MQRMH structure defines the format of a reference message header.
Overview
Purpose: This header is used with user-written message channel exits to send 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 IBM MQ resources being exhausted by a few 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 statements 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 typically 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.
Fields
The MQRMH structure contains the following fields; the fields are described in alphabetical order:
- RMCSI (10-digit signed integer)
-
Character set identifier of bulk data.
This specifies the character set identifier of the bulk data; it does not apply to character data in the MQRMH structure itself.
On the MQPUT or MQPUT1 call, the application must set this field to the value appropriate to the data. The following special value can be used:- CSINHT
- Inherit character-set identifier of this structure.
Character data in the data following this structure is in the same character set as this structure.
The queue manager changes this value in the structure sent in the message to the actual character-set identifier of the structure. Provided no error occurs, the value CSINHT is not returned by the MQGET call.
CSINHT cannot be used if the value of the MDPAT field in MQMD is ATBRKR.
The initial value of this field is CSUNDF.
- RMDEL (10-digit signed integer)
-
Length of destination environment data.
If this field is zero, there is no destination environment data, and RMDEO is ignored.
- RMDEO (10-digit signed integer)
-
Offset of destination environment data.
This field specifies the offset of the destination environment data from the start of the MQRMH structure. Destination environment data can be specified by the creator of the reference message, if that data is known to the creator. For example, the destination environment data might be the directory path of the object where the bulk data is to be stored. However, if the creator does not know the destination environment data, it is the responsibility of the user-supplied message exit to determine any environment information needed.
The length of the destination environment data is given by RMDEL ; if this length is zero, there is no destination environment data, and RMDEO is ignored. If present, the destination environment data must reside completely within RMLEN bytes from the start of the structure.
Applications should not assume that the destination environment data is contiguous with any of the data addressed by the RMSEO, RMSNO, and RMDNO fields.
The initial value of this field is 0.
- RMDL (10-digit signed integer)
-
Length of bulk data.
The RMDL field specifies the length of the bulk data referenced by the MQRMH structure.
If the bulk data is present in the message, the data begins at an offset of RMLEN bytes from the start of the MQRMH structure. The length of the entire message minus RMLEN gives the length of the bulk data present.
If data is present in the message, RMDL specifies the amount of that data that is relevant. The normal case is for RMDL to have the same value as the length of data present in the message.
If the MQRMH structure represents the remaining data in the object (starting from the specified logical offset), the value zero can be used for RMDL, if the bulk data is not present in the message.
If no data is present, the end of MQRMH coincides with the end of the message.
The initial value of this field is 0.
- RMDNL (10-digit signed integer)
-
Length of destination object name.
If this field is zero, there is no destination object name, and RMDNO is ignored.
- RMDNO (10-digit signed integer)
-
Offset of destination object name.
This field specifies the offset of the destination object name from the start of the MQRMH structure. The destination object name can be specified by the creator of the reference message, if that data is known to the creator. However, if the creator does not know the destination object name, it is the responsibility of the user-supplied message exit to identify the object to be created or modified.
The length of the destination object name is given by RMDNL ; if this length is zero, there is no destination object name, and RMDNO is ignored. If present, the destination object name must reside completely within RMLEN bytes from the start of the structure.
Applications should not assume that the destination object name is contiguous with any of the data addressed by the RMSEO, RMSNO, and RMDEO fields.
The initial value of this field is 0.
- RMDO (10-digit signed integer)
-
Low offset of bulk data.
This field specifies the low offset of the bulk data from the start of the object of which the bulk data forms part. The offset of the bulk data from the start of the object is called the logical offset. This is not the physical offset of the bulk data from the start of the MQRMH structure - that offset is given by RMLEN.
To allow large objects to be sent using reference messages, the logical offset is divided into two fields, and the actual logical offset is given by the sum of these two fields:- RMDO represents the remainder obtained when the logical offset is divided by 1 000 000 000. It is thus a value in the range 0 through 999 999 999.
- RMDO2 represents the result obtained when the logical offset is divided by 1 000 000 000. It is thus the number of complete multiples of 1 000 000 000 that exist in the logical offset. The number of multiples is in the range 0 through 999 999 999.
The initial value of this field is 0.
- RMDO2 (10-digit signed integer)
-
High offset of bulk data.
This field specifies the high offset of the bulk data from the start of the object of which the bulk data forms part. It is a value in the range 0 through 999 999 999. See RMDO for details.
The initial value of this field is 0.
- RMENC (10-digit signed integer)
-
Numeric encoding of bulk data.
This specifies the numeric encoding of the bulk data; it does not apply to numeric data in the MQRMH structure itself.
On the MQPUT or MQPUT1 call, the application must set this field to the value appropriate to the data.
The initial value of this field is ENNAT.
- RMFLG (10-digit signed integer)
-
Reference message flags.
The following flags are defined:- RMLAST
- Reference message contains or represents last part of object.
This flag indicates that the reference message represents or contains the last part of the referenced object.
- RMNLST
- Reference message does not contain or represent last part of object.
RMNLST is defined to aid program documentation. It is not intended that this option be used with any other, but as its value is zero, such use cannot be detected.
The initial value of this field is RMNLST.
- RMFMT (8-byte character string)
-
Format name of bulk data.
This specifies the format name of the bulk data.
On the MQPUT or MQPUT1 call, the application must set this field to the value appropriate to the data. The rules for coding this field are the same as those for the MDFMT field in MQMD.
The initial value of this field is FMNONE.
- RMLEN (10-digit signed integer)
-
Total length of MQRMH, including strings at end of fixed fields, but not the bulk data.
The initial value of this field is zero.
- RMOII (24-byte bit string)
-
Object instance identifier.
This field can be used to identify a specific instance of an object. If it is not needed, it should be set to the following value:- OIINON
- No object instance identifier specified.
The value is binary zero for the length of the field.
The length of this field is given by LNOIID. The initial value of this field is OIINON.
- RMOT (8-byte character string)
-
Object type.
This is a name that can be used by the message exit to recognize types of reference message that it supports. Consider making the name conform to the same rules as the RMFMT field.
The initial value of this field is 8 blanks.
- RMSEL (10-digit signed integer)
-
Length of source environment data.
If this field is zero, there is no source environment data, and RMSEO is ignored.
The initial value of this field is 0.
- RMSEO (10-digit signed integer)
-
Offset of source environment data.
This field specifies the offset of the source environment data from the start of the MQRMH structure. Source environment data can be specified by the creator of the reference message, if that data is known to the creator. For example, the source environment data might be the directory path of the object containing the bulk data. However, if the creator does not know the source environment data, it is the responsibility of the user-supplied message exit to determine any environment information needed.
The length of the source environment data is given by RMSEL ; if this length is zero, there is no source environment data, and RMSEO is ignored. If present, the source environment data must reside completely within RMLEN bytes from the start of the structure.
Applications should not assume that the environment data starts immediately after the last fixed field in the structure or that it is contiguous with any of the data addressed by the RMSNO, RMDEO, and RMDNO fields.
The initial value of this field is 0.
- RMSID (4-byte character string)
-
Structure identifier.
The value must be:- RMSIDV
- Identifier for reference message header structure.
The initial value of this field is RMSIDV.
- RMSNL (10-digit signed integer)
-
Length of source object name.
If this field is zero, there is no source object name, and RMSNO is ignored.
The initial value of this field is 0.
- RMSNO (10-digit signed integer)
-
Offset of source object name.
This field specifies the offset of the source object name from the start of the MQRMH structure. The source object name can be specified by the creator of the reference message, if that data is known to the creator. However, if the creator does not know the source object name, it is the responsibility of the user-supplied message exit to identify the object to be accessed.
The length of the source object name is given by RMSNL ; if this length is zero, there is no source object name, and RMSNO is ignored. If present, the source object name must reside completely within RMLEN bytes from the start of the structure.
Applications should not assume that the source object name is contiguous with any of the data addressed by the RMSEO, RMDEO, and RMDNO fields.
The initial value of this field is 0.
- RMVER (10-digit signed integer)
-
Structure version number.
The value must be:- RMVER1
- Version-1 reference message header structure.
The following constant specifies the version number of the current version:
- RMVERC
- Current version of reference message header structure.
The initial value of this field is RMVER1.
Initial values
| Field name | Name of constant | Value of constant |
|---|---|---|
| RMSID | RMSIDV | 'RMH¬' |
| RMVER | RMVER1 | 1 |
| RMLEN | None | 0 |
| RMENC | ENNAT | Depends on environment |
| RMCSI | CSUNDF | 0 |
| RMFMT | FMNONE | Blanks |
| RMFLG | RMNLST | 0 |
| RMOT | None | Blanks |
| RMOII | OIINON | Nulls |
| RMSEL | None | 0 |
| RMSEO | None | 0 |
| RMSNL | None | 0 |
| RMSNO | None | 0 |
| RMDEL | None | 0 |
| RMDEO | None | 0 |
| RMDNL | None | 0 |
| RMDNO | None | 0 |
| RMDL | None | 0 |
| RMDO | None | 0 |
| RMDO2 | None | 0 |
Notes:
|
||
D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
D*
D* MQRMH Structure
D*
D* Structure identifier
D RMSID 1 4 INZ('RMH ')
D* Structure version number
D RMVER 5 8I 0 INZ(1)
D* Total length of MQRMH, includingstrings at end of fixed fields,but not
D* the bulk data
D RMLEN 9 12I 0 INZ(0)
D* Numeric encoding of bulk data
D RMENC 13 16I 0 INZ(273)
D* Character set identifier of bulkdata
D RMCSI 17 20I 0 INZ(0)
D* Format name of bulk data
D RMFMT 21 28 INZ(' ')
D* Reference message flags
D RMFLG 29 32I 0 INZ(0)
D* Object type
D RMOT 33 40 INZ
D* Object instance identifier
D RMOII 41 64 INZ(X'00000000000000-
D 0000000000000000000000-
D 000000000000')
D* Length of source environmentdata
D RMSEL 65 68I 0 INZ(0)
D* Offset of source environmentdata
D RMSEO 69 72I 0 INZ(0)
D* Length of source object name
D RMSNL 73 76I 0 INZ(0)
D* Offset of source object name
D RMSNO 77 80I 0 INZ(0)
D* Length of destination environmentdata
D RMDEL 81 84I 0 INZ(0)
D* Offset of destination environmentdata
D RMDEO 85 88I 0 INZ(0)
D* Length of destination objectname
D RMDNL 89 92I 0 INZ(0)
D* Offset of destination objectname
D RMDNO 93 96I 0 INZ(0)
D* Length of bulk data
D RMDL 97 100I 0 INZ(0)
D* Low offset of bulk data
D RMDO 101 104I 0 INZ(0)
D* High offset of bulk data
D RMDO2 105 108I 0 INZ(0)