MQCB-管理回调

语法

MQCB（Hconn、Operation、CallbackDesc、Hobj、MsgDesc、GetMsgOpts、CompCode、Reason）

参数

Hconn

类型 :MQHCONN-输入

此句柄表示与队列管理器的连接。 先前的 MQCONN 或 MQCONNX 调用返回了 Hconn 的值。

在 z/OS® (对于 CICS® 应用程序) 和 IBM i (对于以兼容性方式运行的应用程序) 上，可以为 MQHC_DEF_HCONN 指定以下特殊值以使用与此执行单元相关联的连接句柄。

重要信息: 如果仍在使用兼容性方式，请考虑重新编译应用程序并改为使用静态绑定调用。 请参阅 IBM i上 RPG 应用程序的兼容性方式

操作

类型 :MQLONG-输入

在为指定对象句柄定义的回调上正在处理的操作。 必须指定下列其中一个选项。 要指定多个选项，请将值一起添加 (请勿多次添加相同的常量) ，或者使用按位 OR 运算来组合值 (如果编程语言支持位运算)。

MQOP_REGISTER

定义指定对象句柄的回调函数。 此操作定义要调用的函数以及要使用的选择标准。

如果已经为对象句柄定义了回调函数，那么将替换该定义。 如果在替换回调时检测到错误，那么将注销该函数。

如果在先前已注销的回调函数中注册回调，那么会将其视为替换操作; 不会调用任何初始或最终调用。

您可以将 MQOP_REGISTER 与 MQOP_SUSPEND 或 MQOP_RESUME 配合使用。

mqop_deregister

停止使用对象句柄的消息，并从符合回调条件的对象句柄中除去该句柄。

如果关闭了关联的句柄，那么将自动注销回调。

如果从使用者内部调用 MQOP_DEREGISTER ，并且回调定义了停止调用，那么将在从使用者返回时调用该回调。

如果对没有注册使用者的 Hobj 发出此操作，那么调用将返回 MQRC_CALLBACK_NOT_REGISTERED。

MQOP_SUSPEND

暂挂使用对象句柄的消息。

如果此操作应用于事件处理程序，那么事件处理程序在暂挂时不会获取事件，并且在恢复操作时不会向操作提供处于暂挂状态时丢失的任何事件。

暂挂时，使用者函数将继续获取控制类型回调。

MQOP_RESUME

继续使用对象句柄的消息。

如果此操作应用于事件处理程序，那么事件处理程序在暂挂时不会获取事件，并且在恢复操作时不会向操作提供处于暂挂状态时丢失的任何事件。

CallbackDesc

类型 :MQCBD-输入

这是一种结构，用于标识应用程序正在注册的回调函数以及注册该回调函数时使用的选项。

请参阅 MQCBD 以获取结构的详细信息。

只有 MQOP_REGISTER 选项需要回调描述符; 如果不需要该描述符，那么传递的参数地址可以为空。

Hobj

类型 :MQHOBJ-输入

此句柄表示对要从中使用消息的对象建立的访问权。 这是从先前的 MQOPEN 或 MQSUB 调用 (在 Hobj 参数中) 返回的句柄。

定义事件处理程序例程 (MQCBT_EVENT_HANDLER) 时不需要 Hobj ，应该将其指定为 MQHO_NONE。

如果已从 MQOPEN 调用返回 Hobj ，那么必须已使用以下一个或多个选项打开队列:

• MQOO_INPUT_SHARED
• MQOO_INPUT_EXCLUSIVE
• MQOO_INPUT_AS_Q_DEF
• MQOO_BROWSE

MsgDesc

类型 :MQMD-输入

此结构描述所需消息的属性以及检索的消息的属性。

MsgDesc 参数定义使用者所需的消息属性，以及要传递给消息使用者的 MQMD 版本。

MQMD 中的 MsgId， CorrelId， GroupId， MsgSeqNumber和 Offset 用于消息选择，具体取决于 GetMsgOpts 参数中指定的选项。

如果指定 MQGMO_CONVERT 选项，那么 Encoding 和 CodedCharSetId 将用于消息转换。

请参阅 MQMD 以获取详细信息。

MsgDesc 用于 MQOP_REGISTER ，如果您需要任何字段的缺省值以外的值。 MsgDesc 不用于事件处理程序。

如果不需要描述符，那么传递的参数地址可以为空。

请注意，如果针对具有重叠选择器的同一队列注册了多个使用者，那么未定义每条消息的所选使用者。

GetMsgOpts

类型 :MQGMO-输入

GetMsgOpts 参数控制消息使用者获取消息的方式。 此参数的所有选项都具有 MQGMO-Get-message 选项中描述的含义 (在 MQGET 调用上使用时除外):

MQGMO_SET_SIGNAL

不允许此选项。

MQGMO_BROWSE_FIRST ， MQGMO_BROWSE_NEXT 和 MQGMO_MARK_ *

传递到浏览使用者的消息的顺序由这些选项的组合决定。 重要组合包括:

MQGMO_BROWSE_FIRST

队列上的第一条消息将重复传递给使用者。 当使用者以破坏性方式使用回调中的消息时，这很有用。 请谨慎使用此选项。

MQGMO_BROWSE_NEXT

将向使用者提供队列上的每条消息，从当前光标位置直到到达队列末尾。

mqgmoo_browse_first + mqgmoo_browse_next

将光标重置为队列的开始。 然后，将为使用者提供每条消息，直到光标到达队列的末尾为止。

MQGMO_BROWSE_FIRST + MQGMO_MARK_ *

从队列开始，将为使用者提供队列上的第一条未标记的消息，然后对此使用者进行标记。 此组合确保使用者可以接收在当前光标点后面添加的新消息。

MQGMO_BROWSE_NEXT + MQGMO_MARK_ *

从光标位置开始，将为使用者提供队列上的下一条未标记的消息，然后对此使用者进行标记。 请谨慎使用此组合，因为可以将消息添加到当前光标位置后的队列中。

MQGMO_BROWSE_FIRST + MQGMO_BROWSE_NEXT + MQGMO_MARK_ *

不允许此组合。 如果已使用，那么调用将返回 MQRC_OPTIONS_ERROR。

MQGMO_NO_WAIT ， MQGMO_WAIT 和 WaitInterval

这些选项控制如何调用使用者。

MQGMO_NO_WAIT

从不使用 MQRC_NO_MSG_AVAILABLE 调用使用者。 仅针对消息和事件调用使用者。

具有零 WaitInterval 的 MQGMO_WAIT

MQRC_NO_MSG_AVAILABLE 代码在没有可用消息时传递给使用者，并且自上次 "无消息" 原因码以来，使用者已启动或至少传递了一条消息。

当指定零等待时间间隔时，这将阻止使用者在繁忙循环中进行轮询。

MQGMO_WAIT 和正 WaitInterval

将在指定的等待时间间隔之后调用使用者，原因码为 MQRC_NO_MSG_AVAILABLE。 无论是否已将任何消息传递给使用者，都将进行此调用。 这允许用户执行脉动信号或批处理类型处理。

MQGMO_WAIT 和 MQWI_UNLIMITED 的 WaitInterval

这指定返回 MQRC_NO_MSG_AVAILABLE 之前的无限等待。 从不使用 MQRC_NO_MSG_AVAILABLE 调用使用者。

GetMsgOpts 仅用于 MQOP_REGISTER ，如果您需要任何字段的缺省值以外的值。 GetMsgOpts 不用于事件处理程序。

如果不需要 GetMsgOpts ，那么传递的参数地址可以为空。 使用此参数与将 MQGMO_DEFAULT 与 MQGMO_FAIL_IF_QUIESCING 一起指定相同。

如果在 MQGMO 结构中提供了消息属性句柄，那么将在传递到使用者回调的 MQGMO 结构中提供副本。 从 MQCB 调用返回时，应用程序可以删除消息属性句柄。

CompCode

类型：MQLONG - 输出

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

MQCC_OK

成功完成。

MQCC_WARNING

警告（部分完成）。

MQCC_FAILED

调用失败。

原因

类型：MQLONG - 输出

以下列表中的原因码是队列管理器可以针对 Reason 参数返回的原因码。

如果 CompCode 为 MQCC_OK：

MQRC_NONE

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

如果 CompCode 为 MQCC_FAILED：

MQRC_ADAPTER_NOT_AVAILABLE

(2204, X'89C') 适配器不可用。

mqrc_adapter_conv_load_error

(2133 ， X'855 ') 无法装入数据转换服务模块。

MQRC_ADAPTER_SERV_LOAD_ERROR

(2130, X'852') 无法装入适配器服务模块。

MQRC_API_EXIT_ERROR

(2374, X'946') API 出口失败。

mqrc_api_exit_load_error

(2183 ， X'887 ') 无法装入 API 出口。

MQRC_ASID_MISMATCH

(2157, X'86D') 主 ASID (Primary ASID) 与主 ASID (home ASID) 不同。

MQRC_BUFFER_LENGTH_ERROR

(2005, X'7D5') 缓冲区长度参数无效。

MQRC_CALL_IN_PROGRESS

(2219, X'8AB') 在先前调用完成前输入了 MQI 调用。

mqrc_callback_link_error

(2487，X'9B7'）回调类型字段不正确。

mqrc_callback_not_registered

(2448 ， X' 990 ') 无法注销，暂挂或恢复，因为没有已注册的回调。

mqrc_callback_routine_error

(2486，X'9B6'）必须指定 "CallbackFunction或 "CallbackName，但不能同时指定。

mqrc_callback_type_error

(2483，X'9B3'）回调类型字段不正确。

mqrc_cbd_options_error

(2484，X'9B4'）MQCBD 选项字段不正确。

mqrc_CICS_wait_failed

(2140,X'85C') 等待请求被 "CICS拒绝 .

MQRC_CONNECTION_BROKEN

(2009, X'7D9') 与队列管理器的连接丢失。

mqrc_connection_not_authorized

(2217，X'8A9'）未授权连接。

MQRC_CONNECTION_QUIESCING

(2202, X'89A') 连接正在停顿。

MQRC_CONNECTION_STOPPING

(2203, X'89B') 连接正在关闭。

mqrc_correl_id_error

(2207，X'89F'）相关标识符错误。

mqrc_data_length_error

(2010，X'7DA'）数据长度参数无效。

mqrc_function_not_supported

(2298,X'8FA') 请求的功能在当前环境中不可用。

MQRC_GET_禁止

(2016，X'7E0'）获得队列抑制。

mqrc_global_uow_conflict

(2351，X'92F'）全球工作单位冲突。

MQRC_GMO_ERROR

(2186,X'88A') Get-message 选项结构无效。

mqrc_handle_in_use_for_uow

(2353 ， X' 931 ') 用于全局工作单元的句柄。

MQRC_HCONN_ERROR

(2018, X'7E2') 连接句柄无效。

mqrc_hobj_error

(2019，X'7E3'）对象句柄无效。

mqrc_inconsistent_browse

(2259，X'8D3'）不符合浏览规范。

MQRC_INCONSISTENT_UOW

(2245，X'8C5'）工作单位规格不一致。

mqrc_invalid_msg_under_cursor

(2246，X'8C6'）光标下的信息无效，无法检索。

mqrc_local_uow_conflict

(2352 ， X' 930 ') 全局工作单元与本地工作单元冲突。

mqrc_match_options_error

(2247，X'8C7'）匹配选项无效。

mqrc_max_msg_length_error

(2485，X'9B4'）"MaxMsgLength字段不正确。

MQRC_MD_ERROR

(2026，X'7EA'）报文描述符无效。

mqrc_module_entry_not_found

(2497,X'9C1') 在模块中找不到指定的函数入口点。

mqrc_module_invalid

(2496,X'9C0') 模块已找到，但类型错误；不是 32 位、64 位或有效的动态链接库。

mqrc_module_not_found

(2495,X'9BF') 在搜索路径中未发现模块或未授权加载模块。

mqrc_msg_seq_number_error

(2250，X'8CA'）报文序列号无效。

mqrc_msg_token_error

(2331，X'91B'）信息令牌使用无效。

MQRC_NO_MSG_AVAILABLE

(2033，X'7F1'）无信息。

mqrc_no_msg_under_cursor

(2034,X'7F2') 浏览光标未定位在信息上。

mqrc_not_open_for_browse

(2036，X'7F4'）队列未开放浏览。

mqrc_not_open_for_input

(2037，X'7F5'）队列未开放输入。

mqrc_object_changed

(2041，X'7F9'）打开后对象定义已更改。

mqrc_object_damaged

(2101 ， X'835 ') 对象已损坏。

mqrc_operation_error

(2206，X'89E'）API 调用的操作代码不正确。

mqrc_options_error

(2046，X'7FE'） 选项无效或不一致。

mqrc_pageset_error

(2193 ， X'891 ') 访问页集数据集时出错。

MQRC_Q_DELETED

(2052 ， X'804 ') 队列已删除。

mqrc_q_index_type_error

(2394，X'95A'）队列的索引类型错误。

MQRC_Q_MGR_NAME_ERROR

(2058, X'80A') 队列管理器名称无效或者未知。

MQRC_Q_MGR_NOT_AVAILABLE

(2059, X'80B') 队列管理器针对连接不可用。

MQRC_Q_MGR_QUIESCING

(2161, X'871') 队列管理器正在停顿。

MQRC_Q_MGR_STOPPING

(2162, X'872') 队列管理器正在关闭。

MQRC_RESOURCE_PROBLEM

(2102, X'836') 没有足够系统资源可用。

MQRC_SIGNAL_众数

(2069 ， X'815 ') 此句柄的信号未完成。

MQRC_STORAGE_NOT_AVAILABLE

(2071, X'817') 没有足够的存储空间可用。

mqrc_suppressed_by_exit

(2109，X'83D'）退出程序抑制了调用。

MQRC_SYNCPOINT_LIMIT_已达到

(2024，X'7E8'）当前工作单元内无法处理更多信息。

mqrc_syncpoint_not_available

(2072 ， X'818 ') 同步点支持不可用。

MQRC_UNEXPECTED_ERROR

(2195, X'893') 发生了意外错误。

mqrc_uow_enlistment_error

(2354 ， X' 932 ') 在全局工作单元中登记失败。

mqrc_uow_mix_not_supported

(2355 ， X' 933 ') 不支持混合工作单元调用。

mqrc_uow_not_available

(2255，X'8CF'）队列管理器无法使用的工作单位。

mqrc_wait_interval_error

(2090,X'82A') MQGMO 中的等待时间间隔无效。

MQRC_不法 _gmo_version

(2256，X'8D0'）提供的 MQGMO 版本错误。

MQRC_不法 _md_version

(2257，X'8D1'）提供的 MQMD 版本错误。

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

使用说明

消息使用者回调序列

确保应用程序在 START 和 STOP 回调中执行基于线程的初始化和清除。 可以使用 REGISTER 和 DEREGISTER 回调执行基于非线程的初始化和清除。

请勿对线程的寿命和可用性进行任何非声明的假设。 例如，不要依赖在上次调用 DEREGISTER 之后保持活动状态的线程。 同样，当您选择不使用 THREAD_AFFINITY 时，请勿假定每当启动连接时都存在该线程。

如果应用程序对线程特征有特殊要求，那么它可以始终相应地创建线程，然后使用 MQCTL (WAIT)。 这具有向 IBM MQ "提供" 线程以进行异步消息传递的效果。

消息使用者连接使用情况

确保应用程序在 START 和 STOP 回调中执行基于线程的初始化和清除。 可以使用 REGISTER 和 DEREGISTER 回调执行基于非线程的初始化和清除。

请勿对线程的寿命和可用性进行任何非声明的假设。 例如，不要依赖在上次调用 DEREGISTER 之后保持活动状态的线程。 同样，当您选择不使用 THREAD_AFFINITY 时，请勿假定每当启动连接时都存在该线程。

如果应用程序对线程特征有特殊要求，那么它可以始终相应地创建线程，然后使用 MQCTL (WAIT)。 这具有向 IBM MQ "提供" 线程以进行异步消息传递的效果。

C 调用

MQCB (Hconn, Operation, CallbackDesc, Hobj, MsgDesc,
GetMsgOpts, &CompCode, &Reason);

MQHCONN  Hconn;         /* Connection handle */
MQLONG   Operation;     /* Operation being processed */
MQCBD    CallbackDesc;  /* Callback descriptor */
MQHOBJ   HObj           /* Object handle */
MQMD     MsgDesc        /* Message descriptor attributes */
MQGMO    GetMsgOpts     /* Message options */
MQLONG   CompCode;      /* Completion code */
MQLONG   Reason;        /* Reason code qualifying CompCode */

COBOL 调用

CALL 'MQCB' USING HCONN, OPERATION, CBDESC, HOBJ, MSGDESC,
            GETMSGOPTS, COMPCODE, REASON.

**   Connection handle
 01  HCONN    PIC S9(9) BINARY.
**   Operation
 01  OPERATION PIC S9(9) BINARY.
**   Callback Descriptior
 01  CBDESC.
     COPY CMQCBDV.
01  HOBJ     PIC S9(9) BINARY.
**   Message Descriptior
 01  MSGDESC.
     COPY CMQMDV.
**   Get Message Options
 01  GETMSGOPTS.
     COPY CMQGMOV.
**   Completion code
 01  COMPCODE PIC S9(9) BINARY.
**   Reason code qualifying COMPCODE
 01  REASON   PIC S9(9) BINARY.

PL/I 调用

call MQCB(Hconn, Operation, CallbackDesc, Hobj, MsgDesc, GetMsgOpts,
          CompCode, Reason)

dcl Hconn        fixed bin(31); /* Connection handle */
dcl Operation    fixed bin(31); /* Operation */
dcl CallbackDesc like MQCBD;    /* Callback Descriptor */
dcl Hobj         fixed bin(31); /* Object Handle */
dcl MsgDesc      like MQMD;     /* Message Descriptor */
dcl GetMsgOpts   like MQGMO;    /* Get Message Options */
dcl CompCode     fixed bin(31); /* Completion code */
dcl Reason       fixed bin(31); /* Reason code qualifying CompCode */