MQSUB-注册预订

使用 MQSUB 调用来注册特定主题的应用程序预订。

语法

MQSUB （ Hconn、 SubDesc、 Hobj、 Hsub、 Compcode、 Reason ）

参数

Hconn
类型 :MQHCONN-输入

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

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

这是一种结构，用于标识正在由应用程序注册的正在使用的对象。 有关详细信息，请参阅 MQSD - 订阅描述符。

Hobj
类型 :MQHOBJ-输入/输出

此句柄表示为获取发送到此预订的消息而建立的访问权。 这些消息可以存储在特定队列上，或者队列管理器可以在不使用特定队列的情况下管理其存储器。

要使用特定队列，必须在创建预订时将其与预订相关联。 您可以使用两种方式执行此操作：
  • 通过使用 DEFINE SUB MQSC 命令并为该命令提供队列对象的名称。
  • 通过在使用 MQSO_CREATE 调用 MQSUB 时提供此句柄
    如果此句柄作为调用上的输入参数提供，那么它必须是使用以下至少一个选项从队列的先前 MQOPEN 调用返回的有效对象句柄:
    • MQOO_INPUT_ *
    • MQOO_BROWSE
    • MQOO_OUTPUT (如果队列是远程队列)
    如果情况并非如此，那么调用将失败并返回 MQRC_HOBJ_ERROR。 它不能是解析为主题对象的别名队列的对象句柄。 如果是这样，那么调用将失败并返回 MQRC_HOBJ_ERROR。

如果队列管理器要管理发送到此预订的消息的存储，那么应在使用 MQSO_MANAGED 选项创建预订时进行设置。 然后，队列管理器将此句柄作为调用的输出参数返回。 返回的句柄称为受管句柄。 如果指定了 MQHO_NONE ，但未指定 MQSO_MANAGED ，那么调用将失败并返回 MQRC_HOBJ_ERROR。

当队列管理器向您返回受管句柄时，可以在带有或不带浏览选项的 MQGET 或 MQCB 调用， MQINQ 调用或 MQCLOSE 上使用该句柄。 不能在 MQPUT ， MQSUB 和 MQSET 上使用此参数; 尝试执行此操作将失败，返回 MQRC_NOT_OPEN_FOR_OUTPUT ， MQRC_HOBJ_ERROR 或 MQRC_NOT_OPEN_FOR_SET。

如果正在使用 MQSD 结构中的 MQSO_RESUME 选项恢复此预订，那么可以通过将 MQSO_MANAGED 设置为 MQHO_NONE 来将句柄返回到此参数中的应用程序。 无论预订是否正在使用受管句柄，都可以执行此操作，并且将使用 DEFINE SUB 创建的预订与该句柄一起提供给该命令上定义的预订队列很有用。 在恢复以管理方式创建的预订的情况下，将使用 MQOO_INPUT_AS_Q_DEF 和 MQOO_BROWSE 打开队列。 如果需要指定其他选项，那么应用程序必须显式打开预订队列并在调用时提供对象句柄。 如果打开队列时发生问题，那么调用将失败并返回 MQRC_INVALID_DESTINATION。 如果提供了 Hobj ，那么它必须等同于原始 MQSUB 调用中的 Hobj 。 这意味着如果提供了从 MQOPEN 调用返回的对象句柄，那么该句柄必须与先前使用的队列相同。 如果它不是同一队列，那么调用将失败并返回 MQRC_HOBJ_ERROR。

如果正在使用 MQSD 结构中的 MQSO_ALTER 选项更改此预订，那么可以提供其他 Hobj 。 任何已传递到队列且先前通过此参数识别的发布都将保留在该队列中，如果 Hobj 参数现在表示另一个队列，那么应用程序将负责检索这些消息。

表 1. 将 hobj 与各种预订选项配合使用
选项 Hobj 描述
mqso_create + mqso_managed 在输入时忽略 创建具有队列管理器管理的消息存储的预订
MQSO_CREATE 有效的对象句柄 创建提供特定队列作为消息目标的预订。
MQSO_简历 MQHO_无 恢复先前创建的预订 (无论其是否受管) ，并使队列管理器返回对象句柄以供应用程序使用。
MQSO_简历 有效的匹配对象句柄 恢复先前创建的预订，该预订使用特定队列作为消息的目标，并使用具有特定打开选项的对象句柄。
mqso_alter + mqso_managed MQHO_无 更改先前使用特定队列的现有预订，因此它现在是受管预订。 无法更改目标的类 (受管或未受管)。
MQSO_ALTER 有效的对象句柄 更改现有预订 (无论它是否受管) ，以便它现在使用特定队列。 未使用 MQSO_MANAGED 选项时，可以更改提供的队列，但无法更改目标的类（受管或非受管）。

无论提供还是返回，都必须在要接收发送到此预订的发布消息的后续 MQGET 或 MQCB 调用上指定 Hobj 。

当对其发出 MQCLOSE 调用时，或者当定义句柄作用域的处理单元终止 (直到应用程序断开连接) 时， Hobj 句柄不再有效。 返回的对象句柄的作用域与调用上指定的连接句柄的作用域相同。 有关句柄作用域的信息，请参阅 Hconn (MQHCONN)-output 。 Hobj 句柄的 MQCLOSE 不会影响 Hsub 句柄。

Hsub
类型 :MQHOBJ-输出
此句柄表示已进行的预订。 它可用于两个进一步的操作:
  • 它可以在后续 MQSUBRQ 调用上使用，以在进行预订时使用 MQSO_publicATIONS_ON_REQUEST 选项时请求发送发布。
  • 可以在后续 MQCLOSE 调用上使用此参数来除去已进行的预订。 发出 MQCLOSE 调用时，或者定义句柄作用域的处理单元终止时， Hsub 句柄不再有效。 返回的对象句柄的作用域与调用上指定的连接句柄的作用域相同。 Hsub 句柄的 MQCLOSE 不会影响 Hobj 句柄。

无法将此句柄传递到 MQGET 或 MQCB 调用。 必须使用 Hobj 参数。 不能在除 MQCLOSE 或 MQSUBRQ 以外的任何 IBM® MQ 调用上使用此句柄。 将此句柄传递给任何其他 "IBM MQ调用都会导致 MQRC_HOBJ_ERROR。

CompCode
类型：MQLONG - 输出
完成代码；此完成代码为以下其中一项：
MQCC_OK
成功完成
MQCC_WARNING
警告 (部分完成)
MQCC_FAILED
通话失败
原因
类型：MQLONG - 输出

限定 CompCode的原因码。

如果 CompCode 是 MQCC_OK ，那么原因码如下所示:
MQRC_NONE
(0, X'000') 没有要报告的原因。
如果 CompCode 是 MQCC_FAILED ，那么原因码为下列其中一项:
mqrc_cluster_resolution_error
(2189, X'88D') 集群名称解析失败。
mqrc_durability_not_allowed
2436 (X'0984 ') 使用MQSO_持久选项的 MQSUB 调用失败。
mqrc_function_not_supported
2298 (X'08FA') 请求的功能在当前环境中不可用。
mqrc_hobj_error
2019 (X'07E3') 对象句柄 Hobj 无效。
MQRC_IDENTITY_MATCH
2434 (X'0982 ') 预订名称与现有预订匹配。
MQRC_NOT_AUTHORIZED
2035 (X'07F3') 用户无权执行该操作。
mqrc_no_subscription
2428 (X'097C') 识别的订阅名称不存在。
mqrc_object_string_error
2441 (X'0989 ') Objectstring 字段无效。
mqrc_options_error
2046 (X'07FE') 选项参数或字段包含无效选项，或无效选项组合。
MQRC_Q_MGR_QUIESCING
2161 (X'0871 ') 队列管理器正在停顿。
mqrc_reconnect_q_mgr_reqd
2555 (X'09FB'X) 需要 MQCNO_RECONNECT_Q_MGR 选项。
mqrc_retained_msg_q_error
2525 (X'09DD') 无法检索已订阅主题字符串的保留出版物。
MQRC_RETAINED_NOT_交付
2526 (X'09DE')订阅主题字符串存在的保留出版物，无法投递到订阅目标队列，也无法投递到死信队列。
MQRC_SD_ERROR
2424 (X'0978 ') 预订描述符 (MQSD) 无效。
mqrc_selection_not_available
2551 (X'09F7') 选择字符串不符合 IBM MQ 选择器语法，并且没有可用的扩展报文选择提供程序。
mqrc_selection_string_error
2519 (X'09D7') 必须按照 MQCHARV 结构文档中的说明指定选择字符串。
mqrc_selector_syntax_error
2459 (X'099B') 已发出 MQOPEN、MQPUT1 或 MQSUB 调用，但指定的选择字符串包含语法错误。
mqrc_sub_user_data_error
2431 (X'097F') SubUserData 字段无效。
mqrc_sub_name_error
2440 (X'0988 ') SubName 字段无效。
mqrc_sub_already_exists
2432 (X'0980 ') 预订已存在。
mqrc_sub_user_data_error
2431 (X'097F') SubUserData 字段无效。
mqrc_topic_string_error
2425 (X'0979 ') 主题字符串无效。
mqrc_unknown_object_name
2085 (X'0825 ') 找不到 MQSD ObjectName 字段中标识的对象。
mqrc_sub_join_not_alterable
29440 (X'7300 ') 预订共享方式与现有预订不兼容。 尝试在非 JMS 应用程序中恢复 JMS 2.0 共享预订时，可能会返回此错误。

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

使用说明

  • 对主题进行预订，使用预定义主题对象的短名称，主题字符串的全名或由两个部分并置而成。 请参阅 MQSD - 订阅描述符中对 ObjectName 和 ObjectString 的描述。
  • 在发出 MQSUB 调用时，队列管理器将执行安全性检查，以验证在允许访问之前，运行应用程序的用户标识是否具有相应的权限级别。 相应的主题对象位于主题层次结构中，并且将对此主题对象进行权限检查以确保设置了预订权限。 如果未使用 MQSO_MANAGED 选项，那么将对目标队列进行权限检查，以确保设置输出权限。 如果使用 MQSO_MANAGED 选项，那么不会对受管队列进行权限检查以进行输出或查询访问。
  • 如果未提供 Hobj 作为输入，那么 MQSUB 调用会分配两个句柄，一个对象句柄 (Hobj) 和一个预订句柄 (Hsub)。
  • 使用 MQSO_MANAGED 选项时，可以查询在 MQSUB 调用上返回的 Hobj ，以找出回退阈值和过多回退重排队列名称之类的属性。 您还可以查询受管队列的名称，但不得尝试直接打开此队列。
  • 可以对预订进行分组，仅允许将单个发布内容传递到预订组，即使其中有多个组与该发布内容匹配也是如此。 使用 MQSO_GROUP_SUB 选项对预订进行分组，以便对预订进行分组。
    • 在同一队列管理器上使用相同的指定队列 (未使用 MQSO_MANAGED 选项)-由 MQSUB 调用上的 Hobj 参数表示
    • 共享相同的 SubCorrelId
    • 属于同一 SubLevel
    这些属性定义被视为在组中的预订集，并且也是在对预订进行分组时无法更改的属性。 更改 SubLevel 会导致 MQRC_SUBLEVEL_NOT_ALTERABLE ，而更改任何其他 (如果预订未分组，那么可以更改) 会导致 MQRC_GROUPING_NOT_ALTERABLE。
  • 成功完成 MQSUB 调用并不意味着操作已完成。 要检查此调用是否已完成，请参阅 检查分布式网络的异步命令是否已完成中的 DEFINE SUB 步骤。
  • MQSD 中的字段是从使用 MQSO_RESUME 选项的 MQSUB 调用返回时填写的。 返回的 MQSD 可直接传递到 MQSUB 调用中，该调用使用 MQSO_ALTER 选项以及您需要对应用于 MQSD 的预订进行的任何更改。 如表中所述，某些字段具有特殊注意事项。
    表 2. MQSD 中字段的特殊注意事项
    MQSD 中的字段名 特殊注意事项
    访问或创建选项 某些选项可以在从 MQSUB 调用返回时重置。 如果然后在 MQSUB 调用中复用 MQSD ，那么必须显式设置所需的选项。
    耐久性选项，目标选项，注册选项和通配符选项 根据需要设置这些选项
    发布选项 除仅适用于 MQSO_CREATE 的 MQSO_NEW_PUBLIC ICATIONS_ONLY 外，将根据需要设置这些选项。
    其他选项 这些选项在从 MQSUB 调用返回时保持不变。 它们控制如何发出 API 调用并且不随预订一起存储。 必须在复用 MQSD 的任何后续 MQSUB 调用上根据需要进行设置。
    ObjectName 此仅输入字段在从 MQSUB 调用返回时保持不变。
    ObjectString 此仅输入字段在从 MQSUB 调用返回时保持不变。 如果提供了缓冲区，那么将在 ResObjectString 字段中返回所使用的完整主题名称。
    AlternateUserId 和 AlternateSecurityId 这些仅输入字段在从 MQSUB 调用返回时保持不变。 它们控制如何发出 API 调用并且不随预订一起存储。 必须在复用 MQSD 的任何后续 MQSUB 调用上根据需要进行设置。
    SubExpiry 使用 MQSO_RESUME 选项从 MQSUB 调用返回时，此字段将设置为预订的原始到期时间，而不是剩余的到期时间。 如果然后使用 MQSO_ALTER 选项在 MQSUB 调用中复用 MQSD ，请重置预订到期时间以重新开始计数。
    SubName 此字段是 MQSUB 调用上的输入字段，在输出时不会更改。
    SubUserData 和 SelectionString

    如果提供了缓冲区，那么将在使用 MQSO_RESUME 选项的 MQSUB 调用的输出中返回这些可变长度字段，并在 VSBufSize中返回正缓冲区长度。 如果未提供缓冲区，那么仅在 MQCHARV 的 VSLength 字段中返回长度。 如果提供的缓冲区小于返回该字段所需的空间，那么在提供的缓冲区中仅返回 VSBufSize 字节。

    如果然后使用 MQSO_ALTER 选项在 MQSUB 调用中复用 MQSD ，并且未提供缓冲区，但提供了非零 VSLength ，那么如果该长度与字段的现有长度匹配，那么不会对该字段进行任何更改。
    SubCorrelId 和 PubAccountingToken

    如果不使用 MQSO_SET_CORREL_ID ，那么队列管理器将生成 SubCorrelId 。 如果不使用 MQSO_SET_IDENTITY_CONTEXT ，那么队列管理器将生成 PubAccountingToken 。

    这些字段是在 MQSD 中使用 MQSO_RESUME 选项从 MQSUB 调用返回的。 如果它们是由队列管理器生成的，那么将使用 MQSO_CREATE 或 MQSO_ALTER 选项在 MQSUB 调用上返回生成的值。
    PubPriority, SubLevel & PubApplIdentityData 这些字段在 MQSD 中返回。
    ResObjectString 如果提供了缓冲区，那么仅在 MQSD 中返回此输出字段。

C 调用

MQSUB (Hconn, &SubDesc, &Hobj, &Hsub, &CompCode, &Reason)
按如下所示声明参数：
MQHCONN Hconn;    /* Connection handle */
MQSD    SubDesc;  /* Subscription descriptor */
MQHOBJ  Hobj;     /* Object handle */
MQHOBJ  Hsub;     /* Subscription handle */
MQLONG  CompCode; /* Completion code */
MQLONG  Reason;   /* Reason code qualifying CompCode */

COBOL 调用

CALL 'MQSUB' USING HCONN, SUBDESC, HOBJ, HSUB, COMPCODE, REASON.
按如下所示声明参数：
**   Connection handle
 01  HCONN    PIC S9(9) BINARY.
**   Subscription descriptor
 01  SUBDESC.
     COPY CMQSDV.
**   Object handle
 01  HOBJ     PIC S9(9) BINARY.
**   Subscription handle
 01  HSUB     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 MQSUB (Hconn, SubDesc, Hobj, Hsub, CompCode, Reason)
按如下所示声明参数：
dcl Hconn    fixed bin(31); /* Connection handle */
dcl SubDesc  like MQSD;     /* Subscription descriptor */
dcl Hobj     fixed bin(31); /* Object handle */
dcl Hsub     fixed bin(31); /* Subscription handle */
dcl CompCode fixed bin(31); /* Completion code */
dcl Reason   fixed bin(31); /* Reason code qualifying CompCode */

高级汇编程序调用

CALL MQSUB,(HCONN,SUBDESC,HOBJ,HSUB,COMPCODE,REASON)
按如下所示声明参数：
HCONN    DS      F  Connection handle
SUBDESC  CMQSDA  ,  Subscription descriptor
HOBJ     DS      F  Object handle
HSUB     DS      F  Subscription handle
COMPCODE DS      F  Completion code
REASON   DS      F  Reason code qualifying COMPCODE