Home

 

Optional parameters

QMgrName

name:

"MQPSQMgrName"   (string constant: MQPS_Q_MGR_NAME)

value:

The subscriber's queue manager name.

The default is the ReplyToQMgr name in the message descriptor (MQMD). If the resulting name is blank, it represents a publisher that can be reached by resolving QName at the broker.

QName

name:

"MQPSQName"   (string constant: MQPS_Q_NAME)

value:

The subscriber's queue name.

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

RegistrationOptions

name:

"MQPSRegOpts"   (string constant: MQPS_REGISTRATION_OPTIONS)

value:

The following registration options can be specified:

"AddName"  

(string constant: MQPS_ADD_NAME, integer constant: MQREGO_ADD_NAME)

If AddName is specified, the SubName field is mandatory.

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

If a subscription already exists by this SubName, or if a matching subscription (as identified by the traditional identity) with a different SubName exists on this stream, the command fails.

"Anon"  

(string constant: MQPS_ANONYMOUS, integer constant: MQREGO_ANONYMOUS)

Tells the broker that the identity of the publisher is not to be divulged, except to subscribers with additional authority.

"CorrelAsId"  

(string constant: MQPS_CORREL_ID_AS_IDENTITY, integer constant: MQREGO_CORREL_ID_AS_IDENTITY)

The CorrelId in the message descriptor, MQMD, (which must not be zero) is part of the subscriber's identity.

"DupsOK"  

(string constant: MQPS_DUPLICATES_OK, integer constant: MQREGO_DUPLICATES_OK)

Set this option results in the occasional delivery of duplicate publications to the subscriber. The subscriber should be tolerant of such duplicate publications.

The advantage this option provides is reduced overhead in the broker that can enhance performance.

"FullResp"  

(string constant: MQPS_FULL_RESPONSE, integer constant: MQREGO_FULL_RESPONSE)

If a response message is requested and this option is specified, all attributes of a subscription are returned in the response message of any command that does not fail. When using MQRFH messages, the NameValueString of the response is in the following format. First the standard response fields (space delimited):

MQPSCompCode    <value>
MQPSReason      <value>
MQPSReasonText  <value>

followed by all subscription fields, if defined, (again space delimited) as they appear after any registration changes were made as a result of a Register Subscriber command, or before any changes were made as a result of a Deregister Subscriber command.

MQPSCommand     <value>
MQPSSubName     <value>   (Might not be present)
MQPSTopic       <value>
MQPSQMgrName    <value>
MQPSQName       <value>
MQPSCorrelId    <value>   (Might not be present,
                          48-byte character representation of hex chars)
MQPSUserId      <value>
MQPSRegOpts     <value>   (Can be repeated)
MQPSSubIdentity <value>   (Might not be present, can be repeated)
MQPSSubUserData <value>   (Might not be present)

FullResp is valid only when the command message (Register Subscriber or Deregister Subscriber) refers to only a single subscription. Therefore, only a single topic is permitted in the command, otherwise the command fails.

When PCF structures are used, the above data is returned in an equivalent PCF structured message.

If no response is returned (for example, MQMT_DATAGRAM), this option is ignored.

"InclStreamName"  

(string constant: MQPS_INCLUDE_STREAM_NAME, integer constant: MQREGO_INCLUDE_STREAM_NAME)

Each Publish message that is sent must include the StreamName parameter. The broker does this by adding the appropriate name/value pair to the NameValueString of the message. The NameValueString is extended if necessary.

If this option is not set, StreamName is included only if it was specified explicitly by the publisher.

"InformIfRet"  

(string constant: MQPS_INFORM_IF_RETAINED, integer constant: MQREGO_INFORM_IF_RETAINED)

The broker informs the subscriber if a publication is retained when a Publish message is sent. It does this by adding the name/value pair"MQPSPubOpts IsRetainedPub" to the NameValueString of the message (after the StreamName if that has been added in accordance with theInclStreamName option).

Use this option if a subscriber needs to distinguish between new publications and old publications that were retained by the broker before the subscription was made. If this option is specified, the broker always adds the name/value pair to a publication sent in response to a Request Update command.

"JoinExcl"  

(string constant: MQPS_JOIN_EXCLUSIVE, integer constant: MQREGO_JOIN_EXCLUSIVE)

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 subscription is currently exclusively locked, the command fails if the identity with the exclusive lock is not the one in this command message; if it is the same identity, the command succeeds, but returns a warning of MQRCCF_ALREADY_JOINED.

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.

If an application attempts to register with a SubIdentity and the userid differs from that currently registered with the subscription, it fails if VariableUserId is not set on the original subscription or, if it is set, the userid of the command message is checked for authority to browse the stream queue and put to the subscriber's queue; if it does not have sufficient authority, the command fails.

This option is valid only when SubIdentity is specified.

"JoinShared"  

(string constant: MQPS_JOIN_SHARED, integer constant: MQREGO_JOIN_SHARED)

Indicates that the specified SubIdentity should be added to the identity set for the subscription.

If the subscription currently has zero or more members in the identity set and none match this identity, and it is not exclusively locked (see"JoinExcl"), the command succeeds and adds this identity to the set.

If the identity already has a shared entry for this subscription, the command succeeds but returns a warning of MQRCCF_ALREADY_JOINED.

If the subscription is currently locked exclusively, MQRCCF_SUBSCRIPTION_LOCKED is returned, unless the identity that has the subscription locked is the same identity as the one in this command message, in which case the lock is atomically modified to a shared lock.

If an application attempts to register with a SubIdentity, and the userid differs from the one currently registered with the subscription, it fails if VariableUserId is not set on the original subscription. If it is set, the userid of the command message is checked for authority to browse the stream queue and put to the subscriber's queue; if it does not have sufficient authority, the command fails.

This option is valid only when SubIdentity is specified.

"Local"  

(string constant: MQPS_LOCAL, integer constant: MQREGO_LOCAL)

Tells the broker that the subscription is local and should not be distributed to other brokers in the network. Only publications published at this node by a publisher specifyingLocal are sent to this subscriber.

"Locked"  

(string constant: MQPS_LOCKED, integer constant: MQREGO_LOCKED)

Can be set only by the broker.

This subscription is currently locked (someone has exclusive access to the subscription). This option is automatically set and unset against the subscription as identities JoinExcl and leave. Anyone inquiring on the subscription (either by metatopics or the FullResp option) can see this option set and the current identity set, thus identifying the owner of the lock.

"NewPubsOnly"  

(string constant: MQPS_NEW_PUBLICATIONS_ONLY, integer constant: MQREGO_NEW_PUBLICATIONS_ONLY)

Tells the broker that no currently retained publications are to be sent, only new publications. If a subscriber re-registers and changes this option so that it is not set, it is possible that a publication that has already been sent to it is sent to it again.

"NoAlter"  

(string constant: MQPS_NO_ALTERATION, integer constant: MQREGO_NO_ALTERATION)

When NoAlter is specified, the Register Subscriber command does not modify an existing matching subscription's attributes. This option has no effect when a subscription is created. This is the converse of the default behavior for a subsequent subscription that matches the identity of an existing subscription overwriting any modifiable attributes of the original subscription.

If a SubIdentity is supplied along with a Join option, the identity is added to the identity set (if possible) irrespective of the NoAlter option, because this applies to a subscription's attributes not its current state.

"NonPers"  

(string constant: MQPS_NON_PERSISTENT, integer constant: MQREGO_NON_PERSISTENT)

Any publication sent from a broker to a subscriber that specified this option is sent as a non-persistent message, irrespective of the persistence of the publication message received by the broker.

If you set this option, we cannot set"Pers", "PersAsPub", or "PersAsQueue".

"Pers"  

(string constant: MQPS_PERSISTENT, integer constant: MQREGO_PERSISTENT)

Any publication sent from a broker to a subscriber that specified this option is sent as a persistent message, irrespective of the persistence of the publication message received by the broker.

If you set this option, we cannot set"NonPers", "PersAsPub", or "PersAsQueue".

"PersAsPub"  

(string constant: MQPS_PERSISTENT_AS_PUBLISH, integer constant: MQREGO_PERSISTENT_AS_PUBLISH)

Any publication sent from a broker to a subscriber that specified this option is sent with the persistence of the original publication. This is the default option.

If you set this option, we cannot set"NonPers", "Pers", or "PersAsQueue".

"PersAsQueue"  

(string constant: MQPS_PERSISTENT_AS_Q, integer constant: MQREGO_PERSISTENT_AS_Q)

Any publication sent from a broker to a subscriber that specified this option is sent with the persistence specified on the subscriber queue. The persistence is derived from the DEFPSIST setting of the subscriber queue definition local to the broker: for example, the transmission queue to the subscriber's queue manager if the subscriber's queue manager is remote from the broker's queue manager.

If you set this option, we cannot set"NonPers", "Pers", or "PersAsPub".

"PubOnReqOnly"  

(string constant: MQPS_PUBLISH_ON_REQUEST_ONLY, integer constant: MQREGO_PUBLISH_ON_REQUEST_ONLY)

Indicates that the subscriber polls only for information with Request Update. The broker is not to send unsolicited messages to the subscriber.

This option is not propagated if the broker sends this subscription to other brokers in the network. Publications are sent to it in the normal way, and these publications must specifyRetainPub to be eligible for return in response to a Request Update message.

"VariableUserId"  

(string constant: MQPS_VARIABLE_USER_ID, integer constant: MQREGO_VARIABLE_USER_ID)

When VariableUserId is specified, the identity of the subscriber (queue name, queue manager name, and correlation identifier) is not restricted to a single userid. This allows any user to modify or deregister the subscription when they have suitable authority. To add this option to an existing subscription the command must come from the same userid as the original subscription itself.

If a Register Subscriber command message specifying this option refers to an existing subscription with this option set, and the userid of this message differs from the original subscription, the command succeeds only if the userid of the new command message has authority to browse the stream queue, and put authority to the subscriber queue of the modified subscription (that is, existing Publish/Subscribe authority check for a subscriber). On successful completion, future publications to this subscriber are put to the subscriber's queue with the new userid.

If a Register Subscriber command message without this option set refers to an existing subscription with this option set, the option is removed from this subscription, and the userid of the subscription is now fixed. If at this time a subscriber already exists that has the same identity (queue name, queue manager name, and correlation identifier), but with a different userid associated to it, the command fails.

If the Registration Options parameter is omitted and the subscriber is already registered, its registration options are unchanged. If the subscriber is not already registered, the default is that no registration options are set.

StreamName

name:

"MQPSStreamName"   (string constant: MQPS_STREAM_NAME)

value:

The name of the publication stream for the specified Topic(s).

The default value is SYSTEM.BROKER.DEFAULT.STREAM.

SubIdentity

name:

"MQPSSubIdentity"   (string constant: MQPS_SUBSCRIPTION_IDENTITY)

value:

The subscription identity.

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 unlimited identities (see the"JoinShared" and "JoinExcl" options).

A Register Subscriber command that specifies the JoinShared or JoinExcl option adds the SubIdentity to the subscription's identity set, if it is not already there. Any alteration of the subscription's attributes as the result of a Register Subscriber command where a SubIdentity is specified succeeds only if it would be the only member of the set of identities for this subscription. Otherwise the command fails.

If no SubIdentity is specified the alteration succeeds irrespective of a possible set of identities.

The maximum length of a SubIdentity is defined by MQ_SUB_IDENTITY_LENGTH.

SubName

name:

"MQPSSubName"   (string constant: MQPS_SUBSCRIPTION_NAME)

value:

The subscription name.

If SubName is specified, the subscription name is the single field used to identify a subscription, overriding the traditional identity.

If a subscription already exists that matches the traditional identity of this command, but has no SubName, the Register Subscriber command fails unless the AddName option is specified.

If an existing named subscription is to be altered by another Register Subscriber command specifying 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: two subscription names cannot refer to a single subscription.

Altering or deregistering a subscription that has a SubName is also allowed by a command message that matches the traditional identity but with no SubName specified.

When a SubName value is specified, only one topic attribute is permitted.

If the underlying topic of the subscription is changed, existing retained publications are sent to the subscriber, whether or not they received them as a result of a previous topic for this subscription.

SubUserData

name:

"MQPSSubUserData"   (string constant: MQPS_SUBSCRIPTION_USER_DATA)

value:

The subscription user data.

Variable length text string. The value is stored by the broker 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 for the use of the application.

 

Home