CLWLRANK (Cluster Workload Rank)

CLWLPRTY tells IBM MQ which cluster queue instance should win when sites compete at different importance levels. What happens when QM_APP1 and QM_APP2 are both production-active, both set to CLWLPRTY(7), and both healthy? Priority no longer distinguishes them—CLWLRANK (cluster workload rank) supplies the next ordering key. Lower rank values are more preferred when priorities match, so rank 0 beats rank 1 at the same priority band. Operators who only tune priority see unexplained fifty-fifty splits because both sites share priority 7 with default rank 0 and equal weights. This tutorial explains rank on queues and channels, pairing rank with priority for subtle preference, active/active tie-break design, DISPLAY and ALTER MQSC, algorithm position after CLWLUSEQ and CLWLPRTY, misconceptions about inverting rank numbers, failover scenarios when ranks should change, and lab validation steps before go-live.

Rank in the Workload Algorithm

Simplified decision flow: filter instances by availability and CLWLUSEQ; compare CLWLPRTY and keep the highest priority candidates; among those with equal priority, prefer lower CLWLRANK; if still tied, CLWLWGHT may distribute proportionally. Rank therefore matters most in active/active pairs deliberately given the same priority. It also matters when architects want two tiers inside one priority band—both sites priority 7, but London rank 0 and Paris rank 1 so London wins ties without demoting Paris to priority 5.

Defining Rank on Cluster Queues

1
2
3
4
5
6
7
* Active/active same priority - rank breaks ties
DEFINE QLOCAL('ORDERS.IN') CLUSTER('SALES') REPLACE +
  CLWLPRTY(7) CLWLRANK(0) CLWLWGHT(50) CLWLUSEQ(ANY)
* On QM_APP2:
DEFINE QLOCAL('ORDERS.IN') CLUSTER('SALES') REPLACE +
  CLWLPRTY(7) CLWLRANK(1) CLWLWGHT(50) CLWLUSEQ(ANY)
DISPLAY QLOCAL('ORDERS.IN') CLWLPRTY CLWLRANK CLWLWGHT

Here APP1 wins ties against APP2 because rank 0 is more preferred than rank 1 at equal priority. Weights at 50 suggest balanced share when the algorithm reaches weighting—observe actual distribution in lab; rank may steer many puts before weights apply depending on candidate set. Document intended steady-state percentages and adjust rank or weight together rather than one attribute in isolation.

Rank on Cluster Channels

When multiple cluster paths exist between the same pair of queue managers—different listeners, VPNs, or data centers—channel CLWLPRTY and CLWLRANK influence which path workload prefers. Queue tuning does not help if all paths use a congested channel with poor rank. DISPLAY CHANNEL(name) CLWLPRTY CLWLRANK on CLUSSDR and CLUSRCVR pairs when diagnosing uneven link utilization. Align channel rank with queue rank strategy so applications and infrastructure tell a consistent story.

Failover and Rank Swaps

Some runbooks lower priority on failure; others keep priority and swap rank so DR moves from rank 1 to rank 0 while primary is inhibited. Rank swap alone does not help if the primary instance still appears available to the repository—combine with queue inhibit, queue manager outage simulation, or removal of primary from candidate set per your architecture. After failover drill, restore rank and priority to documented normal values to avoid silent preference for DR after recovery.

Explainer: Sub-Priority Seat Numbers

CLWLPRTY is the ticket class—first class versus coach. CLWLRANK is the seat number within the same class—row 1 beats row 5 when both passengers hold first class tickets.

Common Mistakes

• Assuming higher rank number is better—it is usually the opposite.
• Setting rank without equal priority—priority difference may hide rank entirely.
• Equal priority, equal rank, equal weight—then wondering why distribution looks random.
• Changing rank on one member only—cluster queue definitions should be symmetric unless intentionally asymmetric.
• Skipping lab measurement—always count messages per instance under load.

Monitoring

During load test, sample CURDEPTH on each instance every minute. If rank 0 instance depth grows faster while both are eligible, rank behaves as expected. If depths stay equal despite rank skew, check CLWLUSEQ LOCAL on putting members, bind options, or whether only one instance appears in repository cache. DISPLAY CLUSQ on putting queue manager shows known instances and attributes cached from repository.

Explain Like I'm Five: CLWLRANK

Two friends both have gold stars (same priority). CLWLRANK is the smaller number written on your gold star so the teacher picks you first when only gold-star kids can go to recess.

Practice Exercises

Exercise 1

Two members both CLWLPRTY(8)—design ranks so site A wins ties but site B still receives traffic when weights apply.

Exercise 2

Explain why setting rank 9 on primary and rank 0 on backup at equal priority may invert your intent.

Exercise 3

List DISPLAY commands to verify rank on all instances of ORDERS.IN.

Frequently Asked Questions

Test Your Knowledge