CLWLPRTY (Cluster Workload Priority)

After you define the same cluster queue name on QM_LONDON and QM_DR, messages do not automatically prefer London just because it is primary in your runbook—the queue manager workload algorithm needs a numeric hint. CLWLPRTY (cluster workload priority) is that hint on each queue instance and can also appear on cluster channels to influence path selection in advanced designs. Higher values mean this instance or path should win when other candidates are equally eligible after CLWLUSEQ filtering and availability checks. Beginners who copy a queue definition to a disaster recovery site without lowering CLWLPRTY on DR sometimes see fifty-fifty traffic split during normal operations, or DR never receiving failover traffic because London still wins every tie. This tutorial explains the 0–9 scale, primary and backup patterns, interaction with CLWLRANK and CLWLWGHT, setting priority on channels versus queues, DISPLAY and ALTER MQSC, monitoring with message depth counters, common misconceptions, and lab exercises to validate behavior before production cutover.

Where CLWLPRTY Lives

The attribute appears on local queues that have a CLUSTER name—those are the instances competing for puts. It can also be set on cluster sender and cluster receiver channels when architects want the network path choice to reflect site preference. Most teams tune queue CLWLPRTY first because application puts target queue names, not channel names. DISPLAY QLOCAL('PAYMENT.IN') CLUSTER CLWLPRTY CLWLRANK CLWLWGHT CLWLUSEQ shows the full workload picture on one member; repeat on every member that hosts an instance.

Primary and Backup Pattern

1
2
3
4
5
6
7
8
* QM_LONDON - primary
DEFINE QLOCAL('SETTLEMENT.IN') CLUSTER('FIN') REPLACE +
  CLWLPRTY(9) CLWLRANK(0) CLWLUSEQ(LOCAL)
* QM_DR - backup
DEFINE QLOCAL('SETTLEMENT.IN') CLUSTER('FIN') REPLACE +
  CLWLPRTY(2) CLWLRANK(0) CLWLUSEQ(ANY)
* Under normal operations London keeps local traffic;
* if London instance unavailable, DR can receive cluster puts

CLWLUSEQ(LOCAL) on the primary encourages applications on London to use the London instance when it exists—pair with higher CLWLPRTY so remote competition is unlikely even when USEQ allows any on the backup. Backup CLWLUSEQ(ANY) lets the DR instance participate when the algorithm selects it. Failover drills should include inhibiting the primary queue (INHIBIT PUT) or stopping the queue manager to prove DR depth increases—paper architecture fails when channels are down or repository cache lacks the DR instance.

Active/Active and Priority

Two healthy data centers both serving traffic might use equal CLWLPRTY(5) and different CLWLWGHT values instead of priority skew—priority then does not favor one site. Alternatively, slight priority differences (7 versus 5) bias toward a larger data center while still allowing the smaller site to receive work. Document the intended steady state and measure CURDEPTH on each instance during load tests. Priority alone does not guarantee exact percentage split; weights handle proportionality better when priorities match.

Algorithm Order (Simplified)

1. Build candidate list from repository—hosts of cluster queue name with running paths.
2. Apply CLWLUSEQ and availability—remove or deprioritize per rules.
3. Compare CLWLPRTY—higher preferred among remaining candidates.
4. Compare CLWLRANK on ties—see CLWLRANK tutorial.
5. Apply CLWLWGHT for proportional choice when configured—see CLWLWGHT tutorial.
6. Route message over cluster channel to chosen instance.

Application MQOPEN bind options and DEFBIND on the queue can override or constrain this flow—developers must align with operations. A program that binds to a specific instance bypasses priority intended for cluster-wide puts.

Altering Priority in Production

1
2
3
4
ALTER QLOCAL('SETTLEMENT.IN') CLWLPRTY(1)
* Planned role reversal during maintenance:
ALTER QLOCAL('SETTLEMENT.IN') CLWLPRTY(9)
DISPLAY QLOCAL('SETTLEMENT.IN') CLWLPRTY CLUSTER

ALTER takes effect for new routing decisions; messages already bound to an instance follow existing handles. Schedule priority swaps during low traffic and communicate to application teams. Some estates automate priority swap with operations runbooks during datacenter maintenance windows.

Explainer: VIP Line at the Bank

CLWLPRTY is the VIP level written on each teller window sign. When two windows can both serve you, the higher VIP number wins. If both signs show the same VIP level, the bank uses rank and weight rules to pick—those are CLWLRANK and CLWLWGHT.

Mistakes Beginners Make

• Setting DR to 9 and primary to 9—expect unpredictable split.
• Forgetting to define the queue on DR with the same name and CLUSTER—priority irrelevant.
• Assuming priority overrides broken cluster channels—it does not.
• Tuning priority while CLWLUSEQ(LOCAL) on every member—traffic never leaves each site.
• Ignoring channel CLWLPRTY when paths have different costs—queue-only tuning may not fix path selection.

Explain Like I'm Five: CLWLPRTY

When three toy stores share one name, CLWLPRTY is the number that tells the post office to try the store with the biggest number first when delivering a package.

Practice Exercises

Exercise 1

Design CLWLPRTY values for primary 9, secondary 6, DR 2 on three members.

Exercise 2

Why does CLWLPRTY not matter when only one cluster instance exists in the repository?

Exercise 3

After raising DR from 2 to 9, what else must you verify before expecting all traffic on DR?

Frequently Asked Questions

Test Your Knowledge