MQCTL-控制回调

语法

MQCTL （ Hconn、 操作、 控制选项、 CompCode、 原因 ）

参数

Hconn

类型 :MQHCONN-输入

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

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

MQHC_DEF_HCONN

缺省连接句柄。

操作

类型 :MQLONG-输入

在为指定对象句柄定义的回调上正在处理的操作。 必须指定下列选项中的一个 (且仅指定一个):

MQOP_START

开始对指定连接句柄的所有已定义消息使用者函数使用消息。

回调在系统启动的线程上运行，这与任何应用程序线程不同。

此操作将控制提供给系统的连接句柄。 可以由除使用者线程以外的线程发出的唯一 MQI 调用是:

• 具有操作 MQOP_STOP 的 MQCTL
• 具有操作 MQOP_SUSPEND 的 MQCTL
• MQDISC-在断开 HConn 连接之前使用操作 MQOP_STOP 执行 MQCTL。

如果在启动连接句柄时发出了 IBM® MQ API 调用，并且该调用并非源自消息使用者函数，那么将返回 MQRC_HCONN_ASYNC_ACTIVE。

如果消息使用者在 MQCBCT_START_CALL 期间停止连接，那么 MQCTL 调用将返回失败原因码 MQRC_CONNECTION_STOPPED。

这可以在使用者函数中发出。 对于与回调例程相同的连接，其唯一目的是取消先前发出的 MQOP_STOP 操作。

此选项在以下环境中不受支持: CICS on z/OS 或如果应用程序与非线程 IBM MQ 库绑定。

mqop_start_wait

开始对指定连接句柄的所有已定义消息使用者函数使用消息。

在同一线程上运行的消息使用者和控制不会返回到 MQCTL 的调用者，直到:

• 通过使用 MQCTL MQOP_STOP 或 MQOP_SUSPEND 操作发布，或
• 已注销或暂挂所有使用者例程。

如果所有使用者都已注销或暂挂，那么将发出隐式 MQOP_STOP 操作。

此选项不能在回调例程中用于当前连接句柄或任何其他连接句柄。 如果尝试调用，那么将返回 MQRC_environmenT_ERROR。

如果在 MQOP_START_WAIT 操作期间的任何时间没有已注册的非暂挂使用者，那么调用将失败，原因码为 MQRC_NO_CALLBACKS_ACTIVE。

如果在 MQOP_START_WAIT 操作期间暂挂连接，那么 MQCTL 调用将返回警告原因码 MQRC_CONNECTION_SUSPENDED; 连接将保持 "已启动" 状态。

应用程序可以选择发出 MQOP_STOP 或 MQOP_RESUME。 在此实例中， MQOP_RESUME 操作将阻塞。

此选项在单线程客户机中不受支持。

MQOP_STOP

停止使用消息，并在此选项完成之前等待所有使用者完成其操作。 此操作将释放连接句柄。

如果是从回调例程中发出的，那么此选项直到例程退出后才会生效。 在已读消息的使用者例程完成之后，以及在对回调例程进行停止调用 (如果请求) 之后，不再调用更多消息使用者例程。

如果在回调例程外部发出，那么直到已读消息的使用者例程完成，并且在对回调进行停止调用 (如果已请求) 之后，控制才会返回到调用者。 但是，回调本身仍保持已注册状态。

此功能对预读消息没有影响。 您必须确保使用者从回调函数中运行 MQCLOSE (MQCO_QUIESCE) ，以确定是否有任何其他消息可供传递。

MQOP_SUSPEND

暂停使用消息。 此操作将释放连接句柄。

这不会对应用程序的提前读取消息产生任何影响。 如果您打算长时间停止使用消息，请考虑关闭队列并在继续使用时重新打开该队列。

如果从回调例程中发出，那么直到例程退出后才会生效。 在当前例程退出后将不再调用消息使用者例程。

如果在回调外部发出，那么直到当前使用者例程完成且不再调用时，控制才会返回到调用者。

MQOP_RESUME

恢复使用消息。

通常从主应用程序线程发出此选项，但也可以从回调例程中使用此选项来取消在同一例程中发出的较早暂挂请求。

如果使用 MQOP_RESUME 来恢复 MQOP_START_WAIT ，那么操作将阻塞。

ControlOpts

类型 :MQCTLO-输入

用于控制 MQCTL 的操作的选项

有关结构的详细信息，请参阅 MQCTLO 。

CompCode

类型：MQLONG - 输出

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

MQCC_OK

成功完成。

MQCC_WARNING

警告（部分完成）。

MQCC_FAILED

调用失败。

原因

类型：MQLONG - 输出

如果 CompCode 为 MQCC_OK:

MQRC_NONE

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

如果 CompCode 是 MQCC_FAILED:

mqrc_adapter_conv_load_error

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

MQRC_ADAPTER_NOT_AVAILABLE

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

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_callback_link_error

(2487, X'9B7') 无法调用回调例程

MQRC_CALLBACK_NOT_ 已注册

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

mqrc_callback_routine_error

(2486, X'9B6') 要么，CallbackFunction 和 CallbackName 都已在 MQOP_REGISTER 调用中指定。

或者指定了 CallbackFunction 或 CallbackName ，但与当前注册的回调函数不匹配。

mqrc_callback_type_error

(2483, X'9B3') CallBackType 字段不正确。

MQRC_CALL_IN_PROGRESS

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

MQRC_CBD_ERROR

(2444，X'98C'）选项块不正确。

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_ENVIRONMENT_ERROR

(2012, X'7DC') 调用在环境中无效。

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'9B5') 不正确的 MaxMsgLength 字段

MQRC_MD_ERROR

(2026, X'7EA') 信息描述符无效。

mqrc_module_entry_not_found

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

mqrc_module_invalid

(2496, X'9C0') 模块已找到，但类型错误（32 bit/64 位）或不是有效的 dll。

mqrc_module_not_found

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

mqrc_msg_id_error

(2206, X'89E') 信息标识符错误。

mqrc_msg_seq_number_error

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

mqrc_msg_token_error

(2331，X'91B'）信息标记使用无效。

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

(2488, X'9B8') 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_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 版本错误。

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

使用说明

1. 回调例程必须检查来自它们调用的所有服务的响应，如果例程检测到无法解析的条件，那么它必须发出 MQCB MQOP_DEREGISTER 命令以防止重复调用回调例程。
2. 如果要在 XA 事务管理器管理全局事务 (包括 IBM MQ的更新) 的应用程序中使用异步使用，那么需要考虑以下其他要点:
   1. 在创建 MQCTL (MQOP_START) 之后，在调用 xa_open之后，对 HConn调用 MQCTL (MQOP_START) 是无效的。

      原因是 HConn 已连接到 XA 上下文，因此无法在异步使用机制使用的单独线程上进行访问。

   2. 如果在该场景中调用 MQCTL (MQOP_START) ，那么调用将失败，原因码为 MQRC_ASYNC_XA_CONFLICT (2350)。
   3. 在创建 MQCTL (MQOP_START_WAIT) 之后，在调用 xa_open之后，对 HConn调用 MQCTL (MQOP_START_WAIT) 是有效的。

      原因是此启动异步使用机制的方法会导致 HConn 的所有进一步回调在执行 MQCTL 调用的线程上运行。 因此， HConn 与线程之间的链接不会丢失。

3. On z/OS，当操作为 MQOP_START 时：
   • 使用异步回调例程的程序必须获得授权才能使用z/OS UNIX System Services（z/OS UNIX ）。
   • Language Environment (LE) 程序使用异步回调例程时，必须使用 LE 运行时选项 (ON)。 POSIX
   • 使用异步回调例程的非 LE 程序不得使用z/OS UNIXpthread_create 接口（可调用服务BPX1PTC ）。
4. MQCTL 不支持 IMS 适配器。

C 调用

MQCTL (Hconn, Operation, &ControlOpts, &CompCode, &Reason)

MQHCONN  Hconn;         /* Connection handle */
MQLONG   Operation;     /* Operation being processed */
MQCTLO   ControlOpts    /* Options that control the action of MQCTL */
MQLONG   CompCode;      /* Completion code */
MQLONG   Reason;        /* Reason code qualifying CompCode */

COBOL 调用

CALL 'MQCTL' USING HCONN, OPERATION, CTLOPTS, COMPCODE, REASON.

**   Connection handle
 01  HCONN    PIC S9(9) BINARY.
**   Operation
 01  OPERATION PIC S9(9) BINARY.
**   Control Options
 01  CTLOPTS.
     COPY CMQCTLOV.
**   Completion code
 01  COMPCODE PIC S9(9) BINARY.
**   Reason code qualifying COMPCODE
 01  REASON   PIC S9(9) BINARY.

PL/I 调用

call MQCTL(Hconn, Operation, CtlOpts, CompCode, Reason)

dcl Hconn        fixed bin(31); /* Connection handle */
dcl Operation    fixed bin(31); /* Operation */
dcl CtlOpts like MQCTLO;        /* Options that control the action of MQCTL */
dcl CompCode     fixed bin(31); /* Completion code */
dcl Reason       fixed bin(31); /* Reason code qualifying CompCode */