CLUSTER (Queue Attribute)

The CLUSTER attribute on a local queue definition is how you advertise that queue to an IBM MQ cluster—a group of queue managers that share object knowledge through a full or partial repository. Setting CLUSTER('INVENTORY') does not by itself move messages; it tells the cluster “this queue name is available here.” Remote members can then route application puts and cluster channels can forward traffic. Beginners confuse this attribute with the cluster-objects tutorial (channels, repositories, namelists); this page focuses on the CLUSTER keyword on DEFINE QLOCAL and ALTER QLOCAL, how naming works, prerequisites on the queue manager, and how CLUSTER combines with DEFBIND, CLWLUSEQ, and cluster workload priorities.

From Standalone Queue to Cluster Queue

A normal local queue serves only clients connected to that queue manager. Adding CLUSTER('PAYMENTS') publishes the queue to every member of the PAYMENTS cluster (subject to repository sync). Applications on other members can MQPUT to ORDERS.IN without a static remote queue definition for each host—the cluster resolves instances. High availability comes from multiple members hosting the same name; workload spreads per DEFBIND and CLWLUSEQ. Operations must still define CLUSRCVR and CLUSSDR channels, cluster sender to repository, and verify the queue manager CLUSQMGR name is unique in the cluster.

CLUSTER Name and Queue Name

The CLUSTER attribute value is the cluster name from your cluster design document—not necessarily the same string as the queue name. Queue name ORDERS.IN with CLUSTER('FINANCE') publishes ORDERS.IN into FINANCE. Cluster workload alias attributes (CLCHNAME, CLWQNAME on some configurations) can alter advertised names; beginners should start with queue name equals put name. DISPLAY QCSTATUS and cluster administrative commands show where the repository thinks instances live. Typos in CLUSTER('FINANCE') versus CLUSQMGR cluster membership strand queues in the wrong group.

DEFINE and ALTER MQSC

1
2
3
4
5
6
DEFINE QLOCAL('ORDERS.IN') REPLACE CLUSTER('PAYMENTS') +
  DEFBIND(NOTFIXED) CLWLUSEQ(ANY) MAXDEPTH(200000)
* Remove from cluster but keep local queue:
ALTER QLOCAL('ORDERS.IN') CLUSTER(' ')
* Or cluster empty per platform docs — verify DISPLAY
DISPLAY QLOCAL('ORDERS.IN') CLUSTER DEFBIND CLWLUSEQ

Multiple Instances of the Same Name

ORDERS.IN on QM_LON and ORDERS.IN on QM_NYC both with CLUSTER('PAYMENTS') are two instances of one logical cluster queue. Producers on any member put to ORDERS.IN; the workload algorithm picks LON or NYC (or more). Consumers may run on both nodes for scale. Repository conflicts occur if two queues with incompatible attributes advertise the same name—govern attribute templates. When one instance is down, traffic routes to survivors if channels and weights allow.

CLUSTER vs Remote Queue Definitions

Before clusters, every spoke needed QREMOTE definitions pointing at hub queue managers. Cluster queues reduce static routing tables: the repository is the directory. You may still use remote queues for non-cluster partners or explicit paths. Hybrid estates mix CLUSTER queues inside the data center and XMITQ/remote queues to external vendors. Do not duplicate the same business flow with both patterns without documentation—double delivery and confused monitoring result.

Attributes That Should Match on All Instances

• DEFBIND — same binding semantics everywhere.
• CLWLUSEQ — consistent local vs any preference.
• MAXDEPTH, MAXMSGL, DEFPSIST — avoid surprise reject on one node.
• GET, PUT, SHARE — security and access parity.

Monitoring Cluster Queues

Monitor CURDEPTH per instance, not only the logical name. Cluster channel (CLUSSDR, CLUSRCVR) status explains routing failures. Repository issues show as incomplete object lists on new members. After adding CLUSTER to an existing busy queue, expect repository propagation delay before remote puts succeed—plan change windows. Use IBM MQ observability tools and DISPLAY CLUSQMGR for channel health.

Explain Like I'm Five: CLUSTER on a Queue

Your shop puts its name on a shared mall directory (the cluster). Shoppers at any entrance can ask for “Toy Store” and the directory lists which wing has it. CLUSTER on the queue is signing up for that directory. Without signing up, only people already in your wing find the store.

Practice Exercises

Exercise 1

List five objects or attributes you would verify on a queue manager before adding CLUSTER to a production queue.

Exercise 2

Two instances of ORDERS.IN exist; puts from a third member fail. Name four cluster components to check.

Exercise 3

When is a remote queue still preferable to a cluster queue?

Frequently Asked Questions

Test Your Knowledge