注册订户消息

注册订户命令消息由订户发送到代理,或以订户的行为通过另一个应用程序发送到代理,以表明它要在预订点预订一至多个主题。 也可指定一条消息内容过滤器。

发布/预订过滤器表达式中,嵌套圆括号将引起性能以指数形式降低。实际上,应避免嵌套 6 层以上的圆括号。

将消息发送至 SYSTEM.BROKER.CONTROL.QUEUE(代理的控制队列)。除了预订中对主题的访问权限(由代理的系统管理员设置)外,必需具有可将消息放置该队列的权限。

若用户已对一些(不是所有)主题拥有权限,只有具有权限的才能注册;一个警告响应表明那些没注册的用户。

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

如果队列是一个临时的动态队列,预订就会在队列关闭时被代理自动注销。

属性

<Command> MQPSC_COMMAND
该值为 RegSubMQPSC_REGISTER_SUBSCRIBER)。 必须指定该属性。
<Topic> MQPSC_TOPIC
想从其接收发布内容的主题。通配符可指定为主题的一部分。

此属性是必要的,且可以按照需要无数次重复需要的主题。

<SubPoint> MQPSC_SUBSCRIPTION_POINT
该值是预订被连接到的预订点。

如果省略该属性,则使用缺省的预订点。

<Filter> MQPSC_FILTER
值是一个SQL 表达式,它被用作为一个发布消息内容的过滤器。如果指定主题的发布内容与过滤器匹配,则将发布内容发送到订户。

如果省略该属性,则不发生内容过滤。

<RegOpt> (MQPSC_REGISTRATION_OPTION)
该注册选项属性可以采用以下值:
AddName  
MQPSC_ADD_NAME

当已指定了一个现有的预订(它与此预订注册命令的传统身份相匹配),但当前没有 SubName 值, 在这条命令中指定的 SubName 会加入到预订中。

AddName 已指定,SubName 是必需字段,否则会返回 MQRCCF_REG_OPTIONS_ERROR。

CorrelAsId  
MQPSC_CORREL_ID_AS_IDENTITY

在消息描述符(MQMD) CorrelId 用来向订户队列发送匹配的发布内容。CorrelId 必须不为零,

FullResp  
MQPSC_FULL_RESPONSE

若命令没有失败,那么所有已定义属性的发布内容会在响应消息中返回。

只有当命令消息引用单个预订时,FullResp 才有效。因此,命令中只能有一个主题,否则命令将出错,返回码为 MQRCCF_REG_OPTIONS_ERROR

InformIfRet  
MQPSC_INFORM_IF_RETAINED

当发布内容发送发布消息响应 Register SubscriberRequest Update 命令消息时保留发布内容,此时代理通知订户。如果代理在消息中使用包含 IsRetainedPub 的发布选项。

JoinExcl  
MQPSC_JOIN_EXCLUSIVE

此选项表明指定的 SubIdentity 必须作为标识集合中的互斥成员加入到预订中,且其他成员不能加入到这个身份集中。

若标识已加入‘共享’且为集合中唯一条目 ,此集合被改变为一个这个标识持有的一个互斥锁。否则,如果当前预订在标识集(共享访问权)中有其他身份,则该命令失败,返回码为 MQRCCF_SUBSCRIPTION_IN_USE

JoinShared  
MQPSC_JOIN_SHARED

此选项表明指定的 SubIdentity 预订必须添加到标识集中。

如果当前预订因其排外性而锁定(使用 JoinExcl 选项),则该命令失败,返回码为 MQRCCF_SUBSCRIPTION_LOCKED,除非锁定的预订标识与命令消息中的标识相同。在这种情况下,锁会自动修改为共享锁。

Local  
MQPSC_LOCAL

预订是本地的即不与网络中其他代理连接。除非发布内容还具有相应的全局预订,否则其他代理上的发布内容不传递到该订户。

NewPubsOnly  
MQPSC_NEW_PUBS_ONLY

在预订被注册时存在的保留发布内容并没有被发送到订户;只有新的发布内容才会发送。

若一个订户重新注册并改变了这个选项使之不再固定,已被发往的发布内容不能再被发送。

NoAlter  
MQPSC_NO_ALTER

已存在的匹配预订的属性没有改变。

当正创建一个预订时,这个选项被忽略。所有其他指定的选项都被应用到新的预订。

如果 SubIdentity 还具有其中一个已指定的连接选项(JoinExclJoinShared),则无论 NoAlter 是否被指定,标识都会被加入到标识集中。

None  
MQPSC_NONE

所有注册选项都采用它们的默认值。

若订户已注册,它的选项将复位为其默认值(注:这并没有与省略注册选项属性有相同的作用),预订有效期通过Register Subscriber消息的MQMD得以更新。

若同时指定其他注册选项,None 被忽略。

NonPers  
MQPSC_NON_PERSISTENT

与此订户匹配的发布内容作为临时消息被传递至订户。

Pers  
MQPSC_PERSISTENT

与此订户匹配的发布内容作为持久消息被传递至订户。

PersAsPub  
MQPSC_PERSISTENT_AS_PUBLISH

与此订户匹配的发布内容作为由订户指定有效期的消息传递至订户。这是缺省行为。

PersAsQueue  
MQPSC_PERSISTENT_AS_Q

与此订户匹配的发布内容作为由订户指定有效期的消息传递至订户。

PubOnReqOnly  
MQPSC_PUB_ON_REQUEST_ONLY

代理不会将发布内容发到订户,除非对一个Request Update 命令消息进行相应。

VariableUserId  
MQPSC_VARIABLE_USER_ID

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

这使得任何有适当权限的用户都能改变或注销预订。因此不必检查用户标识与其原先订户的标识是否匹配。

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

request update 命令有 VariableUserId 集合,必须在请求更新时设置以指定引用哪个预订。否则,使用 request update 命令来标识预订。 如果提供了预订名称,这连同其他订户标识,会被覆盖。

如果注册订户无此选项集的命令消息与一个有此选项集的相关,这个选项将从订户中被删除,而此时预订的用户标识无法修改。如果已存在一个预订,具有与其关联的相同身份(queue、qmgr 和 correlid)不同的用户标识,则该命令失败,返回码为 MQRCCF_DUPLICATE_IDENTITY,因为一个订户身份只能有一个用户标识与之关联。

若忽略注册选项属性且订户已经注册,它的注册选项没被改变,预订有效期也从注册订户消息的 MQMD 得以更新。

如果订户还没注册,一个新的预订会建立且所有注册选项取它们的默认值。

默认值为 PersAsPub 且无其他选项集。

<QMgrName> MQPSC_Q_MGR_NAME
值为订户队列管理器的名称,代理将匹配的发布内容通过此队列发往订户。

如果省略该属性,缺省是消息描述符(MQMD)中的 ReplyToQMgr 名称。 如果生成的名称为空,则它缺省为代理的 QMgrName

<QName> MQPSC_Q_NAME
值为订户队列的名称,代理将匹配的发布内容通过此队列发往订户。

如果省略该属性,则缺省为消息描述符(MQMD)中的 ReplyToQ 名称,这种情况下,该名称不能为空。

如果队列是一个临时动态队列,发布内容的非持久传递(NonPers)必须在 <RegOpt> 属性中指定。

如果队列是一个临时的动态队列,预订就会在队列关闭时被代理自动注销。

<SubName> MQPSC_SUBSCRIPTION_NAME
这是给定到特定的预订的名称。 您可以使用它来引用一个预订而非队列管理器,队列或可选 correlId。

若一个名为 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。这防止了一个预订拥有两个名字。

<SubIdentity> MQPSC_SUBSCRIPTION_IDENTITY
此字符串用来代表对预订感兴趣的一个应用程序。 它是可变长度字符串,其长度上限为 64 个字符(可选)。代理为每个预订保留一组订户标识。每个预订可允许它的身份集只包含一个身份,或用一个不受限制的数字代表身份(参阅 JoinSharedJoinExcl 选项)。

指定了 JoinSharedJoinExcl 选项的预订命令把 SubIdentity 加入到预订的身份集,若身份不在集合中或身份集允许这样做,即, 无其他预订者有专有的连接或身份集是空的。

指定了 SubIdentityRegister Subscriber 命令会导致预订属性的更改,仅当 SubIdentity 为该预订中标识集的唯一成员时,命令才能成功执行。否则,命令失败,返回码为 MQRCCF_SUBSCRIPTION_IN_USE。这防止了在其他感兴趣的订户没被通知的条件下改变一个预订的属性。

如果指定的字符串的长度超过 64 个字符,则该命令失败,返回码为 MQRCCF_SUB_IDENTITY_ERROR

<SubUserData> (MQPSC_SUBSCRIPTION_USER_DATA)
这是一个可变长度的文本字符串。代理将值存入预订,但对发布内容到订户的传递并无任何影响。可以通过使用新的值重新注册到同一预订上来改变该值。 该属性用于应用程序的使用。

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

如果您指定了多于一个的注册选项的值 NonPers、PersAsPub、PersAsQueue、 和 Pers,那么只有最后一个才起作用。不能将这些在一个单独预订中的选项组合。

示例

此处有一个关于 NameValueDataRegister Subscriber 命令消息的实例。在该样本应用程序中,服务使用该消息注册预订到这些主题的结果包含所有匹配中的最新记分,和“仅用于请求的发布”选项设置。订户的身份(包括 CorrelId)从 MQMD 的缺省值中获取。
 <psc>
  <Command>RegSub</Command>
  <RegOpt>PubOnReqOnly</RegOpt>
  <RegOpt>CorrelAsId</RegOpt>
  <Topic>Sport/Soccer/State/LatestScore/#</Topic>
 </psc>
声明 | 商标 | 下载 | 书库 | 支持 | 反馈
Copyright IBM Corporation 1999, 2006 最后一次更新时间:2006/08/14
aq06990_