REFRESH CLUSTER

Use the MQSC command REFRESH CLUSTER to discard all locally held cluster information and force it to be rebuilt. The command also processes any autodefined channels that are in doubt. After the command completes processing, we can perform a cold-start on the cluster.


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 .

Synonym: REF CLUSTER


REFRESH CLUSTER

REFRESH CLUSTER ( generic-clustername ) CMDSCOPE(' ')CMDSCOPE(qmgr-name)12REPOS (NO)REPOS (YES)Notes:

  • 1 Valid only when the queue manager is a member of a queue sharing group.
  • 2 Valid only on z/OS.


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 Check 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 we 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, we 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, we 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, we must refresh the other partial repositories to restore a working cluster.

    If it is not the sole remaining repository, we 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.

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

Parent topic: MQSC commands


Related information