DISPLAY TPSTATUS (display topic status)

Use the MQSC command DISPLAY TPSTATUS to display the status of one or more topics in a topic tree.

Using MQSC commands

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

[z/OS]You can issue this command from sources 2CR. For an explanation of the source symbols, see Sources from which you can issue MQSC commands on z/OS®.

Synonym: DIS TPS

DISPLAY TPSTATUS

Read syntax diagramSkip visual syntax diagram DISPLAY TPSTATUS ( topicstr ) WHERE(FilterCondition) ALL CMDSCOPE(' ')CMDSCOPE(qmgr-name)1CMDSCOPE(*)12TYPE(TOPIC)TYPE(SUB)TYPE(PUB)topic statussub statuspub status
Topic status
Read syntax diagramSkip visual syntax diagram,ADMINCLROUTECLUSTERCOMMINFO3DEFPRESPDEFPRTYDEFPSISTDURSUBMCAST3MDURMDLMNDURMDLNPMSGDLVPMSGDLVPUBPUBCOUNTPUBSCOPERETAINEDSUBSUBCOUNTSUBSCOPEUSEDLQ
Sub status
Read syntax diagramSkip visual syntax diagram,ACTCONNDURABLELMSGDATELMSGTIMEMCASTREL3NUMMSGSRESMDATERESMTIMESUBIDSUBTYPESUBUSER
Pub status
Read syntax diagramSkip visual syntax diagram,ACTCONNLPUBDATELPUBTIMEMCASTREL3NUMPUBS
Notes:
  • 1 Valid only on z/OS when the queue manager is a member of a queue sharing group.
  • 2 Valid only on z/OS.
  • 3 Not valid on z/OS.

Usage notes for DISPLAY TPSTATUS

  1. The TOPICSTR parameter might contain characters that cannot be translated into printable characters when the command output is displayed.
    • [UNIX, Linux, Windows, IBM i]On Multiplatforms using the runmqsc command, these non-printable characters are displayed as dots.
    • [z/OS]On z/OS, these non-printable characters are displayed as blanks.
  2. The topic-string input parameter on this command must match the topic you want to act on. Keep the character strings in your topic strings as characters that can be used from the location issuing the command. If you issue commands using MQSC, you have fewer characters available to you than if you are using an application that submits PCF messages, such as the IBM® MQ Explorer.

Parameter descriptions for DISPLAY TPSTATUS

The DISPLAY TPSTATUS command requires a topic string value to determine which topic nodes the command returns.

topicstr)
The value of the topic string for which you want to display status information. You cannot specify the name of an IBM MQ topic object.

The topic string can have one of the following values:

  • A specific topic string value. For example, DIS TPS('Sports/Football') returns just the 'Sports/Football' node.
  • A topic string containing a + wildcard character. For example, DIS TPS('Sports/Football/+') returns all direct child nodes of the 'Sports/Football' node.
  • A topic string containing a # wildcard character. For example, DIS TPS('Sports/Football/#') returns the 'Sports/Football' node and all its descendant nodes.
  • A topic string containing more than one wildcard. For example, DIS TPS('Sports/+/Teams/#') returns any direct child node of 'Sports' that also has a 'teams' child, with all descendants of the latter nodes.

The DISPLAY TPSTATUS command does not support the '*' wildcard. For more information about using wildcards, see the related topic.

  • To return a list of all root-level topics, use DIS TPS('+')
  • To return a list of all topics in the topic tree, use DIS TPS('#'), but note that this command might return a large amount of data.
  • To filter the list of topics returned, use the WHERE parameter. For example, DIS TPS('Sports/Football/+') WHERE(TOPICSTR LK 'Sports/Football/L*') returns all direct child nodes of the 'Sports/Football' node, that begin with the letter L.
WHERE
Specifies a filter condition to display only those administrative topic definitions that satisfy the selection criterion of the filter condition. The filter condition is in three parts: filter-keyword, operator, and filter-value:
filter-keyword
Except for the CMDSCOPE parameter, any parameter that you can use with this DISPLAY command.
operator
Determines whether a topic string satisfies the filter value on the given filter keyword. The operators are:
LT
Less than
GT
Greater than
EQ
Equal to
NE
Not equal to
LE
Less than or equal to
GE
Greater than or equal to
LK
Matches a generic string that you provide as a topicstr
NL
Does not match a generic string that you provide as a topicstr
filter-value
The value that the attribute value must be tested against using the operator. Depending on the filter-keyword, this value can be:
  • An explicit value that is a valid value for the attribute being tested.

    You can use operators LT, GT, EQ, NE, LE, or GE only. However, if the attribute value is one from a possible set of values on a parameter, you can use only EQ or NE.

  • A generic value. This value is a character string with an asterisk at the end, for example ABC*. If the operator is LK, the command lists all topic nodes that begin with the string (ABC in the example). If the operator is NL, the command lists all topic nodes that do not begin with the string.

    You cannot use a generic filter-value for parameters with numeric values or with one of a set of values.

ALL
Use this parameter to display all attributes.

If this parameter is specified, any attributes that you request specifically have no effect; the command displays all attributes.

This parameter is the default parameter if you do not specify a generic name, and do not request any specific attributes.

[z/OS]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.
' '
The command runs on the queue manager on which it was entered. This value is the default value.
qmgr-name
The command runs on the named queue manager, if the queue manager is active within the queue sharing group.

You can specify a queue manager name other than the queue manager on which you enter the command, but only if you are using a queue sharing group environment and the command server is enabled.

*
The command runs on the local queue manager and on every active queue manager in the queue sharing group. The effect of this option is equivalent to entering the command on every queue manager in the queue sharing group.
TYPE
TOPIC
The command displays status information relating to each topic node, which is the default if you do not provide a TYPE parameter.
PUB
The command displays status information relating to applications that have topic nodes open for publish.
SUB
The command displays status information relating to applications that subscribe to the topic node or nodes. The subscribers that the command returns are not necessarily the subscribers that would receive a message published to this topic node. The value of SelectionString or SubLevel determines which subscribers receive such messages.

Topic status parameters

Topic status parameters define the data that the command displays. You can specify these parameters in any order but must not specify the same parameter more than once.

Topic objects can be defined with attributes that have a value of ASPARENT. Topic status shows the resolved values that result in finding the setting of the closest parent administrative topic object in the topic tree, and so will never display a value of ASPARENT.

ADMIN
If the topic node is an admin-node, the command displays the associated topic object name containing the node configuration. If the field is not an admin-node the command displays a blank.
CLROUTE
The routing behavior to use for topics in the cluster defined by the CLUSTER parameter. The values can be as follows:
DIRECT
A publication on this topic string, originating from this queue manager, is sent direct to any queue manager in the cluster with a matching subscription.
TOPICHOST
A publication on this topic string, originating from this queue manager, is sent to one of the queue managers in the cluster that hosts a definition of the corresponding clustered topic object, and from there to any queue manager in the cluster with a matching subscription.
NONE
This topic node is not clustered.
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.
COMMINFO
Displays the resolved value of the name of the communication information object to be used for ths topic node.
DEFPRESP
Displays the resolved default put response of messages published to the topic. The value can be SYNC or ASYNC
DEFPRTY
Displays the resolved default priority of messages published to the topic.
DEFPSIST
Displays the resolved default persistence for this topic string. The value can be YES or NO.
DURSUB
Displays the resolved value that shows whether applications can make durable subscriptions. The value can be YES or NO.
MCAST
Displays the resolved value that shows whether the topic could be transmittable via multicast or not. The value can be ENABLED, DISABLED, or ONLY.
MDURMDL
Displays the resolved value of the name of the model queue to be used for durable subscriptions.
MNDURMDL
Displays the resolved value of the name of the model queue used for non-durable subscriptions.
NPMSGDLV
Displays the resolved value for the delivery mechanism for non-persistent messages published to this topic. The value can be ALL, ALLDUR, or ALLAVAIL.
PMSGDLV
Displays the resolved value for the delivery mechanism for persistent messages published to this topic. The value can be ALL, ALLDUR, or ALLAVAIL.
PUB
Displays the resolved value that shows whether publications are allowed for this topic. The values can be ENABLED or DISABLED.
PUBCOUNT
Displays the number of handles that are open for publish on this topic node.
PUBSCOPE
Determines whether this queue manager propagates publications, for this topic node, to other queue managers as part of a hierarchy or a cluster, or whether it restricts them to only subscriptions defined on the local queue manager. The value can be QMGR or ALL.
RETAINED
Displays whether there is a retained publication associated with this topic. The value can be YES or NO.
SUB
Displays the resolved value that shows whether subscriptions are allowed for this topic. The values can be ENABLED or DISABLED.
SUBCOUNT
Displays the number of subscribers to this topic node, including durable subscribers that are not currently connected.
SUBSCOPE
Determines whether this queue manager propagates subscriptions, for this topic node, to other queue managers as part of a cluster or hierarchy, or whether it restricts the subscriptions to only the local queue manager. The value can be QMGR or ALL.
USEDLQ
Determines whether the dead-letter queue is used when publication messages cannot be delivered to their correct subscriber queue. The value can be YES or NO.

Sub status parameters

Sub status parameters define the data that the command displays. You can specify these parameters in any order but must not specify the same parameter more than once.

ACTCONN
Detects local publications, returning the currently active ConnectionId (CONNID) that opened this subscription.
DURABLE
Indicates whether a durable subscription is not deleted when the creating application closes its subscription handle, and persists over queue manager restart. The value can be YES or NO.
LMSGDATE
The date on which an MQPUT call last sent a message to this subscription. The MQPUT call updates the date field only when the call successfully puts a message to the destination specified by this subscription. An MQSUBRQ call causes an update to this value.
LMSGTIME
The time at which an MQPUT call last sent a message to this subscription. The MQPUT call updates the time field only when the call successfully puts a message to the destination specified by this subscription. An MQSUBRQ call causes an update to this value.
MCASTREL
Indicator of the reliability of the multicast messages.
The values are expressed as a percentage. A value of 100 indicates that all messages are being delivered without problems. A value less than 100 indicates that some of the messages are experiencing network issues. To determine the nature of these issues you can enable event message generation, use the COMMEV parameter of the COMMINFO objects, and examine the generated event messages.
The following two values are returned:
  • The first value is based on recent activity over a short period.
  • The second value is based on activity over a longer period.
If no measurement is available the values are shown as blanks.
NUMMSGS
Number of messages put to the destination specified by this subscription. An MQSUBRQ call causes an update to this value.
RESMDATE
Date of the most recent MQSUB call that connected to this subscription.
RESMTIME
Time of the most recent MQSUB call that connected to this subscription.
SUBID
An all time unique identifier for this subscription, assigned by the queue manager. The format of SUBID matches that of a CorrelId. For durable subscriptions, the command returns the SUBID even if the subscriber is not currently connected to the queue manager.
SUBTYPE
The type of subscription, indicating how it was created. The value can be ADMIN, API, or PROXY.
SUBUSER
The user ID that owns this subscription, which can be either the user ID associated with the creator of the subscription or, if subscription takeover is permitted, the user ID that last took over the subscription.

Pub status parameters

Pub status parameters define the data that the command displays. You can specify these parameters in any order but must not specify the same parameter more than once.

ACTCONN
The currently active ConnectionId (CONNID) associated with the handle that has this topic node open for publish.
LPUBDATE
The date on which this publisher last sent a message.
LPUBTIME
The time at which this publisher last sent a message.
MCASTREL
Indicator of the reliability of the multicast messages.
The values are expressed as a percentage. A value of 100 indicates that all messages are being delivered without problems. A value less than 100 indicates that some of the messages are experiencing network issues. To determine the nature of these issues you can enable event message generation, using the COMMEV parameter of the COMMINFO objects, and examine the generated event messages.
The following two values are returned:
  • The first value is based on recent activity over a short period.
  • The second value is based on activity over a longer period.
If no measurement is available the values are shown as blanks.
NUMPUBS
Number of publishes by this publisher. This value records the actual number of publishes, not the total number of messages published to all subscribers.