注销订户消息

Deregister Subscriber 命令消息从订户发送至代理或订户所属的其他应用程序,以表明其不再希望接收与给定参数匹配的消息。

该消息被发送至 SYSTEM.BROKER.CONTROL.QUEUE(代理的控制队列)。用户必须有必需的权限把消息放入到该队列。

请参阅到代理的命令消息中的 MQMD 设置以获取发送命令消息到代理时所需的消息描述符(MQMD)参数的详细信息。

通过指定原始预订的相应主题、预订点和过滤器值,可以注销个别的预订。 如果在原始预订中,没有指定任何值(即,它们采用缺省值),在注销预订时应当省略它们。

可以通过使用 DeregAll 选项注销订户或订户组的所有预订。例如,如果指定了 DeregAll,连同预订点(但是没有主题或过滤器),无论主题或过滤器,在指定预订点上的订户的所有预订都注销。 允许主题,过滤器和预订点的任何组合;如果所有三个都被指定仅一个预订可以匹配,则忽略 DeregAll 选项。

该消息必须由注册了预订的订户发送,这将通过检查订户的用户标识来确认。

预订还可以由系统管理员注销。 但是,带有临时动态队列的已注册的预订与该队列而不只是队列名相关联。 如果显式地删除队列,或通过应用程序从队列管理器断开连接,则不可以再使用 Deregister Subscriber 命令注销队列的预订。可使用工作台注销预订,这将使其在下次符合预订的发布内容或代理重启时,被代理自动删除。正常情况下,在删除队列或从队列管理器断开连接之前,应用程序应该注销其预订。

如果订户发送消息以注销预订,并接收到说这被成功处理的响应消息,一些预订可以仍然到达订户队列(如果它们由代理在注销的同一时间处理)。 如果消息没有从队列除去,这可能在订户队列上是未处理消息的构建。 如果在睡眠一会后,应用程序执行包含带有相应 CorrelId 的 MQGET 调用循环,这些消息被清除出队列。 如果您正使用 SCADA 设备协议,有一个清除启动和完成的选项。 这意味着消息从客户机清除。

类似的,如果订户使用永久动态队列,并注销和关闭在 MQCLOSE 调用上带有 MQCO_DELETE_PURGE 选项的队列,该队列可能不为空。 当删除队列时,如果代理有任何发布内容还未提交,MQCLOSE 调用发出 MQRC_Q_NOT_EMPTY 返回码。 该应用程序可以通过反复休眠和不时地重新发出 MQCLOSE 调用来避免该问题。

属性

<Command> MQPSC_COMMAND
该值为 DeregSubMQPSC_DEREGISTER_SUBSCRIBER

必须指定该属性。

<Topic> MQPSC_TOPIC
该值是包含要被注销的主题的字符串。

如果要注销多个主题,该属性可以被重复(可选)。如果在 <RegOpt> 中指定了 DeregAll,则可以将其省略。

如果订户希望保留其他主题的预订,则所指定的主题可以是已注册主题的子集。允许使用通配符,但包含通配符的主题字符串必须完全与 Register Subscriber 命令消息中指定的相应字符串相匹配。

<SubPoint> MQPSC_SUBSCRIPTION_POINT
该值是指定预订点从哪个预订拆离的字符串。
不能重复该属性。如果指定了 <主题> 或如果 DeregAll<RegOpt> 中被指定,则可以忽略这个。如果您忽略该属性,则会发生以下情况:
  • 如果您没有指定 DeregAll,匹配 <Topic>属性(和 <Filter> 属性(如果显示))的预订从缺省预订点中注销。
  • 如果您指定 DeregAll,所有预订(匹配 <Topic><Filter> 属性(如果显示))从所有预订点中注销。

注意,您无法显式地指定缺省预订点。 因此,没有方法只注销该预订点所有的预订,您必须指定主题。

<SubIdentity> MQPSC_SUBSCRIPTION_IDENTITY
这是可变长度字符串(长度上限为 64 个字符)。这用于表示对预订有兴趣的应用程序。代理为每个预订保留一组订户标识。每个预订可让其标识设置为仅容纳单个身份,也可以设置容纳无限个身份。

如果 SubIdentity 在预订的身份集中,随后其从该集中除去。 作为结果如果身份集为空,预订从代理中除去,除非 LeaveOnly 被指定为 RegOpt 属性的值。 如果身份集仍然包含其他身份,则预订不从代理中除去,并且不中断发布内容流。

如果指定了 SubIdentity,但是 SubIdentity 不在预订的标识集中,则 Deregister Subscriber 命令无效,返回码为 MQRCCF_SUB_IDENTITY_ERROR

<Filter>MQPSC_FILTER
该值是指定要注销的过滤器的字符串。 其必须精确地匹配,包含大小写和任何空间,先前已注册了一个预订过滤器。

如果要注销多个过滤器,该属性可以被重复(可选)。 如果指定了 <主题> 或如果 DeregAll<RegOpt> 中被指定,则可以忽略这个。

如果订户希望为其他过滤器保留预订,所指定的该过滤器可以是那些注册的子集。

<RegOpt>MQPSC_REGISTRATION_OPTION
注册选项属性可以采用以下值:
DeregAll  
MQPSC_DEREGISTER_ALL

要注销注册该订户的所有匹配预订。

如果指定 DeregAll
  • <Topic><SubPoint>、和 <Filter> 可以被忽略。
  • 如果需要,<Topic><Filter> 可以被重复。
  • 不能重复 <SubPoint>
如果您指定 DeregAll
  • <Topic> 必须被指定,并且可以被重复(如果需要)。
  • <SubPoint><Filter> 可以被忽略。
  • 不能重复 <SubPoint>
  • <Filter> 可以被重复(如果需要)。
CorrelAsId  
MQPSC_CORREL_ID_AS_IDENTITY

消息描述符(MQMD)(不能为零)中的 CorrelId 用于标识订户。 其必须匹配在原始预订中使用的 CorrelId

FullResp  
()

FullResp 被指定,该预订的所有属性在响应消息中返回(如果命令不失败)。

当指定 FullResp时,Deregister Subscriber 命令中不允许 DeregAll。这也不可能指定多个主题。两种情况下,命令都失败,返回码为 MQRCCF_REG_OPTIONS_ERROR

LeaveOnly  
MQPSC_LEAVE_ONLY

当您指定这个带有预订的身份集中的 SubIdentity 时,SubIdentity 从预订的身份集中除去。 即使结果身份集为空,预订不从代理中除去。 如果 SubIdentity 值不在身份集中,命令失败,返回码为 MQRCCF_SUB_IDENTITY_ERROR。

如果指定 LeaveOnly 而不带 SubIdentity,则命令失败,返回码为 MQRCCF_REG_OPTIONS_ERROR

如果即没指定 LeaveOnly 也没指定 SubIdentity,无论预订的身份集内容,预订都被删除。

None  
(MQPSC_NONE)

所有选项采取它们的缺省值。这与省略注册选项属性的效果相同。 如果同时指定其他选项,则忽略 None

VariableUserId  
MQPSC_VARIABLE_USER_ID

当指定订户(队列、队列管理器和 correlid)的身份时,不限定于单个用户标识。 这不同于以下两种情况:代理的现有工作情况将原始注册消息的用户标识与预订的标识相关联;从此阻止使用该标识的任何其他用户。如果新的订户尝试使用同一身份,则返回 MQRCCF_DUPLICATE_SUBSCRIPTION 代码。

当它们有合适的权限时,任何用户可以修改或注销预订,以避免用户标识必须与原始订户相匹配的现有检查。

要将该项添加到现有的预订,该命令必须来自与原始预订本身相同的用户标识。

如果要被注销的预订有 VariableUserId 设置,这必须在注销时设置以表明哪些预订要被注销。 否则,使用 Deregister Subscriber 命令的用户标识将用于识别预订。如果提供了预订名称,这连同其他订户标识,会被覆盖。

如果属性被省略,缺省是不设置注册选项。

<QMgrName> MQPSC_Q_MGR_NAME
该值是订户队列的队列管理器名。 其必须匹配在原始预订中使用的 QMgrName

如果省略该属性,缺省是消息描述符(MQMD)中的 ReplyToQMgr 名称。 如果结果名称为空,其缺省到代理的队列管理器的名称。

<QName> MQPSC_Q_NAME
该值是订户队列的名称。 其必须匹配在原始预订中使用的 QName

如果省略该属性,缺省是消息描述符(MQMD)中的 ReplyToQ 名称,不得为空。

<SubName> MQPSC_SUBSCRIPTION_NAME
如果在 Deregister Subscriber 命令上指定 SubName,则该值优先于所有其他标识字段(除用户标识外),除非在预订上设置了 VariableUserId。如果未设置 VariableUserId,则仅当命令消息的用户标识与其预订相匹配时,Deregister Subscriber 命令可成功执行,否则该命令将失败,返回码为MQRCCF_DUPLICATE_IDENTITY

如果预订与该命令的传统标识相匹配,但没有指定 SubName,则 Deregister Subscriber 命令失败,返回码为MQRCCF_SUB_NAME_ERROR。如果进行了尝试,使用与传统身份相匹配的命令消息对有 SubName 的预订注销,但是没有指定 SubName,该命令成功。

<SubUserData> (MQPSC_SUBSCRIPTION_USER_DATA)
这是一个可变长度的文本字符串。该值由带有预订的队列存储,但是对于发布内容到订户的传递则没有影响。 可以通过使用新的值重新注册到同一预订上来改变该值。 该属性用于应用程序的使用。

SubUserData 返回在预订的 Metatopic 信息中(MQCACF_REG_SUB_USER_DATA)(如果显示)

示例

此处有一个 Deregister Subscriber 命令消息的 NameValueData 的示例。在本示例中,样本应用程序注销其到包含所有比赛最新比分的主题的预订。 订户的身份(包括 CorrelId)从 MQMD 的缺省值中获取。
 <psc>
  <Command>DeregSub</Command>
  <RegOpt>CorrelAsId</RegOpt>
  <Topic>Sport/Soccer/State/LatestScore/#</Topic>
 </psc>
声明 | 商标 | 下载 | 书库 | 支持 | 反馈
Copyright IBM Corporation 1999, 2006 最后一次更新时间:2006/08/14
aq06970_