runmqsc

The runmqsc command is how most administrators first touch IBM MQ on distributed platforms: a terminal, a queue manager name, and lines of MQSC that create queues, start channels, and display configuration. Every DEFINE QLOCAL, ALTER CHANNEL, and REFRESH SECURITY you type is packaged by runmqsc and delivered to the queue manager command server, which validates syntax, checks authority, and updates the object repository. Scripting runmqsc files in source control is the backbone of repeatable environments—dev, test, and production receive the same object definitions with only queue manager name or path substitutions. Beginners confuse runmqsc with application messaging utilities; runmqsc never puts business messages on application queues. This tutorial covers starting interactive sessions, command syntax and continuation, common DEFINE and DISPLAY patterns, reading AMQ response codes, batch and automation, security requirements, differences from z/OS CSQ commands, relationship to PCF and REST, and troubleshooting connection failures to the command server.

Starting an Interactive Session

Ensure the queue manager is running (dspmq or equivalent). From a shell where the MQ installation is in PATH, run runmqsc followed by the queue manager name, for example runmqsc QM1. The prompt changes to show you are in MQSC mode (historically numbered lines like 1). Type commands ending with semicolons. End the session with end or by closing input on some platforms. Wrong queue manager name fails immediately—double-check spelling on hosts with dozens of queue managers. On Windows, use the same command from an MQ-authorized command prompt.

1
2
3
4
5
runmqsc QM1
DISPLAY QMGR ALL
DEFINE QLOCAL('DEMO.IN') DESCR('Lab queue') MAXDEPTH(5000)
DISPLAY QLOCAL('DEMO.IN') ALL
end

MQSC Command Structure

MQSC uses verb-object syntax: DEFINE, ALTER, DISPLAY, DELETE, START, STOP, REFRESH, CLEAR, and others, followed by object type and name in parentheses, then attributes. String values are quoted. Multiple attributes fit on one line separated by spaces; long lines continue with a plus sign (+) at the end of the line and the next segment on the following line. Comments in scripts often use an asterisk in column one for lines the command server should ignore when configured for comment support in batch files—follow IBM documentation for your release. Typos in attribute names produce AMQ error messages without changing objects.

Reading Command Responses

Successful DEFINE often returns AMQ8006I or similar informational messages. Errors show AMQ8xxx codes with explanation—for example object already exists, syntax error, or not authorized. Scripts should not assume silence means success; parse output in CI pipelines or use echo markers. DISPLAY returns multiple lines per attribute; redirect output to files for diffs during audits. SAVEOBJECT and other advanced commands appear in migration tooling—beginners focus on DEFINE/DISPLAY first.

Scripted and Batch Execution

Store scripts as text files with .mqsc extension by convention. Run with input redirection: runmqsc QM1 < create_objects.mqsc. In CI/CD, the pipeline user needs OS and MQ authority to execute runmqsc against target queue managers. Idempotent scripts use ALTER with REPLACE on supported releases or check DISPLAY before DEFINE. Partial failure leaves some objects created—design scripts in dependency order (queues before channels that reference them) and use transaction-like discipline: test full script in staging, then production change window.

1
2
3
4
5
6
7
8
# Example batch from shell
runmqsc QM1 <

Explainer: Remote Control for the Queue Manager

runmqsc is the remote control for queue manager settings—changing which mailboxes exist and which roads (channels) connect to other buildings—not putting letters in the mailboxes (that is MQPUT).

Security and Authority

On distributed MQ, the OS user running runmqsc must be in the mqm group or equivalent, and may need specific OAM authority for sensitive commands (SECURITY, AUTHREC). Least privilege means separate deploy service accounts with DEFINE on application queues but not DELETE QMGR. Audit who runs runmqsc on production hosts. On z/OS, operators typically use CSQUTIL and console commands rather than runmqsc—do not assume RACF profiles for CSQ are interchangeable with Linux mqm group membership.

runmqsc Versus PCF, REST, and Explorer

• runmqsc — human-readable MQSC; ideal for scripts and grep-friendly diffs.
• PCF — binary programmable command format; used by MQ Explorer and many automation tools.
• REST — HTTP admin API on supported releases; cloud-native pipelines.
• Explorer — GUI; good for discovery, exports some MQSC for scripts.

All paths hit the command server for object changes. Pick one standard for infrastructure-as-code; mixing undocumented Explorer clicks and untracked manual runmqsc causes drift.

Common Beginner Mistakes

1. Missing semicolon at end of command — command not executed or concatenated incorrectly.
2. Wrong quotes — use single quotes around object names with special characters per MQSC rules.
3. DEFINE without REPLACE on existing object — fails in automation reruns.
4. Targeting wrong queue manager on shared admin server — destroys wrong environment.
5. START CHANNEL before partner listener ready — retry storms; use change windows.
6. Forgetting setmqaut after DEFINE QLOCAL — applications get 2035 despite object existing.

Environment Variables and Paths

MQ installation sets PATH and library paths through setmqenv or platform equivalents. runmqsc must match the queue manager installation version—running 9.3 runmqsc against an older queue manager may fail. Container images embed paths in ENTRYPOINT scripts. Document required environment in runbooks so on-call engineers do not use a shell without MQ paths after login.

Troubleshooting runmqsc Connection Failures

Symptom: cannot connect to queue manager — queue manager stopped, wrong name, or IPC permissions on Unix. Symptom: hangs — command server not responding; check queue manager error logs and restart command server if documented safe. Symptom: all commands fail not authorized — OS user or AUTHREC. Symptom: syntax error on every line — copy-paste corrupted continuation characters or smart quotes from documents.

Explain Like I'm Five: runmqsc

runmqsc is typing instructions to the queue manager robot about which boxes and tubes to build—not sending toys through the tubes.

Practice Exercises

Exercise 1

Write a script that DEFINEs a local queue, DISPLAYs it, and ALTERs MAXDEPTH.

Exercise 2

Capture runmqsc output to a file and circle all AMQ error codes.

Exercise 3

List three commands you would not run during peak hours without a change window.

Frequently Asked Questions

Test Your Knowledge