CLEAR TOPICSTR

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

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

• Syntax diagram
• Usage notes for CLEAR TOPICSTR
• Parameter descriptions for CLEAR TOPICSTR

Synonym: None.

CLEAR TOPICSTR

Notes:

• ¹ Valid only on z/OS when the queue manager is a member of a queue sharing group.
• ² 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. We 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 we 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 we issue commands using MQSC, we will have fewer characters available to you than if we are using an application submitting PCF messages, such as the IBM MQ Explorer.
3. We 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, we 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, we 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

We must specify which topic string we 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:

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.

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.

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

Parent topic: MQSC commands