DISPLAY TPSTATUS

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


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 .

Synonym: DIS TPS


DISPLAY TPSTATUS

DISPLAY TPSTATUS ( topicstr ) WHERE(FilterCondition) ALL CMDSCOPE(' ')CMDSCOPE(qmgr-name)1CMDSCOPE(*)12TYPE(TOPIC)TYPE(SUB)TYPE(PUB)topic statussub statuspub statusTopic status,ADMINCLROUTECLUSTERCOMMINFO3DEFPRESPDEFPRTYDEFPSISTDURSUBMCAST3MDURMDLMNDURMDLNPMSGDLVPMSGDLVPUBPUBCOUNTPUBSCOPERETAINEDSUBSUBCOUNTSUBSCOPEUSEDLQSub status,ACTCONNDURABLELMSGDATELMSGTIMEMCASTREL3NUMMSGSRESMDATERESMTIMESUBIDSUBTYPESUBUSERPub status,ACTCONNLPUBDATELPUBTIMEMCASTREL3NUMPUBSNotes:

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

    • On Multiplatforms using the runmqsc command, these non-printable characters are displayed as dots.
    • On z/OS, these non-printable characters are displayed as blanks.

  2. The topic-string input parameter on this command must match the topic we 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 we issue commands using MQSC, you have fewer characters available to you than if we 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 we want to display status information. We 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 we 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.

        We 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, we 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.

        We 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 we do not specify a generic name, and do not request any specific attributes.

    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.

      We can specify a queue manager name other than the queue manager on which you enter the command, but only if we 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. We 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. We 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 we 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. We 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 we 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.

Parent topic: MQSC commands


Related reference


Related information