MQDH (Distribution header) on IBM i

The MQDH structure describes the additional data that is present in a message when that message is a distribution-list message stored on a transmission queue.

Overview

Purpose: A distribution-list message is a message that is sent to multiple destination queues. The additional data consists of the MQDH structure followed by an array of MQOR records and an array of MQPMR records.

This structure is for use by specialized applications that put messages directly on transmission queues, or which remove messages from transmission queues (for example: message channel agents).

This structure should not be used by normal applications which simply want to put messages to distribution lists. Those applications should use the MQOD structure to define the destinations in the distribution list, and the MQPMO structure to specify message properties or receive information about the messages sent to the individual destinations.

Character set and encoding: Data in MQDH must be in the character set given by the CodedCharSetId queue manager attribute and encoding of the local queue manager given by ENNAT for the C programming language.

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

Usage: When an application puts a message to a distribution list, and some or all of the destinations are remote, the queue manager prefixes the application message data with the MQXQH and MQDH structures, and places the message on the relevant transmission queue. The data therefore occurs in the following sequence when the message is on a transmission queue:

• MQXQH structure
• MQDH structure plus arrays of MQOR and MQPMR records
• Application message data

Depending on the destinations, more than one such message might be generated by the queue manager, and placed on different transmission queues. In this case, the MQDH structures in those messages identify different subsets of the destinations defined by the distribution list opened by the application.

An application that puts a distribution-list message directly on a transmission queue must conform to the sequence described previously, and must ensure that the MQDH structure is correct. If the MQDH structure is not valid, the queue manager may choose to fail the MQPUT or MQPUT1 call with reason code RC2135.

Messages can be stored on a queue in distribution-list form only if the queue is defined as being able to support distribution list messages (see the DistLists queue attribute described in Attributes for queues ). If an application puts a distribution-list message directly on a queue that does not support distribution lists, the queue manager splits the distribution list message into individual messages, and places those on the queue instead.

• Fields
• Initial values
• RPG declaration

Fields

The MQDH structure contains the following fields; the fields are described in alphabetical order:

DHCNT (10-digit signed integer)

Number of MQOR records present.

This defines the number of destinations. A distribution list must always contain at least one destination, so DHCNT must always be greater than zero.

The initial value of this field is 0.

DHCSI (10-digit signed integer)

Character set identifier of data that follows the MQOR and MQPMR records.

This specifies the character set identifier of the data that follows the arrays of MQOR and MQPMR records; it does not apply to character data in the MQDH 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.

DHENC (10-digit signed integer)

Numeric encoding of data that follows the MQOR and MQPMR records.

This specifies the numeric encoding of the data that follows the arrays of MQOR and MQPMR records; it does not apply to numeric data in the MQDH 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 0.

DHFLG (10-digit signed integer)

General flags.

The following flag can be specified:

DHFNEW

Generate new message identifiers.

This flag indicates that a new message identifier is to be generated for each destination in the distribution list. This can be set only when there are no put-message records present, or when the records are present but they do not contain the PRMID field.

Use this flag defers generation of the message identifiers until the last possible moment, namely the moment when the distribution-list message is finally split into individual messages. This minimizes the amount of control information that must flow with the distribution-list message.

When an application puts a message to a distribution list, the queue manager sets DHFNEW in the MQDH it generates when both of the following statements are true:

• There are no put-message records provided by the application, or the records provided do not contain the PRMID field.
• The MDMID field in MQMD is MINONE, or the PMOPT field in MQPMO includes PMNMID

If no flags are needed, the following can be specified:

DHFNON

No flags.

This constant indicates that no flags have been specified. DHFNON is defined to aid program documentation. It is not intended that this constant is used with any other, but as its value is zero, such use cannot be detected.

The initial value of this field is DHFNON.

DHFMT (8-byte character string)

Format name of data that follows the MQOR and MQPMR records.

This specifies the format name of the data that follows the arrays of MQOD and MQPMR records (whichever occurs last).

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.

DHLEN (10-digit signed integer)

Length of MQDH structure plus following MQOR and MQPMR records.

This is the number of bytes from the start of the MQDH structure to the start of the message data following the arrays of MQOR and MQPMR records. The data occurs in the following sequence:

• MQDH structure
• Array of MQOR records
• Array of MQPMR records
• Message data

The arrays of MQOR and MQPMR records are addressed by offsets contained within the MQDH structure. If these offsets result in unused bytes between one or more of the MQDH structure, the arrays of records, and the message data, those unused bytes must be included in the value of DHLEN, but the content of those bytes is not preserved by the queue manager. It is valid for the array of MQPMR records to precede the array of MQOR records.

The initial value of this field is 0.

DHORO (10-digit signed integer)

Offset of first MQOR record from start of MQDH.

This field gives the offset in bytes of the first record in the array of MQOR object records containing the names of the destination queues. There are DHCNT records in this array. These records (plus any bytes skipped between the first object record and the previous field) are included in the length given by the DHLEN field.

A distribution list must always contain at least one destination, so DHORO must always be greater than zero.

The initial value of this field is 0.

DHPRF (10-digit signed integer)

Flags indicating which MQPMR fields are present.

Zero or more of the following flags can be specified:

PFMID

Message-identifier field is present.

PFCID

Correlation-identifier field is present.

PFGID

Group-identifier field is present.

PFFB

Feedback field is present.

PFACC

Accounting-token field is present.

If no MQPMR fields are present, the following can be specified:

PFNONE

No put-message record fields are present.

PFNONE is defined to aid program documentation. It is not intended that this constant be used with any other, but as its value is zero, such use cannot be detected.

The initial value of this field is PFNONE.

DHPRO (10-digit signed integer)

Offset of first MQPMR record from start of MQDH.

This field gives the offset in bytes of the first record in the array of MQPMR put message records containing the message properties. If present, there are DHCNT records in this array. These records (plus any bytes skipped between the first put message record and the previous field) are included in the length given by the DHLEN field.

Put message records are optional; if no records are provided, DHPRO is zero, and DHPRF has the value PFNONE.

The initial value of this field is 0.

DHSID (4-byte character string)

Structure identifier.

The value must be:

DHSIDV

Identifier for distribution header structure.

The initial value of this field is DHSIDV.

DHVER (10-digit signed integer)

Structure version number.

The value must be:

DHVER1

Version number for distribution header structure.

The following constant specifies the version number of the current version:

DHVERC

Current version of distribution header structure.

The initial value of this field is DHVER1.

Initial values

1. The symbol ¬ represents a single blank character.

RPG declaration

     D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     D* MQDH Structure
     D*
     D* Structure identifier
     D  DHSID                  1      4    INZ('DH  ')
     D* Structure version number
     D  DHVER                  5      8I 0 INZ(1)
     D* Length of MQDH structure plusfollowing MQOR and MQPMR records
     D  DHLEN                  9     12I 0 INZ(0)
     D* Numeric encoding of data that followsthe MQOR and MQPMR records
     D  DHENC                 13     16I 0 INZ(0)
     D* Character set identifier of data thatfollows the MQOR and MQPMR
     D* records
     D  DHCSI                 17     20I 0 INZ(0)
     D* Format name of data that follows theMQOR and MQPMR records
     D  DHFMT                 21     28    INZ('        ')
     D* General flags
     D  DHFLG                 29     32I 0 INZ(0)
     D* Flags indicating which MQPMR fieldsare present
     D  DHPRF                 33     36I 0 INZ(0)
     D* Number of MQOR records present
     D  DHCNT                 37     40I 0 INZ(0)
     D* Offset of first MQOR record from startof MQDH
     D  DHORO                 41     44I 0 INZ(0)
     D* Offset of first MQPMR record fromstart of MQDH
     D  DHPRO                 45     48I 0 INZ(0)