Cluster Namelists

Most cluster tutorials start with a single cluster name—ALTER QMGR CLUSTER('SALES') and DEFINE QLOCAL CLUSTER('SALES')—and that is enough for a lab with one logical cluster. Production queue managers often participate in more than one cluster, or host partial repository data for several cluster names that share infrastructure but must not merge routing catalogs. Repeating dozens of ALTER QMGR keywords is error-prone; IBM MQ solves this with cluster namelists: ordinary NAMELIST objects whose NAMES attribute holds cluster name strings, referenced by CLUSNL on the queue manager, REPOSNL for partial repository scope, and optionally CLUSNL on cluster sender or cluster receiver channels instead of a single CLUSTER attribute. This tutorial explains how cluster namelists differ from general-purpose namelists, how CLUSTER and CLUSNL interact on channels, how to define and maintain NAMES lists safely, multi-cluster join and leave procedures, troubleshooting when a queue manager appears in the wrong cluster catalog, and beginner MQSC you can run beside the namelists and what-is-an-mq-cluster tutorials.

Why Cluster Names Need a List Object

A cluster name is a label that ties queue managers, queues, channels, and topics into one distributed namespace. When PAYMENTS and LOGISTICS are separate business domains but share the same physical queue managers for cost reasons, one member might need CLUSNL listing both PAYMENTS and LOGISTICS while objects on that box use CLUSTER('PAYMENTS') or CLUSTER('LOGISTICS') per application. The queue manager-level CLUSNL namelist answers which clusters this member belongs to for cluster subsystem processing; individual objects still declare which cluster they publish into the repository. Without a namelist, you would alter queue manager attributes repeatedly; with DEFINE NAMELIST and ALTER QMGR CLUSNL(nlist), you maintain one object whose NAMES you extend when onboarding a new cluster to an existing host.

Defining a Cluster Namelist

1
2
3
4
5
6
7
8
9
10
DEFINE NAMELIST('PROD.CLUSTERS') REPLACE +
  DESCR('Queue manager cluster membership') +
  NAMES(PAYMENTS,LOGISTICS,REPORTING)
ALTER QMGR CLUSNL('PROD.CLUSTERS')
* Partial repository for two of the three:
DEFINE NAMELIST('PROD.REPOS.CLUSTERS') REPLACE +
  NAMES(PAYMENTS,LOGISTICS)
ALTER QMGR REPOSNL('PROD.REPOS.CLUSTERS')
DISPLAY NAMELIST('PROD.CLUSTERS') NAMES NAMCOUNT
DISPLAY QMGR CLUSTER CLUSNL REPOSNL

NAMES entries are cluster name strings, not queue names. Spelling must match CLUSTER attributes on queues and topics exactly—MQ cluster names are case-sensitive on many platforms. NAMCOUNT shows how many names the namelist currently holds. After ALTER NAMES, cluster channels may need recycling or queue manager attention depending on what changed; plan changes in a maintenance window and verify DISPLAY CLUSQMGR on full repository members shows the updated membership.

CLUSTER Versus CLUSNL on Channels

Cluster sender and cluster receiver channels carry traffic and repository updates between members. A channel defined with CLUSTER('SALES') participates only in that cluster. A channel with CLUSNL('MY.CHAN.CLUSTERS') where the namelist contains SALES and FINANCE can serve both—useful when one TCP path between two data centers carries multiple cluster protocols. IBM MQ enforces mutual exclusivity: if CLUSTER is set, CLUSNL must be blank and vice versa. Beginners who set both see MQSC errors or unpredictable ALTER behavior. Pick one style per channel and document it in your standards guide.

• CLUSTER(single)—simplest; one cluster per channel definition; matches most diagrams.
• CLUSNL(list)—fewer channel pairs when two clusters share the same network path between two hosts.
• Wrong cluster on channel—repository updates do not flow; symptoms include stale CLUSQ and missing remote instances.

CLUSNL and REPOSNL Together

CLUSNL declares membership: this queue manager participates in these clusters. REPOSNL declares partial repository scope: for which of those clusters does this member cache and forward repository records. A member can be in three clusters via CLUSNL but partial repository for only one via REPOSNL. Full repository hosts use REPOS (where supported) instead of or in addition to partial roles—see the full repositories tutorial. Mixing REPOSNL without understanding repository topology produces members that receive object definitions they never route to, wasting memory, or members that lack cache entries and fail cluster puts with reason codes indicating unknown object or unavailable destination.

Multi-Cluster Operations Checklist

1. Define namelist with all cluster names before ALTER QMGR CLUSNL.
2. Ensure cluster channels exist or auto-create policy allows paths to repository hosts for each cluster.
3. Define cluster queues and topics with correct per-object CLUSTER(name), not CLUSNL on the queue.
4. Verify DISPLAY CLUSQMGR on a full repository for each cluster name after join.
5. Update CHLAUTH and firewall rules if new cluster traffic shares listeners.
6. Document which applications use which cluster name to avoid cross-cluster puts.

Explainer: One Badge Rack, Several Team Names

Think of the namelist as a badge rack at the office door listing every team you belong to—Payments, Logistics, Reporting. Your desk projects (queues and topics) still have a sticker for which team they report to. CLUSNL is the rack on the building; CLUSTER on each queue is the sticker on the folder. Security and mail routing use both: the building must know you are allowed in the building, and each folder must show which team gets it.

Relationship to General Namelists

The same NAMELIST object type serves SSL certificate revocation lists, distribution lists, and cluster name grouping. Only the NAMES content and the referencing attribute change meaning. DISPLAY NAMELIST(*) in a large estate benefits from naming standards such as QM01.CLUSNL.PROD versus QM01.SSL.CRL so operators do not alter the wrong list during an incident. The general namelists tutorial covers NAMCOUNT and NAMES editing; this page applies that knowledge specifically to cluster membership and repository scope.

Troubleshooting Cluster Namelist Issues

Symptom: queue manager not visible in DISPLAY CLUSQMGR for cluster FINANCE though applications use CLUSTER(FINANCE). Check DISPLAY QMGR CLUSNL and DISPLAY NAMELIST names—FINANCE must appear in the CLUSNL namelist NAMES. Symptom: channel will not start with cluster error—verify CLUSTER and CLUSNL are not both set. Symptom: partial repository never updates—REPOSNL namelist may omit the cluster or full repository hosts are down. Symptom: object exists on one member but not others—object CLUSTER attribute may not match any cluster in peer CLUSNL lists. Always compare three displays: QMGR CLUSNL, object CLUSTER, and CLUSQMGR on a full repository.

Security and Change Management

Altering a cluster namelist effectively changes which distributed catalogs this member trusts and advertises. Restrict MQSC authority for DEFINE NAMELIST and ALTER QMGR. Peer queue managers may accept repository updates from a member that suddenly claims membership in a sensitive cluster name—pair technical controls with approval workflow. In regulated environments, separate namelists per environment (DEV.CLUSTERS versus PROD.CLUSTERS) reduce the chance of copying a lab NAMES list into production.

Explain Like I'm Five: Cluster Namelists

A cluster namelist is a list of team names you belong to at school. Your homework folder still has one team name on it so the teacher knows which team gets the paper, but the front desk needs the full list of teams you are allowed to join.

Practice Exercises

Exercise 1

Write MQSC to create a namelist with two cluster names and attach it with ALTER QMGR CLUSNL.

Exercise 2

Explain why a CLUSRCVR cannot have both CLUSTER(SALES) and CLUSNL(MYLIST) set.

Exercise 3

A queue has CLUSTER(PAYMENTS) but the queue manager CLUSNL namelist omits PAYMENTS—what symptom might operators see?

Frequently Asked Questions

Test Your Knowledge