MQDLH - 死信头

MQDLH 结构描述了以死信 (undelid-message) 队列上的消息的应用程序消息数据为前缀的信息。消息可以到达死信队列，原因是队列管理器或消息通道代理已将其重定向到队列，或者应用程序将消息直接放在队列上。

格式名称

MQFMT_DEAD_LETTER_HEADER

字符集和编码

MQDLH 结构中的字段采用 CodedCharSetId 和 Encoding 字段提供的字符集和编码。这些在 MQDLH 之前的头结构中指定，或者在 MQMD 结构中指定 (如果 MQDLH 位于应用程序消息数据的开头)。

字符集必须是对队列名称中有效的字符具有单字节字符的字符集。

如果您将 "IBM® MQ类用于 "Java/JMS，而 "Java虚拟机不支持 MQMD 中定义的代码页，那么 MQDLH 将以UTF-8字符集编写。

用法

将消息直接放在死信队列上的应用程序必须以 MQDLH 结构作为消息数据的前缀，并使用相应的值初始化字段。但是，队列管理器不要求 MQDLH 结构存在，也不要求为字段指定有效值。

如果消息太长而无法放入死信队列，那么应用程序必须执行下列其中一项操作:

截断消息数据以适应死信队列。
将消息记录在辅助存储器上，并将异常报告消息放置在指示此情况的死信队列上。
废弃消息并向其发起方返回错误。如果消息是 (或可能是) 关键消息，那么仅当已知发起方仍具有消息副本时才执行此操作; 例如，消息通道代理程序从通信通道接收的消息。

上述哪些操作是适当的 (如果有) 取决于应用程序的设计。

当作为段的消息在前面放置 MQDLH 结构时，队列管理器将执行特殊处理; 请参阅 MQMDE 结构的描述以获取更多详细信息。

将消息放入死信队列

将消息放入死信队列时，用于 MQPUT 或 MQPUT1 调用的 MQMD 结构必须与与消息关联的 MQMD (通常是 MQGET 调用返回的 MQMD) 相同，但以下内容除外:

将 CodedCharSetId 和 Encoding 字段设置为用于 MQDLH 结构中的字段的任何字符集和编码。
将 Format 字段设置为 MQFMT_DEAD_LETTER_HEADER ，以指示数据以 MQDLH 结构开头。
使用适合于以下情况的上下文选项来设置上下文字段 (AccountingToken， ApplIdentityData， ApplOriginData， PutApplName， PutApplType， PutDate， PutTime和 UserIdentifier):
- 将不与任何先前消息相关的消息放入死信队列的应用程序必须使用 MQPMO_DEFAULT_CONTEXT 选项; 这会导致队列管理器将消息描述符中的所有上下文字段设置为其缺省值。
- 将刚收到的消息放入死信队列的服务器应用程序必须使用 MQPMO_PASS_ALL_CONTEXT 选项来保留原始上下文信息。
- 将应答放入死信队列的服务器应用程序必须使用 MQPMO_PASS_IDENTITY_CONTEXT 选项; 这将保留身份信息，但将源信息设置为服务器应用程序的源信息。
- 消息通道代理程序将从其通信通道接收到的消息放入死信队列中，必须使用 MQPMO_SET_ALL_CONTEXT 选项来保留原始上下文信息。

在 MQDLH 结构本身中，按如下所示设置字段:

将 CodedCharSetId， Encoding和 Format 字段设置为描述 MQDLH 结构后的数据的值，通常是原始消息描述符中的值。
将上下文字段 PutApplType， PutApplName， PutDate和 PutTime 设置为适合于将消息放入死信队列的应用程序的值; 这些值与原始消息无关。
根据需要设置其他字段。

确保所有字段都具有有效值，并且字符字段用空白填充到定义的字段长度; 不要使用空字符过早结束字符数据，因为队列管理器不会将空字符和后续字符转换为 MQDLH 结构中的空白。

从死信队列获取消息

从死信队列获取消息的应用程序必须验证消息是否以 MQDLH 结构开头。应用程序可以通过检查消息描述符 MQMD 中的 Format 字段来确定是否存在 MQDLH 结构; 如果该字段的值为 MQFMT_DEAD_LETTER_HEADER ，那么消息数据以 MQDLH 结构开头。还请注意，如果应用程序从死信队列中获取的消息最初对于队列太长，那么可能会截断这些消息。

字段

请注意：在下表中，字段按用途分组，而不是按字母顺序排列。

表 1. MQDLH 中的字段
字段名称和描述	常量的名称	常量的初始值 (如果有)
StrucId （结构标识符）	MQDLH_结构ID	`'DLH¬'`
版本（结构版本号）	MQDLH_VERSION_1	`1`
原因（信息到达死信队列的原因）	MQRC_NONE	`0`
DestQName （原始目标队列的名称）	None	空字符串或空白
DestQMgrName （原始目标队列管理器的名称）	None	空字符串或空白
编码（遵循 MQDLH 的数据数字编码）	None	`0`
CodedCharSetId（MQDLH 之后数据的字符集标识符）	mqccsi_undefined	`0`
格式（MQDLH 之后的数据格式名称）	MQFMT_NONE	空白
PutApplType（将消息放入死信队列的应用程序类型）	None	`0`
PutApplName （将信息放入死信队列的应用程序名称）	None	空字符串或空白
PutDate（将信息放入死信队列的日期）	None	空字符串或空白
PutTime（信息进入死信队列的时间）	None	空字符串或空白
注：符号 `¬` 表示单个空白字符。值 Null 字符串或空白表示 C 中的空字符串，而空白字符表示其他编程语言中的空字符。在 C 编程语言中，宏变量 MQDLH_DEFAULT 包含表中列出的值。通过以下方式使用它来为结构中的字段提供初始值: `MQDLH MyDLH = {MQDLH_DEFAULT};`

语言声明

MQDLH 的 C 声明

typedef struct tagMQDLH MQDLH;
struct tagMQDLH {
  MQCHAR4   StrucId;         /* Structure identifier */
  MQLONG    Version;         /* Structure version number */
  MQLONG    Reason;          /* Reason message arrived on dead-letter
                                (undelivered-message) queue */
  MQCHAR48  DestQName;       /* Name of original destination queue */
  MQCHAR48  DestQMgrName;    /* Name of original destination queue
                                manager */
  MQLONG    Encoding;        /* Numeric encoding of data that follows
                                MQDLH */
  MQLONG    CodedCharSetId;  /* Character set identifier of data that
                                follows MQDLH */
  MQCHAR8   Format;          /* Format name of data that follows
                                MQDLH */
  MQLONG    PutApplType;     /* Type of application that put message on
                                dead-letter (undelivered-message)
                                queue */
  MQCHAR28  PutApplName;     /* Name of application that put message on
                                dead-letter (undelivered-message)
                                queue */
  MQCHAR8   PutDate;         /* Date when message was put on dead-letter
                                (undelivered-message) queue */
  MQCHAR8   PutTime;         /* Time when message was put on the
                                dead-letter (undelivered-message)
                                queue */
};

COBOL MQDLH 的声明

**   MQDLH structure
  10 MQDLH.
**    Structure identifier
   15 MQDLH-STRUCID        PIC X(4).
**    Structure version number
   15 MQDLH-VERSION        PIC S9(9) BINARY.
**    Reason message arrived on dead-letter (undelivered-message) queue
   15 MQDLH-REASON         PIC S9(9) BINARY.
**    Name of original destination queue
   15 MQDLH-DESTQNAME      PIC X(48).
**    Name of original destination queue manager
   15 MQDLH-DESTQMGRNAME   PIC X(48).
**    Numeric encoding of data that follows MQDLH
   15 MQDLH-ENCODING       PIC S9(9) BINARY.
**    Character set identifier of data that follows MQDLH
   15 MQDLH-CODEDCHARSETID PIC S9(9) BINARY.
**    Format name of data that follows MQDLH
   15 MQDLH-FORMAT         PIC X(8).
**    Type of application that put message on dead-letter
**    (undelivered-message) queue
   15 MQDLH-PUTAPPLTYPE    PIC S9(9) BINARY.
**    Name of application that put message on dead-letter
**    (undelivered-message) queue
   15 MQDLH-PUTAPPLNAME    PIC X(28).
**    Date when message was put on dead-letter (undelivered-message)
**    queue
   15 MQDLH-PUTDATE        PIC X(8).
**    Time when message was put on the dead-letter (undelivered-message)
**    queue
   15 MQDLH-PUTTIME        PIC X(8).

PL/I MQDLH 的声明

dcl
 1 MQDLH based,
  3 StrucId        char(4),       /* Structure identifier */
  3 Version        fixed bin(31), /* Structure version number */
  3 Reason         fixed bin(31), /* Reason message arrived on
                                     dead-letter (undelivered-message)
                                     queue */
  3 DestQName      char(48),      /* Name of original destination
                                     queue */
  3 DestQMgrName   char(48),      /* Name of original destination queue
                                     manager */
  3 Encoding       fixed bin(31), /* Numeric encoding of data that
                                     follows MQDLH */
  3 CodedCharSetId fixed bin(31), /* Character set identifier of data
                                     that follows MQDLH */
  3 Format         char(8),       /* Format name of data that follows
                                     MQDLH */
  3 PutApplType    fixed bin(31), /* Type of application that put
                                     message on dead-letter
                                     (undelivered-message) queue */
  3 PutApplName    char(28),      /* Name of application that put
                                     message on dead-letter
                                     (undelivered-message) queue */
  3 PutDate        char(8),       /* Date when message was put on
                                     dead-letter (undelivered-message)
                                     queue */
  3 PutTime        char(8);       /* Time when message was put on the
                                     dead-letter (undelivered-message)
                                     queue */

MQDLH 的 High Level Assembler 声明

MQDLH                 DSECT
MQDLH_STRUCID         DS   CL4   Structure identifier
MQDLH_VERSION         DS   F     Structure version number
MQDLH_REASON          DS   F     Reason message arrived on dead-letter
*                                (undelivered-message) queue
MQDLH_DESTQNAME       DS   CL48  Name of original destination queue
MQDLH_DESTQMGRNAME    DS   CL48  Name of original destination queue
*                                manager
MQDLH_ENCODING        DS   F     Numeric encoding of data that follows
*                                MQDLH
MQDLH_CODEDCHARSETID  DS   F     Character set identifier of data that
*                                follows MQDLH
MQDLH_FORMAT          DS   CL8   Format name of data that follows MQDLH
MQDLH_PUTAPPLTYPE     DS   F     Type of application that put message on
*                                dead-letter (undelivered-message) queue
MQDLH_PUTAPPLNAME     DS   CL28  Name of application that put message on
*                                dead-letter (undelivered-message) queue
MQDLH_PUTDATE         DS   CL8   Date when message was put on
*                                dead-letter (undelivered-message) queue
MQDLH_PUTTIME         DS   CL8   Time when message was put on the
*                                dead-letter (undelivered-message) queue
*
MQDLH_LENGTH          EQU  *-MQDLH
                      ORG  MQDLH
MQDLH_AREA            DS   CL(MQDLH_LENGTH)

MQDLH 的 Visual Basic 声明

Type MQDLH
  StrucId        As String*4  'Structure identifier'
  Version        As Long      'Structure version number'
  Reason         As Long      'Reason message arrived on dead-letter'
                              '(undelivered-message) queue'
  DestQName      As String*48 'Name of original destination queue'
  DestQMgrName   As String*48 'Name of original destination queue'
                              'manager'
  Encoding       As Long      'Numeric encoding of data that follows'
                              'MQDLH'
  CodedCharSetId As Long      'Character set identifier of data that'
                              'follows MQDLH'
  Format         As String*8  'Format name of data that follows MQDLH'
  PutApplType    As Long      'Type of application that put message on'
                              'dead-letter (undelivered-message) queue'
  PutApplName    As String*28 'Name of application that put message on'
                              'dead-letter (undelivered-message) queue'
  PutDate        As String*8  'Date when message was put on dead-letter'
                              '(undelivered-message) queue'
  PutTime        As String*8  'Time when message was put on the'
                              'dead-letter (undelivered-message) queue'
End Type