MQCONN - 连接队列管理器

语法

MQCONN（QMgrName、Hconn、CompCode、Reason）

参数

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 客户机环境中运行的应用程序才支持队列管理器组；如果非客户机应用程序指定以星号开头的队列管理器名称，那么调用将失败。 通过提供多个具有相同队列管理器名称（不含星号的指定名称）的客户机连接通道定义来定义组，以与组中每个队列管理器进行通信。 通过提供一个或多个客户机连接通道定义来定义缺省组，其中每个都具有空白的队列管理器名称（指定全空白名称从而实现与针对每个客户机应用程序名称指定一个星号相同的效果）。

连接到组中某个队列管理器后，应用程序可以像通常一样在消息和对象描述符中的队列管理器名称字段中指定空白，表示应用程序已连接到的队列管理器（本地队列管理器）的名称。 如果应用程序需要知道此名称，请使用 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	作业
UNIX 系统	线程
16 位 Windows 应用程序	进程
32 位 Windows 应用程序	线程

在 z/OS for CICS 应用程序和 IBM i 上，对于以兼容性方式运行的应用程序，返回的值为:

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 区域的子系统成员中定义的队列管理器，那么应用程序将异常终止。

   有关使用这些宏的更多信息，请参阅 旨在供客户使用的宏。

8. 在 IBM i上，为队列管理器的先前发行版编写的应用程序可以在不重新编译的情况下运行。 这称为 兼容性方式。 此操作方式为应用程序提供兼容的运行时环境。 它包括以下内容:
   • 驻留在库 QMQM 中的服务程序 AMQZSTUB。

     AMQZSTUB 提供与先前发行版相同的公共接口，并且具有相同的签名。 使用此服务程序通过绑定过程调用访问 MQI。

   • 驻留在库 QMQM 中的程序 QMQM。

     QMQM 提供了通过动态程序调用访问 MQI 的方法。

   • 驻留在库 QMQM 中的程序 MQCLOSE ， MQCONN ，MQ光盘， MQGET ， MQINQ ， MQOPEN ， MQPUT ， MQPUT1和 MQSET。

     这些程序还提供了通过动态程序调用访问 MQI 的方法，但具有对应于 IBM MQ 调用的标准描述的参数列表。

   这三个接口不包含 IBM MQ V 5.1中引入的功能。 例如，不支持 MQBACK ， MQCMIT 和 MQCONNX 调用。 这些接口提供的支持仅适用于单线程应用程序。

   通过服务程序 LIBMQM 和 LIBMQM_R 提供对单线程应用程序中新 IBM MQ 调用以及多线程应用程序中所有 IBM MQ 调用的支持。

   重要信息: 如果仍在使用兼容性方式，请考虑重新编译应用程序并改为使用静态绑定调用。 请参阅 IBM i上 RPG 应用程序的兼容性方式
9. 在 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'