MQXQH - Transmission-queue header

The MQXQH structure describes the information that is prefixed to the application message data of messages when they are on transmission queues. 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 MQUS_TRANSMISSION.

Format name

MQFMT_XMIT_Q_HEADER

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 MQENC_NATIVE.

Set the character set and encoding of the MQXQH into the CodedCharSetId and Encoding 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).

Fields

Note: In the following table, the fields are grouped by usage rather than alphabetically. The child topics follow the same sequence.

Table 1. Fields in MQXQH for MQXQH
Field name and description	Name of constant	Initial value (if any) of constant
StrucId (structure identifier)	MQXQH_STRUC_ID	`'XQH¬'`
Version (structure version number)	MQXQH_VERSION_1	`1`
RemoteQName (name of destination queue)	None	Null string or blanks
RemoteQMgrName (name of destination queue manager)	None	Null string or blanks
MsgDesc (original message descriptor)	Same names and values as MQMD; see Table 1	-
Notes: The symbol `¬` represents a single blank character. The value Null string or blanks denotes the null string in C, and blank characters in other programming languages. In the C programming language, the macro variable MQXQH_DEFAULT contains the values that are listed in the table. Use it in the following way to provide initial values for the fields in the structure: `MQXQH MyXQH = {MQXQH_DEFAULT};`

Language declarations

C declaration for MQXQH


typedef struct tagMQXQH MQXQH;
struct tagMQXQH {
  MQCHAR4   StrucId;         /* Structure identifier */
  MQLONG    Version;         /* Structure version number */
  MQCHAR48  RemoteQName;     /* Name of destination queue */
  MQCHAR48  RemoteQMgrName;  /* Name of destination queue manager */
  MQMD1     MsgDesc;         /* Original message descriptor */
};

COBOL declaration for MQXQH


**   MQXQH structure
  10 MQXQH.
**    Structure identifier
   15 MQXQH-STRUCID                  PIC X(4).
**    Structure version number
   15 MQXQH-VERSION                  PIC S9(9) BINARY.
**    Name of destination queue
   15 MQXQH-REMOTEQNAME              PIC X(48).
**    Name of destination queue manager
   15 MQXQH-REMOTEQMGRNAME           PIC X(48).
**    Original message descriptor
   15 MQXQH-MSGDESC.
**     Structure identifier
    20 MQXQH-MSGDESC-STRUCID          PIC X(4).
**     Structure version number
    20 MQXQH-MSGDESC-VERSION          PIC S9(9) BINARY.
**     Report options
    20 MQXQH-MSGDESC-REPORT           PIC S9(9) BINARY.
**     Message type
    20 MQXQH-MSGDESC-MSGTYPE          PIC S9(9) BINARY.
**     Expiry time
    20 MQXQH-MSGDESC-EXPIRY           PIC S9(9) BINARY.
**     Feedback or reason code
    20 MQXQH-MSGDESC-FEEDBACK         PIC S9(9) BINARY.
**     Numeric encoding of message data
    20 MQXQH-MSGDESC-ENCODING         PIC S9(9) BINARY.
**     Character set identifier of message data
    20 MQXQH-MSGDESC-CODEDCHARSETID   PIC S9(9) BINARY.
**     Format name of message data
    20 MQXQH-MSGDESC-FORMAT           PIC X(8).
**     Message priority
    20 MQXQH-MSGDESC-PRIORITY         PIC S9(9) BINARY.
**     Message persistence
    20 MQXQH-MSGDESC-PERSISTENCE      PIC S9(9) BINARY.
**     Message identifier
    20 MQXQH-MSGDESC-MSGID            PIC X(24).
**     Correlation identifier
    20 MQXQH-MSGDESC-CORRELID         PIC X(24).
**     Backout counter
    20 MQXQH-MSGDESC-BACKOUTCOUNT     PIC S9(9) BINARY.
**     Name of reply-to queue
    20 MQXQH-MSGDESC-REPLYTOQ         PIC X(48).
**     Name of reply queue manager
    20 MQXQH-MSGDESC-REPLYTOQMGR      PIC X(48).
**     User identifier
    20 MQXQH-MSGDESC-USERIDENTIFIER   PIC X(12).
**     Accounting token
    20 MQXQH-MSGDESC-ACCOUNTINGTOKEN  PIC X(32).
**     Application data relating to identity
    20 MQXQH-MSGDESC-APPLIDENTITYDATA PIC X(32).
**     Type of application that put the message
    20 MQXQH-MSGDESC-PUTAPPLTYPE      PIC S9(9) BINARY.
**     Name of application that put the message
    20 MQXQH-MSGDESC-PUTAPPLNAME      PIC X(28).
**     Date when message was put
    20 MQXQH-MSGDESC-PUTDATE          PIC X(8).
**     Time when message was put
    20 MQXQH-MSGDESC-PUTTIME          PIC X(8).
**     Application data relating to origin
    20 MQXQH-MSGDESC-APPLORIGINDATA   PIC X(4).

PL/I declaration for MQXQH


dcl
 1 MQXQH based,
  3 StrucId           char(4),       /* Structure identifier */
  3 Version           fixed bin(31), /* Structure version number */
  3 RemoteQName       char(48),      /* Name of destination queue */
  3 RemoteQMgrName    char(48),      /* Name of destination queue
                                        manager */
  3 MsgDesc,                         /* Original message descriptor */
   5 StrucId          char(4),       /* Structure identifier */
   5 Version          fixed bin(31), /* Structure version number */
   5 Report           fixed bin(31), /* Report options */
   5 MsgType          fixed bin(31), /* Message type */
   5 Expiry           fixed bin(31), /* Expiry time */
   5 Feedback         fixed bin(31), /* Feedback or reason code */
   5 Encoding         fixed bin(31), /* Numeric encoding of message
                                        data */
   5 CodedCharSetId   fixed bin(31), /* Character set identifier of
                                        message data */
   5 Format           char(8),       /* Format name of message data */
   5 Priority         fixed bin(31), /* Message priority */
   5 Persistence      fixed bin(31), /* Message persistence */
   5 MsgId            char(24),      /* Message identifier */
   5 CorrelId         char(24),      /* Correlation identifier */
   5 BackoutCount     fixed bin(31), /* Backout counter */
   5 ReplyToQ         char(48),      /* Name of reply-to queue */
   5 ReplyToQMgr      char(48),      /* Name of reply queue manager */
   5 UserIdentifier   char(12),      /* User identifier */
   5 AccountingToken  char(32),      /* Accounting token */
   5 ApplIdentityData char(32),      /* Application data relating to
                                        identity */
   5 PutApplType      fixed bin(31), /* Type of application that put the
                                        message */
   5 PutApplName      char(28),      /* Name of application that put the
                                        message */
   5 PutDate          char(8),       /* Date when message was put */
   5 PutTime          char(8),       /* Time when message was put */
   5 ApplOriginData   char(4);       /* Application data relating to
                                        origin */

High Level Assembler declaration for MQXQH


MQXQH                           DSECT
MQXQH_STRUCID                   DS   CL4   Structure identifier
MQXQH_VERSION                   DS   F     Structure version number
MQXQH_REMOTEQNAME               DS   CL48  Name of destination queue
MQXQH_REMOTEQMGRNAME            DS   CL48  Name of destination queue
*                                          manager
MQXQH_MSGDESC                   DS   0F    Force fullword alignment
MQXQH_MSGDESC_STRUCID           DS   CL4   Structure identifier
MQXQH_MSGDESC_VERSION           DS   F     Structure version number
MQXQH_MSGDESC_REPORT            DS   F     Report options
MQXQH_MSGDESC_MSGTYPE           DS   F     Message type
MQXQH_MSGDESC_EXPIRY            DS   F     Expiry time
MQXQH_MSGDESC_FEEDBACK          DS   F     Feedback or reason code
MQXQH_MSGDESC_ENCODING          DS   F     Numeric encoding of message
*                                          data
MQXQH_MSGDESC_CODEDCHARSETID    DS   F     Character set identifier of
*                                          message data
MQXQH_MSGDESC_FORMAT            DS   CL8   Format name of message data
MQXQH_MSGDESC_PRIORITY          DS   F     Message priority
MQXQH_MSGDESC_PERSISTENCE       DS   F     Message persistence
MQXQH_MSGDESC_MSGID             DS   XL24  Message identifier
MQXQH_MSGDESC_CORRELID          DS   XL24  Correlation identifier
MQXQH_MSGDESC_BACKOUTCOUNT      DS   F     Backout counter
MQXQH_MSGDESC_REPLYTOQ          DS   CL48  Name of reply-to queue
MQXQH_MSGDESC_REPLYTOQMGR       DS   CL48  Name of reply queue manager
MQXQH_MSGDESC_USERIDENTIFIER    DS   CL12  User identifier
MQXQH_MSGDESC_ACCOUNTINGTOKEN   DS   XL32  Accounting token
MQXQH_MSGDESC_APPLIDENTITYDATA  DS   CL32  Application data relating to
*                                          identity
MQXQH_MSGDESC_PUTAPPLTYPE       DS   F     Type of application that put
*                                          the message
MQXQH_MSGDESC_PUTAPPLNAME       DS   CL28  Name of application that put
*                                          the message
MQXQH_MSGDESC_PUTDATE           DS   CL8   Date when message was put
MQXQH_MSGDESC_PUTTIME           DS   CL8   Time when message was put
MQXQH_MSGDESC_APPLORIGINDATA    DS   CL4   Application data relating to
*                                          origin
MQXQH_MSGDESC_LENGTH            EQU  *-MQXQH_MSGDESC
                                ORG  MQXQH_MSGDESC
MQXQH_MSGDESC_AREA              DS   CL(MQXQH_MSGDESC_LENGTH)
*
MQXQH_LENGTH                    EQU  *-MQXQH
                                ORG  MQXQH
MQXQH_AREA                      DS   CL(MQXQH_LENGTH)

Visual Basic declaration for MQXQH


Type MQXQH
  StrucId        As String*4  'Structure identifier'
  Version        As Long      'Structure version number'
  RemoteQName    As String*48 'Name of destination queue'
  RemoteQMgrName As String*48 'Name of destination queue manager'
  MsgDesc        As MQMD1     'Original message descriptor'
End Type

Fields in the separate message descriptor

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 MsgDesc 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 MsgDesc parameter of the MQGET call when the message is removed from the final destination queue.

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

Table 2. Values used for fields in the separate MQMD
Field in separate MQMD	Value used
`StrucId`	MQMD_STRUC_ID
`Version`	MQMD_VERSION_2
`Report`	Copied from the embedded message descriptor, but with the bits identified by MQRO_ACCEPT_UNSUP_IF_XMIT_MASK 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.)
`MsgType`	Copied from the embedded message descriptor.
`Expiry`	Copied from the embedded message descriptor.
`Feedback`	Copied from the embedded message descriptor.
`Encoding`	MQENC_NATIVE (see note)
`CodedCharSetId`	Queue manager's CodedCharSetId attribute.
`Format`	MQFMT_XMIT_Q_HEADER
`Priority`	Copied from the embedded message descriptor.
`Persistence`	Copied from the embedded message descriptor.
`MsgId`	A new value is generated by the queue manager. This message identifier is different from the `MsgId` that the queue manager may have generated for the embedded message descriptor described previously.
`CorrelId`	The `MsgId` from the embedded message descriptor. For messages being put to the SYSTEM.CLUSTER.TRANSMIT.QUEUE, `CorrelId` is reserved for internal use.
`BackoutCount`	0
`ReplyToQ`	Copied from the embedded message descriptor.
`ReplyToQMgr`	Copied from the embedded message descriptor.
`UserIdentifier`	Copied from the embedded message descriptor.
`AccountingToken`	Copied from the embedded message descriptor. For messages being put to the SYSTEM.CLUSTER.TRANSMIT.QUEUE, `AccountingToken` is reserved for internal use.
`ApplIdentityData`	Copied from the embedded message descriptor.
`PutApplType`	MQAT_QMGR
`PutApplName`	First 28 bytes of the queue manager name.
`PutDate`	Date when message was put on transmission queue.
`PutTime`	Time when message was put on transmission queue.
`ApplOriginData`	Blanks
`GroupId`	MQGI_NONE
`MsgSeqNumber`	1
`Offset`	0
`MsgFlags`	MQMF_NONE
`OriginalLength`	MQOL_UNDEFINED

On Windows, the value of MQENC_NATIVE for Micro Focus COBOL differs from the value for C. The value in the Encoding field in the separate message descriptor is always the value for C in these environments; this value is 546 in decimal. Also, the integer fields in the MQXQH structure are in the encoding that corresponds to this value (the native Intel encoding).

Fields in the embedded message descriptor

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

The Version field always has the value MQMD_VERSION_1.
If the Priority field has the value MQPRI_PRIORITY_AS_Q_DEF, it is replaced by the value of the queue's DefPriority attribute.
If the Persistence field has the value MQPER_PERSISTENCE_AS_Q_DEF, it is replaced by the value of the queue's DefPersistence attribute.
If the MsgId field has the value MQMI_NONE, or the MQPMO_NEW_MSG_ID option was specified, or the message is a distribution-list message, MsgId 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 MsgId field in each of the new embedded message descriptors is the same as that in the original distribution-list message.
If the MQPMO_NEW_CORREL_ID option was specified, CorrelId is replaced by a new correlation identifier generated by the queue manager.
The context fields are set as indicated by the MQPMO_*_CONTEXT options specified in the PutMsgOpts parameter; the context fields are:
- AccountingToken
- ApplIdentityData
- ApplOriginData
- PutApplName
- PutApplType
- PutDate
- PutTime
- UserIdentifier
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.

Putting 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

Putting messages directly on transmission queues

An application can also 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 Format field in the MsgDesc parameter of the MQPUT or MQPUT1 call must have the value MQFMT_XMIT_Q_HEADER.

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.

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

Applications should not put their messages directly to the SYSTEM.CLUSTER.TRANSMIT.QUEUE.

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 MQFMT_XMIT_Q_HEADER being returned in the Format field in the MsgDesc parameter of the MQGET call. The values returned in the CodedCharSetId and Encoding fields in the MsgDesc parameter indicate 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 CodedCharSetId and Encoding fields in the embedded message descriptor.