Deregister Subscriber message

The Deregister Subscriber command message is sent to a broker from a subscriber, or to another application on a subscriber's behalf, to indicate that it no longer wants to receive messages matching the given parameters.

This message is sent to SYSTEM.BROKER.CONTROL.QUEUE, the broker's control queue. The user must have the necessary authority to put a message onto this queue.

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

An individual subscription can be deregistered by specifying the corresponding topic, subscription point and filter values of the original subscription. If any of the values were not specified (that is, they took the default values) in the original subscription, they should be omitted when the subscription is deregistered.

All subscriptions for a subscriber, or a group of subscribers, can be deregistered by using the DeregAll option. For example, if DeregAll is specified, together with a subscription point (but no topic or filter), then all subscriptions for the subscriber on the specified subscription point are deregistered, regardless of the topic and filter. Any combination of topic, filter and subscription point is allowed; if all three are specified only one subscription can match, and the DeregAll option is ignored.

The message must be sent by the subscriber that registered the subscription; this is confirmed by checking the subscriber's user ID.

Subscriptions can also be deregistered by a system administrator. However, the subscriptions registered with a temporary dynamic queue are associated with the queue, not just the queue name. If the queue is deleted, either explicitly, or by the application disconnecting from the queue manager, it is no longer possible to use the Deregister Subscriber command to deregister the subscriptions for that queue. The subscriptions can be deregistered using the workbench, and they are removed automatically by the broker the next time that it matches a publication to the subscription, or the next time the broker restarts. Under normal circumstances, applications should deregister their subscriptions before deleting the queue, or disconnecting from the queue manager.

If a subscriber sends a message to deregister a subscription, and receives a response message to say that this was processed successfully, some publications might still reach the subscriber queue if they were being processed by the broker at the same time as the subscription was being deregistered. If the messages are not removed from the queue, there might be a buildup of unprocessed messages on the subscriber queue. If the application executes a loop that includes an MQGET call with the appropriate CorrelId after sleeping for a while, these messages are cleared off the queue. If you are using the SCADA Device Protocol there is an option of clean start and finish. This means that the messages are cleared away for the client.

Similarly, if the subscriber uses a permanent dynamic queue, and deregisters and closes the queue with the MQCO_DELETE_PURGE option on an MQCLOSE call, the queue might not be empty. If any publications from the broker are not yet be committed when the queue is deleted, an MQRC_Q_NOT_EMPTY return code is issued by the MQCLOSE call. The application can avoid this problem by sleeping and reissuing the MQCLOSE call from time to time.

Properties

<Command> (MQPSC_COMMAND)
The value is DeregSub (MQPSC_DEREGISTER_SUBSCRIBER).

This property must be specified.

<Topic> (MQPSC_TOPIC)
The value is a string that contains the topic to be deregistered.

This property can, optionally, be repeated if multiple topics are to be deregistered. It can be omitted if DeregAll is specified in <RegOpt>.

The topics that are specified can be a subset of those that are registered if the subscriber wants to retain subscriptions for other topics. Wildcard characters are allowed, but a topic string that contains wildcard characters must exactly match the corresponding string that was specified in the Register Subscriber command message.

<SubPoint> (MQPSC_SUBSCRIPTION_POINT)
The value is a string that specifies the subscription point from which the subscription is to be detached.
This property must not be repeated. It can be omitted if a <Topic> is specified, or if DeregAll is specified in <RegOpt>. If you omit this property, the following happens:
  • If you do not specify DeregAll, subscriptions matching the <Topic> property (and the <Filter> property, if present) are deregistered from the default subscription point.
  • If you specify DeregAll, all subscriptions (matching the <Topic> and <Filter> properties if present) are deregistered from all subscription points.

Note that you cannot specify the default subscription point explicitly. Therefore, there is no way of deregistering all subscriptions from this subscription point only; you must specify the topics.

<SubIdentity> (MQPSC_SUBSCRIPTION_IDENTITY)
This is a variable-length string with a maximum length of 64 characters. It is used to represent an application with an interest in a subscription. The broker maintains a set of subscriber identities for each subscription. Each subscription can allow its identity set to hold only a single identity, or an unlimited number of identities.

If the SubIdentity is in the identity set for the subscription then it is removed from the set. If the identity set becomes empty as a result of this, the subscription is removed from the broker, unless LeaveOnly is specified as a value of the RegOpt property. If the identity set still contains other identities then the subscription is not removed from the broker, and publication flow is not interrupted.

If SubIdentity is specified, but the SubIdentity is not in the identity set for the subscription, then the Deregister Subscriber command fails with the return code MQRCCF_SUB_IDENTITY_ERROR.

<Filter> (MQPSC_FILTER)
The value is a string specifying the filter to be deregistered. It must match exactly, including case and any spaces, a subscription filter that has been previously registered.

This property can, optionally, be repeated if more than one filter is to be deregistered. It can be omitted if a <Topic> is specified, or if DeregAll is specified in <RegOpt>.

The filters specified can be a subset of those registered if the subscriber wants to retain subscriptions for other filters.

<RegOpt> (MQPSC_REGISTRATION_OPTION)
The registration options property can take the following values:
DeregAll  
(MQPSC_DEREGISTER_ALL)

All matching subscriptions registered for this subscriber are to be deregistered.

If you specify DeregAll:
  • <Topic>, <SubPoint>, and <Filter> can be omitted.
  • <Topic> and <Filter> can be repeated, if required.
  • <SubPoint> must not be repeated.
If you do not specify DeregAll:
  • <Topic> must be specified, and can be repeated if required.
  • <SubPoint> and <Filter> can be omitted.
  • <SubPoint> must not be repeated.
  • <Filter> can be repeated, if required.
CorrelAsId  
(MQPSC_CORREL_ID_AS_IDENTITY)

The CorrelId in the message descriptor (MQMD), which must not be zero, is used to identify the subscriber. It must match the CorrelId used in the original subscription.

FullResp  
()

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

When FullResp is specified DeregAll is not permitted in the Deregister Subscriber command. It is also not possible to specify multiple topics. The command fails with return code MQRCCF_REG_OPTIONS_ERROR, in both cases.

LeaveOnly  
(MQPSC_LEAVE_ONLY)

When you specify this with a SubIdentity which is in the identity set for the subscription the SubIdentity is removed from the identity set for the subscription. The subscription is not removed from the broker, even if the resulting identity set is empty. If the SubIdentity value is not in the identity set the command fails with return code MQRCCF_SUB_IDENTITY_ERROR.

If LeaveOnly is specified with no SubIdentity, the command fails with return code MQRCCF_REG_OPTIONS_ERROR.

If neither LeaveOnly nor a SubIdentity are specified, then the subscription is removed regardless of the contents of the identity set for the subscription.

None  
(MQPSC_NONE)

All options take their default values. This has the same effect as omitting the registration options property. If other options are specified at the same time, None is ignored.

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 broker 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, the return code MQRCCF_DUPLICATE_SUBSCRIPTION is returned.

Any user can modify or deregister the subscription when they have suitable authority, avoiding the existing check that the userid must match 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 to be deregistered has VariableUserId set this must be set at deregister time to indicate which subscription is being deregistered. Otherwise, the userid of the Deregister Subscriber command is used to identify the subscription. This is overridden, along with the other subscriber identifiers, if a subscription name is supplied.

The default, if this property is omitted, is that no registration options are set.

<QMgrName> (MQPSC_Q_MGR_NAME)
The value is the queue manager name for the subscriber queue. It must match the QMgrName used in the original subscription.

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 name of the broker's queue manager.

<QName> (MQPSC_Q_NAME)
The value is the name of the subscriber queue. It must match the QName used in the original subscription.

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

<SubName> (MQPSC_SUBSCRIPTION_NAME)
If you specify SubName on a Deregister Subscriber command the SubName value takes precedence over all other identifier fields except the userid, unless VariableUserId is set on the subscription itself. If VariableUserId is not set, the Deregister Subscriber command succeeds only if the userid of the command message matches that of the subscription, if not the command fails with return code MQRCCF_DUPLICATE_IDENTITY.

If a subscription exists that matches the traditional identity of this command but has no SubName the Deregister Subscriber command fails with return code MQRCCF_SUB_NAME_ERROR. If an attempt is made to deregister a subscription that has a SubName using a command message that matches the traditional identity but with no SubName specified the command succeeds.

<SubUserData> (MQPSC_SUBSCRIPTION_USER_DATA)
This is a variable-length text string. The value is stored by the broker with the subscription but has no influence on the delivery of the publication 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.

Example

Here is an example of NameValueData for a Deregister Subscriber command message. In this example, the sample application is deregistering its subscription to the topics which contain the latest score for all matches. The subscriber's identity, including the CorrelId, is taken from the defaults in the MQMD.
 <psc>
  <Command>DeregSub</Command>
  <RegOpt>CorrelAsId</RegOpt>
  <Topic>Sport/Soccer/State/LatestScore/#</Topic>
 </psc>