MQOPEN-打开对象

MQOPEN 调用建立对对象的访问权。

以下类型的对象有效:
  • 队列 (包括分发列表)
  • 名称列表
  • 进程定义
  • 队列管理器
  • Topic

语法

MQOPEN （Hconn、 ObjDesc、 Options 、Hobj、 CompCode、 Reason ）

参数

Hconn
类型 :MQHCONN-输入

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

在 z/OS® (对于 CICS® 应用程序) 和 IBM® i (对于以兼容性方式运行的应用程序) 上，可以省略 MQCONN 调用，并为 Hconn指定以下值:
MQHC_DEF_HCONN
缺省连接句柄。
ObjDesc
类型 :MQOD-输入/输出

这是用于标识要打开的对象的结构; 请参阅 MQOD-对象描述符 以获取详细信息。

如果 ObjDesc 参数中的 ObjectName 字段是模型队列的名称，那么将使用模型队列的属性创建动态本地队列; 这将发生您在 Options 参数上指定的任何选项。 使用 MQOPEN 调用返回的 Hobj 的后续操作将在新的动态队列上执行，而不是在模型队列上执行。 即使对于 MQINQ 和 MQSET 调用也是如此。 ObjDesc 参数中模型队列的名称将替换为创建的动态队列的名称。 动态队列的类型由模型队列的 DefinitionType 属性值确定 (请参阅 队列属性)。 有关适用于动态队列的关闭选项的信息，请参阅 MQCLOSE 调用的描述。

选项
类型 :MQLONG-输入
必须至少指定下列其中一个选项:
  • MQOO_BROWSE
  • MQOO_INPUT_ * (仅其中一个)
  • MQOO_INQUIRE
  • MQOO_OUTPUT
  • MQOO_SET
  • MQOO_BIND_ * (仅其中一个)
请参阅下表以获取这些选项的详细信息; 可以根据需要指定其他选项。 如果需要多个选项，那么值可以是:
  • 一起添加 (请勿多次添加同一常量) ，或者
  • 通过按位“或”运算组合在一起（如果编程语言支持位运算）。
将记录无效的组合; 所有其他组合都有效。 只允许使用适用于 ObjDesc 指定的对象类型的选项。 下表显示了查询和主题的有效 MQOPEN 选项。
选项 别名 1 本地和模型 远程 非本地集群 分发列表 Topic
MQOO_INPUT_AS_Q_DEF Yes Yes 否 否 否 否
MQOO_INPUT_SHARED Yes Yes 否 否 否 否
MQOO_INPUT_EXCLUSIVE Yes Yes 否 否 否 否
MQOO_OUTPUT Yes Yes Yes Yes Yes Yes
MQOO_BROWSE Yes Yes 否 否 否 否
MQOO_CO_OP Yes Yes 否 否 否 否
MQOO_INQUIRE Yes Yes 2 Yes 否 否
MQOO_SET Yes Yes 2 否 否 否
MQOO_BIND_ON_OPEN 3 Yes Yes Yes Yes Yes 否
MQOO_BIND_NOT_FIXED 3 Yes Yes Yes Yes Yes 否
MQOO_BIND_ON_GROUP 3 Yes Yes Yes Yes Yes 否
MQOO_BIND_AS_Q_DEF 3 Yes Yes Yes Yes Yes 否
MQOO_SAVE_ALL_CONTEXT Yes Yes 否 否 否 否
MQOO_PASS_IDENTITY_CONTEXT Yes Yes Yes Yes Yes 4
MQOO_PASS_ALL_CONTEXT Yes Yes Yes Yes Yes Yes
MQOO_SET_IDENTITY_CONTEXT Yes Yes Yes Yes Yes 4
MQOO_SET_ALL_CONTEXT Yes Yes Yes Yes Yes Yes
MQOO_NO_READ_AHEAD Yes Yes 否 否 否 否
MQOO_READ_AHEAD Yes Yes 否 否 否 否
MQOO_READ_AHEAD_AS_Q_DEF Yes Yes 否 否 否 否
MQOO_ALTERNATE_USER_AUTHORITY Yes Yes Yes Yes Yes Yes
MQOO_FAIL_IF_QUIESCING Yes Yes Yes Yes Yes Yes
MQOO_RESOLVE_LOCAL_Q Yes Yes Yes Yes 否 否
MQOO_RESOLVE_LOCAL_TOPIC 否 否 否 否 否 Yes
MQOO_NO_多点广播 否 否 否 否 否 Yes
注：
  1. 别名选项的有效性取决于别名解析到的队列的选项的有效性。
  2. 此选项仅对远程队列的本地定义有效。
  3. 可以为任何队列类型指定此选项，但如果队列不是集群队列，那么将忽略此选项。 但是，即使别名队列不在集群中， DefBind 队列属性也会覆盖基本队列。
  4. 这些属性可与主题配合使用，但仅影响保留消息的上下文集，而不影响发送给任何订户的上下文字段。
访问选项: 以下选项控制可以对对象执行的操作的类型:
MQOO_INPUT_AS_Q_DEF
打开队列以使用队列定义的缺省值获取消息。

打开队列以与后续 MQGET 调用配合使用。 访问类型为共享或互斥，具体取决于 DefInputOpenOption 队列属性的值; 请参阅 队列属性 以获取详细信息。

此选项仅对本地队列，别名队列和模型队列有效; 对于非队列的远程队列，分发列表和对象无效。

MQOO_INPUT_SHARED
打开队列以获取具有共享访问权的消息。

打开队列以与后续 MQGET 调用配合使用。 如果队列当前由此应用程序或另一个应用程序使用 MQOO_INPUT_SHARED 打开，但如果队列当前使用 MQOOO_INPUT_EXCLUSIVE 打开，那么调用可能成功失败，原因码为 MQRC_OBJECT_IN_USE。

此选项仅对本地队列，别名队列和模型队列有效; 对于非队列的远程队列，分发列表和对象无效。

MQOO_INPUT_EXCLUSIVE
打开队列以获取具有独占访问权的消息。

打开队列以与后续 MQGET 调用配合使用。 如果此应用程序或其他应用程序当前打开队列以用于任何类型的输入 (MQOO_INPUT_SHARED 或 MQOO_INPUT_EXCLUSIVE) ，那么调用将失败并返回原因码 MQRC_OBJECT_IN_USE。

此选项仅对本地队列，别名队列和模型队列有效; 对于非队列的远程队列，分发列表和对象无效。

MQOO_OUTPUT

打开队列以放置消息，或打开主题或主题字符串以发布消息。

打开队列或主题以用于后续 MQPUT 调用。

使用此选项的 MQOPEN 调用可能成功，即使 InhibitPut 队列属性设置为 MQQA_PUT_ALLOWED (尽管在此属性设置为此值时后续 MQPUT 调用失败) 也是如此。

此选项对所有类型的队列 (包括分发列表和主题) 都有效。

以下说明适用于这些选项:
  • 只能指定其中一个选项。
  • 具有这些选项之一的 MQOPEN 调用可能会成功，即使 InhibitGet 队列属性设置为 MQQA_GET_ALLOWED (尽管后续 MQGET 调用在该属性设置为该值时失败) 也是如此。
  • 如果将队列定义为不可共享 (即， Shareability 队列属性的值为 MQQA_NOT_SHAREABLE) ，那么打开共享访问队列的尝试将被视为尝试打开具有互斥访问权的队列。
  • 如果使用其中一个选项打开别名队列，那么针对别名解析到的基本队列的互斥使用测试 (或其他应用程序是否具有互斥使用)。
  • 如果 ObjectQMgrName 是队列管理器别名的名称，那么这些选项无效; 即使用于队列管理器别名判别的远程队列的本地定义中的 RemoteQMgrName 属性值是本地队列管理器的名称，也是如此。
MQOO_BROWSE
打开队列以浏览消息。
将打开此队列以用于具有下列其中一个选项的后续 MQGET 调用:
  • MQGMO_BROWSE_FIRST
  • MQGMO_BROWSE_NEXT
  • MQGMO_BROWSE_MSG_UNDER_CURSOR
即使当前针对 MQOO_INPUT_EXCLUSIVE 打开了队列，也允许执行此操作。 带有 MQOO_BROWSE 选项的 MQOPEN 调用将建立浏览光标，并将其逻辑地定位在队列上的第一条消息之前; 请参阅 MQGMO-选项字段 以获取更多信息。

此选项仅对本地队列，别名队列和模型队列有效; 对于非队列的远程队列，分发列表和对象无效。 如果 ObjectQMgrName 是队列管理器别名的名称，那么此属性也无效; 即使用于队列管理器别名判别的远程队列的本地定义中的 RemoteQMgrName 属性值是本地队列管理器的名称，也是如此。

MQOO_CO_OP
作为一组手柄的协同成员打开。

此选项仅对 MQOO_BROWSE 选项有效。 如果未指定 MQOO_BROWSE ，那么 MQOPEN 将返回 MQRC_OPTIONS_ERROR。

返回的句柄被视为具有下列其中一个选项的后续 MQGET 调用的协同句柄集的成员:
  • MQGMO_MARK_BROWSE_CO_OP
  • MQGMO_UNMARKED_BROWSE_MSG
  • MQGMO_UNMARK_BROWSE_CO_OP

此选项仅对本地队列，别名队列和模型队列有效; 对于非队列的远程队列，分发列表和对象无效。

MQOO_INQUIRE
打开对象以查询属性。

打开队列，名称列表，进程定义或队列管理器以用于后续 MQINQ 调用。

此选项对除分发列表以外的所有类型的对象有效。 如果 ObjectQMgrName 是队列管理器别名的名称，那么此属性无效; 即使用于队列管理器别名判别的远程队列的本地定义中的 RemoteQMgrName 属性值是本地队列管理器的名称，也是如此。

MQOO_SET
打开队列以设置属性。

打开队列以用于后续 MQSET 调用。

此选项对除分发列表以外的所有类型的队列都有效。 如果 ObjectQMgrName 是远程队列的本地定义的名称，那么此属性无效; 即使用于队列管理器别名判别的远程队列的本地定义中的 RemoteQMgrName 属性值是本地队列管理器的名称，也是如此。

绑定选项: 当要打开的对象是集群队列时，以下选项适用; 这些选项控制队列句柄与集群队列实例的绑定:
MQOO_BIND_ON_OPEN
当打开队列时，本地队列管理器将队列句柄绑定到目标队列的实例。 因此，使用此句柄放入的所有消息都将发送到目标队列的同一实例，并通过同一路径发送。

此选项仅对于队列有效，并且仅影响集群队列。 如果为不是集群队列的队列指定此选项，则会忽略此选项。

MQOO_BIND_NOT_FIXED
这将停止本地队列管理器将队列句柄绑定到目标队列的实例。 因此，使用此句柄的连续 MQPUT 调用会将消息发送到目标队列的 不同 实例，或者发送到同一实例，但通过不同的路径。 它还允许选择的实例稍后由本地队列管理器，远程队列管理器或消息通道代理程序 (MCA) 根据网络条件进行更改。
注: 需要交换 一系列 消息以完成事务的客户机和服务器应用程序不得使用 MQOO_BIND_NOT_FIXED (或者当 DefBind 具有值 MQBND_BIND_NOT_FIXED 时使用 MQOO_BIND_AS_Q_DEF) ，因为系列中的连续消息可能会发送到服务器应用程序的不同实例。

如果为集群队列指定了 MQOO_BROWSE 或其中一个 MQOO_INPUT_ * 选项，那么将强制队列管理器选择集群队列的本地实例。 因此，队列句柄的绑定是固定的，即使指定了 MQOO_BIND_NOT_FIXED 也是如此。

如果使用 MQOO_BIND_NOT_FIXED 指定了 MQOOO_INQUIRE ，那么使用该句柄的连续 MQINQ 调用可能会查询集群队列的不同实例，尽管通常所有实例都具有相同的属性值。

MQOO_BIND_NOT_FIXED 仅对队列有效，并且仅影响集群队列。 如果为不是集群队列的队列指定此选项，则会忽略此选项。

MQOO_BIND_ON_GROUP
允许应用程序请求将一组消息全部分配给同一目标实例。

此选项仅对于队列有效，并且仅影响集群队列。 如果为不是集群队列的队列指定此选项，则会忽略此选项。

MQOO_BIND_AS_Q_DEF
本地队列管理器以 DefBind 队列属性定义的方式绑定队列句柄。 此属性的值为 MQBND_BIND_ON_OPEN ， MQBND_BIND_NOT_FIXED 或 MQBND_BIND_ON_GROUP。

当未指定 MQOO_BIND_ON_OPEN ， MQOO_BIND_NOT_FIXED 或 MQOO_BIND_ON_GROUP 时， MQOO_BIND_AS_Q_DEF 是缺省值。

MQOO_BIND_AS_Q_DEF 辅助程序文档。 不打算将此选项与其他两个绑定选项中的任何一个一起使用，但由于其值为零，因此无法检测到使用情况。

上下文选项: 以下选项控制消息上下文的处理:
MQOO_SAVE_ALL_CONTEXT
上下文信息与此队列句柄相关联。 此信息是从使用此句柄检索的任何消息的上下文中设置的。 有关消息上下文的更多信息，请参阅 消息上下文 和 控制上下文信息。

可以将此上下文信息传递到消息，然后使用 MQPUT 或 MQPUT1 调用将此消息放入队列中。 请参阅 MQPMO-Put-message 选项中描述的 MQPMO_PASS_IDENTITY_CONTEXT 和 MQPMO_PASS_ALL_CONTEXT 选项。

在成功检索消息之前，无法将上下文传递到正在放入队列中的消息。

使用其中一个 MQGMO_BROWSE_ * 浏览选项检索的消息未保存其上下文信息 (尽管 MsgDesc 参数中的上下文字段是在浏览后设置的)。

此选项仅对本地队列，别名队列和模型队列有效; 对于非队列的远程队列，分发列表和对象无效。 必须指定其中一个 MQOO_INPUT_ * 选项。

MQOO_PASS_IDENTITY_CONTEXT
这允许在将消息放入队列时在 PutMsgOpts 参数中指定 MQPMO_PASS_IDENTITY_CONTEXT 选项; 这将为消息提供使用 MQOO_SAVE_ALL_CONTEXT 选项打开的输入队列中的身份上下文信息。 有关消息上下文的更多信息，请参阅 消息上下文 和 控制上下文信息。

必须指定 MQOO_OUTPUT 选项。

此选项对所有类型的队列 (包括分发列表) 有效。

MQOO_PASS_ALL_CONTEXT
这允许在将消息放入队列时在 PutMsgOpts 参数中指定 MQPMO_PASS_ALL_CONTEXT 选项; 这将为消息提供来自使用 MQOO_SAVE_ALL_CONTEXT 选项打开的输入队列的身份和源上下文信息。 有关消息上下文的更多信息，请参阅 消息上下文 和 控制上下文信息 。

此选项暗示 MQOO_PASS_IDENTITY_CONTEXT ，因此无需指定。 必须指定 MQOO_OUTPUT 选项。

此选项对所有类型的队列 (包括分发列表) 有效。

MQOO_SET_IDENTITY_CONTEXT
这允许在将消息放入队列时在 PutMsgOpts 参数中指定 MQPMO_SET_IDENTITY_CONTEXT 选项; 这将为消息提供包含在 MQPUT 或 MQPUT1 调用上指定的 MsgDesc 参数中的身份上下文信息。 有关消息上下文的更多信息，请参阅 消息上下文 和 控制上下文信息 。

此选项暗示 MQOO_PASS_IDENTITY_CONTEXT ，因此无需指定。 必须指定 MQOO_OUTPUT 选项。

此选项对所有类型的队列 (包括分发列表) 有效。

MQOO_SET_ALL_CONTEXT
这允许在将消息放入队列时在 PutMsgOpts 参数中指定 MQPMO_SET_ALL_CONTEXT 选项; 这将向消息提供 MQPUT 或 MQPUT1 调用上指定的 MsgDesc 参数中包含的身份和源上下文信息。 有关消息上下文的更多信息，请参阅 消息上下文 和 控制上下文信息 。
此选项意味着以下选项，因此无需指定这些选项:
  • MQOO_PASS_IDENTITY_CONTEXT
  • MQOO_PASS_ALL_CONTEXT
  • MQOO_SET_IDENTITY_CONTEXT
必须指定 MQOO_OUTPUT 选项。

此选项对所有类型的队列 (包括分发列表) 有效。

预读选项:

使用 MQOO_READ_AHEAD 调用 MQOPEN 时，仅当满足特定条件时， WebSphere® MQ 客户机才会启用预读。 这些条件包括：
  • 客户机和远程队列管理器都必须处于 WebSphere MQ V 7 或更高版本。
  • 必须针对线程 WebSphere MQ MQI 客户机库编译和链接客户机应用程序。
  • 客户机通道必须使用的是 TCP/IP 协议
  • 该通道必须在客户机和服务器通道定义中具有非零 SharingConversations (SHARECNV) 设置。
以下选项控制在应用程序请求非持久消息之前是否将其发送到客户机。 以下说明适用于预读选项:
  • 只能指定其中一个选项。
  • 这些选项仅对本地队列，别名队列和模型队列有效。 它们对于远程队列，分发列表，主题或队列管理器无效。
  • 仅当还指定了 MQOO_BROWSE ， MQOO_INPUT_SHARED 和 MQOO_INPUT_EXCLUSIVE 之一时，这些选项才适用，尽管使用 MQOOO_INQUIRE 或 MQOO_SET 指定这些选项不是错误。
  • 如果应用程序未作为 IBM WebSphere MQ 客户机运行，那么将忽略这些选项。
MQOO_NO_READ_AHEAD
在应用程序请求非持久消息之前，不会向客户机发送这些消息。
MQOO_READ_AHEAD
在应用程序请求非持久消息之前，会将非持久消息发送到客户机。
MQOO_READ_AHEAD_AS_Q_DEF
预读行为由正在打开的队列的缺省预读属性确定。 这是缺省值。
其他选项: 以下选项控制授权检查，队列管理器停顿时发生的情况，是否解析本地队列名称以及多点广播:
MQOO_ALTERNATE_USER_AUTHORITY
ObjDesc 参数中的 AlternateUserId 字段包含用于验证此 MQOPEN 调用的用户标识。 仅当此 AlternateUserId 有权使用指定的访问选项打开对象时，该调用才能成功，而不管运行应用程序的用户标识是否有权执行此操作。 这不适用于指定的任何上下文选项，但是，将始终根据运行应用程序的用户标识来检查这些上下文选项。

此选项对所有类型的对象都有效。

MQOO_FAIL_IF_QUIESCING
如果队列管理器处于停顿状态，那么 MQOPEN 调用将失败。

在 z/OS上，对于 CICS 或 IMS 应用程序，如果连接处于停顿状态，那么此选项还会强制 MQOPEN 调用失败。

此选项对所有类型的对象都有效。

有关客户机通道的信息，请参阅 IBM WebSphere MQ MQI 客户机概述 。

MQOO_RESOLVE_LOCAL_Q
使用打开的本地队列的名称填充 MQOD 结构中的 ResolvedQName 。 同样， ResolvedQMgrName 中包含托管本地队列的本地队列管理器的名称。 如果 MQOD 结构低于 V 3 ，那么将忽略 MQOO_RESOLVE_LOCAL_Q ，并且不会返回任何错误。

当打开本地队列、别名队列或模型队列时，总是返回本地队列，但当打开远程队列或非本地集群队列时，如果没有使用 MQOO_RESOLVE_LOCAL_Q 选项，则不会返回本地队列； ResolvedQName 和 ResolvedQMgrName 会被远程队列定义中的 RemoteQName 和 RemoteQMgrName 填充，或者与所选的远程集群队列类似。

如果在打开 (例如) 远程队列时指定 MQOO_RESOLVE_LOCAL_Q ，那么 ResolvedQName 是将消息放入的传输队列。 ResolvedQMgrName 中包含主持传输队列的本地队列管理器的名称。

如果您有权在队列上进行浏览，输入或输出，那么您具有在 MQOPEN 调用上指定此标志的必需权限。 不需要特殊权限。

此选项仅对队列和队列管理器有效。

MQOO_RESOLVE_LOCAL_TOPIC
使用打开的管理主题的名称填充 MQOD 结构中的 ResolvedQName 。
MQOO_NO_多点广播
不使用多点广播发送发布消息。

此选项仅对 MQOO_OUTPUT 选项有效。 如果未指定 MQOO_OUTPUT ，那么 MQOPEN 将返回 MQRC_OPTIONS_ERROR。

此选项仅对主题有效。

Hobj
类型 :MQHOBJ-输出

此句柄表示已建立的对对象的访问权。 必须在对该对象进行操作的后续 IBM WebSphere MQ 调用上指定此参数。 当发出 MQCLOSE 调用时，或者当定义句柄作用域的处理单元终止时，它将停止有效。

返回的对象句柄的作用域与调用上指定的连接句柄的作用域相同。 有关句柄作用域的信息，请参阅 MQCONN-Hconn 参数 。

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

限定 CompCode的原因码。

如果 CompCode 为 MQCC_OK：
MQRC_NONE
(0, X'000') 没有要报告的原因。
如果 CompCode 为 MQCC_WARNING：
MQRC_MULTIPLE_原因
(2136 ， X'858 ') 返回了多个原因码。
如果 CompCode 为 MQCC_FAILED：
MQRC_ADAPTER_NOT_AVAILABLE
(2204, X'89C') 适配器不可用。
MQRC_ADAPTER_SERV_LOAD_ERROR
(2130, X'852') 无法装入适配器服务模块。
MQRC_ALIAS_BASE_Q_TYPE_ERROR
（2001， X'7D1' ）别名基本队列不是有效类型。
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_AUTH_FAILED
(2348, X'92C' ) 耦合设施结构授权检查失败。
MQRC_CF_STRUC_ERROR
(2349, X'92D' ) 耦合设施结构无效。
MQRC_CF_STRUC_FAILED
(2373 ， X' 945 ') 耦合设施结构失败。
MQRC_CF_STRUC_IN_USE
(2346, X'92A' ) 耦合设施结构正在使用中。
MQRC_CF_STRUC_LIST_HDR_IN_USE
(2347, X'92B' ) 耦合设施结构列表标题正在使用中。
MQRC_CICS_WAIT_FAILED
(2140, X'85C' ) 等待请求被 CICS 拒绝。
MQRC_CLUSTER_EXIT_ERROR
(2266, X'8DA' ) 群集工作负载退出失败。
MQRC_CLUSTER_PUT_禁止
(2268, X'8DC' ) 禁止呼叫所有队列。
MQRC_CLUSTER_RESOLUTION_ERROR
(2189, X'88D' ) 群集名称解析失败。
MQRC_CLUSTER_RESOURCE_ERROR
(2269, X'8DD' ) 集群资源错误。
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_DB2_NOT_AVAILABLE
(2342 ， X' 926 ') DB2® 子系统不可用。
MQRC_DEF_XMIT_Q_TYPE_ERROR
(2198 ， X'896 ') 缺省传输队列不是本地传输队列。
MQRC_DEF_XMIT_Q_USAGE_ERROR
(2199 ， X'897 ') 缺省传输队列使用错误。
MQRC_DYNAMIC_Q_NAME_ERROR
（2011， X'7DB' ）动态队列名称无效。
MQRC_HANDLE_NOT_AVAILABLE
（2017， X'7E1' ）没有可用的手柄。
MQRC_HCONN_ERROR
(2018, X'7E2') 连接句柄无效。
MQRC_HOBJ_ERROR
(2019, X'7E3' ) 对象句柄无效。
MQRC_MULTIPLE_原因
(2136 ， X'858 ') 返回了多个原因码。
MQRC_NAME_IN_USE
(2201 ， X'899 ') 名称正在使用中。
MQRC_NAME_NOT_VALID_FOR_TYPE
(2194 ， X'892 ') 对象名对对象类型无效。
MQRC_NOT_AUTHORIZED
(2035, X'7F3') 未获得访问授权。
MQRC_OBJECT_ALREADY_EXISTS
(2100 ， X'834 ') 对象存在。
MQRC_OBJECT_DAMAGED
(2101 ， X'835 ') 对象已损坏。
MQRC_OBJECT_IN_USE
(2042, X'7FA' ) 对象已打开，选项冲突。
MQRC_OBJECT_LEVEL_不兼容
(2360 ， X' 938 ') 对象级别不兼容。
MQRC_OBJECT_NAME_ERROR
(2152 ， X'868 ') 对象名无效。
MQRC_OBJECT_NOT_UNIQUE
(2343 ， X' 927 ') 对象不唯一。
MQRC_OBJECT_Q_MGR_NAME_ERROR
(2153 ， X'869 ') 对象队列管理器名称无效。
MQRC_OBJECT_RECORDS_ERROR
(2155, X'86B' ) 对象记录无效。
MQRC_OBJECT_STRING_ERROR
(2441 ， X'0989 ') Objectstring 字段无效
MQRC_OBJECT_TYPE_ERROR
(2043, X'7FB' ) 对象类型无效。
MQRC_OD_ERROR
(2044, X'7FC' ) 对象描述符结构无效。
MQRC_OPTION_NOT_VALID_FOR_TYPE
(2045, X'7FD' ) 选项不适用于对象类型。
MQRC_OPTIONS_ERROR
(2046, X'7FE' ) 选项无效或不一致。
MQRC_PAGESET_ERROR
(2193 ， X'891 ') 访问页集数据集时出错。
MQRC_PAGESET_FULL
(2192 ， X'890 ') 外部存储介质已满。
MQRC_Q_DELETED
(2052 ， X'804 ') 队列已删除。
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_Q_TYPE_ERROR
(2057 ， X'809 ') 队列类型无效。
MQRC_RECS_PRESENT_ERROR
(2154, X'86A' ) 当前记录数无效。
MQRC_REMOTE_Q_NAME_ERROR
(2184 ， X'888 ') 远程队列名无效。
MQRC_RESOURCE_PROBLEM
(2102, X'836') 没有足够系统资源可用。
MQRC_RESPONSE_RECORDS_ERROR
(2156, X'86C' ) 响应记录无效。
MQRC_SECURITY_ERROR
(2063, X'80F') 发生了安全性错误。
MQRC_SELECTOR_SYNTAX_ERROR
2459 ( X'099B' ) 发送了 MQOPEN、 MQPUT1 或 MQSUB 调用，但指定的选择字符串包含语法错误。
MQRC_STOPPED_BY_CLUSTER_EXIT
(2188, X'88C' ) 集群工作负载退出导致呼叫被拒。
MQRC_STORAGE_MEDIUM_FULL
(2192 ， X'890 ') 外部存储介质已满。
MQRC_STORAGE_NOT_AVAILABLE
(2071, X'817') 没有足够的存储空间可用。
MQRC_SUPPRESSED_BY_EXIT
(2109, X'83D' ) 退出程序后，呼叫被取消。
MQRC_UNEXPECTED_ERROR
(2195, X'893') 发生了意外错误。
MQRC_UNKNOWN_ALIAS_BASE_Q
(2082 ， X'822 ') 未知别名基本队列。
MQRC_UNKNOWN_DEF_XMIT_Q
(2197 ， X'895 ') 未知缺省传输队列。
MQRC_UNKNOWN_OBJECT_NAME
(2085 ， X'825 ') 未知对象名。
MQRC_UNKNOWN_OBJECT_Q_MGR
(2086 ， X'826 ') 未知对象队列管理器。
MQRC_UNKNOWN_REMOTE_Q_MGR
(2087 ， X'827 ') 未知远程队列管理器。
MQRC_UNKNOWN_XMIT_Q
(2196 ， X'894 ') 未知传输队列。
MQRC_不法 _cf_level
(2366, X'93E' ) 耦合设施结构水平错误。
MQRC_XMIT_Q_TYPE_ERROR
(2091, X'82B' ) 传输队列不是本地的。
MQRC_XMIT_Q_USAGE_ERROR
(2092, X'82C' ) 传输队列使用错误。
有关这些代码的详细信息，请参阅:
  • 所有其他 IBM WebSphere MQ 平台 ( z/OS除外) 的 原因码 。

一般使用说明

  1. 打开的对象是下列其中一项:
    • 要执行以下操作的队列:
      • 获取或浏览消息 (使用 MQGET 调用)
      • 放置消息 (使用 MQPUT 调用)
      • 查询队列的属性 (使用 MQINQ 调用)
      • 设置队列的属性 (使用 MQSET 调用)

      如果指定的队列是模型队列，那么将创建动态本地队列。 请参阅 MQOPEN-Open 对象中描述的 ObjDesc 参数。

      分发列表是包含队列列表的特殊类型的队列对象。 可以打开它来放置消息，但不能获取或浏览消息，也不能查询或设置属性。 请参阅用法说明 8 以获取更多详细信息。

      具有 QSGDISP(GROUP) 的队列是无法与 MQOPEN 或 MQPUT1 调用配合使用的特殊类型的队列定义。

    • 用于查询列表中队列的名称的名称列表 (使用 MQINQ 调用)。
    • 用于查询进程属性的进程定义 (使用 MQINQ 调用)。
    • 用于查询本地队列管理器属性的队列管理器 (使用 MQINQ 调用)。
    • 用于发布消息的主题 (使用 MQPUT 调用)
  2. 应用程序可以多次打开同一对象。 对于每个打开的对象，将返回不同的对象句柄。 返回的每个句柄都可用于执行相应打开的功能。
  3. 如果要打开的对象是除集群队列以外的队列，那么本地队列管理器中的所有名称解析都在 MQOPEN 调用时进行。 这可能包括：
    • 将远程队列的本地定义的名称解析为远程队列管理器的名称，以及该队列在远程队列管理器上的已知名称
    • 将远程队列管理器名称解析为本地传输队列的名称
    • (仅限z/OS ) 将远程队列管理器名称解析为 IGQ 代理程序所使用的共享传输队列的名称 (仅当本地和远程队列管理器属于同一队列共享组时才适用)
    • 基本队列或主题对象的名称的别名解析。

    但是，请注意，句柄的后续 MQINQ 或 MQSET 调用仅与已打开的名称相关，而不与发生名称解析后生成的对象相关。 例如，如果打开的对象是别名，那么 MQINQ 调用返回的属性是别名的属性，而不是基本队列的属性或别名解析为的主题对象。

    如果要打开的对象是集群队列，那么可以在 MQOPEN 调用时进行名称解析，也可以延迟到以后。 发生解析的点由 MQOPEN 调用上指定的 MQOO_BIND_ * 选项控制:
    • MQOO_BIND_ON_OPEN
    • MQOO_BIND_NOT_FIXED
    • MQOO_BIND_AS_Q_DEF
    • MQOO_BIND_ON_GROUP

    有关集群队列的名称解析的更多信息，请参阅 名称解析 。

  4. 带有 MQOO_BROWSE 选项的 MQOPEN 调用将建立浏览游标，以用于指定对象句柄和其中一个浏览选项的 MQGET 调用。 这允许在不改变其内容的情况下扫描队列。 可以使用 MQGMO_MSG_UNDER_CURSOR 选项从队列中除去通过浏览找到的消息。

    通过对同一队列发出多个 MQOPEN 请求，可以对单个应用程序激活多个浏览游标。

  5. 由触发器监视器启动的应用程序将在应用程序启动时传递与该应用程序相关联的队列的名称。 可以在 ObjDesc 参数中指定此队列名称以打开队列。 请参阅 MQTMC2 -触发器消息 2 (字符格式) 以获取更多详细信息。
  6. 在 IBM i上，以兼容性方式运行的应用程序将通过应用程序发出的第一个 MQOPEN 调用自动连接到队列管理器 (如果应用程序尚未使用 MQCONN 调用连接到队列管理器)。

    未以兼容性方式运行的应用程序必须先发出 MQCONN 或 MQCONNX 调用以显式连接到队列管理器，然后再使用 MQOPEN 调用来打开对象。

预读选项

使用 MQOO_READ_AHEAD 调用 MQOPEN 时，仅当满足特定条件时， WebSphere MQ 客户机才会启用预读。 这些条件包括：
  • 客户机和远程队列管理器都必须处于 WebSphere MQ V 7 或更高版本。
  • 必须针对线程 WebSphere MQ MQI 客户机库编译和链接客户机应用程序。
  • 客户机通道必须使用的是 TCP/IP 协议
  • 该通道必须在客户机和服务器通道定义中具有非零 SharingConversations (SHARECNV) 设置。

以下说明适用于预读选项的使用。

  1. 仅当同时指定了 MQOO_BROWSE ， MQOO_INPUT_SHARED 和 MQO_INPUT_EXCLUSIVE 选项中的一个且仅一个时，预读选项才适用。 如果使用 MQOO_ INQUIRE 或 MQOO_SET 选项指定了预读选项，那么不会抛出错误。
  2. 如果第一个 MQGET 调用上使用的选项不支持用于预读，那么在请求时不会启用预读。 此外，当客户机连接到不支持预读的队列管理器时，将禁用预读。
  3. 如果应用程序未作为 IBM WebSphere MQ 客户机运行，那么将忽略预读选项。

集群队列

以下说明适用于集群队列的使用。

  1. 首次打开集群队列时，如果本地队列管理器不是完整存储库队列管理器，那么本地队列管理器将从完整存储库队列管理器获取有关集群队列的信息。 当网络繁忙时，本地队列管理器可能需要几秒钟才能从存储库队列管理器接收所需信息。 因此，发出 MQOPEN 调用的应用程序可能必须等待最多 10 秒，然后才能从 MQOPEN 调用返回控制权。 如果本地队列管理器在此时间内未收到有关集群队列的所需信息，那么调用将失败，原因码为 MQRC_CLUSTER_RESOLUTION_ERROR。
  2. 当打开集群队列并且集群中有多个队列实例时，打开的实例取决于 MQOPEN 调用上指定的选项:
    • 如果指定的选项包含以下任何选项:
      • MQOO_BROWSE
      • MQOO_INPUT_AS_Q_DEF
      • MQOO_INPUT_EXCLUSIVE
      • MQOO_INPUT_SHARED
      • MQOO_SET
      打开的集群队列的实例必须是本地实例。 如果没有队列的本地实例，那么 MQOPEN 调用将失败。
    • 如果指定的选项不包含先前描述的任何选项，但包含以下一个或两个选项:
      • MQOO_INQUIRE
      • MQOO_OUTPUT
      如果存在本地实例，那么打开的实例是本地实例，否则是远程实例 (如果使用 CLWLULUSEQ 缺省值)。 但是，队列管理器选择的实例可以由集群工作负载出口 (如果有) 变更。
  3. 如果存在该队列的预订，但该预订未被完整存储库确认，那么该对象在集群中不存在，并且调用失败，原因码为 MQRC_OBJECT_NAME。

有关集群队列的更多信息，请参阅 集群队列。

分发列表

以下说明适用于分发列表的使用。

在以下环境中支持分发列表: AIX®， HP-UX， IBM i， Solaris， Linux®， Windows以及连接到这些系统的 IBM WebSphere MQ MQI 客户机。
  1. 打开分发列表时，必须按如下所示设置 MQOD 结构中的字段:
    • Version 必须为 MQOD_VERSION_2 或更高版本。
    • ObjectType 必须是 MQOT_Q。
    • ObjectName 必须为空白或空字符串。
    • ObjectQMgrName 必须为空白或空字符串。
    • RecsPresent 必须大于零。
    • 其中一个 ObjectRecOffset 和 ObjectRecPtr 必须为零，另一个非零。
    • 不能有多个 ResponseRecOffset 和 ResponseRecPtr 非零。
    • 必须有 RecsPresent 个对象记录，由 ObjectRecOffset 或 ObjectRecPtr寻址。 必须将对象记录设置为要打开的目标队列的名称。
    • 如果 ResponseRecOffset 和 ResponseRecPtr 之一非零，那么必须存在 RecsPresent 个响应记录。 如果调用完成且原因码为 MQRC_MULTIPLE_REASON ，那么队列管理器会设置这些参数。

    通过确保 RecsPresent 为零，还可以使用 version-2 MQOD 来打开不在分发列表中的单个队列。

  2. 只有下列打开选项在 Options 参数中有效:
    • MQOO_OUTPUT
    • MQOO_PASS_ * _CONTEXT
    • MQOO_SET_ * _CONTEXT
    • MQOO_ALTERNATE_USER_AUTHORITY
    • MQOO_FAIL_IF_QUIESCING
  3. 分发列表中的目标队列可以是本地队列，别名队列或远程队列，但它们不能是模型队列。 如果指定了模型队列，那么该队列无法打开，原因码为 MQRC_Q_TYPE_ERROR。 但是，这不会阻止成功打开列表中的其他队列。
  4. 完成代码和原因码参数设置如下:
    • 如果分发列表中队列的打开操作全部成功或以相同方式失败，那么将设置完成代码和原因码参数以描述公共结果。 在这种情况下，未设置 MQRR 响应记录 (如果由应用程序提供)。

      例如，如果每次打开都成功，那么完成代码将设置为 MQCC_OK ，原因码将设置为 MQRC_NONE; 如果每次打开都失败，因为不存在任何队列，那么参数将设置为 MQCC_FAILED 和 MQRC_UNKNOWN_OBJECT_NAME。

    • 如果分发列表中队列的打开操作并非全部成功或以相同方式失败:
      • 如果至少有一个打开成功，那么完成代码参数将设置为 MQCC_WARNING ，如果所有操作都失败，那么将设置为 MQCC_FAILED。
      • 原因码参数设置为 MQRC_MULTIPLE_REASON。
      • 响应记录 (如果由应用程序提供) 将设置为分发列表中队列的各个完成代码和原因码。
  5. 成功打开分发列表后，调用返回的句柄 Hobj 可用于后续 MQPUT 调用以将消息放入分发列表中的队列，以及 MQCLOSE 调用以放弃对分发列表的访问权。 分发列表的唯一有效关闭选项是 MQCO_NONE。

    MQPUT1 调用还可用于将消息放入分发列表; 定义列表中的队列的 MQOD 结构被指定为该调用上的参数。

  6. 当检查应用程序是否已超过允许的最大句柄数时，分发列表中的每个成功打开的目标都将计为一个单独的句柄 (请参阅 MaxHandles queue-manager 属性)。 即使当分发列表中的两个或更多目标解析为同一物理队列时，也是如此。 如果针对分发列表的 MQOPEN 或 MQPUT1 调用将导致应用程序正在使用的句柄数超过 MaxHandles，那么调用将失败，原因码为 MQRC_HANDLE_NOT_AVAILABLE。
  7. 成功打开的每个目标都将其 OpenOutputCount 属性的值递增 1。 如果分发列表中的两个或多个目标解析为同一物理队列，那么该队列的 OpenOutputCount 属性将按分发列表中解析为该队列的目标数递增。
  8. 如果对队列定义的任何更改 (例如，解析路径中的更改) 会导致在单独打开队列时句柄变为无效) ，那么这些更改不会导致分发列表句柄变为无效。 但是，在后续 MQPUT 调用上使用分发列表句柄时，会导致该特定队列发生故障。
  9. 分发列表只能包含一个目标。

远程队列

以下说明适用于远程队列的使用。

可以通过此调用的 ObjDesc 参数中的两种方法之一来指定远程队列。

  • 通过为 ObjectName 指定远程队列的本地定义的名称。 在这种情况下， ObjectQMgrName 引用本地队列管理器，并且可以将其指定为空白或 (在 C 编程语言中) 空字符串。

    由本地队列管理器执行的安全性验证将验证用户是否有权打开远程队列的本地定义。

  • 通过为 ObjectName 指定远程队列管理器已知的远程队列名称。 在这种情况下， ObjectQMgrName 是远程队列管理器的名称。

    由本地队列管理器执行的安全性验证将验证用户是否有权向由名称解析过程产生的传输队列发送消息。

在任何一种情况下:
  • 本地队列管理器不会向远程队列管理器发送任何消息，以检查用户是否有权将消息放入队列中。
  • 当消息到达远程队列管理器时，远程队列管理器可能会拒绝该消息，因为发起该消息的用户未经授权。

请参阅 MQOD-对象描述符 中描述的 ObjectName 和 ObjectQMgrName 字段，以获取更多信息。

对象

安全性

以下说明涉及使用 MQOPEN 的安全性方面。

在发出 MQOPEN 调用时，队列管理器将执行安全性检查，以验证在允许访问之前，运行应用程序的用户标识是否具有相应的权限级别。 将对要打开的对象的名称进行权限检查，而不是对在解析名称后生成的名称进行权限检查。

如果要打开的对象是指向主题对象的别名队列，那么队列管理器会先对别名队列名称执行安全性检查，然后再对主题执行安全性检查，就像直接使用了主题对象一样。

如果要打开的对象是主题对象 (无论是单独使用 ObjectName 还是使用 ObjectString (具有或不具有基本 ObjectName)) ，那么队列管理器将使用从 ObjectName中指定的主题对象中获取的结果主题字符串来执行安全性检查，如果需要将其与 ObjectString中提供的主题对象并置，然后在主题树中的该点或该点以上找到最接近的主题对象以执行安全性检查。 这可能与 ObjectName中指定的主题对象不同。

如果要打开的对象是模型队列，那么队列管理器将对模型队列的名称和创建的动态队列的名称执行完全安全性检查。 如果随后显式打开生成的动态队列，那么将对动态队列的名称执行进一步的资源安全性检查。

属性

以下注释与属性相关。

当应用程序打开对象时，可以更改该对象的属性。 在许多情况下，应用程序不会注意到这一点，但对于某些属性，队列管理器会将句柄标记为不再有效。 这些属性为:

  • 影响对象的名称解析的任何属性。 这将适用，而不考虑所使用的打开选项，包括以下内容:
    • 对已打开的别名队列的 BaseQName 属性的更改。
    • 对已打开的别名队列的 TargetType 属性的更改。
    • 对 RemoteQName 或 RemoteQMgrName 队列属性的更改，对于为此队列打开的任何句柄，或者对于通过此定义解析为队列管理器别名的队列。
    • 导致远程队列的当前打开句柄解析到另一个传输队列，或根本无法解析到一个传输队列的任何更改。 例如，这可以包括:
      • 对远程队列的本地定义的 XmitQName 属性的更改，无论该定义是用于队列还是用于队列管理器别名。
      • (仅适用于z/OS ) 对 IntraGroupQueuing 队列管理器属性值的更改，或对共享传输队列 (SYSTEM.QSG.TRANSMIT.QUEUE) 由 IGQ 代理程序使用。

      有一个例外: 创建新的传输队列。 如果在打开句柄时该句柄已解析到此队列，但改为解析为缺省传输队列，那么该句柄不会变为无效。

    • 对 DefXmitQName 队列管理器属性的更改。 在这种情况下，解析为先前指定的队列 (仅因为它是缺省传输队列而解析为该队列) 的所有打开句柄都将标记为无效。 由于其他原因解析到此队列的句柄不受影响。
  • Shareability 队列属性，如果有两个或更多句柄当前正在为此队列提供 MQOO_INPUT_SHARED 访问权，或者为解析到此队列的队列提供 MQOOO_INPUT_SHARED 访问权。 如果是这样，那么针对此队列或解析到此队列的队列打开的 所有 句柄都将标记为无效，而不考虑打开的选项。

    在 z/OS上，如果一个或多个句柄当前正在提供对队列的 MQOO_INPUT_SHARED 或 MQOO_INPUT_EXCLUSIVE 访问权，那么先前描述的句柄将标记为无效。

  • Usage 队列属性，针对为此队列打开的所有句柄，或针对解析到此队列的队列，而不考虑打开的选项。
当句柄标记为无效时，使用此句柄的所有后续调用 (MQCLOSE 除外) 都将失败，原因码为 MQRC_OBJECT_CHANGED。 应用程序必须发出 MQCLOSE 调用 (使用原始句柄) ，然后重新打开队列。 根据应用程序逻辑的要求，仍可以落实或回退来自先前成功调用的旧句柄的任何未落实更新。

如果更改属性导致发生此情况，请使用特殊强制版本的调用。

C 调用


MQOPEN (Hconn, &ObjDesc, Options, &Hobj, &CompCode,
       &Reason);
按如下所示声明参数：

MQHCONN  Hconn;     /* Connection handle */
MQOD     ObjDesc;   /* Object descriptor */
MQLONG   Options;   /* Options that control the action of MQOPEN */
MQHOBJ   Hobj;      /* Object handle */
MQLONG   CompCode;  /* Completion code */
MQLONG   Reason;    /* Reason code qualifying CompCode */

COBOL 调用


CALL 'MQOPEN' USING HCONN, OBJDESC, OPTIONS, HOBJ, COMPCODE, REASON
按如下所示声明参数：

**   Connection handle
 01  HCONN     PIC S9(9) BINARY.
**   Object descriptor
 01  OBJDESC.
     COPY CMQODV.
**   Options that control the action of MQOPEN
 01  OPTIONS   PIC S9(9) BINARY.
**   Object handle
 01  HOBJ      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 MQOPEN (Hconn, ObjDesc, Options, Hobj, CompCode, Reason);
按如下所示声明参数：

dcl Hconn     fixed bin(31);  /* Connection handle */
dcl ObjDesc   like MQOD;      /* Object descriptor */
dcl Options   fixed bin(31);  /* Options that control the action of
                                 MQOPEN */
dcl Hobj      fixed bin(31);  /* Object handle */
dcl CompCode  fixed bin(31);  /* Completion code */
dcl Reason    fixed bin(31);  /* Reason code qualifying CompCode */

高级汇编程序调用


CALL MQOPEN,(HCONN,OBJDESC,OPTIONS,HOBJ,COMPCODE,REASON)
按如下所示声明参数：

HCONN     DS      F  Connection handle
OBJDESC   CMQODA  ,  Object descriptor
OPTIONS   DS      F  Options that control the action of MQOPEN
HOBJ      DS      F  Object handle
COMPCODE  DS      F  Completion code
REASON    DS      F  Reason code qualifying COMPCODE

Visual Basic 调用


MQOPEN Hconn, ObjDesc, Options, Hobj, CompCode, Reason
按如下所示声明参数：

Dim Hconn    As Long 'Connection handle'
Dim ObjDesc  As MQOD 'Object descriptor'
Dim Options  As Long 'Options that control the action of MQOPEN'
Dim Hobj     As Long 'Object handle'
Dim CompCode As Long 'Completion code'
Dim Reason   As Long 'Reason code qualifying CompCode'