DISTL

DISTL controls distribution list support on a local queue. In older IBM MQ applications, one MQPUT could target a list of queue names—fanning the same message to several destinations in a single call—useful before pub/sub was ubiquitous. Today most new designs use topics, multiple orchestrated puts, or enterprise service buses, but mainframe estates still run COBOL and C programs that rely on namelists and distribution lists. Administrators see DISTL in DISPLAY QLOCAL output and wonder whether YES is required. This page explains DISTL(YES) versus DISTL(NO), how distribution lists relate to namelists, comparison with publish/subscribe, security and operations implications, and when to leave DISTL(NO) on modern application queues.

What Is a Distribution List Put?

In a standard put, the destination is one queue name on one queue manager (or resolved through alias/remote). In a distribution list put, the destination is a list structure referencing multiple queues—often built from a namelist object that stores the queue names. The queue manager creates a copy of the message for each member of the list (subject to API and platform rules). DISTL on participating queues must allow the operation; otherwise puts fail with reason codes indicating distribution list not supported.

DISTL and Namelists

Namelist objects hold lists of names—queue names, cluster names, or other object types depending on definition. Distribution list processing may reference namelists to avoid hard-coding ten queue names in every program. When migrating, export DISPLAY NL and DISPLAY QLOCAL DISTL together. If you retire distribution lists, confirm no program still opens a namelist destination before mass ALTER DISTL(NO).

DISTL vs Publish/Subscribe

Topics decouple publishers from subscriber count: new subscriptions receive messages without changing the publisher. Distribution lists are static: change the list, change namelist or program. Topics support durable subscriptions, retained messages (where configured), and hierarchical topic strings. For broadcast to many unknown consumers, pub/sub wins. For fixed duplicate delivery to three known back-office queues, distribution lists were historically convenient—many teams now use three puts in an integration layer or one topic with three subscriptions for clearer monitoring.

When to Set DISTL(YES)

• Existing application issues distribution list puts documented in interface specs.
• Third-party tool requires distribution list support on specific queues.
• Migration phase where both old list puts and new topic consumers run in parallel.

Enable YES only on queues that participate—do not blanket YES all queues “just in case.” Unnecessary YES slightly widens the attack surface of misconfigured puts fanning data to unintended queues if a program bug supplies wrong list content.

When to Keep DISTL(NO)

New microservice queues, reply queues, XMITQ, DLQ, and initiation queues should remain DISTL(NO) unless a specific requirement exists. Model queues (QMODEL) used for dynamic reply queues typically inherit NO so temporary queues cannot be abused as distribution fan-out points. Review inherited attributes from model queues when dynamic queues behave unexpectedly.

1
2
3
4
5
6
DISPLAY QLOCAL('BROADCAST.IN') DISTL
ALTER QLOCAL('BROADCAST.IN') DISTL(YES)
* Legacy namelist (example):
DEFINE NAMELIST('FANOUT.LIST') REPLACE +
  NAMTYPE(QUEUE) NAMES('QUEUE.A','QUEUE.B','QUEUE.C')
* Modern alternative: DEFINE TOPIC + subscriptions

Operational and Security Notes

One distribution list put can multiply storage and audit events by the number of targets. Capacity planning must count worst-case copies. Authority checks apply per target queue; a partial failure may leave some copies delivered and others not—applications need report options and error handling documented in IBM MQ API guides. Logging should record distribution list use because it is less obvious than ten separate puts in trace tools.

Migration Path Off Distribution Lists

1. Inventory programs and namelists using list puts (DISTL YES queues).
2. Design equivalent topic or orchestration flow.
3. Parallel run with compare of destination depths.
4. ALTER source queues DISTL(NO) after cutover.
5. Retire unused namelists from repository.

Explain Like I'm Five: DISTL

Usually you mail one letter to one friend. A distribution list is mailing the same letter to several friends at once from one envelope stack. DISTL(YES) means this mailbox can be on that multi-friend list. DISTL(NO) means “only one friend at a time here.”

Practice Exercises

Exercise 1

Your team wants broadcast to fifty subscribers that change weekly. Recommend DISTL/topics/orchestration and why.

Exercise 2

DISPLAY shows DISTL(YES) but no legacy apps. What ALTER would you suggest?

Exercise 3

List two risks of accidental distribution list puts on a payments queue.

Frequently Asked Questions

Test Your Knowledge