MQXQH (Transmission-queue header) on IBM i

The MQXQH structure describes the information that is prefixed to the application message data of messages when they are on transmission queues.


Overview

Purpose: A transmission queue is a special type of local queue that temporarily holds messages destined for remote queues (that is, destined for queues that do not belong to the local queue manager). A transmission queue is denoted by the Usage queue attribute having the value USTRAN.

Format name: FMXQH.

Character set and encoding: Data in MQXQH 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 character set and encoding of the MQXQH must be set into the MDCSI and MDENC fields in:

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

Usage: A message that is on a transmission queue has two message descriptors:

  • One message descriptor is stored separately from the message data; this is called the separate message descriptor, and is generated by the queue manager when the message is placed on the transmission queue. Some of the fields in the separate message descriptor are copied from the message descriptor provided by the application on the MQPUT or MQPUT1 call.

    The separate message descriptor is the one that is returned to the application in the MSGDSC parameter of the MQGET call when the message is removed from the transmission queue.

  • A second message descriptor is stored within the MQXQH structure as part of the message data; this is called the embedded message descriptor, and is a copy of the message descriptor that was provided by the application on the MQPUT or MQPUT1 call (with minor variations). The embedded message descriptor is always a version-1 MQMD. If the message put by the application has nondefault values for one or more of the version-2 fields in the MQMD, an MQMDE structure follows the MQXQH, and is in turn followed by the application message data (if any). The MQMDE is either:

    • Generated by the queue manager (if the application uses a version-2 MQMD to put the message), or
    • Already present at the start of the application message data (if the application uses a version-1 MQMD to put the message).

    The embedded message descriptor is the one that is returned to the application in the MSGDSC parameter of the MQGET call when the message is removed from the final destination queue.


Fields in the separate message descriptor

The fields in the separate message descriptor are set by the queue manager as shown in the following list. If the queue manager does not support the version-2 MQMD, a version-1 MQMD is used without loss of function.

Field in separate MQMD Value used
MDSID MDSIDV
MDVER MDVER2
MDREP Copied from the embedded message descriptor, but with the bits identified by ROAUXM set to zero. (This prevents a COA or COD report message being generated when a message is placed on or removed from a transmission queue.)
MDMT Copied from the embedded message descriptor.
MDEXP Copied from the embedded message descriptor.
MDFB Copied from the embedded message descriptor.
MDENC ENNAT
MDCSI Queue manager's CodedCharSetId attribute.
MDFMT FMXQH
MDPRI Copied from the embedded message descriptor.
MDPER Copied from the embedded message descriptor.
MDMID A new value is generated by the queue manager. This message identifier is different from the MDMID that the queue manager may have generated for the embedded message descriptor (see described previously).
MDCID The MDMID from the embedded message descriptor.
MDBOC 0
MDRQ Copied from the embedded message descriptor.
MDRM Copied from the embedded message descriptor.
MDUID Copied from the embedded message descriptor.
MDACC Copied from the embedded message descriptor.
MDAID Copied from the embedded message descriptor.
MDPAT ATQM
MDPAN First 28 bytes of the queue manager name.
MDPD Date when message was put on transmission queue.
MDPT Time when message was put on transmission queue.
MDAOD Blanks
MDGID GINONE
MDSEQ 1
MDOFF 0
MDMFL MFNONE
MDOLN OLUNDF


Fields in the embedded message descriptor

The fields in the embedded message descriptor have the same values as those in the MSGDSC parameter of the MQPUT or MQPUT1 call, except for the following:

  • The MDVER field always has the value MDVER1.
  • If the MDPRI field has the value PRQDEF, it is replaced by the value of the queue's DefPriority attribute.
  • If the MDPER field has the value PEQDEF, it is replaced by the value of the queue's DefPersistence attribute.
  • If the MDMID field has the value MINONE, or the PMNMID option was specified, or the message is a distribution-list message, MDMID is replaced by a new message identifier generated by the queue manager.

    When a distribution-list message is split into smaller distribution-list messages placed on different transmission queues, the MDMID field in each of the new embedded message descriptors is the same as that in the original distribution-list message.

  • If the PMNCID option was specified, MDCID is replaced by a new correlation identifier generated by the queue manager.
  • The context fields are set as indicated by the PM* options specified in the PMO parameter; the context fields are:

    • MDACC
    • MDAID
    • MDAOD
    • MDPAN
    • MDPAT
    • MDPD
    • MDPT
    • MDUID

  • The version-2 fields (if they were present) are removed from the MQMD, and moved into an MQMDE structure, if one or more of the version-2 fields has a nondefault value.


Put messages on remote queues

: When an application puts a message on a remote queue (either by specifying the name of the remote queue directly, or by using a local definition of the remote queue), the local queue manager:

  • Creates an MQXQH structure containing the embedded message descriptor
  • Appends an MQMDE if one is needed and is not already present
  • Appends the application message data
  • Places the message on an appropriate transmission queue


Put messages directly on transmission queues

It is also possible for an application to put a message directly on a transmission queue. In this case the application must prefix the application message data with an MQXQH structure, and initialize the fields with appropriate values. In addition, the MDFMT field in the MSGDSC parameter of the MQPUT or MQPUT1 call must have the value FMXQH.

Character data in the MQXQH structure created by the application must be in the character set of the local queue manager (defined by the CodedCharSetId queue manager attribute), and integer data must be in the native machine encoding. In addition, character data in the MQXQH structure must be padded with blanks to the defined length of the field; the data must not be ended prematurely by using a null character, because the queue manager does not convert the null and subsequent characters to blanks in the MQXQH structure.

Note however that the queue manager does not check that an MQXQH structure is present, or that valid values have been specified for the fields.


Getting messages from transmission queues

Applications that get messages from a transmission queue must process the information in the MQXQH structure in an appropriate fashion. The presence of the MQXQH structure at the beginning of the application message data is indicated by the value FMXQH being returned in the MDFMT field in the MSGDSC parameter of the MQGET call. The values returned in the MDCSI and MDENC fields in the MSGDSC parameter, indicates the character set and encoding of the character and integer data in the MQXQH structure. The character set and encoding of the application message data are defined by the MDCSI and MDENC fields in the embedded message descriptor.


Fields

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

    XQMD (MQMD1)

    Original message descriptor.

    This is the embedded message descriptor, and is a close copy of the message descriptor MQMD that was specified as the MSGDSC parameter on the MQPUT or MQPUT1 call when the message was originally put to the remote queue.

    Note: This is a version-1 MQMD.

    The initial values of the fields in this structure are the same as those in the MQMD structure.

    XQRQ (48-byte character string)

    Name of destination queue.

    This is the name of the message queue that is the apparent eventual destination for the message (this may prove not to be the actual eventual destination if, for example, this queue is defined at XQRQM to be a local definition of another remote queue).

    If the message is a distribution-list message (that is, the MDFMT field in the embedded message descriptor is FMDH), XQRQ is blank.

    The length of this field is given by LNQN. The initial value of this field is 48 blank characters.

    XQRQM (48-byte character string)

    Name of destination queue manager.

    This is the name of the queue manager or queue sharing group that owns the queue that is the apparent eventual destination for the message.

    If the message is a distribution-list message, XQRQM is blank.

    The length of this field is given by LNQMN. The initial value of this field is 48 blank characters.

    XQSID (4-byte character string)

    Structure identifier.

    The value must be:

      XQSIDV
      Identifier for transmission-queue header structure.

    The initial value of this field is XQSIDV.

    XQVER (10-digit signed integer)

    Structure version number.

    The value must be:

      XQVER1
      Version number for transmission-queue header structure.

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

      XQVERC
      Current version of transmission-queue header structure.

    The initial value of this field is XQVER1.


Initial values

Field name Name of constant Value of constant
XQSID XQSIDV 'XQH¬'
XQVER XQVER1 1
XQRQ None Blanks
XQRQM None Blanks
XQMD Same names and values as MQMD; see Table 2 -
Notes:
  1. The symbol ¬ represents a single blank character.


RPG declaration

     D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     D*
     D* MQXQH Structure
     D*
     D* Structure identifier
     D  XQSID                  1      4    INZ('XQH ')
     D* Structure version number
     D  XQVER                  5      8I 0 INZ(1)
     D* Name of destination queue
     D  XQRQ                   9     56    INZ
     D* Name of destination queue manager
     D  XQRQM                 57    104    INZ
     D* Original message descriptor
     D  XQ1SID               105    108    INZ('MD  ')
     D  XQ1VER               109    112I 0 INZ(1)
     D  XQ1REP               113    116I 0 INZ(0)
     D  XQ1MT                117    120I 0 INZ(8)
     D  XQ1EXP               121    124I 0 INZ(-1)
     D  XQ1FB                125    128I 0 INZ(0)
     D  XQ1ENC               129    132I 0 INZ(273)
     D  XQ1CSI               133    136I 0 INZ(0)
     D  XQ1FMT               137    144    INZ('        ')
     D  XQ1PRI               145    148I 0 INZ(-1)
     D  XQ1PER               149    152I 0 INZ(2)
     D  XQ1MID               153    176    INZ(X'00000000000000-
     D                                     0000000000000000000000-
     D                                     000000000000')
     D  XQ1CID               177    200    INZ(X'00000000000000-
     D                                     0000000000000000000000-
     D                                     000000000000')
     D  XQ1BOC               201    204I 0 INZ(0)
     D  XQ1RQ                205    252    INZ
     D  XQ1RM                253    300    INZ
     D  XQ1UID               301    312    INZ
     D  XQ1ACC               313    344    INZ(X'00000000000000-
     D                                     0000000000000000000000-
     D                                     0000000000000000000000-
     D                                     000000')
     D  XQ1AID               345    376    INZ
     D  XQ1PAT               377    380I 0 INZ(0)
     D  XQ1PAN               381    408    INZ
     D  XQ1PD                409    416    INZ
     D  XQ1PT                417    424    INZ
     D  XQ1AOD               425    428    INZ
Parent topic: Data type descriptions on IBM i