Alias Queues

An alias queue is a second name for an existing queue. Applications open and put to the alias; IBM MQ resolves the name to a target queue (and optionally a target queue manager) defined in the QALIAS object. No messages live on the alias itself—think of it as a signpost, not a mailbox. Enterprises use alias queues heavily during migrations, environment promotion, and naming standards where developers see PAYMENTS.IN but operators maintain PAYMENTS.IN.PROD on the back end. This tutorial explains DEFINE QALIAS, TARGET and TARGQMGR, chaining, authority resolution, and how alias queues differ from remote queues and from simply renaming QLOCAL objects.

DEFINE QALIAS Basics

DEFINE QALIAS('ORDERS') TARGET('ORDERS.IN') creates alias ORDERS pointing at local queue ORDERS.IN. MQPUT to ORDERS lands on ORDERS.IN. DISPLAY QALIAS('ORDERS') shows TARGET, TARGQMGR, DESCR, and other attributes. ALTER QALIAS changes the target without redeploying application binaries—valuable when cutover windows are short. REPLACE on DEFINE makes scripts idempotent across environments.

1
2
3
4
5
6
7
8
9
DEFINE QLOCAL('ORDERS.IN.PROD') REPLACE MAXDEPTH(100000) DEFPSIST(YES)
DEFINE QALIAS('ORDERS') REPLACE +
  TARGET('ORDERS.IN.PROD') +
  TARGQMGR(' ') +
  DESCR('Logical name - apps use ORDERS')
* Put test uses alias name:
* amqsput ORDERS QM1
DISPLAY QALIAS('ORDERS') TARGET TARGQMGR
DISPLAY QLOCAL('ORDERS.IN.PROD') CURDEPTH

TARGET and TARGQMGR Explained

TARGET is the queue name after resolution—a QLOCAL, QREMOTE, or another QALIAS on some queue manager. TARGQMGR names which queue manager holds that definition. When blank or local, the target is on the connected queue manager. When TARGQMGR names a remote queue manager, resolution uses the repository on that system—typical in QSG or federated naming patterns advanced sites use. Beginners on a single queue manager leave TARGQMGR empty and point TARGET at a local queue name.

Alias vs Remote vs Local Rename

Renaming QLOCAL from OLD to NEW breaks every program hard-coded to OLD. Creating QALIAS OLD TARGET(NEW) lets you deploy application config changes gradually. QREMOTE solves cross-queue-manager routing; QALIAS solves naming. Combined pattern: alias PAYMENTS points to QREMOTE PAYMENTS.TO.HUB so developers use one short name while routing stays administrative. Compare maintenance: ALTER QALIAS TARGET for indirection change; ALTER QREMOTE RNAME/RQMNAME/XMITQ for path change.

Authority and Security

Authority checks apply to the object the application names and to the resolved object depending on platform rules and object types. Grant put authority on the alias for developers; ensure they cannot alter TARGET to a queue they should not access. Some shops grant only alias names in production namespaces, hiding physical queue names. Channel and listener security are separate; alias does not bypass CHLAUTH on remote puts.

Migration and Environment Patterns

• Dev QALIAS ORDERS TARGET(ORDERS.IN.DEV); prod TARGET(ORDERS.IN.PROD)—same app config key ORDERS per environment.
• Blue/green cutover: switch TARGET from OLD.IN to NEW.IN during maintenance window.
• Deprecation: leave alias pointing to archive queue while retiring producer apps.
• Documentation: DESCR on QALIAS states owner and target for operators.

Attributes on QALIAS

QALIAS objects have fewer attributes than QLOCAL. You cannot set MAXDEPTH on an alias—capacity is on the target. Custom attributes may exist for tooling. DEFBIND, CLUSTER, and scope attributes appear in cluster alias scenarios covered in cluster tutorials. For beginners, TARGET, TARGQMGR, and DESCR are the critical trio on day one.

Monitoring and Troubleshooting

Application reports put OK but wrong data arrives: DISPLAY QALIAS—did TARGET change? Put succeeds but 2035 on get: authority on target queue, not alias. Depth always zero on alias name: normal—monitor target QLOCAL CURDEPTH. Trace resolution with DISPLAY QALIAS ALL and DISPLAY QLOCAL or DISPLAY QREMOTE on TARGET name.

Alias Chains

ALIAS1 TARGET(ALIAS2), ALIAS2 TARGET(REAL.QUEUE) works but obscures operations. Standards often forbid more than one hop. If chain breaks (missing target), puts fail with reason codes for unknown object or not resolved depending on stage. Prefer flat alias to final queue for runbook clarity.

Explain Like I'm Five: Alias Queue

Your friend's house has a secret nickname “The Castle.” Mail addressed to The Castle still goes to the same house—the nickname is not a second building. An alias queue is the nickname; the real queue is the house where letters pile up.

Practice Exercises

Exercise 1

Create QALIAS APP.IN TARGET(QLAB). Write steps to repoint to QPROD without changing application queue name APP.IN.

Exercise 2

When is QREMOTE better than QALIAS for a cross-site put?

Exercise 3

Why does DISPLAY QALIAS not show CURDEPTH? Where do you look?

Frequently Asked Questions

Test Your Knowledge