MQMHBUF-将消息句柄转换为缓冲区

MQMHBUF 调用将消息句柄转换为缓冲区，并且是 MQBUFMH 调用的逆调用。

语法

MQMHBUF (Hconn, Hmsg, MsgHBufOpts, 名称, MsgDesc, 缓冲区长度, 缓冲器, 数据长度, CompCode, 原因)

参数

Hconn

类型 :MQHCONN-输入

此句柄表示与队列管理器的连接。 Hconn 的值必须与用于创建 Hmsg 参数中指定的消息句柄的连接句柄相匹配。

如果消息句柄是使用 MQHC_UNASSOCIATED_HCONN 创建的，那么必须在删除消息句柄的线程上建立有效连接。如果未建立有效连接，那么调用将失败，并返回 MQRC_CONNECTION_BROKEN。

赫消息

类型 :MQHMSG-输入

这是需要缓冲区的消息句柄。该值由先前的 MQCRTMH 调用返回。

MsgHBufOpts

类型 :MQMHBO-输入

MQMHBO 结构允许应用程序指定用于控制如何从消息句柄生成缓冲区的选项。

有关详细信息，请参阅 MQMHBO-消息句柄到缓冲区选项。

名称

类型 :MQCHARV-输入

要放入缓冲区中的一个或多个属性的名称。

如果找不到与名称匹配的属性，那么调用将失败并返回 MQRC_PROPERTY_NOT_AVAILABLE。

可以使用通配符将多个属性放入缓冲区中。为此，请在属性名末尾使用通配符 "%"。此通配符与零个或多个字符匹配，包括 "." 字符。

在 C 编程语言中，定义了以下宏变量，用于查询所有属性以及以 "usr" 开头的所有属性:

MQPROP_INQUIRE_ALL: 将消息的所有属性放入缓冲区中
MQPROP_INQUIRE_ALL_USR: 放置以字符 "usr." 开头的消息的所有属性。进入缓冲区。

请参阅属性名和属性名限制，以获取有关使用属性名的更多信息。

MsgDesc

类型 :MQMD-输入/输出

MsgDesc 结构描述缓冲区的内容。

在输出时， Encoding， CodedCharSetId 和 Format 字段设置为正确描述缓冲区中由调用写入的数据的编码，字符集标识和格式。

此结构中的数据采用应用程序的字符集和编码。

BufferLength

类型 :MQLONG-输入

BufferLength 是缓冲区的长度 (以字节为单位)。

缓冲区

类型：MQBYTExBufferLength- 输出

Buffer 定义要包含消息属性的区域。必须在 4 字节边界上对齐缓冲区。

如果 BufferLength 小于在 Buffer中存储属性所需的长度，那么 MQMHBUF 将失败，并带有 MQRC_PROPERTY_VALUE_TOO_BIG。

即使调用失败，缓冲区的内容也会更改。

DataLength

类型：MQLONG - 输出

DataLength 是缓冲区中返回的属性的长度 (以字节计)。如果值为零，那么没有任何属性与 Name 中给定的值匹配，并且调用失败，原因码为 MQRC_PROPERTY_NOT_AVAILABLE。

如果 BufferLength 小于在缓冲区中存储属性所需的长度，那么 MQMHBUF 调用将失败并返回 MQRC_PROPERTY_VALUE_TOO_BIG ，但仍会在 DataLength中输入值。这允许应用程序确定容纳属性所需的缓冲区大小，然后使用所需的 BufferLength重新发出调用。

CompCode

类型：MQLONG - 输出

完成代码；此完成代码为以下其中一项：

MQCC_OK: 成功完成。
MQCC_FAILED: 调用失败。

原因

类型：MQLONG - 输出

限定 CompCode的原因码。

如果 CompCode 为 MQCC_OK:

MQRC_NONE: (0, X'000') 没有要报告的原因。

如果 CompCode 是 MQCC_FAILED:

MQRC_ADAPTER_NOT_AVAILABLE: (2204，X'089C'）适配器不可用。
MQRC_ADAPTER_SERV_LOAD_ERROR: (2130, X'852') 无法装入适配器服务模块。
MQRC_ASID_MISMATCH: (2157, X'86D') 主 ASID (Primary ASID) 与主 ASID (home ASID) 不同。
MQRC_MHBO_ERROR: (2501,X'095C') 缓冲区选项结构的报文句柄无效。
MQRC_BUFFER_ERROR: (2004，X'07D4'）缓冲区参数无效。
MQRC_BUFFER_LENGTH_ERROR: (2005，X'07D5'）缓冲区长度参数无效。
MQRC_CALL_IN_PROGRESS: (2219，X'08AB'） MQI 呼叫在前一个呼叫完成前进入。
MQRC_CONNECTION_BROKEN: (2009，X'07D9'）与队列管理器的连接丢失。
MQRC_DATA_LENGTH_ERROR: (2010，X'07DA'）数据长度参数无效。
MQRC_HMSG_ERROR: (2460,X'099C') 信息句柄无效。
MQRC_MD_ERROR: (2026，X'07EA'）报文描述符无效。
MQRC_MSG_HANDLE_IN_USE: (2499,X'09C3') 消息句柄已在使用中。
MQRC_OPTIONS_ERROR: (2046,X'07FE') 选项无效或不一致。
MQRC_PROPERTY_NAME_ERROR: (2442,X'098A') 属性名称无效。
MQRC_PROPERTY_NOT_AVAILABLE: (2471，X'09A7'）属性不可用。
MQRC_PROPERTY_VALUE_TOO_BIG: (2469，X'09A5'）BufferLength值太小，无法包含指定属性。
MQRC_UNEXPECTED_ERROR: (2195, X'893') 发生了意外错误。

有关这些代码的详细信息，请参阅消息和原因码。

C 调用

MQMHBUF (Hconn, Hmsg, &MsgHBufOpts, &Name, &MsgDesc, BufferLength, Buffer,
         &DataLength, &CompCode, &Reason);

按如下所示声明参数：

MQHCONN Hconn;        /* Connection handle */
MQHMSG  Hmsg;         /* Message handle */
MQMHBO  MsgHBufOpts;  /* Options that control the action of MQMHBUF */
MQCHARV Name;         /* Property name */
MQMD    MsgDesc;      /* Message descriptor */
MQLONG  BufferLength; /* Length in bytes of the Buffer area */
MQBYTE  Buffer[n];    /* Area to contain the properties */
MQLONG  DataLength;   /* Length of the properties */
MQLONG  CompCode;     /* Completion code */
MQLONG  Reason;       /* Reason code qualifying CompCode */

使用说明

MQMHBUF 将消息句柄转换为缓冲区。

您可以将其与 MQGET API 出口配合使用，以使用消息属性 API 来访问某些属性，然后将这些属性在缓冲区中传递回设计为使用 MQRFH2 头而不是消息句柄的应用程序。

此调用是 MQBUFMH 调用的逆调用，可用于将消息属性从缓冲区解析为消息句柄。

COBOL 调用

     CALL 'MQMHBUF' USING HCONN, HMSG, MSGHBUFOPTS, NAME, MSGDESC,
                          BUFFERLENGTH, BUFFER, DATALENGTH, COMPCODE, REASON.

按如下所示声明参数：

**   Connection handle
 01  HCONN         PIC S9(9) BINARY.
**   Message handle
 01  HMSG          PIC S9(18) BINARY.
**   Options that control the action of MQMHBUF
 01  MSGHBUFOPTS.
     COPY CMQMHBOV.
**   Property name
 01  NAME
     COPY CMQCHRVV.
**   Message descriptor
 01  MSGDESC
     COPY CMQMDV.
**   Length in bytes of the Buffer area */
 01  BUFFERLENGTH  PIC S9(9) BINARY.
**   Area to contain the properties
 01  BUFFER        PIC X(n).
**   Length of the properties
 01  DATALENGTH    PIC S9(9) BINARY.
**   Completion code
 01  COMPCODE      PIC S9(9) BINARY.
**   Reason code qualifying COMPCODE
 01  REASON        PIC S9(9) BINARY.

PL/I 调用

call MQMHBUF (Hconn, Hmsg, MsgHBufOpts, Name, MsgDesc, BufferLength, Buffer,
DataLength, CompCode, Reason);

按如下所示声明参数：

dcl Hconn        fixed bin(31); /* Connection handle */
dcl Hmsg         fixed bin(63); /* Message handle */
dcl MsgHBufOpts  like MQMHBO;   /* Options that control the action of MQMHBUF */
dcl Name         like MQCHARV;  /* Property name */
dcl MsgDesc      like MQMD;     /* Message descriptor */
dcl BufferLength fixed bin(31); /* Length in bytes of the Buffer area */
dcl Buffer       char(n);       /* Area to contain the properties */
dcl DataLength   fixed bin(31); /* Length of the properties */
dcl CompCode     fixed bin(31); /* Completion code */
dcl Reason       fixed bin(31); /* Reason code qualifying CompCode */

高级汇编程序调用

CALL MQMHBUF,(HCONN,HMSG,MSGHBUFOPTS,NAME,MSGDESC,BUFFERLENGTH,
                BUFFER,DATALENGTH,COMPCODE,REASON)

按如下所示声明参数：

HCONN        DS       F      Connection handle
HMSG         DS       D      Message handle
MSGHBUFOPTS  CMQMHBOA ,      Options that control the action of MQMHBUF
NAME         CMQCHRVA ,      Property name
MSGDESC      CMQMDA   ,      Message descriptor
BUFFERLENGTH DS       F      Length in bytes of the BUFFER area
BUFFER       DS       CL(n)  Area to contain the properties
DATALENGTH   DS       F      Length of the properties
COMPCODE     DS       F      Completion code
REASON       DS       F      Reason code qualifying COMPCODE