Refresh Cluster

The Refresh Cluster (MQCMD_REFRESH_CLUSTER) command discards all locally held cluster information, including any auto-defined channels that are not in doubt, and forces the repository to be rebuilt.

Note: 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.


Required parameters

    ClusterName (MQCFST)
    Cluster name (parameter identifier: MQCA_CLUSTER_NAME).

    The name of the cluster to be refreshed.

    The maximum length of the string is MQ_CLUSTER_NAME_LENGTH.

    This parameter is the name of the cluster to be refreshed. If an asterisk (*) is specified for the name, the queue manager is refreshed in all the clusters to which it belongs.

    If an asterisk (*) is specified with RefreshRepository set to MQCFO_REFRESH_REPOSITORY_YES, the queue manager restarts its search for repository queue managers, using information in the local cluster-sender channel definitions.


Optional parameters

    CommandScope (MQCFST)
    Command scope (parameter identifier: MQCACF_COMMAND_SCOPE). This parameter applies to z/OS® only. Specifies how the command is executed when the queue manager is a member of a queue-sharing group. We can specify one of the following:

    • blank (or omit the parameter altogether). The command is executed on the queue manager on which it was entered.
    • a queue manager name. The command is executed on the queue manager you specify, providing it is active within the queue sharing group. If you specify a queue manager name other than the queue manager on which it was entered, you must be using a queue sharing group environment, and the command server must be enabled.

    The maximum length is MQ_QSG_NAME_LENGTH.

    RefreshRepository (MQCFIN)
    Whether repository information is refreshed (parameter identifier: MQIACF_REFRESH_REPOSITORY).

    This parameter indicates whether the information about repository queue managers is refreshed.

    The value can be:

      MQCFO_REFRESH_REPOSITORY_YES
      Refresh repository information.

      This value cannot be specified if the queue manager is itself a repository queue manager.

      MQCFO_REFRESH_REPOSITORY_YES specifies that in addition to MQCFO_REFRESH_REPOSITORY_NO behavior, objects representing full repository cluster queue managers are also refreshed. Do not use this option 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 cluster-sender channel definitions. After the refresh with MQCFO_REFRESH_REPOSITORY_YES has been issued the queue manager can be altered so that it is once again a full repository.

      MQCFO_REFRESH_REPOSITORY
      Do not refresh repository information. MQCFO_REFRESH_REPOSITORY is the default.

    If you select MQCFO_REFRESH_REPOSITORY_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 when the Refresh is processed, and they are used exclusively by the cluster or clusters being refreshed and MQCFO_REFRESH_REPOSITORY_YES is used, the channels are stopped, by using the Stop Channel command with a value of MQMODE_FORCE in the Mode parameter if necessary.

    This scenario ensures that the Refresh can remove the channel state and that the channel will run with the refreshed version after the Refresh has completed. If the state of a channel cannot be deleted, for example because it is in doubt, or because it is also running as part of another cluster, it is state is not new after the refresh and it does not automatically restart if it was stopped.