MQSC scripting turns ad hoc runmqsc typing into repeatable infrastructure. A text file checked into Git containing DEFINE QLOCAL, DEFINE CHANNEL, START LISTENER, and SET AUTHREC (where applicable) becomes the contract for what a queue manager should look like after deployment. When auditors ask how production PAYMENT.IN was created, the answer is pull request #1842, not memory of a Friday night console session. Beginners start with ten-line lab scripts; mature estates have hundreds of lines per environment with variables substituted for queue manager names, hostnames, and partner CONNAME values. This tutorial covers file structure, execution methods on Linux and Windows, continuation lines, idempotent DEFINE and ALTER patterns, promotion across dev/test/prod, pairing scripts with setmqaut, rollback limitations, secrets handling, and common pipeline failures so your automation survives the first production cutover.
A typical script groups objects logically: queue manager attributes (rare in frequent scripts), queues, channels, listeners, namelists, topics, and security-related definitions. Each command ends with a semicolon. Long DEFINE lines use plus (+) continuation at line end. Comment lines start with asterisk in column one for batch processing. Blank lines improve readability. File naming conventions like 01-queues.mqsc and 02-channels.mqsc enforce run order when multiple files are piped sequentially.
1234567* 01-queues.mqsc — payment queues for QM1 DEFINE QLOCAL('PAYMENT.IN') REPLACE + DESCR('Inbound payments') MAXDEPTH(50000) DEFPSIST(YES) DEFINE QLOCAL('PAYMENT.OUT') REPLACE + DESCR('Outbound status') MAXDEPTH(10000) DEFPSIST(YES) DEFINE QLOCAL('PAYMENT.DLQ') REPLACE + DESCR('Payment dead letter') MAXDEPTH(5000)
Unix: runmqsc QM1 < 01-queues.mqsc. Windows: same redirection in PowerShell or cmd. Shell loops: for qm in QM1 QM2; do runmqsc $qm < script.mqsc; done. Ansible modules and Terraform IBM MQ provider may generate MQSC or call APIs instead—know which layer owns truth. Always run against the intended queue manager name; many incidents come from running prod script on test because the shell variable was unset.
| Pattern | Behavior on re-run | When to use |
|---|---|---|
| DEFINE without REPLACE | Fails if object exists | First-time install only |
| DEFINE with REPLACE | Creates or replaces definition | DevOps pipelines, DR rebuild |
| ALTER only | Fails if object missing | Patch scripts changing one attribute |
| DELETE then DEFINE | Brief window object absent | Legacy; risky on prod with open handles |
Dev scripts should not contain production partner IPs. Use placeholders: CONNAME('$PARTNER_HOST(1414)') substituted by CI before runmqsc. Keep one template repo; generate environment-specific artifacts in the pipeline. Promotion flow: merge to main, deploy artifact to test, automated smoke put/get, manual approval, deploy to prod. Diff DISPLAY output before and after in test to catch typos. z/OS may use different command paths—maintain separate script libraries if CSQUTIL is required instead of runmqsc.
DEFINE QLOCAL creates the object; it does not grant application +put. Distributed MQ needs setmqaut commands in the same change ticket or a parallel script run as security admin. Forgetting setmqaut is the top cause of “script succeeded but app gets 2035.” Document run order: objects first, authority second, application deploy third, channel START last.
123runmqsc QM1 < define_queues.mqsc setmqaut -m QM1 -n PAYMENT.IN -t queue -p PAYSRV +put +get +browse setmqaut -m QM1 -n PAYMENT.IN -t queue -g PAYOPS +browse
MQSC scripting is a recipe card the kitchen robot (runmqsc) follows exactly every time you open a restaurant branch (new queue manager), so every branch has the same menu (queues and channels).
Do not commit SSLKEYR passwords or partner credentials in cleartext MQSC. Use vault injection at deploy time or define channels without secrets and ALTER in a secured step. AUTHINFO objects for LDAP bind passwords belong in secret stores. Scripts in Git are forever—rotate if leaked.
MQSC has no built-in transaction across commands. If script part 3 fails, parts 1–2 already applied. Rollback scripts must DELETE or ALTER back explicitly. Production changes need forward and backward scripts in the change record. CLEAR QLOCAL in rollback is destructive—label clearly.
It is a written list of setup steps for the message mailbox building so you never forget a step when building a new one.
Write a two-file script: queues then channels referencing an XMITQ defined in file one.
Add REPLACE and re-run; document what changed in DISPLAY output.
Design a pipeline step that fails if grep finds AMQ8 in runmqsc log.
1. MQSC scripts are executed by:
2. Idempotent scripts avoid:
3. Script order should define:
4. CI pipelines should parse: