注册订户命令消息由订户发送到代理,或以订户的行为通过另一个应用程序发送到代理,以表明它要在预订点预订一至多个主题。 也可指定一条消息内容过滤器。
在发布/预订过滤器表达式中,嵌套圆括号将引起性能以指数形式降低。实际上,应避免嵌套 6 层以上的圆括号。
将消息发送至 SYSTEM.BROKER.CONTROL.QUEUE(代理的控制队列)。除了预订中对主题的访问权限(由代理的系统管理员设置)外,必需具有可将消息放置该队列的权限。
若用户已对一些(不是所有)主题拥有权限,只有具有权限的才能注册;一个警告响应表明那些没注册的用户。
请参阅代理响应消息以获取发送命令消息到代理时所需的消息描述符(MQMD)参数的详细信息。
如果队列是一个临时的动态队列,预订就会在队列关闭时被代理自动注销。
此属性是必要的,且可以按照需要无数次重复需要的主题。
如果省略该属性,则使用缺省的预订点。
如果省略该属性,则不发生内容过滤。
当已指定了一个现有的预订(它与此预订注册命令的传统身份相匹配),但当前没有 SubName 值, 在这条命令中指定的 SubName 会加入到预订中。
若 AddName 已指定,SubName 是必需字段,否则会返回 MQRCCF_REG_OPTIONS_ERROR。
在消息描述符(MQMD) CorrelId 用来向订户队列发送匹配的发布内容。CorrelId 必须不为零,
若命令没有失败,那么所有已定义属性的发布内容会在响应消息中返回。
只有当命令消息引用单个预订时,FullResp 才有效。因此,命令中只能有一个主题,否则命令将出错,返回码为 MQRCCF_REG_OPTIONS_ERROR。
当发布内容发送发布消息响应 Register Subscriber 或 Request Update 命令消息时保留发布内容,此时代理通知订户。如果代理在消息中使用包含 IsRetainedPub 的发布选项。
此选项表明指定的 SubIdentity 必须作为标识集合中的互斥成员加入到预订中,且其他成员不能加入到这个身份集中。
若标识已加入‘共享’且为集合中唯一条目 ,此集合被改变为一个这个标识持有的一个互斥锁。否则,如果当前预订在标识集(共享访问权)中有其他身份,则该命令失败,返回码为 MQRCCF_SUBSCRIPTION_IN_USE。
此选项表明指定的 SubIdentity 预订必须添加到标识集中。
如果当前预订因其排外性而锁定(使用 JoinExcl 选项),则该命令失败,返回码为 MQRCCF_SUBSCRIPTION_LOCKED,除非锁定的预订标识与命令消息中的标识相同。在这种情况下,锁会自动修改为共享锁。
预订是本地的即不与网络中其他代理连接。除非发布内容还具有相应的全局预订,否则其他代理上的发布内容不传递到该订户。
在预订被注册时存在的保留发布内容并没有被发送到订户;只有新的发布内容才会发送。
若一个订户重新注册并改变了这个选项使之不再固定,已被发往的发布内容不能再被发送。
已存在的匹配预订的属性没有改变。
当正创建一个预订时,这个选项被忽略。所有其他指定的选项都被应用到新的预订。
如果 SubIdentity 还具有其中一个已指定的连接选项(JoinExcl 或 JoinShared),则无论 NoAlter 是否被指定,标识都会被加入到标识集中。
所有注册选项都采用它们的默认值。
若订户已注册,它的选项将复位为其默认值(注:这并没有与省略注册选项属性有相同的作用),预订有效期通过Register Subscriber消息的MQMD得以更新。
若同时指定其他注册选项,None 被忽略。
与此订户匹配的发布内容作为临时消息被传递至订户。
与此订户匹配的发布内容作为持久消息被传递至订户。
与此订户匹配的发布内容作为由订户指定有效期的消息传递至订户。这是缺省行为。
与此订户匹配的发布内容作为由订户指定有效期的消息传递至订户。
代理不会将发布内容发到订户,除非对一个Request Update 命令消息进行相应。
当指定订户(队列、队列管理器和 correlid)的身份时,不限定于单个用户标识。 这不同于以下两种情况:代理的现有工作情况将原始注册消息的用户标识与预订的标识相关联;从此阻止使用该标识的任何其他用户。如果新的订户尝试使用同一身份,则返回 MQRCCF_DUPLICATE_SUBSCRIPTION 代码。
这使得任何有适当权限的用户都能改变或注销预订。因此不必检查用户标识与其原先订户的标识是否匹配。
要将该项添加到现有的预订,该命令必须来自与原始预订本身相同的用户标识。
若 request update 命令有 VariableUserId 集合,必须在请求更新时设置以指定引用哪个预订。否则,使用 request update 命令来标识预订。 如果提供了预订名称,这连同其他订户标识,会被覆盖。
如果注册订户无此选项集的命令消息与一个有此选项集的相关,这个选项将从订户中被删除,而此时预订的用户标识无法修改。如果已存在一个预订,具有与其关联的相同身份(queue、qmgr 和 correlid)不同的用户标识,则该命令失败,返回码为 MQRCCF_DUPLICATE_IDENTITY,因为一个订户身份只能有一个用户标识与之关联。
若忽略注册选项属性且订户已经注册,它的注册选项没被改变,预订有效期也从注册订户消息的 MQMD 得以更新。
如果订户还没注册,一个新的预订会建立且所有注册选项取它们的默认值。
默认值为 PersAsPub 且无其他选项集。
如果省略该属性,缺省是消息描述符(MQMD)中的 ReplyToQMgr 名称。 如果生成的名称为空,则它缺省为代理的 QMgrName。
如果省略该属性,则缺省为消息描述符(MQMD)中的 ReplyToQ 名称,这种情况下,该名称不能为空。
如果队列是一个临时动态队列,发布内容的非持久传递(NonPers)必须在 <RegOpt> 属性中指定。
如果队列是一个临时的动态队列,预订就会在队列关闭时被代理自动注销。
若一个名为 SubName 的预订已存在,任何其他预订(Topic、QMgrName、QName、CorrelId, UserId、RegOpts、UserSubData 和 Expiry)的属性被这些属性覆盖,如果指定了这些属性,就会在新的 注册订户命令消息中传递。但是,如果使用 SubName 且无 QName 定义, 且已在 MQMD 头部指定 ReplyToQ,订户队列改变为 ReplyToQ。
如果与该命令的传统身份匹配的预订已存在,但没有指定 SubName,则注册命令失败,返回码为 MQRCCF_DUPLICATE_SUBSCRIPTION,除非指定了 AddName 选项。
如果您尝试使用其他 Register Subscriber 命令改变现有已命名的预订,该命令指定新的 SubName,并且新命令中的 Topic、QMgrName、QName 和 CorrelId 的值与现有另一个预订相匹配(无论是否指定了 SubName),则该命令失败,返回码为 MQRCCF_DUPLICATE_SUBSCRIPTION。这防止了一个预订拥有两个名字。
指定了 JoinShared 或 JoinExcl 选项的预订命令把 SubIdentity 加入到预订的身份集,若身份不在集合中或身份集允许这样做,即, 无其他预订者有专有的连接或身份集是空的。
指定了 SubIdentity 的 Register Subscriber 命令会导致预订属性的更改,仅当 SubIdentity 为该预订中标识集的唯一成员时,命令才能成功执行。否则,命令失败,返回码为 MQRCCF_SUBSCRIPTION_IN_USE。这防止了在其他感兴趣的订户没被通知的条件下改变一个预订的属性。
如果指定的字符串的长度超过 64 个字符,则该命令失败,返回码为 MQRCCF_SUB_IDENTITY_ERROR。
SubUserData 返回到预订的 Metatopic 信息中(MQCACF_REG_SUB_USER_DATA)(如果显示)。
如果您指定了多于一个的注册选项的值 NonPers、PersAsPub、PersAsQueue、 和 Pers,那么只有最后一个才起作用。不能将这些在一个单独预订中的选项组合。