MQCONN - 连接队列管理器

MQCONN 调用可将应用程序连接到队列管理器。

它可提供要给队列管理器连接句柄，以供应用程序在后续消息排队调用上使用。
  • 在 z/OS®上， CICS® 应用程序不必发出此调用。 这些应用程序会自动连接到 "CICS系统所连接的队列管理器。 不过，"CICS应用程序仍然接受 MQCONN 和 MQDISC 调用。
  • 在 IBM® i上，应用程序必须使用 MQCONN 或 MQCONNX 调用来连接到队列管理器，并使用 MQDISC 调用来断开与队列管理器的连接。
无法在纯服务器安装中进行客户机连接，并且无法在纯客户机安装中进行本地连接。

语法

MQCONN （ QMgrName ， Hconn ， CompCode ， 原因 ）

参数

QMgrName
类型：MQCHAR48 - 输入
这是应用程序要连接到的队列管理器的名称。 此名称可包含以下字符：
  • 大写字母字符（A 到 Z）
  • 小写字母字符（a 到 z）
  • 数字位（0 到 9）
  • 句点 (.)、正斜杠 (/)、下划线 (_)、百分号 (%)
此名称不得包含前导空格或嵌入空格，但可以包含尾部空格。 空字符可用于指示名称中重要数据结束；空字符及空字符后的任何字符都作为空格来处理。 以下限制适用于指示的环境中：
  • 在使用 EBCDIC 片假名的系统上，不得使用小写字符。
  • 在 z/OS上，操作和控制面板无法处理以下划线开头或结尾的名称。 因此，请避免使用此类名称。
  • 在 IBM i上，当在命令上指定时，请将包含小写字符，正斜杠或百分号的名称括在引号中。 请勿在 QMgrName 参数中指定这些引号。

如果名称完全由空格组成，那么将使用缺省队列管理器的名称。 但是，请注意使用 IBM MQ MQI client 应用程序部分中描述的空白队列管理器名称。

为 QMgrName 指定的名称必须是 可连接 队列管理器的名称，如果正在使用队列管理器组，那么必须是队列管理器组的名称。

在 z/OS上，可以连接到的队列管理器由环境确定:
  • 对于 CICS，只能使用 CICS 系统所连接的队列管理器。 仍必须指定 QMgrName 参数，但将忽略其值; 空白字符是合适的选项。
  • 对于 IMS，只有在子系统定义表 (CSQQDEFV) 中列出的队列管理器 和 (在 IMS的 SSM 表中列出) 可连接 (请参阅用法说明 6 )。
  • 对于 z/OS 批处理和 TSO ，只有与应用程序位于同一系统上的队列管理器才可连接 (请参阅用法说明 6 )。

队列共享组: 在存在多个队列管理器并配置为构成队列共享组的系统上，可以为 QMgrName 指定队列共享组的名称以代替队列管理器的名称。 这允许应用程序连接到队列共享组中可用的 任何 队列管理器，该队列共享组与应用程序位于同一 z/OS 映像上。 还可以配置系统，以便使用空白 QMgrName 连接到队列共享组而不是缺省队列管理器。

如果 QMgrName 指定队列共享组的名称，但系统上也存在具有该名称的队列管理器，那么将建立与前者的连接。 仅当连接失败时，才会尝试连接到队列共享组中的其中一个队列管理器。

如果连接成功，那么您可以使用由 MQCONN 或 MQCONNX 调用返回的句柄来访问属于已连接到的队列管理器的所有资源（包括已共享和未共享的资源）。 对这些资源的访问受到典型授权控件的影响。

如果应用程序发出两个 MQCONN 或 MQCONNX 调用以建立并发连接，并且一个或两个调用指定队列共享组的名称，那么第二个调用在与第一个调用连接到同一队列管理器时返回完成代码 MQCC_WARNING 和原因码 MQRC_ALREADY_CONNECTED。

仅在 z/OS上支持队列共享组。 仅在批处理， RRS 批处理， CICS和 TSO 环境中支持与队列共享组的连接。 对于 CICS，只能使用 CICS 系统所连接的队列共享组。 仍必须指定 QMgrName 参数，但忽略其值；空白字符为适合的选项。
注意: IMS 无法连接到队列共享组。

IBM MQ MQI client 应用程序: 对于 IBM MQ MQI client 应用程序，将针对具有指定队列管理器名称的每个客户机连接通道定义尝试连接，直到成功为止。 但此队列管理器的名称必须与指定名称相同。 如果指定了全空白名称，那么将尝试每个具有全空白队列管理器名称的客户机连接通道，直到成功为止; 在这种情况下，不会检查队列管理器的实际名称。

IBM MQ 客户机应用程序在 z/OS中不受支持，但 z/OS 可以充当 IBM MQ 客户机应用程序可以连接到的 IBM MQ 服务器。

IBM MQ MQI client 队列管理器组: 如果指定的名称以星号 (*) 开头，那么与之建立连接的队列管理器的名称可能与应用程序指定的名称不同。 指定的名称（不含星号）可定义一组可连接的队列管理器。 此实施会从组中选择一个队列管理器，方法是轮流尝试每个队列管理器，直到找到可连接的队列管理器为止。 尝试连接的顺序受到客户机通道权重和候选通道的连接亲缘关系值的影响。 如果组中没有任何队列管理器可供连接，那么调用失败。 每个队列管理器仅尝试一次。 如果为名称指定了单独的星号，那么将使用实现定义的缺省队列管理器组。

仅在 MQ-client 环境中运行的应用程序支持队列管理器组; 如果非客户机应用程序指定以星号开头的队列管理器名称，那么调用将失败。 通过提供具有相同队列管理器名称 (不带星号的指定名称) 的多个客户机连接通道定义来定义组，以与组中的每个队列管理器进行通信。 通过提供一个或多个客户机连接通道定义来定义缺省组，每个客户机连接通道定义都具有空白队列管理器名称 (因此，指定全空白名称与为客户机应用程序的名称指定单个星号具有相同的效果)。

连接到组的一个队列管理器后，应用程序可以在消息和对象描述符中的队列管理器名称字段中以典型方式指定空白，以表示应用程序已连接到的队列管理器 ( 本地队列管理器 ) 的名称。 如果应用程序需要知道此名称，请使用 MQINQ 调用来查询 QMgrName 队列管理器属性。

在连接名称中使用星号作为前缀表示应用程序不依赖于连接到组中的特定队列管理器。 适合的应用程序为：
  • 放置消息但不获取消息的应用程序。
  • 放置请求消息然后从临时动态队列中获取应答消息的应用程序。
不适合的应用程序为需要从特定队列管理器中的特定队列获取消息的应用程序；此类应用程序不得使用星号作为其名称的前缀。

如果指定星号，那么此名称的剩余部分的最大长度为 47 个字符。

此参数的长度由 MQ_Q_MGR_NAME_LENGTH 提供。

Hconn
类型：MQHCONN - 输出

此句柄表示与队列管理器的连接。 在由应用程序发出的所有后续消息排队调用上指定此句柄。 发出 MQDISC 调用时，或者当定义句柄作用域的处理单元终止时，此句柄将不再有效。

IBM MQ 现在提供了具有客户机软件包和服务器软件包的 mqm 库。 这意味着执行 mqm 库中找到的 MQI 调用时，将检查连接类型以查看它属于客户机连接还是服务器连接，然后执行正确的底层调用。 因此，现在可针对 mqm 库链接传递 Hconn 的出口，但在客户机安装上使用此出口。

句柄作用域: 返回的句柄作用域取决于用于连接到队列管理器 (MQCONN 或 MQCONNX) 的调用。 如果使用的调用是 MQCONNX ，那么句柄的作用域还取决于 MQCNO 结构的 Options 字段中指定的 MQCNO_HANDLE_SHARE_ * 选项。
  • 如果调用为 MQCONN，或者如果指定了 MQCNO_HANDLE_SHARE_NONE 选项，那么返回的句柄为非共享句柄。
    非共享句柄的范围是运行应用程序的平台所支持的最小并行处理单元（详见 表 1）；句柄在发出调用的并行处理单元之外无效。
  • 如果指定 MQCNO_HANDLE_SHARE_BLOCK 或 MQCNO_HANDLE_SHARE_NO_BLOCK 选项，那么返回的句柄为共享句柄。

    共享句柄的作用域为拥有从中发出调用的线程的进程；可从属于该进程的任何线程使用此句柄。 并非所有平台都支持线程。

  • 如果 MQCONN 或 MQCONNX 调用失败，并且完成代码为 MQCC_FAILED，那么 Hconn 值未定义。
表 1. 各种平台上非共享句柄的作用域
平台 非共享句柄的作用域
z/OS
  • CICS: CICS 任务
  • IMS: 任务，直至下一个同步点 (不包括任务的子任务)
  • z/OS 批处理和 TSO: 任务 (不包括任务的子任务)
IBM i 作业
AIX® and Linux® 线程
32 位 Windows 应用程序 线程
64 位 Windows 应用程序 线程
在 z/OS for CICS 应用程序上，返回的值为:
MQHC_DEF_HCONN
缺省连接句柄。
CompCode
类型：MQLONG - 输出
完成代码；此完成代码为以下其中一项：
MQCC_OK
成功完成。
MQCC_WARNING
警告（部分完成）。
MQCC_FAILED
调用失败。
原因
类型：MQLONG - 输出
如果 CompCode 为 MQCC_OK:
MQRC_NONE
(0, X'000') 没有要报告的原因。
如果 CompCode 为 MQCC_WARNING:
MQRC_ALREADY_CONNECTED
(2002, X'7D2') 应用程序已连接。
MQRC_CLUSTER_EXIT_LOAD_ERROR
(2267, X'8DB') 无法装入集群工作负载出口。
MQRC_SSL_ALREADY_INITIALIZED
(2391, X'957') 已初始化 SSL。
如果 CompCode 是 MQCC_FAILED:
MQRC_ADAPTER_CONN_LOAD_ERROR
(2129, X'851') 无法装入适配器连接模块。
MQRC_ADAPTER_DEFS_ERROR
(2131, X'853') 适配器子系统定义模块无效。
MQRC_ADAPTER_DEFS_LOAD_ERROR
(2132, X'854') 无法装入适配器子系统定义模块。
MQRC_ADAPTER_NOT_AVAILABLE
(2204, X'89C') 适配器不可用。
MQRC_ADAPTER_SERV_LOAD_ERROR
(2130, X'852') 无法装入适配器服务模块。
MQRC_ADAPTER_STORAGE_SHORTAGE
(2127, X'84F') 适配器存储空间不足。
MQRC_ANOTHER_Q_MGR_CONNECTED
(2103, X'837') 已连接另一个队列管理器。
MQRC_API_EXIT_ERROR
(2374, X'946') API 出口失败。
MQRC_API_EXIT_INIT_ERROR
(2375, X'947') API 出口初始化失败。
MQRC_API_EXIT_TERM_ERROR
(2376, X'948') 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_CONN_ID_IN_USE
(2160, X'870') 连接标识已在使用中。
MQRC_CONNECTION_BROKEN
(2009, X'7D9') 与队列管理器的连接丢失。
MQRC_CONNECTION_ERROR
(2273, X'8E1') 处理 MQCONN 调用时出错。
MQRC_CONNECTION_NOT_AVAILABLE
(2568, X'A08') 当队列管理器无法在当前安装中提供所请求连接类型的连接时，在 MQCONN 或 MQCONNX 调用上发生此情况。 无法在纯服务器安装中进行客户机连接。 无法在纯客户机安装中进行本地连接。
MQRC_CONNECTION_QUIESCING
(2202, X'89A') 连接正在停顿。
MQRC_CONNECTION_STOPPING
(2203, X'89B') 连接正在关闭。
MQRC_CRYPTO_HARDWARE_ERROR
(2382, X'94E') 加密硬件配置错误。
MQRC_DUPLICATE_RECOV_COORD
(2163, X'873') 恢复协调程序已存在。
MQRC_ENVIRONMENT_ERROR
(2012, X'7DC') 调用在环境中无效。

此外，在 MQCONNX 调用中，从 CICS 或 IMS 应用程序传递 MQCSP - 安全参数控制块。

MQRC_HCONN_ERROR
(2018, X'7E2') 连接句柄无效。
MQRC_HOST_NOT_AVAILABLE
(2538, X'9EA') 从客户机发出了 MQCONN 调用以连接到队列管理器，但尝试将对话分配给远程系统失败。
MQRC_INSTALLATION_MISMATCH
(2583, X'A17') 在队列管理器安装与所选库之间存在不匹配。
MQRC_KEY_REPOSITORY_ERROR
(2381, X'94D') 密钥存储库无效。
MQRC_MAX_CONNS_LIMIT_REACHED
(2025, X'7E9') 已达到最大连接数。
MQRC_NOT_AUTHORIZED
(2035, X'7F3') 未获得访问授权。
MQRC_OPEN_FAILED
(2137, X'859') 对象未成功打开。
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_SECURITY_ERROR
(2063, X'80F') 发生了安全性错误。
MQRC_SSL_INITIALIZATION_ERROR
(2393, X'959') SSL 初始化错误。
MQRC_STORAGE_NOT_AVAILABLE
(2071, X'817') 没有足够的存储空间可用。
MQRC_UNEXPECTED_ERROR
(2195, X'893') 发生了意外错误。

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

使用说明

  1. 使用 MQCONN 调用连接到的队列管理器称为本地队列管理器。
  2. 由本地队列管理器所拥有的队列对于该应用程序显示为本地队列。 可以在这些队列中放置消息和获取消息。

    本地队列管理器所属的队列共享组所拥有的共享队列将作为本地队列显示给应用程序。 可以在这些队列中放置消息和获取消息。

    由远程队列管理器所拥有的队列显示为远程队列。 可以在这些队列上放置消息，但是不能从中获取消息。

  3. 如果队列管理器在应用程序运行时失败，那么应用程序必须再次发出 MQCONN 调用以获取要在后续 IBM MQ 调用中使用的新连接句柄。 此应用程序可以定期发出 MQCONN 调用，直至调用成功为止。

    如果应用程序不确定是否已连接到队列管理器，那么该应用程序可以安全地发出 MQCONN 调用以获取连接句柄。 如果该应用程序已连接，那么返回的句柄与先前 MQCONN 调用返回的句柄相同，但会显示完成代码 MQCC_WARNING 和原因码 MQRC_ALREADY_CONNECTED。

  4. 当应用程序完成使用 IBM MQ 调用时，应用程序必须使用 MQDISC 调用与队列管理器断开连接。
  5. 如果 MQCONN 调用失败，并且完成代码为 MQCC_FAILED，那么 Hconn 值未定义。
  6. 在 z/OS 上：
    • 批处理， TSO 和 IMS 应用程序必须发出 MQCONN 调用以使用其他 IBM MQ 调用。 这些应用程序可同时连接到多个队列管理器。

      如果队列管理器发生故障，那么队列管理器重新启动后，该应用程序必须重新发出此调用以获取新的连接句柄。

      尽管 IMS 应用程序可以重复发出 MQCONN 调用 (即使已连接) ，但不建议对联机消息处理程序 (MPP) 执行此操作。

    • CICS 应用程序不必发出 MQCONN 调用以使用其他 IBM MQ 调用，但可以根据需要执行此操作; 接受 MQCONN 调用和 MQDISC 调用。 但是，不能同时连接到多个队列管理器。

      如果队列管理器发生故障，那么队列管理器重新启动时，这些应用程序会自动重新连接，因此无需发出 MQCONN 调用。

  7. 在 z/OS上，要定义可用队列管理器:
    • 对于批处理应用程序，系统程序员可以使用 CSQBDEF 宏来创建用于定义缺省队列管理器名称或队列共享组名的模块 (CSQBDEFV)。
    • 对于 IMS 应用程序，系统程序员可以使用 CSQQDEFX 宏来创建模块 (CSQQDEFV) ，该模块定义可用队列管理器的名称并指定缺省队列管理器。

      此外，必须将每个队列管理器定义到 IMS 控制区域以及访问该队列管理器的每个从属区域。 为此，必须在 IMS中创建子系统成员。PROCLIB 库并将子系统成员标识到适用的 IMS 区域。 如果应用程序尝试连接到未在其 IMS 区域的子系统成员中定义的队列管理器，那么应用程序将异常终止。

    [z/OS] 有关使用这些宏的更多信息，请参阅 供客户使用的宏。

  8. 在 IBM i上，异常结束的程序不会自动与队列管理器断开连接。 请编写应用程序以允许 MQCONN 或 MQCONNX 调用返回完成代码 MQCC_WARNING 和原因码 MQRC_ALREADY_CONNECTED。 在此情况下，请正常使用返回的连接句柄。

C 调用

MQCONN (QMgrName, &Hconn, &CompCode, &Reason);
按如下所示声明参数：
MQCHAR48  QMgrName;  /* Name of queue manager */
MQHCONN   Hconn;     /* Connection handle */
MQLONG    CompCode;  /* Completion code */
MQLONG    Reason;    /* Reason code qualifying CompCode */

COBOL 调用

CALL 'MQCONN' USING QMGRNAME, HCONN, COMPCODE, REASON.
按如下所示声明参数：
**   Name of queue manager
 01  QMGRNAME  PIC X(48).
**   Connection handle
 01  HCONN     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 MQCONN (QMgrName, Hconn, CompCode, Reason);
按如下所示声明参数：
dcl QMgrName  char(48);       /* Name of queue manager */
dcl Hconn     fixed bin(31);  /* Connection handle */
dcl CompCode  fixed bin(31);  /* Completion code */
dcl Reason    fixed bin(31);  /* Reason code qualifying CompCode */

高级汇编程序调用

CALL MQCONN,(QMGRNAME,HCONN,COMPCODE,REASON)
按如下所示声明参数：
QMGRNAME  DS  CL48  Name of queue manager
HCONN     DS  F     Connection handle
COMPCODE  DS  F     Completion code
REASON    DS  F     Reason code qualifying COMPCODE

Visual Basic 调用

MQCONN QMgrName, Hconn, CompCode, Reason
按如下所示声明参数：
Dim QMgrName As String*48 'Name of queue manager'
Dim Hconn    As Long      'Connection handle'
Dim CompCode As Long      'Completion code'
Dim Reason   As Long      'Reason code qualifying CompCode'