Namelists

Namelists are one of the quieter object types in IBM MQ—and one of the most useful when you need the same set of names in several places. Instead of typing twelve queue names on a queue manager attribute or hard-coding them in an application, you define a single NAMELIST object whose NAMES attribute holds the list. Other objects, QMGR settings, and programs refer to the namelist by name. When membership changes, you alter one object. This tutorial explains what namelists are, how they differ from queues and channels, essential attributes, SSL certificate revocation namelists, cluster and workload uses, how applications inquire names, and MQSC examples suitable for a first lab.

Namelist vs Queue vs Channel

Beginners sometimes hear "list of names" and imagine a special queue. A namelist does not have CURDEPTH, MAXDEPTH, or message storage. It is pure metadata in the object repository, created with DEFINE NAMELIST and viewed with DISPLAY NAMELIST. Queues hold business payloads; channels define how queue managers talk; namelists group names of those (or other) objects for convenience and consistency.

Explainer: Why Group Names at All?

Imagine three applications that must fan out the same administrative broadcast to five work queues: PAYMENTS.A, PAYMENTS.B, PAYMENTS.C, PAYMENTS.D, and PAYMENTS.E. Without a namelist, every program embeds five names and must be redeployed when you add PAYMENTS.F. With DEFINE NAMELIST('PAYMENTS.WORK.SET') NAMES(PAYMENTS.A, PAYMENTS.B, ...), each program opens the namelist, inquires NAMES, and loops. Operations add PAYMENTS.F to the namelist only—no code change. The same pattern appears in queue manager configuration: SSLCRLNL names one namelist that lists every AUTHINFO used for revocation checking, so TLS policy stays centralized.

SSL and Certificate Revocation

Modern MQ estates use TLS on channels and client connections. Part of trust is knowing a partner certificate has not been revoked. DEFINE AUTHINFO objects (AUTHTYPE CRLLDAP or OCSP) point to LDAP or responders. You place those AUTHINFO names in a namelist, then ALTER QMGR SSLCRLNL(namelist-name). During handshake, MQ consults the listed definitions. If you add a new corporate CA with its own CRL location, you DEFINE AUTHINFO, add it to the namelist, and refresh—without touching every channel definition.

Cluster and Channel Namelists

Cluster configuration sometimes references namelists of channels or queues for workload or repository purposes (exact attributes vary by MQ version and platform—see your IBM MQ documentation for CLWL and cluster namelist parameters). The idea remains: the cluster subsystem iterates members rather than hard-coding one channel. On z/OS and distributed systems, naming standards often prefix namelists with the queue manager or domain, for example PROD.QM01.SSL.CRL.LIST, so DISPLAY NAMELIST(*) in a large estate stays readable.

Nested and Mixed Membership

A NAMES entry can reference another namelist on some uses, but beginners should confirm platform support and avoid deep nesting until they understand limits. Typically each entry is a queue, channel, or authinfo name. Duplicate names in one list are usually pointless; order may matter for applications that round-robin in list order. Document the intended order in DESCR for the operations team.

Authority and Object Type

Namelists have their own object type for authorization (display, alter, delete). Grant authority carefully: NAMES reveals which queues or security objects exist. In regulated environments, namelist changes belong in change control alongside ALTER CHANNEL and DEFINE AUTHINFO. DISPLAY NAMELIST shows NAMCOUNT and NAMES; it does not show message content from member queues.

Tutorial: Define and Use a Work Queue Namelist

1. Define three local queues for a lab.
2. Create a namelist containing their names.
3. Use amqsput or a small program to inquire NAMES and put one message to each member.
4. ALTER NAMELIST to add a fourth queue; confirm the program picks it up on reopen.

1
2
3
4
5
6
7
8
9
10
11
12
DEFINE QLOCAL('WORK.A') REPLACE
DEFINE QLOCAL('WORK.B') REPLACE
DEFINE QLOCAL('WORK.C') REPLACE
DEFINE NAMELIST('WORK.ALL') REPLACE +
  DESCR('Lab work queues for fan-out') +
  NAMES(WORK.A,WORK.B,WORK.C)
DISPLAY NAMELIST('WORK.ALL')
* Add member later:
ALTER NAMELIST('WORK.ALL') NAMES(WORK.A,WORK.B,WORK.C,WORK.D)
* Queue manager TLS example (after AUTHINFO exists):
* DEFINE NAMELIST('SSL.CRL.LIST') NAMES(CORP.CRL1,CORP.CRL2)
* ALTER QMGR SSLCRLNL(SSL.CRL.LIST)

Comparing Approaches

• Hard-coded queue names in source: simple for two queues, painful at scale.
• QALIAS indirection: one logical name to one queue—not a list.
• Namelist: one logical name to many targets; best for fan-out and QMGR attributes.
• Topic pub/sub: many subscribers via subscriptions—not the same as a static name list.

Explain Like I'm Five: Namelists

You have a list of friends to invite to a party written on one card. When you add a new friend, you erase the old list and write the whole list again on the same card—everyone still looks at that one card to see who is invited. The namelist is the card; the friends' names are the queues and other objects.

Practice Exercises

Exercise 1

Your estate requires two CRL AUTHINFO objects for different CAs. Write the DEFINE NAMELIST and ALTER QMGR SSLCRLNL steps in order.

Exercise 2

A program opens NAMELIST PAYMENTS.WORK.SET but gets authorization failure. List three authority checks an administrator should make.

Exercise 3

DISPLAY NAMELIST shows NAMCOUNT 3 but NAMES lists four entries. What should you investigate?

Frequently Asked Questions

Test Your Knowledge