Cluster Queues

A cluster queue is how IBM MQ scales one logical queue name across many queue managers without hard-wiring remote definitions for every pair. You define a local queue, set CLUSTER('FINANCE') so the cluster repository learns it exists, and applications on any member can put to PAYMENTS.IN—the queue manager decides whether the message stays local or travels over a cluster sender channel to another member's instance. For beginners coming from a single queue manager, cluster queues feel like magic until you understand repositories, workload priorities, and DEFBIND. This page explains the cluster queue pattern as a usage topic (not only the CLUSTER keyword), how puts are resolved, how multiple instances compete for work, how cluster queues compare to alias and remote queues, and what to monitor when routing goes wrong.

From Single Queue Manager to Cluster Queue

On one queue manager, PAYMENTS.IN is a simple QLOCAL. When you join a cluster and add CLUSTER('FINANCE') to that definition, the queue becomes a cluster queue: its name and hosting queue manager appear in the cluster cache. Another member in FINANCE can receive a put to PAYMENTS.IN even if that queue is not defined locally—the message routes via cluster channels. Consumers can run on the same member as the queue definition or on a remote member that forwards to the instance selected by the workload algorithm.

Publishing a Cluster Queue

Prerequisites live on the queue manager: CLUSQMGR for the cluster name, cluster receiver and sender channels, connection to full or partial repository. Then DEFINE QLOCAL with CLUSTER(name). CLWLPRTY and CLWLRANK on the queue influence workload choice when multiple instances exist. CLWLUSEQ(YES) on a queue tells the workload algorithm to prefer the local instance when this member hosts one—useful when you want to keep traffic on-box unless the local queue is unavailable.

1
2
3
4
5
DEFINE QLOCAL('PAYMENTS.IN') CLUSTER('FINANCE') REPLACE +
  MAXDEPTH(100000) GET(YES) PUT(YES) DEFBIND(NOTFIXED) +
  CLWLUSEQ(LOCAL) CLWLPRTY(5)
DISPLAY QLOCAL('PAYMENTS.IN') CLUSTER CLWLPRTY CLWLUSEQ DEFBIND
DISPLAY CLUSQMGR('FINANCE')

Explainer: One Name, Many Mailboxes

Think of cluster queues as several mailboxes all labeled PAYMENTS.IN in different buildings, and a central directory that knows which buildings have that label. When you mail a letter (MQPUT), the post office (queue manager) picks a building based on rules: which buildings are open (channels running), which have capacity, whether you asked for a specific building (DEFBIND FIXED), and whether the building you are standing in has its own mailbox (CLWLUSEQ). The sender does not need to know the street address of every building—only the logical name on the envelope.

Multiple Instances and Competing Consumers

Operations often define PAYMENTS.IN on QM_A, QM_B, and QM_C with the same cluster name so three consumer farms can share load. Each instance has its own CURDEPTH; there is no single global depth across the cluster unless you monitor all instances. Producers putting from QM_A might fill QM_B's instance depending on algorithm weights—design consumers on each instance or use CLWLUSEQ and binding to steer traffic. Competing consumers on one instance still need SHARE(YES) and shared get open options like any work queue.

DEFBIND and Application Transparency

• NOTFIXED — queue manager can choose different instances over time; good for general load spread.
• FIXED — binds to one instance for the life of the queue handle context; useful when ordering or affinity matters.
• GROUP — cluster group binding semantics per IBM documentation for your release.

Application code usually stays a simple MQPUT to the queue name; binding is in the object definition and MQI options, not in COBOL or Java string hacks for the common case.

Cluster Queues vs Shared Queues (z/OS)

z/OS shared queues (QSGDISP SHARED) put message data in the coupling facility inside a queue sharing group. Cluster queues work across queue managers that may not share CF—including Linux and Windows members. Pick shared queues for Sysplex-wide one backlog on z/OS; pick cluster queues for heterogeneous estates and geographic distribution.

Troubleshooting Cluster Queue Puts

1. DISPLAY CLUSQMGR and cluster channels—repository must be reachable.
2. DISPLAY QLOCAL CLUSTER—queue must be published to the expected cluster name.
3. Check reason codes on put: unknown object often means name not in repository or wrong cluster.
4. Verify target instance GET(YES) and authority for the putting application's MCAUSER or local user.
5. Inspect transmission queues and cluster sender channels if messages stall between members.

Tutorial: Observe Cluster Resolution

1
2
3
4
5
* On member A: put test messages to cluster queue
* DISPLAY QLOCAL('PAYMENTS.IN') CURDEPTH
* On member B: same DISPLAY — depth may differ (separate instance)
* DISPLAY CLUSQMGR('FINANCE') CLWLMRUC
* Use amqsput from a third member; trace which instance depth increases

Explain Like I'm Five: Cluster Queues

Cluster queues are like calling a pizza chain by one phone number and the operator picks which shop near you actually makes the pizza—you do not memorize every shop's address.

Practice Exercises

Exercise 1

Draw a diagram with two queue managers, one cluster queue name on both, and label where puts land when CLWLUSEQ is LOCAL on each.

Exercise 2

When would you use QREMOTE instead of a cluster queue for PAYMENTS.IN?

Exercise 3

List four MQSC commands to diagnose a put failing with unknown queue in a cluster.

Frequently Asked Questions

Test Your Knowledge