REFRESH CLUSTER

Use REFRESH CLUSTER to discard all locally held cluster information (including any autodefined channels that are in doubt), and force it to be rebuilt. This enables you to perform a "cold-start" on the cluster.

Notes:

  1. It is not normally necessary to issue a REFRESH CLUSTER command except in one of the following circumstances:

    • Messages have been removed from either the SYSTEM.CLUSTER.COMMAND.QUEUE, or from another queue manager's SYSTEM.CLUSTER.TRANSMIT.QUEUE, where the destination queue is SYSTEM.CLUSTER.COMMAND.QUEUE on the queue manager in question.

    • Issuing a REFRESH CLUSTER command has been recommended by IBM Service.

    • The CLUSRCVR channels were removed from a cluster, or their CONNAMEs were altered on two or more full repository queue managers while they could not communicate.

    • The same name has been used for a CLUSRCVR channel on more than one queue manager in a cluster, and as a result, messages destined for one of the queue managers have been delivered to another. In this case, the duplicates should be removed, and then a REFRESH CLUSTER command should be issued on the single remaining queue manager that has the CLUSRCVR definition.

    • RESET CLUSTER ACTION(FORCEREMOVE) was issued in error.

    • The queue manager has been restarted from an earlier point in time than it last finished, (for example, by restoring backed up data.)

  2. Issuing REFRESH CLUSTER does not correct mistakes in cluster definitions, nor is it necessary to issue the command after such mistakes have been corrected.

  3. On UNIX systems, the command is valid only on AIX, HP-UX, Linux, and Solaris.

  4. On z/OS, the command fails if the channel initiator has not been started.

  5. On z/OS, any errors are reported to the console on the system where the channel initiator is running; they are not reported to the system that issued the command.

  6. This command is not available within the reduced function form of WebSphere MQ for z/OS supplied with WebSphere Application Server.

Synonym: REF CLUSTER 

REFRESH CLUSTER
 
>>-REFRESH CLUSTER(generic-clustername)------------------------->
 
   .-CMDSCOPE(' ')------------. (1)   .-REPOS (NO)--.
>--+--------------------------+-------+-------------+----------><
   |                     (2)  |       '-REPOS (YES)-'
   '-CMDSCOPE(qmgr-name)------'

Notes:

  1. Valid only on z/OS.

  2. Valid only on full function WebSphere MQ for z/OS when the queue manager is a member of a queue-sharing group.

 

Parameter descriptions

(generic-clustername)
The name of the cluster to be refreshed. Alternatively the clustername can be specified as '*'. In this case the queue manager is refreshed in all the clusters that it is a member of. If used in conjunction with REPOS(YES), this has the additional effect of forcing the queue manager to restart its search for full repositories from the information in the local CLUSSDR definitions, even if the CLUSSDR connects the queue manager to several clusters.

This is required.

CMDSCOPE
This parameter applies to z/OS only and specifies how the command is executed when the queue manager is a member of a queue-sharing group.

' '
The command is executed on the queue manager on which it was entered. This is the default value.

qmgr-name
The command is executed 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.

REPOS
Specifies whether objects representing full repository cluster queue managers are also refreshed.

NO
The queue manager retains knowledge of all cluster queue manager and cluster queues marked as locally defined, and all cluster queue managers that are marked as full repositories. In addition, if the queue manager is a full repository for the cluster, it retains knowledge of the other cluster queue managers in the cluster. Everything else is removed from the local copy of the repository and rebuilt from the other full repositories in the cluster. Cluster channels are not stopped if REPOS(NO) is used, a full repository uses its CLUSSDR channels to inform the rest of the cluster that it has completed its refresh.

This is the default.

YES
Specifies that in addition to the REPOS(NO) behavior, objects representing full repository cluster queue managers are also refreshed. This option must not be used if the queue manager is itself a full repository, if it is a full repository, first alter it so that it is not a full repository for the cluster in question. The full repository location is recovered from the manually defined CLUSSDR definitions. After the refresh with REPOS(YES) has been issued, the queue manager can be altered so that it is once again a full repository, if required.

On z/OS, N and Y are accepted synonyms of NO and YES.

 

Usage Notes

  1. Issuing REFRESH CLUSTER is disruptive to the cluster. It might make cluster objects invisible for a short period of time until the REFRESH processing completes. Specifically, if an application is using a queue that it has opened with MQOO_BIND_NOT_FIXED in effect, it might receive the return code MQRC_NO_DESTINATIONS_AVAILABLE. If the command is issued on a full repository queue manager, REFRESH CLUSTER might make a large volume of messages flow.

  2. If cluster sender channels are running at the time REFRESH CLUSTER is issued, the refresh might not be complete until the channels have stopped and restarted. It is strongly recommended that all cluster sender channels for the cluster are stopped before the REFRESH CLUSTER command is issued. During the processing of the REFRESH CLUSTER command, the channel state might be recreated if the channel is not in doubt.

  3. If you select REPOS(YES), check that all cluster sender channels in the relevant cluster are inactive or stopped before you issue the REFRESH CLUSTER command. If there are cluster sender channels running at the time the REFRESH CLUSTER command is processed, and they are used exclusively by the clusters being refreshed, and REPOS(YES) is used, the channels are stopped, by using the STOP CHANNEL command with MODE(FORCE) if necessary. This ensures that the refresh can remove the channel state, and that the channel runs with the refreshed version after the refresh has completed. If a channel's state cannot be deleted, for example because it is in doubt, or because it is also running as part of a another cluster, its state will not be new after the refresh, and it does not automatically restart if it was stopped.

    Selecting REPOS(YES) on the sole working full repository queue manager in a cluster requires you to alter it to be a partial repository, with the result that there would be no full repository left. After the queue manager is refreshed and then restored to its status of a full repository, the other partial repositories would also have to be refreshed to restore a working cluster. If there is another working full repository in the cluster, it informs the other members of the cluster that the full repository executing the REFRESH CLUSTER command has resumed its role as a full repository, and no further action is needed.

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.