REFRESH CLUSTER (rebuild a cluster)

Using MQSC commands

For information on how you use MQSC commands, see Performing local administration tasks using MQSC commands.

Usage notes for REFRESH CLUSTER

1. Issuing REFRESH CLUSTER is disruptive to the cluster. It might make cluster objects invisible for a short time until the REFRESH CLUSTER processing completes. This can affect running applications, as described in Application issues seen when running REFRESH CLUSTER. If an application is publishing or subscribing on a cluster topic, that topic might become temporarily unavailable. See REFRESH CLUSTER considerations for publish/subscribe clusters. The unavailability results in a break in the publication stream until the REFRESH CLUSTER command completes. If the command is issued on a full repository queue manager, REFRESH CLUSTER might make a large volume of messages flow.
2. For large clusters, use of the REFRESH CLUSTER command can be disruptive to the cluster while it is in progress, and again at 27 day intervals thereafter when the cluster objects automatically send status updates to all interested queue managers. See Refreshing in a large cluster can affect performance and availability of the cluster.
3. Quiesce all publish/subscribe applications before issuing the REFRESH CLUSTER command, because issuing this command in a publish/subscribe cluster disrupts delivery of publications to and from other queue managers in the cluster, and might result in proxy subscriptions from other queue managers being canceled. If this happens, resynchronize the proxy subscriptions after the cluster has refreshed, and keep all publish/subscribe applications quiesced until after the proxy subscriptions have been resynchronized. See REFRESH CLUSTER considerations for publish/subscribe clusters.
4. When the command returns control to the user, it does not signify the command has completed. Activity on SYSTEM.CLUSTER.COMMAND.QUEUE indicates the command is still processing. See also the REFRESH CLUSTER step in Checking that async commands for distributed networks have finished.
5. If cluster-sender channels are running at the time REFRESH CLUSTER is issued, the refresh might not complete until the channels stop and restart. To hasten completion, stop all cluster-sender channels for the cluster before you run the REFRESH CLUSTER command. During the processing of the REFRESH CLUSTER command, if the channel is not in doubt, the channel state might be re-created.
6. 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 cluster-sender channels are running at the time you run the REFRESH CLUSTER REPOS(YES) command, those cluster-sender channels are ended during the operation and left in an INACTIVE state after the operation completes. Alternatively, you can force the channels to stop using the STOP CHANNEL command with MODE(FORCE).

   Stopping the channels ensures that the refresh can remove the channel state, and that the channel runs with the refreshed version after the refresh completes. If the state of a channel cannot be deleted, its state is not renewed after the refresh. If a channel was stopped, it does not automatically restart. The channel state cannot be deleted if the channel is in doubt, or because it is also running as part of another cluster.

   If you choose the option REPOS(YES) on full repository queue manager, you must alter it to be a partial repository. If it is the sole working repository in the cluster, the result is that there is no full repository left in the cluster. After the queue manager is refreshed, and restored to its status of a full repository, you must refresh the other partial repositories to restore a working cluster.

   If it is not the sole remaining repository, you do not need to refresh the partial repositories manually. Another working full repository in the cluster informs the other members of the cluster that the full repository running the REFRESH CLUSTER command resumed its role as a full repository.

7. It is not normally necessary to issue a REFRESH CLUSTER command except in one of the following circumstances:
   • Messages were removed from either the SYSTEM.CLUSTER.COMMAND.QUEUE, or from another a cluster transmission queue, where the destination queue is SYSTEM.CLUSTER.COMMAND.QUEUE on the queue manager in question.
   • Issuing a REFRESH CLUSTER command is recommended by IBM® Service.
   • The CLUSRCVR channels were removed from a cluster, or their CONNAME s were altered on two or more full repository queue managers while they could not communicate.
   • The same name was used for a CLUSRCVR channel on more than one queue manager in a cluster. As a result, messages destined for one of the queue managers were delivered to another. In this case, remove the duplicates, and run a REFRESH CLUSTER command on the single remaining queue manager with a CLUSRCVR definition.
   • RESET CLUSTER ACTION(FORCEREMOVE) was issued in error.
   • The queue manager was restarted from an earlier point in time than it finished last time it was used; for example, by restoring backed up data.
8. Issuing REFRESH CLUSTER does not correct mistakes in cluster definitions, nor is it necessary to issue the command after such mistakes are corrected.
9. During REFRESH CLUSTER processing, the queue manager generates the message AMQ9875 followed by the message AMQ9442 or AMQ9404. The queue manager might also generate the message AMQ9420. If the cluster functionality is not affected, the message AMQ9420 can be ignored.
10. On z/OS, the command fails if the channel initiator is not started.
11. 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.

Parameter descriptions for REFRESH CLUSTER

( generic-clustername )

The name of the cluster to be refreshed. Alternatively generic-clustername can be specified as *. If * is specified, the queue manager is refreshed in all the clusters that it is a member of. If used with REPOS(YES), this forces the queue manager to restart its search for full repositories from the information in the local CLUSSDR definitions. It restarts its search, even if the CLUSSDR definitions connect the queue manager to several clusters.

The generic-clustername parameter is required.

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. '' 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. If you do so, you must be using a queue sharing group environment and the command server must be 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. It also retains knowledge of 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 completed its refresh.

NO is the default.

YES

Specifies that in addition to the REPOS(NO) behavior, objects representing full repository cluster queue managers are also refreshed. The REPOS(YES) option must not be used if the queue manager is itself a full repository. If it is a full repository, you must 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) is 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.