DEFINE TOPIC

Use DEFINE TOPIC to define a new IBM MQ administrative topic in a topic tree, and set its parameters.

Use MQSC commands

For information on how we use MQSC commands, see Performing local administration tasks using MQSC commands.

We can issue this command from sources 2CR. For an explanation of the source symbols, see Sources from which we can issue MQSC commands on z/OS .

Syntax diagram
Usage notes for DEFINE TOPIC
Parameter descriptions for DEFINE TOPIC

Synonym: DEF TOPIC

Values shown above the main line in the railroad diagram are the defaults supplied with IBM MQ, but your installation might have changed them. See Syntax diagrams.

DEFINE TOPIC

Define attrs

Topic attrs

Notes:

¹ Valid only on z/OS when the queue manager is a member of a queue sharing group.
² Valid only on z/OS.
³ Not valid on z/OS.

Usage notes for DEFINE TOPIC

When an attribute has the value ASPARENT, the value is taken from the setting of the first parent administrative node that is found in the topic tree. Administered nodes are based on either locally defined topic objects or remotely defined cluster topics when participating in a publish/subscribe cluster. If the first parent topic object also has the value ASPARENT, the next object is looked for. If every object that is found, when looking up the tree, uses ASPARENT, the values are taken from the SYSTEM.BASE.TOPIC, if it exists. If SYSTEM.BASE.TOPIC does not exist, the values are the same as the values supplied with IBM MQ in the definition of the SYSTEM.BASE.TOPIC.
The ASPARENT attribute is applied at each queue manager in the cluster collective by inspecting the set of local definitions and cluster definitions that is visible in the queue manager at the time.
When a publication is sent to multiple subscribers, the attributes used from the topic object are used consistently for all subscribers that receive the publication. For example, inhibiting publication on a topic is applied for the next application MQPUT to the topic. A publication that is in progress to multiple subscribers completes to all subscribers. This publication does not take note of a change that has happened, part of the way through, to any attribute on the topic.
Successful completion of the command does not mean that the action completed. To check for true completion, see the DEFINE TOPIC step in Check that async commands for distributed networks have finished.

Parameter descriptions for DEFINE TOPIC

(topic-name)

Name of the IBM MQ topic definition (see Rules for naming IBM 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).

CLROUTE

The routing behavior to use for topics in the cluster defined by the CLUSTER parameter.

DIRECT: When you configure a direct routed clustered topic on a queue manager, all queue managers in the cluster become aware of all other queue managers in the cluster. When performing publish and subscribe operations, each queue manager can connect direct to any other queue manager in the cluster.
TOPICHOST: When we use topic host routing, all queue managers in the cluster become aware of the cluster queue managers that host the routed topic definition (that is, the queue managers on which you have defined the topic object). When performing publish and subscribe operations, queue managers in the cluster connect only to these topic host queue managers, and not directly to each other. The topic host queue managers are responsible for routing publications from queue managers on which publications are published to queue managers with matching subscriptions.

After a topic object has been clustered (through setting the CLUSTER property) we cannot change the value of the CLROUTE property. The object must be un-clustered (CLUSTER set to ' ') before we can change the value. Un-clustering a topic converts the topic definition to a local topic, which results in a period during which publications are not delivered to subscriptions on remote queue managers; this should be considered when performing this change. See The effect of defining a non-cluster topic with the same name as a cluster topic from another queue manager. If you try to change the value of the CLROUTE property while it is clustered, the system generates an MQRCCF_CLROUTE_NOT_ALTERABLE exception.

CLUSTER

The name of the cluster to which this topic belongs. Setting this parameter to a cluster that this queue manager is a member of makes all queue managers in the cluster aware of this topic. Any publication to this topic or a topic string below it put to any queue manager in the cluster is propagated to subscriptions on any other queue manager in the cluster. For more details, see Distributed publish/subscribe networks.

' ': If no topic object above this topic in the topic tree has set this parameter to a cluster name, then this topic does not belong to a cluster. Publications and subscriptions for this topic are not propagated to publish/subscribe cluster-connected queue managers. If a topic node higher in the topic tree has a cluster name set, publications and subscriptions to this topic are also propagated throughout the cluster.
string: The topic belongs to this cluster. It is not recommended that this is set to a different cluster from a topic object above this topic object in the topic tree. Other queue managers in the cluster will honor this object's definition unless a local definition of the same name exists on those queue managers.

To prevent all subscriptions and publications being propagated throughout a cluster, leave this parameter blank on the system topics SYSTEM.BASE.TOPIC and SYSTEM.DEFAULT.TOPIC, except in special circumstances, for example to support migration.

CMDSCOPE

This parameter applies to z/OS only and specifies how the command runs 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 runs on the queue manager on which it was entered.
qmgr-name: The command runs on the queue manager you specify, providing the queue manager is active within the queue sharing group.
We can specify a queue manager name other than the queue manager on which it was entered, only if we are using a shared queue environment and if the command server is enabled.
*: The command runs 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 Multicast communication information object associated with this topic object.

CUSTOM(string)

The custom attribute for new features.

This attribute contains the values of attributes, as pairs of attribute name and value, separated by at least one space. The attribute name-value pairs have the form NAME(VALUE).

CAPEXPRY(integer)

The maximum time, expressed in tenths of a second, until a message published to a topic which inherits properties from this object, remains in the system until it becomes eligible for expiry processing.

For more information on message expiry processing, see Enforcing lower expiration times.

integer: The value must be in the range one through to 999 999 999.
NOLIMIT: There is no limit on the expiry time of messages put to this topic.
ASPARENT: The maximum message expiry time is based on the setting of the closest parent administrative topic object in the topic tree. This is the default value.

Specify a value for CAPEXPRY that is not valid, does not cause the command to fail. Instead, the default value is used.

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; but an improvement in performance might be seen for messages put in a transaction and any non-persistent messages

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.

On z/OS, N and Y are accepted as synonyms of NO and YES.

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.

LIKE( topic-name )

The name of a topic. The topic parameters are used to model this definition.

If this field is not completed, and we do not complete the parameter fields related to the command, the values are taken from the default definition for topics on this queue manager.

Not completing this field is equivalent to specifying:

LIKE(SYSTEM.DEFAULT.TOPIC)

A default topic definition is provided, but it can be altered by the installation to the default values required. See Rules for naming IBM MQ objects.

On z/OS, the queue manager searches page set zero for an object with the name you specify and a disposition of QMGR or COPY. The disposition of the LIKE object is not copied to the object we are defining. Note:

QSGDISP (GROUP) objects are not searched.
LIKE is ignored if QSGDISP(COPY) is specified.

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 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.

If we use MDURMDL to specify a model queue for a clustered topic, we must ensure that the queue is defined on every queue manager in the cluster where a durable subscription using this topic can be made.

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 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.

If we use MNDURMDL to specify a model queue for a clustered topic, we must ensure that the queue is defined on every queue manager in the cluster where a non-durable subscription using this topic can be made.

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 Subscription performance in publish/subscribe networks.

FIRSTUSE

For each unique topic string at or below this topic object, a proxy subscription is asynchronously sent to all neighboring queue managers in the following scenarios:

When a local subscription is created.
When a proxy subscription is received that must be propagated to further directly connected queue managers.

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: We can restrict the behavior on a publication-by-publication basis, using MQPMO_SCOPE_QMGR on the Put Message options.

ASPARENT: Determines whether this queue manager propagates publications to queue managers as part of a hierarchy or as part of a publish/subscribe cluster. This 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	DEFINE
COPY	The object is defined on the page set of the queue manager that executes the command using the QSGDISP(GROUP) object of the same name as the 'LIKE' object.
GROUP	The object definition resides in the shared repository but only if the queue manager is in a queue sharing group. If the definition is successful, the following command is generated and sent to all active queue managers in the queue sharing group to attempt to make or refresh local copies on page set zero: DEFINE TOPIC(name) REPLACE QSGDISP(COPY) The DEFINE for the group object takes effect regardless of whether the generated command with QSGDISP(COPY) fails.
PRIVATE	Not permitted.
QMGR	The object is defined on the page set of the queue manager that executes the command.

REPLACE and NOREPLACE

Determines whether the existing definition (and on z/OS, with the same disposition) is to be replaced with this one. Any object with a different disposition is not changed.

REPLACE

If the object does exist, the effect is like issuing the ALTER command without the FORCE option and with all the other parameters specified.

(The difference between the ALTER command without the FORCE option, and the DEFINE command with the REPLACE option, is that ALTER does not change unspecified parameters, but DEFINE with REPLACE sets all the parameters. When we use REPLACE, unspecified parameters are taken either from the object named on the LIKE option, or from the default definition, and the parameters of the object being replaced, if one exists, are ignored.)

The command fails if both of the following statements are true:

The command sets parameters that would require the use of the FORCE option if you were using the ALTER command.
The object is open.

The ALTER command with the FORCE option succeeds in this situation. Note: The REPLACE option does not replace the TOPICSTR properties of a topic. TOPICSTR is a property that is usefully varied in the example to test different topic trees. To change topics, delete the topic first.

NOREPLACE

The definition must not replace any existing definition of the object.

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: We 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. Note: The REPLACE option does not replace the TOPICSTR properties of a topic. TOPICSTR is a property that is usefully varied in the example to test different topic trees. To change topics, delete the topic first.

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. This value is the default supplied with IBM MQ, but your installation might have changed it.
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. To force the matching set of topics to be re-evaluated for existing subscriptions, we must restart the queue manager.

Parent topic: MQSC commands

Related information

Defining an administrative topic