MQCRTMH-创建消息句柄

MQCRTMH 调用返回消息句柄。

应用程序可以在后续消息排队调用上使用 MQCRTMH 调用:

使用 MQSETMP 调用来设置消息句柄的属性。
使用 MQINQMP 调用查询消息句柄的属性值。
使用 MQDLTMP 调用删除消息句柄的一个属性。

可以在 MQPUT 和 MQPUT1 调用上使用消息句柄，以将消息句柄的属性与正在放入的消息的属性相关联。同样，通过在 MQGET 调用上指定消息句柄，可以在 MQGET 调用完成时使用消息句柄来访问正在检索的消息的属性。

使用 MQDLTMH 删除消息句柄。

语法

MQCRTMH （ Hconn、 CrtMsgHOpts、 Hmsg、 CompCode、 原因 ）

参数

Hconn

类型 :MQHCONN-输入

此句柄表示与队列管理器的连接。先前的 MQCONN 或 MQCONNX 调用返回了 Hconn 的值。如果与队列管理器的连接不再有效，且消息句柄上没有 IBM® MQ 调用，则会隐式调用 MQDLTMH 删除消息。

或者，可以指定以下值:

mqhc_unassociated_hconn

连接句柄不表示与任何特定队列管理器的连接。

使用此值时，必须通过显式调用 MQDLTMH 来删除消息句柄，以便释放分配给它的任何存储空间；IBM MQ 绝不会隐式删除消息句柄。

必须至少有一个与创建消息句柄的线程上建立的队列管理器的有效连接，否则调用将失败并返回 MQRC_HCONN_ERROR。

在单个系统上具有多个安装的环境中， MQHC_UNASSOCIATED_HCONN 值仅限用于装入到进程中的第一个安装。如果将消息句柄提供给其他安装，那么将返回原因码 MQRC_HMSG_NOT_AVAILABLE。

在 z/OS® for CICS® 应用程序上，可以省略 MQCONN 调用，并且可以为 Hconn指定以下值:

MQHC_DEF_HCONN: 缺省连接句柄

CrtMsgHOpts

类型 :MQCMHO-输入

用于控制 MQCRTMH 操作的选项。有关详细信息，请参阅 MQCMHO 。

赫消息

类型 :MQHMSG-输出

在输出时，将返回可用于设置，查询和删除消息句柄的属性的消息句柄。最初，消息句柄不包含任何属性。

消息句柄还具有关联的消息描述符。最初，这包含缺省值。可以使用 MQSETMP 和 MQINQMP 调用来设置和查询关联消息描述符字段的值。 MQDLTMP 调用将消息描述符的字段重置回其缺省值。

如果将 Hconn 参数指定为值 MQHC_UNASSOCIATED_HCONN ，那么返回的消息句柄可以用于 MQGET ， MQPUT 或 MQPUT1 调用以及处理单元中的任何连接，但一次只能由一个 IBM MQ 调用使用。如果第二个 IBM MQ 调用尝试使用同一消息句柄时正在使用该句柄，那么第二个 IBM MQ 调用将失败，原因码为 MQRC_MSG_HANDLE_IN_USE。

如果 Hconn 参数不是 MQHC_UNASSOCIATED_HCONN ，那么只能在指定的连接上使用返回的消息句柄。

必须在使用此消息句柄的后续 MQI 调用上使用相同的 Hconn 参数值:

MQDLTMH
MQSETMP
MQINQMP
MQDLTMP
MQMHBUF
MQBUFMH

当针对消息句柄发出 MQDLTMH 调用时，或者当定义句柄作用域的处理单元终止时，返回的消息句柄不再有效。如果在创建消息句柄时提供了特定连接，并且与队列管理器的连接不再有效 (例如，如果调用了 MQDBC) ，那么将隐式调用 MQDLTMH。

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_CALL_IN_PROGRESS: (2219，X'08AB'）MQI 呼叫在前一个呼叫完成前进入。
mqrc_cmhoo_error: (2461, X'099D') 创建报文句柄选项结构无效。
MQRC_CONNECTION_BROKEN: (2273, X'7D9') 与队列管理器的连接丢失。
mqrc_handle_not_available: (2017，X'07E1'）没有更多手柄可用。
MQRC_HCONN_ERROR: (2018, X'7E2') 连接句柄无效。
mqrc_hmsg_error: (2460, X'099C') 报文句柄指针无效。
mqrc_options_error: (2046，X'07FE'）选项无效或不一致。
MQRC_STORAGE_NOT_AVAILABLE: (2071, X'817') 没有足够的存储空间可用。
MQRC_UNEXPECTED_ERROR: (2195, X'893') 发生了意外错误。

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

C

MQCRTMH (Hconn, &CrtMsgHOpts, &Hmsg, &CompCode, &Reason);

按如下所示声明参数：

MQHCONN  Hconn;       /* Connection handle */
MQCMHO   CrtMsgHOpts; /* Options that control the action of MQCRTMH */
MQHMSG   Hmsg;        /* Message handle */
MQLONG   CompCode;    /* Completion code */
MQLONG   Reason;      /* Reason code qualifying CompCode */

COBOL

CALL 'MQCRTMH' USING HCONN, CRTMSGHOPTS, HMSG, COMPCODE, REASON.

按如下所示声明参数：

**   Connection handle
 01  HCONN     PIC S9(9) BINARY.
**   Options that control the action of MQCRTMH
 01  CRTMSGHOPTS.
     COPY CMQCMHOV.
**   Message handle
 01  HMSG    PIC S9(18) BINARY.
**   Completion code
 01  COMPCODE  PIC S9(9) BINARY.
**   Reason code qualifying COMPCODE
 01  REASON    PIC S9(9) BINARY.

PL/I

call MQCRTMH (Hconn, CrtMsgHOpts, Hmsg, CompCode, Reason);

按如下所示声明参数：

dcl Hconn       fixed bin(31);  /* Connection handle */
dcl CrtMsgHOpts like MQCMHO;    /* Options that control the action of MQCRTMH */
dcl Hmsg        fixed bin(63);  /* Message handle */
dcl CompCode    fixed bin(31);  /* Completion code */
dcl Reason      fixed bin(31);  /* Reason code qualifying CompCode */

High Level Assembler

CALL MQCRTMH,(HCONN,CRTMSGHOPTS,HMSG,COMPCODE,REASON)

按如下所示声明参数：

HCONN          DS        F  Connection handle
CRTMSGHOPTS    CMQCMHOA  ,  Options that control the action of MQCRTMH
HMSG           DS        D  Message handle
COMPCODE       DS        F  Completion code
REASON         DS        F  Reason code qualifying COMPCODE