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

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

此调用在缓冲区中获取消息描述符和 MQRFH2 属性，并通过消息句柄提供这些属性。可以选择除去消息数据中的 MQRFH2 属性。必要时，将更新消息描述符的 Encoding， CodedCharSetId和 Format 字段，以在除去属性后正确描述缓冲区的内容。

语法

MQBUFMH（Hconn、Hmsg、BufMsgHOpts、MsgDesc、BufferLength、Buffer、DataLength、Compcode、Reason）

参数

Hconn

类型 :MQHCONN-输入

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

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

赫消息

类型 :MQHMQSG-输入

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

BufMsgHOpts

类型 :MQBMHO-输入

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

请参阅 MQBMHO-缓冲区到消息句柄选项以获取详细信息。

MsgDesc

类型 :MQMD-输入/输出

MsgDesc 结构包含消息描述符属性并描述缓冲区的内容。

在调用的输出上，可选择从缓冲区中除去属性，在这种情况下，将更新消息描述符以正确描述缓冲区。

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

BufferLength

类型 :MQLONG-输入

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

零字节的 BufferLength 有效，指示缓冲区不包含任何数据。

缓冲区

类型：MQBYTExBufferLength- 输入/输出

这些选项用于控制 MQBEGIN 的操作，如 MQBEGIN-开始工作单元中所述。

Buffer 定义包含消息缓冲区的区域。对于大多数数据，您应该在 4 字节边界上对齐缓冲区。

如果 Buffer 包含字符或数字数据，请将 MsgDesc 参数中的 CodedCharSetId 和 Encoding 字段设置为适合于数据的值; 这将允许在必要时转换数据。

如果在消息缓冲区中找到属性，那么可以选择除去这些属性; 这些属性稍后将在从调用返回时从消息句柄变为可用。

在 C 编程语言中，该参数被声明为指向 void 的指针，这意味着任何类型的数据的地址都可以被指定为参数。

如果 BufferLength 参数为零，那么不会引用 Buffer ; 在这种情况下，以 C 或 System/390 汇编程序编写的程序传递的参数地址可以为空。

DataLength

类型：MQLONG - 输出

可能已除去属性的缓冲区的长度 (以字节计)。

CompCode

类型：MQLONG - 输出

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

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

原因

类型：MQLONG - 输出

如果 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_BMHO_ERROR: (2489,X'09B9') 缓冲区到报文句柄选项结构无效。
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_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_RFH_ERROR: (2334，X'091E'）MQRFH2结构无效。
MQRC_RFH_FORMAT_ERROR: (2421 ， X'0975 ') 无法解析包含属性的 MQRFH2 文件夹。
MQRC_UNEXPECTED_ERROR: (2195, X'893') 发生了意外错误。

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

使用说明

MQBUFMH 调用无法被 API 出口拦截-缓冲区将转换为应用程序空间中的消息句柄; 该调用无法到达队列管理器。

C 调用

MQBUFMH (Hconn, Hmsg, &BufMsgHOpts, &MsgDesc, BufferLength, Buffer,
         &DataLength, &CompCode, &Reason);

按如下所示声明参数：

MQHCONN Hconn;        /* Connection handle */
MQHMSG  Hmsg;         /* Message handle */
MQBMHO  BufMsgHOpts;  /* Options that control the action of MQBUFMH */
MQMD    MsgDesc;      /* Message descriptor */
MQLONG  BufferLength; /* Length in bytes of the Buffer area */
MQBYTE  Buffer[n];    /* Area to contain the message buffer */
MQLONG  DataLength;   /* Length of the output buffer */
MQLONG  CompCode;     /* Completion code */
MQLONG  Reason;       /* Reason code qualifying CompCode */

COBOL 调用

CALL 'MQBUFMH' USING HCONN, HMSG, BUFMSGHOPTS, 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 MQBUFMH
 01  BUFMSGHOPTS.
     COPY CMQBMHOV.
**   Message descriptor
 01  MSGDESC.
     COPY CMQMD.
**   Length in bytes of the Buffer area
 01  BUFFERLENGTH  PIC S9(9) BINARY.
**   Area to contain the message buffer
 01  BUFFER        PIC X(n).
**   Length of the output buffer
 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 MQBUFMH (Hconn, Hmsg, BufMsgHOpts, MsgDesc, BufferLength, Buffer,
DataLength, CompCode, Reason);

按如下所示声明参数：

dcl Hconn        fixed bin(31); /* Connection handle */
dcl Hmsg         fixed bin(63); /* Message handle */
dcl BufMsgHOpts  like MQBMHO;   /* Options that control the action of
                                   MQBUFMH */
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 message buffer */
dcl DataLength   fixed bin(31); /* Length of the output buffer */
dcl CompCode     fixed bin(31); /* Completion code */
dcl Reason       fixed bin(31); /* Reason code qualifying CompCode */

高级汇编程序调用

CALL MQBUFMH,(HCONN,HMSG,BUFMSGHOPTS,MSGDESC,BUFFERLENGTH,BUFFER,
                DATALENGTH,COMPCODE,REASON)

按如下所示声明参数：

HCONN        DS       F      Connection handle
HMSG         DS       D      Message handle
BUFMSGHOPTS  CMQBMHOA ,      Options that control the action of MQBUFMH
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 output buffer
COMPCODE     DS       F      Completion code
REASON       DS       F      Reason code qualifying COMPCODE