Command Server

Every DEFINE QLOCAL, START CHANNEL, and REFRESH CLUSTER you run flows through the IBM MQ command server. It is the administrative brain attached to the queue manager: not moving business messages for applications, but changing the repository, refreshing cluster cache, and answering DISPLAY questions. When runmqsc hangs or returns CSQ errors on z/OS, operators troubleshoot this component. Beginners who learn only MQI still need the command server for day-one lab work and production changes. This page explains how it starts, how MQSC and PCF reach it, common errors, security, and automation patterns.

Role in the Queue Manager

At queue manager startup, the queue manager starts core agents including the command server (exact service name in STATUS varies by platform). It listens for administrative work while application MQPUT and MQGET use different paths. Stopping the command server deliberately is rare; maintenance usually stops the entire queue manager with endmqm. Partial administration outage with messaging still up can occur if the process fails—treat as severity high because you cannot ALTER objects during an incident response.

MQSC via runmqsc

runmqsc is a client-style program connecting to the command server. Interactive mode lets you type DISPLAY QMGR and see multi-line responses. Batch mode feeds scripts for CI/CD: runmqsc QM1 < config.mqsc. Each line parses as MQSC; semicolons end commands; plus signs continue lines. Syntax errors return AMQ errors with reason; the command server does not apply half a DEFINE. Successful DEFINE creates objects visible immediately to new MQOPEN calls subject to attribute rules.

Explainer: PCF and Graphical Tools

MQ Explorer sends PCF requests instead of raw MQSC text. The command server executes equivalent operations. REST administration APIs on modern MQ also translate into internal commands. From a learning perspective, DISPLAY QLOCAL in runmqsc and the same queue shown in Explorer are the same repository data. Automation teams pick MQSC files in Git for readability or PCF for programmatic error codes.

Security and Authority

Administrative commands require privileges on the queue manager—often membership in mqm group on Linux or explicit AUTHREC +connect +inq +chg on objects. ALTER QMGR demands higher privilege than DISPLAY QLOCAL. In regulated environments, separate roles: operators DISPLAY and START CHANNEL; engineers DEFINE in CI with approval. CONNAUTH applies to runmqsc connections like any client. Audit logs record who issued destructive DELETE commands.

Errors and Troubleshooting

• Queue manager not running—runmqsc cannot connect; strmqm first.
• MQRC_NOT_AUTHORIZED—check OS user, AUTHREC, and CHLAUTH if remote admin.
• Syntax error in script—fix line; later commands may not run in same batch depending on settings.
• Object already exists—use ALTER or DEFINE REPLACE per change standard.
• Command server not active—DISPLAY QMSTATUS and review AMQERR logs.

Automation and GitOps

Pipelines store mqsc files per environment. Promotion merges DEFINE scripts; runmqsc applies on deploy. Idempotent patterns use DEFINE ... REPLACE. Pairs with dmpmqcfg export after deploy to verify drift. Rate-limit concurrent scripts during incidents so operators are not fighting automation. For clusters, REFRESH CLUSTER after bulk DEFINE may be required so partial repositories see updates.

Tutorial: Interactive and Batch MQSC

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# Interactive (exit with 'end' or Ctrl+C per platform)
runmqsc QM1
 
# One-liner
echo "DISPLAY QMGR ALL" | runmqsc QM1
 
# Script file
cat > /tmp/create-orders.mqsc << 'EOF'
DEFINE QLOCAL('ORDERS.IN') REPLACE +
  DESCR('Inbound orders') +
  MAXDEPTH(50000) DEFPSIST(YES)
ALTER QMGR DEADQ('SYSTEM.DEAD.LETTER.QUEUE')
DISPLAY QLOCAL('ORDERS.IN') ALL
EOF
runmqsc QM1 < /tmp/create-orders.mqsc
 
# z/OS operators may use CSQUTIL or equivalent panels

Relationship to Other Processes

Listeners accept network connections for messaging and clients; the command server accepts administration. Trigger monitors start applications; command server does not run your COBOL. Channel initiators move messages; command server START CHANNEL only toggles their state. Knowing the split helps read DISPLAY QMSTATUS service lines without conflating components.

Explain Like I'm Five: Command Server

The post office boss has a helper who only updates the big list of mailbox names and rules (command server). Customers dropping letters (applications) use a different window. When you ask to add a new mailbox name, the helper writes it in the list book— that is DEFINE QLOCAL.

Practice Exercises

Exercise 1: Script

Write a five-line mqsc script that DEFINEs a local queue and DISPLAYs it.

Exercise 2: Authority

User can DISPLAY but not ALTER. Which AUTHREC missing?

Exercise 3: Failure

runmqsc fails with queue manager not available. List three checks in order.

Frequently Asked Questions

Test Your Knowledge