Topic properties

An IBM MQ topic is an IBM MQ object that identifies what a publication is about. You can set properties for topics. Some topic properties are specific to z/OS topics. Also, there are some properties that we can alter only while we are creating a topic. We cannot modify these properties after the IBM MQ topic has been created.

The following tables list all the properties for IBM MQ Topics.

For each property, there is a brief description of when you might need to configure the property. The tables also give the equivalent MQSC parameters for the DEFINE, ALTER and DISPLAY TOPIC commands. For more information about MQSC commands, see Administration using MQSC commands.


General

The following table lists the properties on the General page of the IBM MQ Topic Properties dialog.

Property Meaning MQSC parameter
Topic name This value cannot be changed after the topic has been created. This parameter is required and cannot contain an empty string.

The unique identifier of the administrative topic definition to be created. A maximum of 48 characters are allowed.

Topic name must not be the same as any other topic definition defined on the selected queue manager.

 TOPNAME
Topic type This value is read only. This value defines whether the topic is local; Local, or in a cluster; Cluster. N/A
Topic String This value cannot be changed after the topic has been created. This parameter is required and cannot contain an empty string.

The / character within this string has special meaning. It delimits the elements in the topic tree. A topic string can start with the / character but is not required to. A string starting with the / character is not the same as the string which starts without the / character.

Topic String must not be the same as any other topic string already represented by another topic object definition. The maximum length of a topic string is 10 240 characters.

 TOPICSTR
Description This value is a string entered by the administrator. It contains descriptive information about the topic. It must contain only displayable characters. A maximum of 64 characters.

If characters are used that are not in the coded character set identifier (CCSID) for the selected queue manager, then they might be translated incorrectly if the information is sent to another queue manager.

 DESC
Publish This property controls whether messages can be published to the topic. The default value is As parent. The 2 other options available are:

Allowed which means that messages can be published to the topic by an authorized application.

Inhibited which means that messages cannot be published to the topic.

 PUB
Subscribe This property controls whether messages can subscribe to the topic. The default value is As parent. The 2 other options available are:

Allowed which means that subscriptions can me made to the topic by an authorized application.

Inhibited which means that applications cannot subscribe to the topic.

 SUB
Durable subscriptions This property controls whether the topic permits durable subscriptions to be made. The default value is As parent. The 2 other options available are:

Allowed which means that durable subscriptions can me made to the topic by an application.

Inhibited which means that durable subscriptions cannot be made to the topic by an application.

 DURSUB
Default priority The default priority of messages published to the topic. The default value is As parent.

The default priority can be set from 0 (the lowest priority) to 9 (the highest priority)

 DEFPRTY
Default persistence The default persistence of a new topic is As parent. Select Persistent to specify that messages created by applications that use MQPER_PERSISTENCE_AS_Q_DEF become persistent. Select Not Persistent to specify that messages created by applications that use MQPER_PERSISTENCE_AS_Q_DEF become nonpersistent. DEFPSIST
Model durable queue

This value is a string entered by the administrator. It contains the name of the model queue used for durable subscriptions that request that the queue manager manages the destination of its publications.

A maximum of 48 characters are allowed for the name.

If this field is blank, then it is treated as As parent

If we are specifying 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

 MDURMDL
Model non-durable queue This value is a string entered by the administrator. It contains the name of the model queue used for nondurable subscriptions that request that the queue manager manages the destination of its publications.

A maximum of 48 characters are allowed for the name.

If this field is blank, then it is treated as As parent

If we are specifying 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

 MNDURMDL
QSG disposition The queue sharing group disposition of the topic. We can set the queue sharing group disposition to one of three values:

  • Queue manager means that the object definition is available only to the queue manager that hosts it.
  • Group means that the object definition is stored on the shared repository and each queue manager in the queue sharing group has a copy of the definition.
  • Copy means that the object definition is the queue manager's copy of a definition in the shared repository.

The field is displayed as read only when we are displaying the properties of a topic.

 QSGDISP
Default put response type The default response type for message puts. The default value is As parent. The 2 other options available are:

Synchronous which means the response is put synchronously.

Asynchronous which means the response is put asynchronously.

 DEFPRESP
Non-persistent message delivery

The delivery method for non-persistent messages published to this topic. The 4 options are:

As parent The delivery mechanism used is based on the setting of the first parent administrative node found in the topic tree relating to this topic. This is the default supplied with IBM MQ, but your installation might have changed it.

To all available subscribers 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.

To all durable subscribers 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 other subscribers receive the message and the MQPUT calls fails.

To all subscribers 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.

 NPMSGDLV
Persistent message delivery

The delivery method for persistent messages published to this topic. The four options are:

As parent The delivery mechanism used is based on the setting of the first parent administrative node found in the topic tree relating to this topic. This is the default supplied with IBM MQ, but your installation might have changed it.

To all available subscribers 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.

To all durable subscribers 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 other subscribers receive the message and the MQPUT calls fails.

To all subscribers 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.

 PMSGDLV
Wildcard operation This value controls the behavior of wildcard subscriptions with respect to the topic. The 2 values are:

Block. Subscriptions made to a wildcard topic less specific than the topic string for this topic object, do not receive publications made to this topic or to topic strings more specific that this topic.

Passthrough. Subscriptions made to a wildcard topic less specific than the topic string for this topic object receive publications made to this topic and to topic strings more specific than this topic. This is the default value.

 WILDCARD
Use dead-letter queue Specifies whether the dead-letter queue is used when publication messages cannot be delivered to their correct subscriber queue. There are three possible values:

  • No means that publication messages that cannot be delivered to their correct subscriber queue are treated as a failure to put the message, and the application's MQPUT to a topic fails in accordance with the settings of Non-persistent message delivery and Persistent message delivery.
  • Yes means that if the queue manager Dead-letter queue property provides the name of a Dead Letter Queue, then it is used. Otherwise the behavior is as for No.
  • As parent means that the decision to use the Dead Letter Queue is based on the setting of the closest administrative topic object in the topic tree. This is the default supplied with IBM MQ but your installation might have changed it.

USEDLQ
Custom The Custom parameter is included for IBM use only, reserved for the configuration of new features before separate properties have been introduced. The possible values are a list of zero or more properties-value pairs, in MQSC-style syntax, separated by at least one space.The property names and values are case-sensitive, and must be specified in uppercase. The values can contain spaces, parentheses and single-quotes (which must be escaped with another single-quote). Other characters, including nested parentheses (), can be included by enclosing them in two single-quotes on either side. Examples of valid syntax are:

  • CUSTOM('')
  • CUSTOM('A(B)')
  • CUSTOM('C(D) E(F)')
  • CUSTOM('G(5000) H(''9.20.4.6(1415)'')')

The queue manager parses the value, but if the string cannot be parsed according to these rules, or if it contains properties or values that are not recognized, the queue manager ignores the errors.

 CUSTOM


Distributed Pub/Sub

The following table lists the properties on the Distributed Pub/Sub page of the IBM MQ Topic Properties dialog.

Property Meaning MQSC parameter
Proxy subscription behavior Proxy-subscriptions are associated with the queue manager name that created them. Publications are only forwarded to directly connected queue managers if a proxy-subscription exists that includes the publication topic. The two options for this value are:

Force. This forces the sending of a wild-carded proxy-subscription for the topic string associated with this topic object from every queue manager in the cluster to every other queue manager in the pub/sub topology, regardless of whether any local subscriptions have been made. Once this forced proxy subscription has been propagated throughout the topology, any new subscriptions immediately receive any publications from other connected queue manager without suffering latency, although all publications are propagated to all other queue managers in the cluster regardless of whether a subscription has requested them or not.

Set this value at a given level in the topic tree also prevents proxy subscriptions being generated for individual topic strings at subsequent levels in the topic tree, reducing the proxy subscription overhead.

First use. For each unique topic string at or beneath 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.

PROXYSUB
Publication scope The scope of publications can be controlled administratively using the PUBSCOPE topic attribute. The attribute can be set to one of the following 3 values:

  • As parent. This is the default value. The publication scope is set to the same value as the parent queue manager.
  • Queue manager. The publication is only delivered to local subscribers.
  • All. The publication is delivered to local subscribers and remote subscribers by directly connected queue managers.

PUBSCOPE
Subscription scope The scope of subscriptions can be controlled administratively using the SUBSCOPE topic attribute. The attribute can be set to one of the following 3 values:

  • As parent. This is the default value. The subscription scope is set to the same value as the parent queue manager.
  • Queue manager. The subscription receives only local publications, and proxy subscriptions are not propagated to remote queue managers.
  • All. A proxy subscription is propagated to remote queue managers, and the subscriber receives local and remote publications.

SUBSCOPE
Multicast This property controls whether the topic is considered to be transmittable with multicast or not. There are four possible values:

As parent. The multicast property 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.

 MCAST
Communication information The communication information object name. As there are more than one topics in the tree which require the same multicast transmission properties, consider having these properties in a separate object which can be referenced. COMMINFO


Cluster

The following table lists the properties on the Cluster page of the IBM MQ Topic Properties dialog.

Property Meaning MQSC parameter
Cluster name To make a topic a cluster topic, you configure this property. When you do this, any topic used by a publisher or subscriber at that point or in the topic tree is shared across all queue managers in the cluster, and messages published to a clustered branch of the topic tree are automatically routed to subscriptions on other queue managers in the cluster. CLUSTER
Cluster object state The current state of this topic object in this cluster. The values can be as follows:

    ACTIVE
    The cluster topic is correctly configured and being adhered to by this queue manager.

    PENDING
    Only seen by a hosting queue manager, this state is reported when the topic has been created but the full repository has not yet propagated it to the cluster. This might be because the host queue manager is not connected to a full repository, or because the full repository has deemed the topic to be invalid.

    INVALID
    This clustered topic definition conflicts with an earlier definition in the cluster and is therefore not currently active.

    ERROR
    An error has occurred with respect to this topic object.

This parameter is typically used to aid diagnosis when multiple definitions of the same clustered topic are defined on different queue managers, and the definitions are not identical.

CLSTATE
Cluster route The routing behavior to use for topics in the cluster defined by the CLUSTER parameter. There are two possible values:

    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 then connects directly to all the others.

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

 CLROUTE


Statistics

The following table lists the properties on the Statistics page of the IBM MQ Topic Properties dialog.

Property Meaning MQSC parameter
Alteration date This value cannot be changed, it is provided for information purposes only.

This is the date on which the topic properties were last altered.

 ALTDATE
Alteration time This value cannot be changed, it is provided for information purposes only.

This is the time at which the topic properties were last altered.

 ALTTIME
Parent topic: Properties


Related tasks