MQCLOSE-关闭对象

MQCLOSE 调用将放弃对对象的访问权，并且是 MQOPEN 和 MQSUB 调用的逆调用。

语法

MQCLOSE (Hconn、 Hobj、 Options、 CompCode、 Reason ）

参数

Hconn
类型 :MQHCONN-输入

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

在 z/OS® for CICS® 应用程序上，可以省略 MQCONN 调用，并为 Hconn 指定以下值:
MQHC_DEF_HCONN
缺省连接句柄。
Hobj
类型 :MQHOBJ-输入/输出

此句柄表示正在关闭的对象。 对象可以是任何类型。 Hobj 的值由先前的 MQOPEN 调用返回。

成功完成调用时，队列管理器会将此参数设置为不是环境的有效句柄的值。 此值为:
mqhoo_unusable_hobj
不可用的对象句柄。

在 z/OS上， Hobj 设置为未定义的值。

选项
类型 :MQLONG-输入

此参数控制对象的关闭方式。

只有永久动态队列和订阅可以用多种方式关闭，因为它们必须保留或删除；这些队列的 DefinitionType 属性值为 MQQDT_PERMANENT_DYNAMIC（请参阅 队列属性 中描述的 DefinitionType 属性）。 本主题概述了关闭选项。

可保留或除去持久预订; 这些预订是使用带有MQSO_持久选项的 MQSUB 调用创建的。

当关闭对受管目标的句柄 (即在使用 MQSO_MANAGED 选项的 MQSUB 调用上返回的 Hobj 参数) 时，队列管理器将清除在同时除去关联预订时未检索到的任何发布。 使用 MQSUB 调用上返回的 Hsub 参数上的 MQCO_REMOVE_SUB 选项除去预订。 请注意，对于非持久预订， MQCO_REMOVE_SUB 是 MQCLOSE 上的缺省行为。

当关闭非受管目标的句柄时，您将负责清除发送发布的队列。 首先使用 MQCO_REMOVE_SUB 关闭预订，然后处理队列外的消息，直到无保留。

必须仅从以下项指定一个选项:

动态队列选项: 这些选项控制永久动态队列的关闭方式。
MQCO_DELETE
如果以下任一项为 true ，那么将删除该队列:
  • 它是由先前 MQOPEN 调用创建的永久动态队列，并且队列上没有消息，也没有未落实的 get 或 put 请求 (对于当前任务或任何其他任务)。
  • 它是 MQOPEN 调用创建的临时动态队列，返回了 Hobj。 在这种情况下，将清除队列上的所有消息。
在所有其他情况下 (包括在 MQSUB 调用上返回 Hobj 的情况) ，调用失败，原因码为 MQRC_OPTION_NOT_VALID_FOR_TYPE ，并且未删除对象。

在 z/OS上，如果该队列是已逻辑删除的动态队列，并且这是该队列的最后一个句柄，那么将以物理方式删除该队列。 请参阅 用法说明 以获取更多详细信息。

MQCO_DELETE_PURGE
如果以下任一情况为真，那么将删除该队列，并清除该队列上的任何消息:
  • 它是由先前 MQOPEN 调用创建的永久动态队列，没有未落实的 get 或 put 请求 (对于当前任务或任何其他任务)。
  • 它是 MQOPEN 调用创建的临时动态队列，返回了 Hobj。
在所有其他情况下 (包括在 MQSUB 调用上返回 Hobj 的情况) ，调用失败，原因码为 MQRC_OPTION_NOT_VALID_FOR_TYPE ，并且未删除对象。
表 1. 关闭不同对象类型的选项
对象或队列的类型 MQCO_NONE MQCO_DELETE MQCO_DELETE_PURGE
队列以外的对象 已保留 无效 无效
预定义队列 已保留 无效 无效
永久动态队列 已保留 如果为空且无暂挂更新，那么已删除 已删除消息; 如果没有暂挂更新，那么队列已删除
临时动态队列 (由队列的创建者发出的调用) 已删除 已删除 已删除
临时动态队列 (队列创建者未发出调用) 已保留 无效 无效
分发列表 已保留 无效 无效
受管预订目标 已保留 无效 无效
分发列表 (已除去预订) 已删除消息; 已删除队列 无效 无效
预订关闭选项: 这些选项控制关闭句柄时是否除去持久预订，以及是否清除仍等待应用程序读取的发布。 这些选项仅适用于 MQSUB 调用的 Hsub 参数中返回的对象句柄。
MQCO_KEEP_SUB
已关闭预订的句柄，但保留所进行的预订。 继续将发布发送到预订中指定的目标。 仅当使用选项MQSO_耐久性进行预订时，此选项才有效。
如果预订是持久预订，那么 MQCO_KEEP_SUB 是缺省值
mqco_remove_sub
将除去该预订，并关闭该预订的句柄。
MQSUB 调用的 Hobj 参数不会因 Hsub 参数的闭包而失效，并且可能继续用于 MQGET 或 MQCB 以接收其余发布内容。 当 MQSUB 调用的 Hobj 参数也关闭时，如果它是受管目标，那么将除去任何未检索的发布。
MQCO_REMOVE_SUB 是缺省值 (如果预订是非持久预订)。
MQCO_REMOVE_SUB 成功完成并不意味着操作已完成。 要检查此调用是否已完成，请参阅 检查分布式网络的异步命令是否已完成中的 DELETE SUB 步骤。

下表概述了这些预订关闭选项。

表 2. 用于关闭持久预订句柄但保留预订的选项
任务 预订关闭选项
保留 MQOPENed 句柄上的发布 MQCO_KEEP_SUB
除去 MQOPENed 句柄上的发布 不允许操作
将发布保留在 MQSO_MANAGED 句柄上 MQCO_KEEP_SUB
除去 MQSO_MANAGED 句柄上的发布 不允许操作
要取消预订，请通过关闭持久预订句柄并将其取消预订，或者关闭非持久预订句柄，使用以下预订关闭选项:
表 3. 要取消预订的选项
任务 预订关闭选项
保留 MQOPENed 句柄上的发布 mqco_remove_sub
除去 MQOPENed 句柄上的发布 不允许操作
将发布保留在 MQSO_MANAGED 句柄上 mqco_remove_sub
预读选项: 以下选项控制在应用程序请求非持久消息之前已发送到客户机且尚未由应用程序使用的非持久消息发生的情况。 这些消息存储在等待应用程序请求的客户机预读缓冲区中，并且可以在完成 MQCLOSE 之前从队列中废弃或使用这些消息。
MQCO_IMMEDIATE
该对象将立即关闭，并且在应用程序请求之前发送到客户机的任何消息都将被废弃，并且不可供任何应用程序使用。 这是缺省值。
MQCO_QUIESCE
发出了关闭对象的请求，但如果在应用程序请求之前发送到客户机的任何消息仍驻留在客户机预读缓冲区中，那么 MQCLOSE 调用将返回警告 MQRC_READ_AHEAD_MSGS ，并且对象句柄保持有效。

然后，应用程序可以继续使用对象句柄来检索消息，直到没有更多可用消息为止，然后再次关闭该对象。 在应用程序发出请求之前，不再向客户机发送更多消息，现在已关闭预读。

建议应用程序使用 MQCO_QUIESCE ，而不是尝试到达客户机预读缓冲区中没有更多消息的点，因为消息可能在上次 MQGET 调用与以下 MQCLOSE 之间到达，如果使用了 MQCO_IMMEDIATE ，那么将废弃该消息。

如果从异步回调函数中发出具有 MQCO_QUIESCE 的 MQCLOSE ，那么预读消息的相同行为适用。 如果返回警告 MQRC_READ_AHEAD_MSGS ，那么至少再调用一次回调函数。 将预读的最后一条剩余消息传递到回调函数时， MQCBC ConsumerFlags 字段将设置为 MQCBCF_READA_BUFFER_EMPTY。

缺省选项: 如果不需要先前描述的任何选项，那么可以使用以下选项:

MQCO_NONE
不需要可选的关闭处理。
必须为以下对象指定此项:
  • 队列以外的对象
  • 预定义队列数
  • 临时动态队列 (但仅在 Hobj 不是创建队列的 MQOPEN 调用所返回的句柄的情况下)。
  • 分发列表
在上述所有情况下，将保留对象而不将其删除。
如果为临时动态队列指定了此选项:
  • 如果队列是由返回了 Hobj 的 MQOPEN 调用创建的，那么将删除该队列; 将清除队列上的所有消息。
  • 在所有其他情况下，将保留队列 (及其上的任何消息)。

如果为永久动态队列指定了此选项，那么将保留该队列，而不会将其删除。

在 z/OS上，如果该队列是已逻辑删除的动态队列，并且这是该队列的最后一个句柄，那么将以物理方式删除该队列。 请参阅 用法说明 以获取更多详细信息。

CompCode
类型：MQLONG - 输出
完成代码；此完成代码为以下其中一项：
MQCC_OK
成功完成。
MQCC_WARNING
警告（部分完成）。
MQCC_FAILED
调用失败。

原因
类型：MQLONG - 输出

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

如果 CompCode 为 MQCC_OK:
MQRC_NONE
(0, X'000') 没有要报告的原因。
如果 CompCode 为 MQCC_WARNING:
MQRC_INCOMPLETE_GROUP
(2241, X'8C1') 信息组未完成。
MQRC_INCOMPLETE_MSG
(2242，X'8C2'）逻辑信息不完整。
mqrc_read_ahead_msgs
(nnnn ， X'xxx ') 客户机已预读应用程序尚未使用的消息。
如果 CompCode 是 MQCC_FAILED:
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_CALL_IN_PROGRESS
(2219, X'8AB') 在先前调用完成前输入了 MQI 调用。
mqrc_cf_not_available
(2345 ， X' 929 ') 耦合设施不可用。
mqrc_cf_struc_failed
(2373 ， X' 945 ') 耦合设施结构失败。
mqrc_cf_struc_in_use
(2346，X'92A'）使用中的耦合设施结构。
mqrc_cics_wait_failed
(2140, X'85C') 等待请求被 CICS 拒绝。
MQRC_CONNECTION_BROKEN
(2009, X'7D9') 与队列管理器的连接丢失。
mqrc_connection_not_authorized
(2217，X'8A9'）未授权连接。
MQRC_CONNECTION_STOPPING
(2203, X'89B') 连接正在关闭。
MQRC_DB2_NOT_AVAILABLE
(2342 ， X' 926 ') Db2® 子系统不可用。
MQRC_HCONN_ERROR
(2018, X'7E2') 连接句柄无效。
mqrc_hobj_error
(2019，X'7E3'）对象句柄无效。
MQRC_NOT_AUTHORIZED
(2035, X'7F3') 未获得访问授权。
mqrc_object_damaged
(2101 ， X'835 ') 对象已损坏。
mqrc_option_not_valid_for_type
(2045, X'7FD') 在调用 MQOPEN 或 MQCLOSE 时：选项对对象类型无效。
mqrc_options_error
(2046，X'7FE'）选项无效或不一致。
mqrc_pageset_error
(2193 ， X'891 ') 访问页集数据集时出错。
MQRC_Q_MGR_NAME_ERROR
(2058, X'80A') 队列管理器名称无效或者未知。
MQRC_Q_MGR_NOT_AVAILABLE
(2059, X'80B') 队列管理器针对连接不可用。
MQRC_Q_MGR_STOPPING
(2162, X'872') 队列管理器正在关闭。
mqrc_q_not_empty
(2055 ， X'807 ') 队列包含一条或多条消息或未落实的 put 或 get 请求。
MQRC_RESOURCE_PROBLEM
(2102, X'836') 没有足够系统资源可用。
MQRC_SECURITY_ERROR
(2063, X'80F') 发生了安全性错误。
MQRC_STORAGE_NOT_AVAILABLE
(2071, X'817') 没有足够的存储空间可用。
mqrc_suppressed_by_exit
(2109，X'83D'）退出程序抑制调用。
MQRC_UNEXPECTED_ERROR
(2195, X'893') 发生了意外错误。

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

使用说明

  1. 当应用程序发出 MQDISC 调用或正常或异常结束时，将使用 MQCO_NONE 选项自动关闭由应用程序打开且仍处于打开状态的任何对象。
  2. 如果要关闭的对象是 队列，那么以下要点适用:
    • 如果队列上的操作作为工作单元的一部分执行，那么可以在同步点发生之前或之后关闭队列，而不会影响同步点的结果。 如果触发队列，那么在关闭队列之前执行回滚会导致发出触发消息。 有关触发器消息的更多信息，请参阅 触发器消息的属性。
    • 如果使用 MQOO_BROWSE 选项打开队列，那么浏览游标将被破坏。 如果随后使用 MQOO_BROWSE 选项重新打开队列，那么将创建新的浏览游标 (请参阅 MQOO_BROWSE )。
    • 如果当前在 MQCLOSE 调用时对此句柄锁定了消息，那么将释放该锁定 (请参阅 MQGMO_LOCK )。
    • 在 z/OS上，如果存在针对要关闭的队列句柄具有未完成的 MQGMO_SET_SIGNAL 选项的 MQGET 请求，那么将取消该请求 (请参阅 MQGMO_SET_SIGNAL )。 针对相同队列但针对不同句柄 (Hobj) 提出的信号请求不受影响 (除非正在删除动态队列，在这种情况下它们也会被取消)。
  3. 如果要关闭的对象是 动态队列 (永久或临时) ，那么以下几点适用:
    • 对于动态队列，可以指定 MQCO_DELETE 和 MQCO_DELETE_PURGE 选项，而不考虑在相应的 MQOPEN 调用上指定的选项。
    • 删除动态队列时，将取消对该队列执行的所有带有 MQGMO_WAIT 选项的 MQGET 调用，并返回原因码 MQRC_Q_DELETED。 请参阅 MQGMO_WAIT。

      虽然应用程序无法访问已删除的队列，但不会从系统中除去该队列，并且不会释放关联的资源，直到引用该队列的所有句柄都已关闭，并且影响该队列的所有工作单元都已落实或回退。

      在 z/OS上，已逻辑删除但尚未从系统中除去的队列会阻止创建与已删除队列同名的新队列; 在此情况下， MQOPEN 调用失败，原因码为 MQRC_NAME_IN_USE。 此外，即使应用程序无法访问此类队列，也仍然可以使用 MQSC 命令来显示该队列。

    • 删除永久动态队列时，如果 MQCLOSE 调用上指定的 Hobj 句柄不是创建队列的 MQOPEN 调用所返回的句柄，那么将检查用于验证 MQOPEN 调用的用户标识是否有权删除该队列。 如果在 MQOPEN 调用上指定了 MQOO_ALTERNATE_USER_AUTHORITY 选项，那么检查的用户标识为 AlternateUserId。
      在下列情况下，将不执行此检查:
      • 指定的句柄是创建队列的 MQOPEN 调用返回的句柄。
      • 要删除的队列是临时动态队列。
    • 当临时动态队列关闭时，如果 MQCLOSE 调用上指定的 Hobj 句柄是创建队列的 MQOPEN 调用返回的句柄，那么将删除该队列。 无论 MQCLOSE 调用上指定的关闭选项如何，都会发生此情况。 如果队列上存在消息，那么将废弃这些消息; 不会生成任何报告消息。

      如果存在影响队列的未落实工作单元，那么仍会删除队列及其消息，但工作单元不会失败。 但是，如前所述，在落实或回退每个工作单元之前，不会释放与工作单元相关联的资源。

  4. 如果要关闭的对象是 分发列表，那么以下要点适用:
    • 分发列表的唯一有效关闭选项是 MQCO_NONE; 调用失败，原因码为 MQRC_OPTIONS_ERROR 或 MQRC_OPTION_NOT_VALID_FOR_TYPE (如果指定了任何其他选项)。
    • 关闭分发列表时，不会针对列表中的队列返回个别完成代码和原因码; 只有调用的 CompCode 和 Reason 参数可用于诊断。

      如果关闭其中一个队列时发生故障，那么队列管理器将继续处理并尝试关闭分发列表中的其余队列。 调用的 CompCode 和 Reason 参数设置为返回描述故障的信息。 完成代码可能为 MQCC_FAILED ，即使大多数队列已成功关闭也是如此。 未识别迂到错误的队列。

      如果在多个队列上发生故障，那么未定义在 CompCode 和 Reason 参数中报告的故障。

C 调用

MQCLOSE (Hconn, &Hobj, Options, &CompCode, &Reason);
按如下所示声明参数：
MQHCONN  Hconn;     /* Connection handle */
MQHOBJ   Hobj;      /* Object handle */
MQLONG   Options;   /* Options that control the action of MQCLOSE */
MQLONG   CompCode;  /* Completion code */
MQLONG   Reason;    /* Reason code qualifying CompCode */

COBOL 调用

     CALL 'MQCLOSE' USING HCONN, HOBJ, OPTIONS, COMPCODE, REASON.
按如下所示声明参数：
**   Connection handle
 01  HCONN     PIC S9(9) BINARY.
**   Object handle
 01  HOBJ      PIC S9(9) BINARY.
**   Options that control the action of MQCLOSE
 01  OPTIONS   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 MQCLOSE (Hconn, Hobj, Options, CompCode, Reason);
按如下所示声明参数：
dcl Hconn     fixed bin(31);  /* Connection handle */
dcl Hobj      fixed bin(31);  /* Object handle */
dcl Options   fixed bin(31);  /* Options that control the action of
                                 MQCLOSE */
dcl CompCode  fixed bin(31);  /* Completion code */
dcl Reason    fixed bin(31);  /* Reason code qualifying CompCode */

高级汇编程序调用

CALL MQCLOSE,(HCONN,HOBJ,OPTIONS,COMPCODE,REASON)
按如下所示声明参数：
HCONN     DS  F  Connection handle
HOBJ      DS  F  Object handle
OPTIONS   DS  F  Options that control the action of MQCLOSE
COMPCODE  DS  F  Completion code
REASON    DS  F  Reason code qualifying COMPCODE

Visual Basic 调用

MQCLOSE Hconn, Hobj, Options, CompCode, Reason
按如下所示声明参数：
Dim Hconn    As Long 'Connection handle'
Dim Hobj     As Long 'Object handle'
Dim Options  As Long 'Options that control the action of MQCLOSE'
Dim CompCode As Long 'Completion code'
Dim Reason   As Long 'Reason code qualifying CompCode'