Overview for MQXQH

Availability: All IBM MQ systems and IBM MQ clients.

Purpose: 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 MQXOH must be in the character set given by the CodedCharSetId queue manager attribute and encoding of the local queue manager given by MQENC_NATIVE.

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

Fields in the separate message descriptor: 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.

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

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