REFRESH (MQSC)

REFRESH is the IBM MQ verb that reloads cached or external configuration without tearing down the queue manager. The two forms beginners hear most often are REFRESH CLUSTER and REFRESH SECURITY. Cluster administrators use REFRESH CLUSTER when a partial repository queue manager does not see cluster queues or queue managers that full repositories already publish—symptoms look like MQRC 2085 unknown object on a cluster put even though DISPLAY QLOCAL on the owning member shows the queue. Security administrators use REFRESH SECURITY after changing CONNAUTH, LDAP, or certificate-related AUTHINFO so new connections pick up policy without endmqm. REFRESH is powerful because it avoids a full restart; it is dangerous when misapplied because it can mask underlying repository or channel failures if operators refresh repeatedly instead of fixing CLUSSDR paths. This tutorial explains cluster refresh mechanics, security refresh types, prerequisites, DISPLAY evidence to collect first, interaction with REPOS and REPOSNL roles, and how REFRESH differs from RESET CLUSTER recovery commands on your MQ version.

REFRESH CLUSTER Syntax and Behavior

On a queue manager that participates in cluster SALES with ALTER QMGR REPOSNL('SALES'), the command REFRESH CLUSTER('SALES') requests an updated copy of cluster repository data from the full repository members. The queue manager already holds a local cache of cluster routes, cluster queue names, and CLUSQMGR attributes; refresh replaces or reconciles that cache against authoritative full repos. Duration depends on cluster size—hundreds of cluster objects may take noticeable seconds. During refresh, some sites see brief routing hesitation; plan maintenance windows for first-time refresh on busy partial members.

1
2
3
4
5
6
7
DISPLAY QMGR REPOS REPOSNL
DISPLAY CLUSQMGR(*) WHERE(CLUSTER EQ SALES)
REFRESH CLUSTER('SALES')
DISPLAY CLUSQMGR('QM_APP') CLUSTER QMTYPE
* REPOS — this QM is full repository for named cluster (if set)
* REPOSNL — partial member subscribes to cluster updates
* REFRESH CLUSTER — cluster-name must match REPOSNL subscription

Full Repository Versus Partial Member

Full repository queue managers (ALTER QMGR REPOS('SALES')) publish cluster updates; they rarely need REFRESH CLUSTER for their own cache in the same way partial members do. If a full repository itself shows inconsistent DISPLAY output between the two full repo partners, the problem is repository synchronization or repository queue health—not solved by refreshing a partial member alone. DISPLAY QMGR REPOS and REPOSNL on every cluster member should be documented in your CMDB. Running REFRESH CLUSTER on a queue manager that is not in the cluster name fails or has no effect depending on syntax—verify spelling of cluster name exactly as in DEFINE CLUSTER and REPOSNL.

REFRESH SECURITY Types

Authentication configuration can be cached. After ALTER AUTHINFO for LDAP or changing CONNAUTH rules, new bindings may still use old behavior until refresh or restart. REFRESH SECURITY TYPE(CONNAUTH) reloads connection authentication configuration on supported releases. LDAP TYPE(LDAP) refresh may apply when directory connection endpoints change. Always test with a non-production queue manager first: a bad AUTHINFO combined with refresh can lock out administrators if CONNAUTH requires valid LDAP and the server is wrong. Keep a break-glass local OS user allowed by CONNAUTH in emergencies.

1
2
3
4
5
6
DISPLAY QMGR CONNAUTH
DISPLAY AUTHINFO(*) AUTHTYPE
ALTER AUTHINFO('LDAP1') CONNAME('ldap.corp.example.com')
REFRESH SECURITY TYPE(CONNAUTH)
* Test new client connection after refresh
* Existing connections may need reconnect to pick up policy

When REFRESH Is Not Enough

• Repository manager publish failures in AMQERR—fix repository queues and channels first.
• Both full repositories disagree after split-brain—follow IBM cluster recovery guide, not only refresh.
• CHLAUTH or TLS failure on cluster channels—REFRESH does not open firewall ports.
• Wrong CLUSTER attribute on QLOCAL—ALTER object, wait sync, then refresh only if needed.

Repository manager problems tutorial covers DISPLAY QSTATUS on SYSTEM.CLUSTER.REPOSITORY.QUEUE and error text referencing publish failures. Escalate to IBM support when REFRESH CLUSTER hangs or returns errors referencing repository manager after infrastructure is healthy.

Operational Checklist Before REFRESH CLUSTER

1. DISPLAY QMGR REPOS REPOSNL—confirm this QM belongs to the cluster.
2. DISPLAY CHSTATUS on cluster channels to full repositories—RUNNING or fix first.
3. DISPLAY CLUSQMGR on full repo—does the missing object exist there?
4. Notify stakeholders if peak traffic—brief routing cache update possible.
5. Run REFRESH CLUSTER('name') once; avoid loops.
6. Re-test cluster put; capture DISPLAY CLUSQMGR and application MQRC.

REFRESH Versus RESET in Cluster Context

REFRESH reloads catalog information from repositories. RESET CLUSTER (where available on your version) is a heavier recovery step used in documented disaster procedures—not interchangeable with casual REFRESH. Never delete messages from SYSTEM.CLUSTER.REPOSITORY.QUEUE without IBM guidance. Beginners confuse REFRESH with RESET CHANNEL; they operate on different subsystems entirely.

Explainer: Updating Your Phone Contact List

Your phone already has contacts, but your friend changed their number. REFRESH CLUSTER is syncing your contact list from the shared company directory again so calls reach the right desk—not throwing away your phone.

Explain Like I'm Five: REFRESH

The teacher wrote new names on the class list on the board at the front. REFRESH is asking your desk to copy the board again so you know who sits where today.

Practice Exercises

Exercise 1

On a lab cluster, DEFINE a cluster queue on one member and time how long until another member sees it without REFRESH. Then simulate stale cache and use REFRESH CLUSTER.

Exercise 2

Document DISPLAY commands that prove full repository health before any REFRESH in production.

Exercise 3

After ALTER AUTHINFO in lab, compare client login before and after REFRESH SECURITY TYPE(CONNAUTH).

Frequently Asked Questions

Test Your Knowledge