Register Subscriber message

The Register Subscriber command message is sent to a queue manager by a subscriber, or by another application on behalf of a subscriber, to indicate that it wants to subscribe to one or more topics at a subscription point. A message content filter can also be specified.

In publish/subscribe filter expressions, nesting parentheses causes performance to decrease exponentially. Avoid nesting parentheses to a depth greater than about 6.

The message is sent to SYSTEM.BROKER.CONTROL.QUEUE, which is the queue manager's control queue. Authority to put a message to this queue is required, in addition to access authority (set by the queue manager's system administrator) for the topic, or topics, in the subscription.

If the user has authority on some, but not all, topics, only those with authority are registered; a warning response indicates those that are not registered.

See MQMD settings in command messages to the queue manager for details of the message descriptor (MQMD) parameters that are needed when sending a command message to the queue manager.

If the reply to queue is a temporary dynamic queue, the subscription is deregistered automatically by the queue manager when the queue is closed.

Properties

Command (MQPSC_COMMAND)

The value is RegSub (MQPSC_REGISTER_SUBSCRIBER). This property must be specified.

Topic (MQPSC_TOPIC)

The topic for which the subscriber wants to receive publications. Wildcard characters can be specified as part of the topic.

If we use the MQSC command display sub to examine the subscription created in this way, the value of the <Topic> tag is shown as the TOPICSTR property of the subscription.

This property is required, and can optionally be repeated for as many topics as needed.

SubPoint (MQPSC_SUBSCRIPTION_POINT)

The value is the subscription point to which the subscription is attached.

If this property is omitted, the default subscription point is used.

In WebSphere Event Broker Version 6.0, the value of the <SubPoint> property must match the value of the Subscription Point attribute of the Publication nodes that are subscribed to.

In IBM WebSphere MQ Version 7.0.1, the value of the <SubPoint> property must match the name of a subscription point. See Adding a subscription point.

Filter (MQPSC_FILTER)

The value is an SQL expression that is used as a filter on the contents of publication messages. If a publication on the specified topic matches the filter, it is sent to the subscriber. This property corresponds to the Selection String that is used in MQSUB and MQOPEN calls. For more information, see Selecting on the content of a message

If this property is omitted, no content filtering takes place.

RegOpt (MQPSC_REGISTRATION_OPTION)

This Registration Options property can take the following values:

AddName   

(MQPSC_ADD_NAME)

When specified for an existing subscription that matches the traditional identity of this Register Subscription command, but with no current SubName value, the SubName specified in this command is added to the subscription.

If AddName is specified the SubName field is mandatory, otherwise MQRCCF_REG_OPTIONS_ERROR is returned.

CorrelAsId   

(MQPSC_CORREL_ID_AS_IDENTITY)

The CorrelId in the message descriptor (MQMD) is used when sending matching publications to the subscriber queue. The CorrelId must not be zero,

FullResp   

(MQPSC_FULL_RESPONSE)

When specified all attributes of the subscription are returned in the response message, if the command does not fail.

FullResp is valid only when the command message refers to a single subscription. Therefore, only one topic is permitted in the command; otherwise the command fails with return code MQRCCF_REG_OPTIONS_ERROR.

InformIfRet   

(MQPSC_INFORM_IF_RETAINED)

The queue manager informs the subscriber if a publication is retained when it sends a Publish message in response to a Register Subscriber or Request Update command message. The queue manager does this by including the IsRetainedPub publication option in the message.

JoinExcl   

(MQPSC_JOIN_EXCLUSIVE)

This option indicates that the specified SubIdentity should be added as the exclusive member of the identity set for the subscription, and that no other identities can be added to the set.

If the identity has already joined 'shared' and is the sole entry in the set, the set is changed to an exclusive lock held by this identity. Otherwise, if the subscription currently has other identities in the identity set (with shared access) the command fails with return code MQRCCF_SUBSCRIPTION_IN_USE.

JoinShared   

(MQPSC_JOIN_SHARED)

This option indicates that the specified SubIdentity should be added to the identity set for the subscription.

If the subscription is currently locked exclusively (using the JoinExcl option), the command fails with return code MQRCCF_SUBSCRIPTION_LOCKED, unless the identity that has the subscription locked is the same identity as that in this command message. In this case the lock is automatically modified to a shared lock.

Local   

(MQPSC_LOCAL)

The subscription is local and is not distributed to other queue managers in the network. Publications made at other queue managers are not delivered to this subscriber, unless it also has a corresponding global subscription.

NewPubsOnly   

(MQPSC_NEW_PUBS_ONLY)

Retained publications that exist at the time the subscription is registered are not sent to the subscriber; only new publications are sent.

If a subscriber re-registers and changes this option so that it is no longer set, a publication that has already been sent to it might be sent again.

NoAlter   

(MQPSC_NO_ALTER)

The attributes of an existing matching subscription is not changed.

When a subscription is being created, this option is ignored. All other options specified apply to the new subscription.

If a SubIdentity also has one of the join options ( JoinExcl or JoinShared ) specified, the identity is added to the identity set regardless of whether NoAlter is specified.

None   

(MQPSC_NONE)

All registration options take their default values.

If the subscriber is already registered, its options are reset to their default values (note that this does not have the same affect as omitting the registration options property), and the subscription expiry is updated from the MQMD of the Register Subscriber message.

If other registration options are specified at the same time, None is ignored.

NonPers   

(MQPSC_NON_PERSISTENT)

Publications matching this subscription are delivered to the subscriber as non-persistent messages.

Pers   

(MQPSC_PERSISTENT)

Publications matching this subscription are delivered to the subscriber as persistent messages.

PersAsPub   

(MQPSC_PERSISTENT_AS_PUBLISH)

Publications matching this subscription are delivered to the subscriber with the persistence specified by the publisher. This is the default behavior.

PersAsQueue   

(MQPSC_PERSISTENT_AS_Q)

Publications matching this subscription are delivered to the subscriber with the persistence specified on the subscriber queue.

PubOnReqOnly   

(MQPSC_PUB_ON_REQUEST_ONLY)

The queue manager does not send publications to the subscriber, except in response to a Request Update command message.

VariableUserId   

(MQPSC_VARIABLE_USER_ID)

When specified the identity of the subscriber (queue, queue manager and correlid) is not restricted to a single userid. This differs from the existing behavior of the queue manager that associates the userid of the original registration message with the subscriber's identity and from then on prevents any other user using that identity. If a new subscriber tries to use the same identity MQRCCF_DUPLICATE_SUBSCRIPTION is returned.

This allows any user to modify or deregister the subscription if the user has suitable authority. There is therefore no need to check that the userid matches that of the original subscriber.

To add this option to an existing subscription the command must come from the same userid as the original subscription itself.

If the subscription of the Request Update command has VariableUserId set, this must be set at request update time to indicate which subscription is referred to. Otherwise, the userid of the Request Update command is used to identify the subscription. This is overridden, along with the other subscriber identifiers, if a subscription name is supplied.

If a Register Subscriber command message without this option set refers to an existing subscription which has this option set, the option is removed from this subscription and the userid of the subscription is now fixed. If there already exists a subscriber which has the same identity (queue, queue manager and correlation identifier) but with a different user ID associated to it, the command fails with return code MQRCCF_DUPLICATE_IDENTITY because there can only be one userid associated with a subscriber identity.

If the registration options property is omitted and the subscriber is already registered, its registration options are not changed and the subscription expiry is updated from the MQMD of the Register Subscriber message.

If the subscriber is not already registered, a new subscription is created with all registration options taking their default values.

The default values are PersAsPub and no other options set.

QMgrName (MQPSC_Q_MGR_NAME)

The value is the name of the queue manager for the subscriber queue, to which matching publications are sent by the queue manager.

If this property is omitted, the default is the ReplyToQMgr name in the message descriptor (MQMD). If the resulting name is blank, it defaults to the queue manager's QMgrName.

QName (MQPSC_Q_NAME)

The value is the name of the subscriber queue, to which matching publications are sent by the queue manager.

If this property is omitted, the default is the ReplyToQ name in the message descriptor (MQMD), which must not be blank in this case.

If the queue is a temporary dynamic queue, nonpersistent delivery of publications ( NonPers ) must be specified in the <RegOpt> property.

If the queue is a temporary dynamic queue, the subscription is deregistered automatically by the queue manager when the queue is closed.

SubName (MQPSC_SUBSCRIPTION_NAME)

This is a name given to a particular subscription. We can use it instead of the queue manager, queue and optional correlId to refer to a subscription.

If a subscription already exists with this SubName , any other attributes of the subscription (Topic, QMgrName, QName, CorrelId, UserId, RegOpts, UserSubData, and Expiry) are overridden with the attributes, if specified, that are passed in the new Register Subscriber command message. However, if SubName is used with no QName field specified, and a ReplyToQ is specified in the MQMD header, the subscriber queue is changed to be the ReplyToQ.

If a subscription that matches the traditional identity of this command already exists, but has no SubName , the Registration command fails with return code MQRCCF_DUPLICATE_SUBSCRIPTION, unless the AddName option is specified.

If you try to alter an existing named subscription by using another Register Subscriber command that specifies the same SubName , and the values of Topic, QMgrName, QName, and CorrelId in the new command match a different existing subscription, with or without a SubName defined, the command fails with return code MQRCCF_DUPLICATE_SUBSCRIPTION. This prevents two subscription names referring to the same subscription.

SubIdentity (MQPSC_SUBSCRIPTION_IDENTITY)

This string is used to represent an application with an interest in a subscription. It is a variable-length character string with a maximum length of 64 characters, and is optional. The queue manager maintains a set of subscriber identities for each subscription. Each subscription can allow its identity set to contain only one identity, or an unlimited number of identities (see the JoinShared and JoinExcl options).

A subscribe command that specifies the JoinShared or JoinExcl option adds the SubIdentity to the subscription's identity set, if it is not already there and if the existing set of identities allows such an action; that is, no other subscriber has joined exclusively or the identity set is empty.

Any alteration of the subscription's attributes as the result of a Register Subscriber command in which a SubIdentity is specified, only succeeds if it would be the only member of the set of identities for this subscription. Otherwise the command fails with return code MQRCCF_SUBSCRIPTION_IN_USE. This prevents a subscription's attributes from changing without other interested subscribers being aware.

If you specify a character string that is longer than 64 characters, the command fails with return code MQRCCF_SUB_IDENTITY_ERROR.

SubUserData (MQPSC_SUBSCRIPTION_USER_DATA)

This is a variable-length text string. The value is stored by the queue manager with the subscription, but has no influence on publication delivery to the subscriber. The value can be altered by re-registering to the same subscription with a new value. This attribute is there for the use of the application.

The SubUserData is returned in the Metatopic information (MQCACF_REG_SUB_USER_DATA) for a subscription if present.

If you specify more than one of the registration option values NonPers, PersAsPub, PersAsQueue, and Pers, then only the last one is used. We cannot combine these options in an individual subscription.

Example

 <psc>
   <Command>RegSub</Command>
   <RegOpt>PersAsPub</RegOpt>
   <RegOpt>CorrelAsId</RegOpt>
   <Topic>Sport/Soccer/State/LatestScore/#</Topic>
 </psc>