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 Use commands on z/OS®.

Synonym: DIS TPS

DISPLAY TPSTATUS

DISPLAY TPSTATUS ( topicstr ) WHERE(FilterCondition)
  • ALL
  • CMDSCOPE(' ')CMDSCOPE(qmgr-name)
  • 1
  • CMDSCOPE(*)1
  • 2TYPE(TOPIC)TYPE(SUB)TYPE(PUB)
  • topic status
  • sub status
  • pub status
  • Topic status,ADMINCLROUTECLUSTERCOMMINFO3
  • DEFPRESPDEFPRTYDEFPSISTDURSUBMCAST3
  • MDURMDLMNDURMDLNPMSGDLVPMSGDLVPUBPUBCOUNTPUBSCOPERETAINEDSUBSUBCOUNTSUBSCOPEUSEDLQ
  • Sub status,ACTCONNDURABLELMSGDATELMSGTIMEMCASTREL3
  • NUMMSGSRESMDATERESMTIMESUBIDSUBTYPESUBUSER
  • Pub status,ACTCONNLPUBDATELPUBTIMEMCASTREL3
  • NUMPUBS
  • 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.

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