CLEAR TOPICSTR

Use the MQSC command CLEAR TOPICSTR to clear the retained message which is stored for the specified topic string.

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 CR. For an explanation of the source symbols, see Sources from which you can issue MQSC commands on z/OS®.

Synonym: None.

CLEAR TOPICSTR

Read syntax diagramSkip visual syntax diagram CLEAR TOPICSTR ( topic-string ) CLRTYPE(RETAINED)SCOPE(LOCAL)CMDSCOPE(' ')CMDSCOPE(qmgr-name)1CMDSCOPE(*)12
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.

Usage notes for CLEAR TOPICSTR

  1. If the topic string specified has no retained message the command will complete successfully. You can find out whether a topic string has a retained message by using the DISPLAY TPSTATUS command. The RETAINED field shows whether there is a retained message.
  2. The topic-string input parameter on this command must match the topic you want to act on. You are advised to keep the character strings in your topic strings as characters that can be used from location issuing the command. If you issue commands using MQSC, you will have fewer characters available to you than if you are using an application submitting PCF messages, such as the IBM® MQ Explorer.
  3. You might need to use CLEAR TOPICSTR to remove a retained publication from a publish/subscribe cluster. For example:
    • If you accidentally configure a retained publication, and then need to remove it from all cluster queue managers, you issue this command on all members of the cluster.
    • In a direct routed publish/subscribe cluster, if you move a publishing application to a new queue manager and the previous queue manager holds no subscriptions for the affected topic string, you need to ensure that the previous queue manager does not resend the old retained publication to other members of the cluster. To do this, wait until the application has published on the new queue manager, then issue this command on the previous queue manager to remove the retained publication held there.
    See also Design considerations for retained publications in publish/subscribe clusters

Parameter descriptions for CLEAR TOPICSTR

You must specify which topic string you want to remove the retained publication from.
(topic-string)
The topic string to be cleared. This string can represent several topics to be cleared by using wildcards as shown in the following table:
Table 1. Special characters for use in topic strings
Special Character Behavior
# Wildcard, multiple topic level
+ Wildcard, single topic level
Note: the '+' and '#' are not treated as wildcards if they are mixed in with other characters (including themselves) within a topic level. In the following string, the '#' and '+' characters are treated as ordinary characters. 

level0/level1/#+/level3/level#
To illustrate the effect of wildcards, the following example is used.
Clearing the following topic: 

/a/b/#/z
clears the following topics: 

/a/b/z
/a/b/c/z
/a/b/c/y/z
CLRTYPE
This is a mandatory parameter.

The value must be:

RETAINED
Remove the retained publication from the specified topic string.
[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.
CMDSCOPE must be blank, or the name of the local queue manager, if the shared queue object definition has its queue sharing group disposition attribute QSGDISP set to SHARED.
' '
The command runs on the queue manager on which it was entered. This is the default value.
qmgr-name
The command runs on the queue manager you specify, providing the queue manager is active within the queue sharing group.

You can specify a queue manager name, other than the queue manager on which the command was entered, only if you are using a queue sharing group 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 this is the same as entering the command on every queue manager in the queue sharing group.
SCOPE
The scope of the deletion of retained messages.

The value can be:

LOCAL
The retained message is removed from the specified topic string at the local queue manager only. This is the default value.