ALTER TOPIC
Use ALTER TOPIC to alter the parameters of an existing IBM® WebSphere® MQ topic object.
UNIX and Linux® | Windows |
---|---|
Parameters not specified in the ALTER TOPIC command result in the existing values for those parameters being left unchanged.
Parameter descriptions for ALTER TOPIC
- (topic-name)
- Name
of the IBM WebSphere MQ topic
definition (see Rules for naming IBM WebSphere MQ objects).
The maximum length is 48 characters.
The name must not be the same as any other topic definition currently defined on this queue manager (unless REPLACE is specified).
- CLUSTER
- The
name of the cluster to which this topic belongs.
- ' '
- This topic does not belong to a cluster. Publications and subscriptions for this topic are not propagated to publish/subscribe cluster-connected queue managers.
- string
- The topic belongs to this cluster.
- CMDSCOPE
- This
parameter applies to z/OS only
and specifies how the command is executed when the queue manager is
a member of a queue-sharing group. CMDSCOPE must be blank, or the local queue manager, if QSGDISP is set to GROUP.
- ' '
- The command is executed on the queue manager on which it was entered.
- qmgr-name
- The command is executed on the queue manager you specify, providing
the queue manager is active within the queue-sharing group.
You can specify a queue manager name other than the queue manager on which it was entered, only if you are using a shared queue environment and if the command server is enabled.
- *
- The command is executed on the local queue manager and is also passed to every active queue manager in the queue-sharing group. The effect of * is the same as entering the command on every queue manager in the queue-sharing group.
- COMMINFO(comminfo-name)
- The name of the communication information object associated with this topic object.
- CUSTOM(string)
- The
custom attribute for new features.
This attribute is reserved for the configuration of new features before separate attributes have been introduced. It can contain the values of zero or more attributes as pairs of attribute name and value, separated by at least one space. The attribute name and value pairs have the form
NAME(VALUE)
. Single quotes must be escaped with another single quote.This description will be updated when features using this attribute are introduced. At the moment there are no possible values for
Custom
.
- DEFPRTY(integer)
- The
default priority of messages published to the topic.
- (integer)
- The value must be in the range zero (the lowest priority), through to the MAXPRTY queue manager parameter (MAXPRTY is 9).
- ASPARENT
- The default priority is based on the setting of the closest parent administrative topic object in the topic tree.
- DEFPSIST
- Specifies
the message persistence to be used when applications specify the MQPER_PERSISTENCE_AS_TOPIC_DEF
option.
- ASPARENT
- The default persistence is based on the setting of the closest parent administrative topic object in the topic tree.
- NO
- Messages on this queue are lost during a restart of the queue manager.
- YES
- Messages on this queue survive a restart of the queue manager.
- DEFPRESP
- Specifies
the put response to be used when applications specify the MQPMO_RESPONSE_AS_DEF
option.
- ASPARENT
- The default put response is based on the setting of the closest parent administrative topic object in the topic tree.
- SYNC
- Put operations to the queue that specify MQPMO_RESPONSE_AS_Q_DEF are issued as if MQPMO_SYNC_RESPONSE had been specified instead. Fields in the MQMD and MQPMO are returned by the queue manager to the application.
- ASYNC
- Put operations to the queue that specify MQPMO_RESPONSE_AS_Q_DEF are always issued as if MQPMO_ASYNC_RESPONSE had been specified instead. Some fields in the MQMD and MQPMO are not returned by the queue manager to the application. However, an improvement in performance might be seen for messages put in a transaction and any non-persistent messages
- DESCR(string)
- Plain-text
comment. It provides descriptive information about the object when
an operator issues the DISPLAY TOPIC command.
It must contain only displayable characters. The maximum length is 64 characters. In a DBCS installation, it can contain DBCS characters (subject to a maximum length of 64 bytes).
Note: If characters are used that are not in the coded character set identifier (CCSID) for this queue manager, they might be translated incorrectly if the information is sent to another queue manager. - DURSUB
- Specifies
whether applications are permitted to make durable subscriptions on
this topic.
- ASPARENT
- Whether durable subscriptions can be made on this topic is based on the setting of the closest parent administrative topic object in the topic tree.
- NO
- Durable subscriptions cannot be made on this topic.
- YES
- Durable subscriptions can be made on this topic.
- MCAST
- Specifies
whether multicast is allowable in the topic tree. The values are:
- ASPARENT
- The multicast attribute of the topic is inherited from the parent.
- DISABLED
- No multicast traffic is allowed at this node.
- ENABLED
- Multicast traffic is allowed at this node.
- ONLY
- Only subscriptions from a multicast capable client are allowed.
- MDURMDL(string)
- The
name of the model queue to be used for durable subscriptions that
request that the queue manager manages the destination of its publications
(see Rules
for naming IBM WebSphere MQ objects).
The maximum length is 48 characters.
If MDURMDL is blank, it operates in the same way as ASPARENT values on other attributes. The name of the model queue to be used is based on the closest parent administrative topic object in the topic tree with a value set for MDURMDL.
The dynamic queue created from this model has a prefix of SYSTEM.MANAGED.DURABLE
- MNDURMDL(string)
- The
name of the model queue to be used for non-durable subscriptions that
request that the queue manager manages the destination of its publications
(see Rules
for naming IBM WebSphere MQ objects).
The maximum length is 48 characters.
If MNDURMDL is blank, it operates in the same way as ASPARENT values on other attributes. The name of the model queue to be used is based on the closest parent administrative topic object in the topic tree with a value set for MNDURMDL.
The dynamic queue created from this model has a prefix of SYSTEM.MANAGED.NDURABLE.
- NPMSGDLV
- The
delivery mechanism for non-persistent messages published to this topic:
- ASPARENT
- The delivery mechanism used is based on the setting of the first parent administrative node found in the topic tree relating to this topic.
- ALL
- Non-persistent messages must be delivered to all subscribers, irrespective of durability for the MQPUT call to report success. If a delivery failure to any subscriber occurs, no other subscribers receive the message and the MQPUT call fails.
- ALLAVAIL
- Non-persistent messages are delivered to all subscribers that can accept the message. Failure to deliver the message to any subscriber does not prevent other subscribers from receiving the message.
- ALLDUR
- Non-persistent messages must be delivered to all durable subscribers. Failure to deliver a non-persistent message to any non-durable subscribers does not return an error to the MQPUT call. If a delivery failure to a durable subscriber occurs, no subscribers receive the message and the MQPUT calls fails.
- PMSGDLV
- The
delivery mechanism for persistent messages published to this topic:
- ASPARENT
- The delivery mechanism used is based on the setting of the first parent administrative node found in the topic tree relating to this topic.
- ALL
- Persistent messages must be delivered to all subscribers, irrespective of durability for the MQPUT call to report success. If a delivery failure to any subscriber occurs, no other subscribers receive the message and the MQPUT call fails.
- ALLAVAIL
- Persistent messages are delivered to all subscribers that can accept the message. Failure to deliver the message to any subscriber does not prevent other subscribers from receiving the message.
- ALLDUR
- Persistent messages must be delivered to all durable subscribers. Failure to deliver a persistent message to any non-durable subscribers does not return an error to the MQPUT call. If a delivery failure to a durable subscriber occurs, no subscribers receive the message and the MQPUT calls fails.
- PROXYSUB
- Controls
when a proxy subscription is sent for this topic, or topic strings
below this topic, to neighboring queue managers when in a publish/subscribe
cluster or hierarchy. For more details, see More on routing
mechanisms.
- FIRSTUSE
- For each unique topic string at or below this topic object, a proxy subscription is asynchronously sent to all neighboring queue managers when a local subscription is created or a proxy subscription is received that is propagated to further directly connected queue managers in a hierarchy.
- FORCE
- A wildcard proxy subscription that matches all topic strings at
and below this point in the topic tree is sent to neighboring queue
managers even if no local subscriptions exist. Note: The proxy subscription is sent when this value is set on DEFINE or ALTER. When set on a clustered topic, all queue managers in the cluster issue the wildcard proxy subscription to all other queue managers in the cluster.
- PUB
- Controls
whether messages can be published to this topic.
- ASPARENT
- Whether messages can be published to the topic is based on the setting of the closest parent administrative topic object in the topic tree.
- ENABLED
- Messages can be published to the topic (by suitably authorized applications).
- DISABLED
- Messages cannot be published to the topic.
- PUBSCOPE
- Determines
whether this queue manager propagates publications to queue managers
as part of a hierarchy or as part of a publish/subscribe cluster. Note: You can restrict the behavior on a publication-by-publication basis, using MQPMO_SCOPE_QMGR on the Put Message options.
- ASPARENT
- Whether this queue manager propagates publications to queue managers as part of a hierarchy or as part of a publish/subscribe cluster is based on the setting of the first parent administrative node found in the topic tree that relates to this topic.
- QMGR
- Publications for this topic are not propagated to connected queue managers.
- ALL
- Publications for this topic are propagated to hierarchically connected queue managers and to publish/subscribe cluster-connected queue managers.
- QSGDISP
- This
parameter applies to z/OS only.
Specifies the disposition of the object within the group.
QSGDISP ALTER COPY The object definition resides on the page set of the queue manager that executes the command. The object was defined using a command that had the parameters QSGDISP(COPY). Any object residing in the shared repository, or any object defined using a command that had the parameters QSGDISP(QMGR), is not affected by this command. GROUP The object definition resides in the shared repository. The object was defined using a command that had the parameters QSGDISP(GROUP). Any object residing on the page set of the queue manager that executes the command (except a local copy of the object) is not affected by this command. If the command is successful, the following command is generated and sent to all active queue managers in the queue-sharing group to attempt to refresh local copies on page set zero:
The ALTER for the group object takes effect regardless of whether the generated command with QSGDISP(COPY) fails.DEFINE TOPIC(name) REPLACE QSGDISP(COPY)
PRIVATE The object resides on the page set of the queue manager that executes the command, and was defined with QSGDISP(QMGR) or QSGDISP(COPY). Any object residing in the shared repository is unaffected. QMGR The object definition resides on the page set of the queue manager that executes the command. The object was defined using a command that had the parameters QSGDISP(QMGR). Any object residing in the shared repository, or any local copy of such an object, is not affected by this command. - SUB
- Controls
whether applications are to be permitted to subscribe to this topic.
- ASPARENT
- Whether applications can subscribe to the topic is based on the setting of the closest parent administrative topic object in the topic tree.
- ENABLED
- Subscriptions can be made to the topic (by suitably authorized applications).
- DISABLED
- Applications cannot subscribe to the topic.
- SUBSCOPE
- Determines
whether this queue manager subscribes to publications in this
queue manager or in the network of connected queue managers.
If subscribing to all queue managers, the queue manager propagates
subscriptions to them as part of a hierarchy or as part of a publish/subscribe
cluster. Note: You can restrict the behavior on a subscription-by-subscription basis, using MQPMO_SCOPE_QMGR on the Subscription Descriptor or SUBSCOPE(QMGR) on DEFINE SUB. Individual subscribers can override the SUBSCOPE setting of ALL by specifying the MQSO_SCOPE_QMGR subscription option when creating a subscription.
- ASPARENT
- Whether this queue manager subscribes to publications in the same way as the setting of the first parent administrative node found in the topic tree relating to this topic.
- QMGR
- Only publications that are published on this queue manager reach the subscriber.
- ALL
- A publication made on this queue manager or on another queue manager reaches the subscriber. Subscriptions for this topic are propagated to hierarchically connected queue managers and to publish/subscribe cluster-connected queue managers.
- TOPICSTR(string)
- The
topic string represented by this topic object definition. This parameter
is required and cannot contain the empty string.
The topic string must not be the same as any other topic string already represented by a topic object definition.
The maximum length of the string is 10,240 characters.
- TYPE (topic-type)
- If this parameter is used it must follow immediately after the topic-name parameter
on all platforms except z/OS.
- LOCAL
- A local topic object.
- USEDLQ
- Determines whether the dead-letter queue is used when publication
messages cannot be delivered to their correct subscriber queue.
- ASPARENT
- Determines whether to use the dead-letter queue using the setting of the closest administrative topic object in the topic tree.
- NO
- Publication messages that cannot be delivered to their correct subscriber queue are treated as a failure to put the message. The MQPUT of an application to a topic fails in accordance with the settings of NPMSGDLV and PMSGDLV.
- YES
- When the DEADQ queue manager attribute provides the name of a dead-letter queue, then it is used. If the queue manager does not provide the name of a dead-letter queue, then the behavior is as for NO.
- WILDCARD
- The
behavior of wildcard subscriptions with respect to this topic.
- PASSTHRU
- Subscriptions made to a wildcarded topic less specific than the topic string at this topic object receive publications made to this topic and to topic strings more specific than this topic.
- BLOCK
- Subscriptions made to a wildcarded topic less specific than the topic string at this topic object do not receive publications made to this topic or to topic strings more specific than this topic.
The value of this attribute is used when subscriptions are defined. If you alter this attribute, the set of topics covered by existing subscriptions is not affected by the modification. This scenario applies also if the topology is changed when topic objects are created or deleted; the set of topics matching subscriptions created following the modification of the WILDCARD attribute is created using the modified topology. If you want to force the matching set of topics to be re-evaluated for existing subscriptions, you must restart the queue manager.