Shared Queues

Shared queues are the workhorses of IBM MQ queue sharing groups on z/OS: one queue name, messages stored in the coupling facility, any healthy QSG member can put or get without shipping bytes through a channel to a sibling queue manager. When architects say payments run on the mainframe hub, they often mean thousands of CICS and batch tasks draining shared queues such as PAYMENTS.IN while Java clients in another LPAR publish to the same name. Beginners coming from Linux queue managers must unlearn the idea that every queue lives in a local directory on disk—shared queues trade local page set simplicity for sysplex-wide visibility and availability. This tutorial defines QSGDISP(SHARED), relates CF structure assignment, contrasts private local queues, explains SHARE(YES) for competing consumers, walks through DEFINE examples, covers depth and performance limits, and lists operational mistakes that cause MQOPEN failures or structure full conditions.

Definition: QSGDISP and CFSTRUCT

When you define a local queue on z/OS in a QSG, QSGDISP tells the queue manager how the definition replicates and where messages live. SHARED means the message data resides in the coupling facility structure named on CFSTRUCT. PRIVATE means messages stay on that member page sets only. COPIED and GROUPED dispositions support administrative patterns for making definitions appear on other members—read IBM documentation before using them in production. A shared queue without a valid CF structure name fails at define time or first put. Structure capacity is finite; MAXDEPTH on the queue and structure size interact to cap backlog.

1
2
3
4
5
6
DEFINE QLOCAL('PAYMENTS.IN') QSGDISP(SHARED) +
  CFSTRUCT(MQSG001) MAXDEPTH(500000) +
  DEFPSIST(YES) SHARE(YES) +
  DESCR('Shared work queue for payments hub')
 
DISPLAY QLOCAL('PAYMENTS.IN') QSGDISP CFSTRUCT CURDEPTH

CFSTRUCT(MQSG001) binds the queue to structure MQSG001. Operations must already have defined and allocated that structure in the coupling facility with adequate size. MAXDEPTH limits messages on the queue object; exceeding it causes MQRC_Q_FULL even if a sliver of CF space remains elsewhere—tune both queue and structure.

Private Local Queues in the Same QSG

Private queues (QSGDISP(PRIVATE) or default private behavior per context) store messages on the member where the put occurred (subject to rules). Another member opening the same name may see a different object or nothing useful. Use private queues for member-specific scratch, migration buffers, or temporary pipelines operators understand. Accidentally defining a critical business queue as private strands half your consumers on the wrong LPAR wondering why depth is zero.

SHARE Attribute on Shared Queues

SHARE(YES) allows multiple applications to hold get handles concurrently—required for worker pools and many CICS tasks. SHARE(NO) restricts concurrent open patterns and causes MQOPEN reason 2042 when a second getter connects. Shared queues with many consumers almost always use SHARE(YES). This attribute is independent of QSGDISP but both words contain share—refer to the queue sharing tutorial for the distributed-platform angle.

Put, Get, and Syncpoint Behavior

MQI put and get on shared queues follow the same syncpoint rules as private queues: MQCMIT makes messages visible to other members after commit; MQBACK rolls back uncommitted work. Cross-member visibility means one member commit can release a message another member gets immediately—design idempotent consumers because failover moves processing between members. Persistent messages log to the member that accepted the put according to IBM rules for shared queues—recovery documentation is essential for operators.

Performance and Sizing

• Message size average and peak—large XML payloads consume CF structure space faster than small triggers.
• Depth spikes during batch—size structures for peak, not average Tuesday afternoon.
• Getter count—many concurrent getters increase CF contention; tune application pools.
• Structure rebuild—changing structure size may require maintenance windows; plan early.

Security and RACF

RACF profiles govern who may put and get shared queues the same way as private queues, with profiles tied to queue names on the queue manager. Shared does not mean public—2035 errors appear when the MCAUSER or application ID lacks access. Change control must update profiles once per queue name, not per member, for shared objects—simpler naming, higher blast radius if mis-granted.

Common Mistakes

1. Defining production queue as private while apps connect to group expecting shared depth.
2. Structure full—no monitoring on CF utilization until puts fail sysplex-wide.
3. SHARE(NO) with multiple CICS tasks—open failures under load.
4. Assuming same queue name on distributed Linux QM is the same object—it is not without channels.

Explainer: Community Bulletin Board

A shared queue is the bulletin board in the town square everyone can read and post on. A private queue is a sticky note on one person desk inside a locked office.

Explain Like I'm Five: Shared Queues

A shared queue is a mailbox in the cloud that every IBM MQ helper in the group can use. A private queue is a mailbox in only one helper room.

Practice Exercises

Exercise 1

Write DEFINE QLOCAL for a shared queue with CFSTRUCT, MAXDEPTH, DEFPSIST, and SHARE explained line by line.

Exercise 2

Given a depth alert on a shared queue, list three places to investigate besides MAXDEPTH.

Exercise 3

Explain to a distributed MQ developer why their Linux queue is not the same as a z/OS shared queue of the same name.

Frequently Asked Questions

Test Your Knowledge