IBM MQ Administration, Troubleshooting and CritSit Guide
1. IBM MQ Basic Command Reference
Platform note: Commands prefixed with `$` apply to UNIX/Linux/AIX. On Windows, run commands from an IBM MQ command prompt (Start → IBM MQ → IBM MQ Command Prompt). The `dspmqver` command is identical on all platforms.
1.1 Display IBM MQ Version Information
dspmqver
Sample output:
Name: IBM MQ
Version: 9.4.0.0
Level: p940-L240101.DE
BuildType: IKAP - (Production)
Platform: IBM MQ for Linux (x86-64 platform)
Mode: 64-bit
O/S: Linux 5.15.0
InstName: Installation1
InstDesc:
Primary: Yes
InstPath: /opt/mqm
DataPath: /var/mqm
MaxCmdLevel: 940
LicenseType: Production
1.2 Display All Queue Managers
dspmq # all queue managers, brief
dspmq -x # extended: includes install name
dspmq -m QM1 # single queue manager status
1.3 Create a Queue Manager
# Basic creation
crtmqm QM1
# Set as default queue manager
crtmqm -q QM1
# Recommended production sample Queue Manager creation with explicit log and data paths
crtmqm -lf 4096 -lp 5 -ls 7 -ld /MQ/MQLogs/ -md /MQ/MQData/ -p 1414 QM1
# Parameters:
# -lf 4096 Log file page size (4096 x 4KB = 16 MB per log file)
# -lp 5 Number of primary log files
# -ls 7 Number of secondary log files
# -ld Log directory
# -md Data directory
# -p Listener port
1.4 Start a Queue Manager
strmqm QM1 # start
1.5 Stop a Queue Manager
endmqm QM1 # quiesce (wait for apps to disconnect)
endmqm -i QM1 # immediate stop
endmqm -p QM1 # preemptive (force) stop — last resort only
1.6 Open MQSC Command Shell
runmqsc QM1 # interactive MQSC session
runmqsc QM1 < /tmp/setup.mqsc # run MQSC script from file
runmqsc -e QM1 < /tmp/setup.mqsc # suppress echo of input commands
1.7 Start and Stop a Listener
# Start listener on port 1414
runmqlsr -t tcp -p 1414 -m QM1 &
# Stop listener
endmqlsr -m QM1
# Or define and start via MQSC:
# DEFINE LISTENER(LISTENER.TCP) TRPTYPE(TCP) PORT(1414) CONTROL(QMGR) REPLACE
# START LISTENER(LISTENER.TCP)
1.8 Display Queue Manager Status
runmqsc QM1 # MQSC commands to a queue manager interactively
Display QMGR ALL # DISPLAY QMGR to display the queue manager parameters for this queue manager.
1.9 Display Queue Depth and Attributes
# Via runmqsc command
runmqsc QM1
display ql(mylocalqueue1) CURDEPTH
end
# Direct command prompt
echo "DISPLAY QL($mylocalqueue1) CURDEPTH" | runmqsc $QM1 | grep CURDEPTH
1.10 Delete a Queue Manager
dltmqm QM1 # queue manager must be stopped first
1.11 Check MQ Service Status (systemd — Linux)
systemctl status mq@QM1.service
journalctl -u mq@QM1.service --since "1 hour ago"
1.12 Apply MQ Fix Pack / Check Installation
# Check installed fix pack level (Linux RPM)
rpm -qa | grep MQSeries
# Check installed fix pack level (Windows)
dspmqver -v
# Apply a fix pack (Linux)
./mqlicense.sh -accept
rpm -Uvh MQSeries*.rpm
2. MQSC Command Reference (Examples)
2.1 Queue Manager Level Commands
Display Queue Manager attributes
DISPLAY QMGR ALL
Alter command for Queue Manager attributes
ALTER QMGR MAXMSGL(104857600) MAXDEPTH(999999999) DEADQ(SYSTEM.DEAD.LETTER.QUEUE)
ALTER QMGR CHLAUTH(ENABLED) CONNAUTH(SYSTEM.DEFAULT.AUTHINFO.IDPWOS)
ALTER QMGR SSLKEYR('/var/mqm/ssl/key') CERTLABL('ibmwebspheremq')
Refresh security
REFRESH SECURITY TYPE(SSL)
REFRESH SECURITY TYPE(AUTHSERV)
Refresh cluster
REFRESH CLUSTER(MYCLUSTER) REPOS(YES)
2.2 Local Queue Commands
Create a local queue
DEFINE QLOCAL(Q.IN) MAXDEPTH(99999) MAXMSGL(104857600) DESCR('Inbound queue') REPLACE
Display current depth of all application queues
DISPLAY QLOCAL(*) WHERE(USAGE EQ NORMAL) CURDEPTH MAXDEPTH IPPROCS OPPROCS
Clear queue (removes all messages — use with caution)
CLEAR QLOCAL(Q.IN)
Delete queue
DELETE QLOCAL(Q.IN) PURGE
2.3 Remote Queue Commands
Define a remote queue definition
DEFINE QREMOTE(Q.REMOTE.SALES) RNAME(Q.SALES) RQMNAME(QMSALES) XMITQ(QM1.TO.QMSALES) REPLACE
Define a transmission queue
DEFINE QLOCAL(QM1.TO.QMSALES) USAGE(XMITQ) MAXDEPTH(999999) REPLACE
2.4 Alias Queue
DEFINE QALIAS(Q.ALIAS.IN) TARGET(Q.IN) TARGTYPE(QUEUE) REPLACE
2.5 Channel Commands
Define a Sender channel
DEFINE CHANNEL(QM1.TO.QMSALES) CHLTYPE(SDR) CONNAME('192.168.1.20(1414)') XMITQ(QM1.TO.QMSALES) TRPTYPE(TCP) REPLACE
Define a Receiver channel
DEFINE CHANNEL(QMSALES.TO.QM1) CHLTYPE(RCVR) TRPTYPE(TCP) REPLACE
Define a Server-Connection channel (for client connections)
DEFINE CHANNEL(SYSTEM.SVRCONN) CHLTYPE(SVRCONN) TRPTYPE(TCP) MCAUSER('mqm') REPLACE
Display channel status
DISPLAY CHSTATUS(*)
DISPLAY CHSTATUS(*) WHERE(STATUS NE INACTIVE)
Start / Stop / Reset a channel
START CHANNEL(QM1.TO.QMSALES)
STOP CHANNEL(QM1.TO.QMSALES) MODE(QUIESCE)
RESET CHANNEL(QM1.TO.QMSALES) SEQNUM(1)
2.6 Listener Commands
DEFINE LISTENER(LISTENER.TCP) TRPTYPE(TCP) PORT(1414) CONTROL(QMGR) IPADDR(0.0.0.0) REPLACE
START LISTENER(LISTENER.TCP)
STOP LISTENER(LISTENER.TCP)
DISPLAY LSSTATUS(LISTENER.TCP)
2.7 Channel Authentication Records (CHLAUTH — v9.4.x)
Block all connections by default (recommended security posture)
ALTER QMGR CHLAUTH(ENABLED)
SET CHLAUTH(*) TYPE(BLOCKUSER) USERLIST(ALLUSERS) ACTION(ADD)
Allow a specific user/IP to connect via a named channel
SET CHLAUTH(SYSTEM.SVRCONN) TYPE(ADDRESSMAP) ADDRESS('192.168.1.*') USERSRC(CHANNEL) CHCKCLNT(REQUIRED) ACTION(ADD)
Allow a specific client DN (TLS)
SET CHLAUTH(SYSTEM.SVRCONN) TYPE(SSLPEERMAP) SSLPEER('CN=App1,O=MyOrg') USERSRC(MAP) MCAUSER('app1user') ACTION(ADD)
Display all CHLAUTH rules
DISPLAY CHLAUTH(*) ALL
2.8 Authentication Information (AUTHINFO — v9.4.x)
DEFINE AUTHINFO(SYSTEM.DEFAULT.AUTHINFO.IDPWOS) AUTHTYPE(IDPWOS) CHCKCLNT(OPTIONAL) REPLACE
ALTER QMGR CONNAUTH(SYSTEM.DEFAULT.AUTHINFO.IDPWOS)
REFRESH SECURITY TYPE(AUTHSERV)
2.9 Topic and Publish/Subscribe Commands
DEFINE TOPIC(NEWS.TOPIC) TOPICSTR('/news/alerts') REPLACE
DISPLAY TPSTATUS('/news/#')
DISPLAY SBSTATUS(*)
2.10 Service Commands
DEFINE SERVICE(MY.CLEANUP.SVC) SERVTYPE(COMMAND) STARTCMD('/opt/scripts/cleanup.sh') STARTARG('-m +QM1') STOPCMD('/opt/scripts/cleanup_stop.sh') CONTROL(MANUAL) REPLACE
START SERVICE(MY.CLEANUP.SVC)
STOP SERVICE(MY.CLEANUP.SVC)
DISPLAY SVSTATUS(*)
2.11 Dead-Letter Queue Handler
# runmqdlq command to start the dead-letter queue (DLQ) handler, which monitors and handles messages on a DLQ
# Run the DLQ handler with a rules table
runmqdlq SYSTEM.DEAD.LETTER.QUEUE QM1 < /opt/mq/conf/dlqrules.txt
2.12 Complete MQSC Quick Reference
|
MQSC Command
|
Object types supported
|
|
`ALTER`
|
QMGR, QLOCAL, QREMOTE, QALIAS, CHANNEL, LISTENER, TOPIC, AUTHINFO, COMMINFO, SERVICE
|
|
`DEFINE`
|
QLOCAL, QREMOTE, QALIAS, QMODEL, CHANNEL, LISTENER, TOPIC, NAMELIST, PROCESS, AUTHINFO, SERVICE
|
|
`DELETE`
|
All definable objects
|
|
`DISPLAY`
|
All object types + CHSTATUS, QSTATUS, LSSTATUS, TPSTATUS, SBSTATUS, SVSTATUS, CONN, CHLAUTH, GROUP
|
|
`START`
|
CHANNEL, LISTENER, SERVICE
|
|
`STOP`
|
CHANNEL, LISTENER, SERVICE, CONN
|
|
`CLEAR`
|
QLOCAL (destructive — removes all messages)
|
|
`RESET`
|
CHANNEL (sequence number), QMGR (statistics)
|
|
`RESOLVE`
|
CHANNEL (in-doubt units of work)
|
|
`RESUME`
|
QMGR (suspended in a cluster)
|
|
`SUSPEND`
|
QMGR (removes from cluster routing temporarily)
|
|
`REFRESH`
|
CLUSTER, SECURITY, QMGR (DQM)
|
|
`SET`
|
CHLAUTH, AUTHREC
|
|
`DISPLAY`
|
AUTHREC (authority records)
|
|
`MOVE`
|
QLOCAL (move messages to another queue)
|
|
`PING`
|
QMGR, CHANNEL
|
3. IBM MQ Server to MQ Client Communication — Cross-Platform (Windows & Linux)
3.1 Architecture Overview
3.2 Scenario A — MQ Server on Windows, MQ Client on Linux
Step 1: Install IBM MQ Client on Linux (Ubuntu/RHEL/CentOS)
Ubuntu / Debian:
# Unpack IBM MQ Client package
tar -xvzf IBM_MQ_9.4.x_LINUX_X86-64.tar.gz
cd MQClient
# Accept license
./mqlicense.sh -accept
# Install required packages in order
sudo dpkg -i ibmmq-runtime_9.4.*.deb
sudo dpkg -i ibmmq-mqclient_9.4.*.deb
sudo dpkg -i ibmmq-samples_9.4.*.deb # optional sample programs
# Verify installation
apt list --installed | grep ibmmq
RHEL / CentOS / Fedora:
sudo rpm -ivh MQSeriesRuntime-9.4.*.rpm
sudo rpm -ivh MQSeriesClient-9.4.*.rpm
sudo rpm -ivh MQSeriesSamples-9.4.*.rpm # optional
# Verify
rpm -qa | grep MQSeries
Step 2: Set Up the MQ Environment on Linux
# Source the MQ environment
. /opt/mqm/bin/setmqenv -s
# Verify
dspmqver
Step 3: Configure the MQ Server on Windows
Open an IBM MQ Command Prompt as Administrator:
:: Start MQSC against your Queue Manager
runmqsc QM_SERVER
:: Create a Server-Connection channel for Linux clients
DEFINE CHANNEL(TO.LINUX.CLIENT) CHLTYPE(SVRCONN) TRPTYPE(TCP) MCAUSER('') DESCR('Linux client connection') REPLACE
:: Enable CHLAUTH and set a rule for the Linux client IP range
SET CHLAUTH(TO.LINUX.CLIENT) TYPE(ADDRESSMAP) ADDRESS('192.168.1.*') USERSRC(CHANNEL) CHCKCLNT(ASQMGR) ACTION(ADD)
:: Define listener if not already running
DEFINE LISTENER(LST.TCP) TRPTYPE(TCP) PORT(1414) CONTROL(QMGR) REPLACE
START LISTENER(LST.TCP)
END
Grant authority to the connecting OS user:
setmqaut -m QM_SERVER -t qmgr -p linuxuser +connect +inq +dsp
setmqaut -m QM_SERVER -t chl -n TO.LINUX.CLIENT -p linuxuser +dsp +ctrlx
setmqaut -m QM_SERVER -t q -n Q.IN -p linuxuser +put +get +browse +inq +dsp
Step 4: Verify Network Connectivity
# From Linux client, ping the Windows MQ server
ping 192.168.1.10
# Test port reachability
telnet 192.168.1.10 1414
# Modern alternative (if telnet not installed)
nc -zv 192.168.1.10 1414
# Or use MQ's own ping
echo "PING QMGR" | runmqsc -c -u linuxuser -m QM_SERVER -n TO.LINUX.CLIENT
Step 5: Connect and Test from Linux Client
Method A — MQSERVER environment variable (quick test):
export MQSERVER='TO.LINUX.CLIENT/TCP/192.168.1.10(1414)'
export MQSAMP_USER_ID='linuxuser'
# Put a message to Q.IN on the Windows QM
/opt/mqm/samp/bin/amqsputc Q.IN QM_SERVER
# Get a message from Q.IN on the Windows QM
/opt/mqm/samp/bin/amqsgetc Q.IN QM_SERVER
Method B — CCDT (Client Channel Definition Table — recommended for production):
export MQCHLLIB='/opt/mqm/ccdt/'
export MQCHLTAB='AMQCLCHL.TAB'
/opt/mqm/samp/bin/amqsputc Q.IN QM_SERVER
Method C — MQ URI / JSON CCDT (IBM MQ 9.2+):
export MQCCDTURL='file:///opt/mqm/ccdt/ccdt.json'
/opt/mqm/samp/bin/amqsputc Q.IN QM_SERVER
3.3 Scenario B — MQ Server on Linux, MQ Client on Windows
Step 1: Install IBM MQ Client on Windows
1. Download IBM MQ 9.4.x client installer from IBM Fix Central.
2. Run setup.exe and select IBM MQ Client installation type.
3. Accept the licence and complete the installer.
4. Verify: Open IBM MQ Command Prompt → dspmqver.
Step 2: Configure the MQ Server on Linux
runmqsc QM_SERVER << 'EOF'
DEFINE CHANNEL(TO.WIN.CLIENT) CHLTYPE(SVRCONN) TRPTYPE(TCP) MCAUSER('') REPLACE
SET CHLAUTH(TO.WIN.CLIENT) TYPE(ADDRESSMAP) ADDRESS('192.168.1.*') USERSRC(CHANNEL) CHCKCLNT(ASQMGR) ACTION(ADD)
DEFINE LISTENER(LST.TCP) TRPTYPE(TCP) PORT(1414) CONTROL(QMGR) REPLACE
START LISTENER(LST.TCP)
END
EOF
# Grant authority
setmqaut -m QM_SERVER -t qmgr -p winuser +connect +inq +dsp
setmqaut -m QM_SERVER -t chl -n TO.WIN.CLIENT -p winuser +dsp +ctrlx
setmqaut -m QM_SERVER -t q -n Q.IN -p winuser +put +get +browse +inq +dsp
Step 3: Test from Windows
SET MQSERVER=TO.WIN.CLIENT/TCP/192.168.1.20(1414)
SET MQSAMP_USER_ID=winuser
amqsputc Q.IN QM_SERVER
amqsgetc Q.IN QM_SERVER
3.4 TLS-Secured Client Connection (Recommended for Production)
# On the MQ Server: create key repository
runmqckm -keydb -create -db /var/mqm/ssl/key.kdb -type cms -pw changeit -stash
# Add personal certificate
runmqckm -cert -create -db /var/mqm/ssl/key.kdb -pw changeit \
-label ibmwebspheremqqm_server -dn "CN=QM_SERVER,O=MyOrg,C=IN" \
-size 2048 -sig_alg SHA256WithRSA
# Configure Queue Manager to use TLS key repo
ALTER QMGR SSLKEYR('/var/mqm/ssl/key')
REFRESH SECURITY TYPE(SSL)
# Define TLS-enabled SVRCONN channel
DEFINE CHANNEL(TO.CLIENT.TLS) CHLTYPE(SVRCONN) TRPTYPE(TCP) \
SSLCIPH(TLS_RSA_WITH_AES_256_CBC_SHA256) SSLCAUTH(OPTIONAL) REPLACE
4. Remote Administration through MQ Explorer — Guided Steps
4.1 Installing MQ Explorer
On Windows (standalone installation):
1. Run the IBM MQ 9.4.x installer.
2. Select IBM MQ Explorer from the component list.
3. Complete the installation.
4. Launch from Start → IBM MQ → MQ Explorer.
On Linux (standalone GUI installation):
# Unpack the MQ Explorer installer
tar -xvzf IBM_MQ_Explorer_9.4.x_Linux.tar.gz
cd MQExplorer
# Run the graphical installer
./Setup.bin
# Or run headless/silent install
./Setup.bin -i console
# Or with a response file:
./Setup.bin -f silent_install.resp
# Launch
/opt/mqexplorer/MQExplorer
4.2 Configuring the MQ Server for Remote Administration
Perform these steps on the MQ Server (can be Windows or Linux):
Step 1: Create the Administration SVRCONN Channel
runmqsc QM_SERVER
DEFINE CHANNEL(MQADMIN) CHLTYPE(SVRCONN) TRPTYPE(TCP) MCAUSER('') \
DESCR('MQ Explorer remote admin channel') REPLACE
Step 2: Configure CHLAUTH for the Explorer Host
-- Allow connections from MQ Explorer machine (replace IP as appropriate)
SET CHLAUTH(MQADMIN) TYPE(ADDRESSMAP) ADDRESS('192.168.1.15') \
USERSRC(CHANNEL) CHCKCLNT(ASQMGR) ACTION(ADD)
-- If using a named user for Explorer
SET CHLAUTH(MQADMIN) TYPE(USERMAP) CLNTUSER('ubuntu') USERSRC(MAP) \
MCAUSER('mqadminuser') ACTION(ADD)
Step 3: Grant Required Authorities
# Queue Manager level
setmqaut -m QM_SERVER -t qmgr -p mqadminuser \
+connect +inq +dsp +altusr +setid
# Administration channel
setmqaut -m QM_SERVER -t chl -n MQADMIN -p mqadminuser +dsp +ctrlx
# SYSTEM queues — Explorer uses these to issue commands and receive replies
setmqaut -m QM_SERVER -t q -n "SYSTEM." -p mqadminuser +dsp
setmqaut -m QM_SERVER -t q -n SYSTEM.DEFAULT.MODEL.QUEUE -p mqadminuser +inq +browse +get +dsp
setmqaut -m QM_SERVER -t q -n SYSTEM.ADMIN.COMMAND.QUEUE -p mqadminuser +inq +put +dsp
setmqaut -m QM_SERVER -t q -n SYSTEM.MQEXPLORER.REPLY.MODEL -p mqadminuser +inq +browse +get +dsp +put
setmqaut -m QM_SERVER -t q -n "SYSTEM.CLUSTER.TRANSMIT.*" -p mqadminuser +dsp
4.3 Connecting MQ Explorer to a Remote Queue Manager
1. Open MQ Explorer on your workstation.
2. In the Navigator panel, right-click Queue Managers → Add Remote Queue Manager…
3. Enter the Queue Manager name: QM_SERVER
4. Click Next.
5. Enter the Host name or IP: 192.168.1.20
6. Enter the Port: 1414
7. Enter the Server-connection channel: MQADMIN
8. Click Next.
9. Security settings — choose one:
· None — for test environments
· User ID and password — if CONNAUTH is enabled
· SSL/TLS — select cipher and point to your client truststore
10. Click Finish.
11. MQ Explorer will attempt to connect. On success, the queue manager icon turns green.
4.4 Common MQ Explorer Tasks
|
Task
|
Navigation Path
|
|
View queue depths
|
Queue Managers → QM_SERVER → Queues
|
|
Start/Stop a channel
|
Queue Managers → QM_SERVER → Channels → right-click channel
|
|
View channel status
|
Queue Managers → QM_SERVER → Channel Status
|
|
View error logs
|
Queue Managers → QM_SERVER → Error Logs
|
|
Test a connection
|
Queue Managers → right-click → Test Connection
|
|
Clear a queue
|
Queues → right-click queue → Clear Messages
|
|
Browse messages
|
Queues → right-click queue → Browse Messages
|
|
Run MQSC commands
|
Queue Managers → right-click QM → Run MQSC Commands
|
4.5 Troubleshooting MQ Explorer Connectivity
|
Symptom
|
Likely Cause
|
Resolution
|
|
`MQRC_HOST_NOT_AVAILABLE (2538)`
|
Network/firewall
|
Check `telnet <host> 1414` from Explorer machine
|
|
`MQRC_CHANNEL_NOT_AVAILABLE (2537)`
|
Channel not started or wrong name
|
Verify channel is RUNNING: `DISPLAY CHSTATUS(MQADMIN)`
|
|
`MQRC_NOT_AUTHORIZED (2035)`
|
Insufficient authority
|
Re-run `setmqaut` grants; check CHLAUTH rules
|
|
`MQRC_SSL_INITIALIZATION_ERROR (2393)`
|
TLS cert mismatch
|
Verify key store path and cipher on both ends
|
|
Grey queue manager icon
|
Connection lost
|
Right-click → Reconnect
|
5. IBM MQ Default Log Locations
5.1 Linux and AIX
|
Log Type
|
Path
|
|
Queue manager data directory
|
`/var/mqm/qmgrs/<QM_NAME>/`
|
|
Queue manager log files
|
`/var/mqm/log/<QM_NAME>/`
|
|
Queue manager configuration file
|
`/var/mqm/qmgrs/<QM_NAME>/qm.ini`
|
|
Queue manager error logs
|
`/var/mqm/qmgrs/<QM_NAME>/errors/`
|
|
IBM MQ installation system errors
|
`/var/mqm/errors/`
|
|
SYSTEM queue manager errors
|
`/var/mqm/qmgrs/@SYSTEM/errors/`
|
|
FFST (FDC) files
|
`/var/mqm/errors/`
|
|
MQ installation directory
|
`/opt/mqm/` (Linux) / `/usr/mqm/` (AIX)
|
|
Trace output directory
|
`/var/mqm/trace/`
|
5.2 Windows
|
IBM MQ Version
|
Program Binary Files
|
Data / Log Files
|
|
WMQ v7.0.1, v7.1, v7.5
|
`C:\Program Files (x86)\IBM\WebSphere MQ` or C:\Program Files (x86)\IBM\WebSphere MQ
|
<Install_Path>\qmgrs\<QM_NAME>\errors\
|
|
IBM MQ v8.0
|
`C:\Program Files\IBM\WebSphere MQ`
|
`C:\ProgramData\IBM\MQ`
|
|
IBM MQ v9.0–v9.4
|
`C:\Program Files\IBM\MQ`
|
`C:\ProgramData\IBM\MQ`
|
|
Log Type
|
Windows Path
|
|
Queue manager error logs
|
`C:\ProgramData\IBM\MQ\qmgrs\<QM_NAME>\errors\`
|
|
MQ installation errors
|
`C:\ProgramData\IBM\MQ\errors\`
|
|
Queue manager log files
|
`C:\ProgramData\IBM\MQ\log\<QM_NAME>\`
|
|
FFST (FDC) files
|
`C:\ProgramData\IBM\MQ\errors\`
|
|
Queue manager config
|
`C:\ProgramData\IBM\MQ\qmgrs\<QM_NAME>\qm.ini`
|
|
Trace output
|
`C:\ProgramData\IBM\MQ\trace\`
|
5.3 iSeries / AS400 (IBM i)
|
Log Type
|
Path / Object
|
|
MQ installation
|
`/QIBM/ProdData/mqm/`
|
|
Queue manager data
|
`/QIBM/UserData/mqm/qmgrs/<QM_NAME>/`
|
|
Queue manager error logs
|
`/QIBM/UserData/mqm/qmgrs/<QM_NAME>/errors/`
|
|
MQ system error logs
|
`/QIBM/UserData/mqm/errors/`
|
|
FFST (FDC) files
|
`/QIBM/UserData/mqm/errors/`
|
|
Queue manager log (journal)
|
`/QIBM/UserData/mqm/log/<QM_NAME>/`
|
|
System job logs
|
Use `DSPJOBLOG` in QMQM subsystem jobs
|
Useful IBM i MQ commands:
STRQMMQSC MQMNAME(<QM_NAME>) -- Start MQSC session
DSPJOB JOB(QMQM) -- Display MQ jobs
WRKACTJOB SBS(QMQM) -- Work with active MQ jobs
DSPMSGD MSGID(AMQ9999) MSGF(QMQMMSG) -- Display MQ message description
6. FFST (FDCs), AMQERRxx Logs, Known Issues, AMQ Diagnostic Messages and MQRC Reason Codes
6.1 Known Issues — FFST (FDC) and AMQERRxx Log Table
|
Log Type
|
Probe ID(s)
|
AMQ Error Code
|
Description & Likely Cause
|
|
FDC/AMQ
|
ZX005025
|
AMQ5008
|
Security exit program caused a resource problem — review exit program code and authority
|
|
FDC/AMQ
|
HL006005
|
AMQ6118
|
Delay in failover caused by external application holding MQ resources
|
|
FDC/AMQ
|
AL004003, HL006003, HL166091
|
AMQ6118, AMQ6125
|
Antivirus or backup software delayed Windows write operations, resulting in FDC and subsequent queue manager termination
|
|
FDC/AMQ
|
AD028000, AD004001
|
AMQ6119, AMQ6125
|
MQ retry-loop functions failed to open or create a file — check file permissions and disk space
|
|
FDC/AMQ
|
XC381010
|
AMQ6119
|
Channel failed to open/start due to a permission problem — check CHLAUTH and setmqaut grants
|
|
FDC/AMQ
|
AO084010
|
AMQ6125
|
Checkpoint processor (amqzllp0) received SIGSEGV — queue had buffers with non-zero write counts on NULL buffers; may indicate memory corruption
|
|
FDC/AMQ
|
AL047011
|
AMQ6125
|
Backup was running during checkpoint (alsCheckPointLoop) — schedule backups outside peak periods
|
|
FDC/AMQ
|
XC274145
|
AMQ6015
|
MQ Admin (MUSR_MQADMIN) authentication failed — domain controller unreachable or network issue
|
|
FDC/AMQ
|
XC381009
|
AMQ6119
|
Recent change to security exit program caused resource problem — review and revert the change
|
|
FDC/AMQ
|
XY334103
|
AMQ6119
|
Queue manager hung — application queue contains a very large number of messages; consider increasing MAXDEPTH or draining queue
|
|
FDC/AMQ
|
CO052000
|
AMQ9207
|
Transmission header received from NATed IP was incorrect for MQ data — check NAT/firewall header rewrite rules
|
|
FDC/AMQ
|
ZX005018
|
AMQ5009
|
System ran out of desktop heap (Windows) — increase `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\SubSystems` SharedSection
|
|
AMQ Log
|
N/A
|
AMQ9526
|
Message sequence number error for channel — reset channel sequence number with `RESET CHANNEL(<name>) SEQNUM(1)`
|
6.2 AMQ Message Number Series Quick Reference
|
AMQ Range
|
Category
|
|
AMQ4000–AMQ4999
|
Configuration and installation messages
|
|
AMQ5000–AMQ5999
|
Queue manager control and administration messages
|
|
AMQ6000–AMQ6999
|
Internal error / diagnostic messages (FDC-related)
|
|
AMQ7000–AMQ7999
|
Application / API messages
|
|
AMQ8000–AMQ8999
|
MQSC and command server messages
|
|
AMQ9000–AMQ9999
|
Channel, communication, and connectivity messages
|
6.3 Common MQRC Reason Codes Quick Reference
|
MQRC Code
|
Numeric
|
Meaning
|
Common Cause
|
|
MQRC_NONE
|
0
|
Success
|
—
|
|
MQRC_NOT_AUTHORIZED
|
2035
|
Not authorised
|
Missing OAM authority — run `setmqaut`
|
|
MQRC_UNKNOWN_OBJECT_NAME
|
2085
|
Queue/object not found
|
Object not defined or wrong QM
|
|
MQRC_Q_FULL
|
2053
|
Queue is full
|
`MAXDEPTH` exceeded — drain queue or increase depth
|
|
MQRC_CONNECTION_BROKEN
|
2009
|
Connection broken
|
Network interruption; channel ended abnormally
|
|
MQRC_HOST_NOT_AVAILABLE
|
2538
|
Host not available
|
Network/firewall blocking the port
|
|
MQRC_CHANNEL_NOT_AVAILABLE
|
2537
|
Channel unavailable
|
Channel stopped or CHLAUTH blocking
|
|
MQRC_SSL_INITIALIZATION_ERROR
|
2393
|
TLS init error
|
Key store missing, cipher mismatch, or expired certificate
|
|
MQRC_SECURITY_ERROR
|
2063
|
Security error
|
CONNAUTH failure; wrong credentials
|
|
MQRC_MSG_TOO_BIG_FOR_Q
|
2030
|
Message too big
|
Exceeds `MAXMSGL` on queue or QM
|
|
MQRC_PUT_INHIBITED
|
2051
|
Put inhibited
|
`INHIBIT` attribute set on queue
|
|
MQRC_GET_INHIBITED
|
2016
|
Get inhibited
|
`INHIBIT` attribute set on queue
|
|
MQRC_TRUNCATED_MSG_ACCEPTED
|
2079
|
Truncated message
|
`MAXMSGL` on client smaller than message
|
|
MQRC_RECONNECT_INCOMPATIBLE
|
2546
|
Reconnect incompatible
|
Client reconnect attempted after incompatible change
|
|
MQRC_HCONN_ERROR
|
2018
|
Bad connection handle
|
Application programming error
|
To look up any AMQ error or MQRC code from the command line:
# Look up an AMQ error
mqrc AMQ9526
# Look up an MQRC reason code
mqrc 2035
# On IBM i
DSPMSGD MSGID(AMQ9526) MSGF(QMQMMSG)
7. Guide for Analyzing Logs
7.1 Analyzing AMQERRxx Log Files
AMQ error log files are named AMQERR01.LOG, AMQERR02.LOG, AMQERR03.LOG (rotating). Each entry follows this format:
----- amqccisa.c : 903 --------------------------------------------------------
05/01/25 10:23:45 - Process(12345.1) User(mqm) Program(amqrmppa)
Host(linuxserver) Installation(Installation1)
VRMF(9.4.0.0) QMgr(QM1)
Time(2025-01-05T10:23:45.123Z)
ArithInsert1(2035) ArithInsert2(0)
CommentInsert1(Q.IN)
CommentInsert2(mquser)
CommentInsert3(SYSTEM.AUTH.DATA.QUEUE)
AMQ9557E: Queue manager authorization failed.
Analysis Steps:
1. Identify the severity: E = Error, W = Warning, I = Informational.
2. Note the AMQ number and look it up: mqrc AMQ9557.
3. Check ArithInsert fields — these carry numeric codes (e.g., MQRC reason code).
4. Check CommentInsert fields — these name the object, user, or channel involved.
5. Correlate with timestamps — match with application logs or system events at the same time.
6. Search for related entries above and below — a single problem typically produces multiple sequential messages.
Useful commands:
# Tail the active error log
tail -f /var/mqm/qmgrs/QM1/errors/AMQERR01.LOG
# Search for a specific error code
grep -i "AMQ9526" /var/mqm/qmgrs/QM1/errors/AMQERR01.LOG
# Count occurrences in the last 24 hours
find /var/mqm/qmgrs/QM1/errors/ -name "AMQERR*.LOG" \
-newer /tmp/24h_ago -exec grep -c "AMQ9526" {} +
# On Windows (PowerShell)
Select-String -Path "C:\ProgramData\IBM\MQ\qmgrs\QM1\errors\AMQERR01.LOG" -Pattern "AMQ9526"
7.2 Analyzing FFST (FDC) Files
FFST (First Failure Support Technology) files are produced when IBM MQ detects an internal error. File names follow the pattern AMQnnnnn.FDC.
Key fields in an FDC file:
|
Field
|
Description
|
|
`Probe ID`
|
Unique probe identifier for the failure point in MQ code (e.g., `XC381010`)
|
|
`Probe Description`
|
Text description of where in MQ the failure occurred
|
|
`Major ErrorCode`
|
Primary error classification
|
|
`Minor ErrorCode`
|
Secondary error classification
|
|
`QMgr Name`
|
Queue manager that triggered the FDC
|
|
`Function Stack`
|
Call stack at time of failure
|
|
`PID`
|
Process ID of the failing process
|
|
`Trace Data`
|
Low-level trace captured at failure time
|
Analysis Steps:
1. Open the FDC file in a text editor and locate the Probe ID.
2. Search IBM Support for the Probe ID at [IBM Support](https://www.ibm.com/support/).
3. Review the `Major ErrorCode` and `Minor ErrorCode` using mqrc <code>.
4. Examine the Function Stack to understand which MQ component was active.
5. Cross-reference the timestamp with AMQERRxx logs for the same queue manager.
6. Check for known APARs — search the IBM APAR database using the Probe ID.
7. Collect and escalate to IBM Support if no APAR match is found (attach the FDC file).
# Find all FDC files generated in the last 24 hours
find /var/mqm/errors/ -name "*.FDC" -mtime -1 -ls
# Extract Probe IDs from all FDC files
grep "Probe Id" /var/mqm/errors/*.FDC | sort | uniq -c | sort -rn
# View a specific FDC file
cat /var/mqm/errors/AMQ54321.FDC | less
8. Problem and CritSit Troubleshooting — Guided Steps
8.1 Queue Manager Not Starting
Symptoms: strmqm returns an error; dspmq shows the queue manager is STOPPED or STARTING.
Troubleshooting steps:
1. Check current status: dspmq -m QM1
2. Review error logs immediately after the failed start:
tail -100 /var/mqm/qmgrs/QM1/errors/AMQERR01.LOG
tail -100 /var/mqm/errors/AMQERR01.LOG
3. Check for FFST files generated at the time of failure:
ls -lt /var/mqm/errors/*.FDC | head -5
4. Verify the OS user has mqm group membership:
id mqm
groups $USER
5. Check for stale IPC resources (Linux/AIX):
ipcs -a | grep mqm
# If stale semaphores/shared memory exist, remove with:
ipcrm -s <semid>
ipcrm -m <shmid>
6. Verify disk space on data and log directories:
df -h /var/mqm/
7. Check file permissions on the log directory:
ls -la /var/mqm/log/QM1/
chown -R mqm:mqm /var/mqm/log/QM1/
8. Attempt a controlled restart: strmqm -x QM1
8.2 Messages Queued Up or Jammed
Symptoms: Queue depth rising; consumers not processing; channels in RETRYING or STOPPED state.
Troubleshooting steps:
1. Check channel status:
DISPLAY CHSTATUS(*) WHERE(STATUS NE INACTIVE)
DISPLAY CHSTATUS(*) ALL
2. Check listener status:
DISPLAY LSSTATUS(*)
3. Check transmission queue depth:
DISPLAY QLOCAL(*) WHERE(USAGE EQ XMITQ) CURDEPTH MAXDEPTH
4. Check for network connectivity to the remote end:
ping <remote_host>
telnet <remote_host> 1414
5. Check AMQERRxx logs for AMQ9526 (sequence number errors) or AMQ9999 channel errors.
6. If sequence numbers are out of sync, reset and restart:
STOP CHANNEL(QM1.TO.QM2)
RESET CHANNEL(QM1.TO.QM2) SEQNUM(1)
START CHANNEL(QM1.TO.QM2)
7. Check if MAXCHANNELS or MAXACTIVECHANNELS is exhausted:
1. Command in your terminal: echo "dis chs(*)" | runmqsc YOUR_QM_NAME | grep RUNNING | wc -l
2. Display all active connections and their associated channels: echo "DIS CONN(*) CHANNEL CONNAME" | runmqsc YOUR_QM_NAME
3. Check the queue manager error log file (AMQERR01.LOG) for the specific message:
AMQ9513E: Maximum number of channels reached.
8.3 Queue Depth Frequently Getting Full
Symptoms: MQRC_Q_FULL (2053) errors in application logs; CURDEPTH = MAXDEPTH.
Troubleshooting steps:
1. Display queue depth and consumer counts:
DISPLAY QLOCAL(Q.IN) CURDEPTH MAXDEPTH IPPROCS OPPROCS
2. Verify destination listener and channels are running:
DISPLAY CHSTATUS(QM1.TO.QM2) STATUS
3. Check whether the consuming application is calling MQDISC for every MQOPEN:
· If OPPROCS is abnormally high, applications may be leaving connections open without consuming.
4. Temporarily increase MAXDEPTH to relieve pressure (not a permanent fix):
ALTER QLOCAL(Q.IN) MAXDEPTH(999999999)
5. Consider enabling dead-letter queue routing for overflow:
ALTER QMGR DEADQ(SYSTEM.DEAD.LETTER.QUEUE)
6. Run an MQ trace during the problem to capture application MQPUT/MQGET calls:
strmqtrc -m QM1 -t all
# reproduce the problem
endmqtrc -m QM1
8.4 Channel Down and Not Starting
Symptoms: DISPLAY CHSTATUS shows STOPPED, RETRYING, or INACTIVE; applications cannot connect.
Troubleshooting steps:
1. Verify channel configuration:
DISPLAY CHANNEL(QM1.TO.QM2) ALL
2. Check CHLAUTH rules that may be blocking:
DISPLAY CHLAUTH(*) ALL
3. Test network connectivity:
ping <remote_host>
telnet <remote_host> 1414
4. Check firewall rules on both ends — ensure port 1414 (or the configured port) is open bidirectionally.
5. Review AMQERRxx on both ends of the channel for AMQ9208, AMQ9999, or AMQ9526.
6. Check TLS certificate validity if SSLCIPH is configured:
runmqckm -cert -list -db /var/mqm/ssl/key.kdb -pw changeit
7. Restart the channel:
START CHANNEL(QM1.TO.QM2)
8.5 Application Getting MQRC_NOT_AUTHORIZED (2035)
1. Identify the user and object in the AMQERRxx log (CommentInsert fields).
2. Check current authority:
dspmqaut -m QM1 -t q -n Q.IN -p appuser
3. Grant the required authority:
setmqaut -m QM1 -t q -n Q.IN -p appuser +put +get +browse +inq +dsp
setmqaut -m QM1 -t qmgr -p appuser +connect +inq
4. Check CHLAUTH rules — even with OAM grants, CHLAUTH can block the connection.
5. Refresh security:
REFRESH SECURITY TYPE(AUTHSERV)
8.6 Dead-Letter Queue Growing
1. Check DLQ depth:
DISPLAY QLOCAL(SYSTEM.DEAD.LETTER.QUEUE) CURDEPTH
2. Browse messages to identify root cause:
/opt/mqm/samp/bin/amqsbcg SYSTEM.DEAD.LETTER.QUEUE QM1
3. Check dead-letter header (MQDLH) for the Reason field — this is an MQRC code.
4. Fix the root-cause object/authority/configuration.
5. Re-route messages using the DLQ handler:
runmqdlq SYSTEM.DEAD.LETTER.QUEUE QM1 < /opt/mq/conf/dlqrules.txt
9. Best Practice Guide and Reference Links
9.1 Configuration Best Practices
|
Best Practice
|
Details
|
|
Enable CHLAUTH
|
Always run `ALTER QMGR CHLAUTH(ENABLED)` in production to block unauthorised connections
|
|
Explicit MCAUSER
|
Never use a blank `MCAUSER('')` on production SVRCONN channels; map to a least-privilege OS user
|
|
TLS everywhere
|
Configure `SSLCIPH` on all external-facing channels; use TLS 1.2 or higher
|
|
Dead-Letter Queue
|
Always define and enable a DLQ: `ALTER QMGR DEADQ(SYSTEM.DEAD.LETTER.QUEUE)`
|
|
Listener CONTROL
|
Set `CONTROL(QMGR)` on listeners so they start/stop with the queue manager
|
|
Log sizing
|
Size primary logs to accommodate at least 1 hour of peak traffic without secondary expansion
|
|
Separate log and data disks
|
Put MQ log files on a separate, fast disk from data files
|
|
Cluster design
|
Use Exactly of two full-repository queue managers per cluster
|
|
Max message length
|
Set an explicit `MAXMSGL` on queues and the QM to prevent runaway large messages
|
|
Regular fix packs
|
Stay within one fix pack of the latest cumulative fix for your version
|
9.2 Performance Best Practices
|
Best Practice
|
Details
|
|
Persistent vs non-persistent
|
Use non-persistent messages for non-critical, high-throughput data to reduce log I/O
|
|
Batch commit
|
Use `SYNCPOINT` with batch commits (`MQCMIT` every N messages) rather than per-message commits
|
|
Connection pooling
|
Reuse connections; avoid connecting and disconnecting per transaction
|
|
Avoid deep queues
|
A queue consistently near its `MAXDEPTH` indicates a processing bottleneck — investigate consumers
|
|
FASTPATH
|
For intra-process messaging, consider `BINDINGS` transport for lower latency
|
|
Reduce MQGET polling
|
Use `MQGET` with `MQGMO_WAIT` and a wait interval rather than a tight polling loop
|
9.3 Security Best Practices
|
Best Practice
|
Details
|
|
Principle of least privilege
|
Grant only the specific authorities each application needs (not blanket `+all`)
|
|
Restrict MQSC access
|
Limit which OS users can run `runmqsc`; use OAM authority on `SYSTEM.ADMIN.COMMAND.QUEUE`
|
|
Audit authority records
|
Periodically run `dmpmqaut -m QM1 -t q -n '*' > /tmp/auth_audit.txt` and review
|
|
Use CONNAUTH
|
Enable `CONNAUTH` with `IDPWOS` or LDAP for authenticated application connections
|
|
Certificate rotation
|
Renew TLS certificates before expiry; use `CERTLABL` for smooth rotation
|
9.4 Updated Reference Links (IBM MQ 9.4.x)
10. Preliminary Checks for the Cause of a Problem
Before raising a PMR/support case or escalating to a CritSit, work through these preliminary questions systematically:
10.1 Initial Triage Checklist
· Has IBM MQ run successfully before in this configuration?
— If not, this is likely a setup/configuration problem rather than a defect.
· Are there any error messages in AMQERRxx or FDC files?
— Always collect these first. They are your primary evidence.
· Have any changes been made since the last successful run?
— Configuration changes, OS patches, fix packs, network changes, firewall rule changes.
· Does the problem affect all queue managers or only specific ones?
— A single QM problem points to configuration; a systemic issue may point to infrastructure.
· Does the problem affect specific channels, queues, or applications?
— Narrow the scope as quickly as possible.
· Is the problem intermittent or consistent and reproducible?
— Consistent problems are easier to diagnose; intermittent problems may need trace capture.
· Have any OS or system patches been applied recently?
— OS patches (especially security patches) can affect file permissions, TLS, and network stacks.
· Is the system under unusual load?
— CPU, memory, or disk saturation can cause MQ timeouts and apparent failures.
· Are any third-party tools active?
— Antivirus real-time scanning, backup agents, and monitoring agents are common culprits.
· Is the problem isolated to a specific time of day?
— Batch jobs, scheduled tasks, and backup windows are common triggers.
10.2 What to Collect Before Calling IBM Support
1. Output of dspmqver (version and fix pack level)
2. Output of dspmq -x (all queue managers and status)
3. Relevant AMQERRxx log snippets (at least 30 minutes before and after the problem)
4. All FDC files from /var/mqm/errors/ generated around the problem time
5. Output of DISPLAY QMGR ALL from runmqsc
6. Output of DISPLAY CHSTATUS(*) ALL (if channel-related)
7. OS-level logs: syslog/journalctl on Linux, Event Viewer on Windows
8. A clear description of the problem: what changed, when it started, and the business impact
11. How to Gather IBM MQ Trace on Different Platforms
Important: MQ trace generates large volumes of data very quickly. Always use size-limited (sliced) traces in production. A trace file of 10–20 MB per slice is recommended.
11.1 Trace on Linux and AIX
Start a Sliced Trace (10 MB slices)
# Start trace for a specific queue manager — 10 MB per file
strmqtrc -m QM1 -t all -p 10
# Start trace for all queue managers
strmqtrc -t all -p 10
# Start trace for a specific process ID
strmqtrc -m QM1 -t all -p 10 -i <PID>
# Start trace capturing only API calls (less volume)
strmqtrc -m QM1 -t api -p 10
# Start trace with 20 MB slices
strmqtrc -m QM1 -t all -p 20
Trace type options:
|
Option
|
Description
|
|
`-t all`
|
Full trace (all components)
|
|
`-t api`
|
API calls only (MQOPEN, MQPUT, MQGET, etc.)
|
|
`-t comms`
|
Communications/channel trace
|
|
`-t chl`
|
Channel-specific trace
|
|
`-t ssl`
|
TLS/SSL trace
|
|
`-t detail`
|
Detailed level (more verbose than `all`)
|
Reproduce the Problem, Then Stop Trace
# Stop trace for queue manager
endmqtrc -m QM1
# Stop all traces
endmqtrc -a
Format the Trace (produces human-readable output)
# Format binary trace files
dspmqtrc /var/mqm/trace/AMQ*.TRC
# Output to a file
dspmqtrc /var/mqm/trace/AMQ*.TRC > /tmp/QM1_trace_formatted.txt
Trace files location: /var/mqm/trace/
11.2 Trace on Windows
:: Start trace — 10 MB slices
strmqtrc -m QM1 -t all -p 10
:: Reproduce the problem, then stop
endmqtrc -m QM1
:: Format trace
dspmqtrc "C:\ProgramData\IBM\MQ\trace\AMQ*.TRC"
:: Output to file
dspmqtrc "C:\ProgramData\IBM\MQ\trace\AMQ*.TRC" > C:\Temp\QM1_trace.txt
Trace files location: C:\ProgramData\IBM\MQ\trace\
11.3 Trace on IBM i (AS400 / iSeries)
:: Start MQ trace on IBM i
STRMQMTRC MQMNAME(QM1) TRCTYPE(*ALL) MAXFILE(10)
:: Stop trace
ENDMQMTRC MQMNAME(QM1)
:: Format trace
DSPMQMTRC MQMNAME(QM1)
Trace files location: /QIBM/UserData/mqm/trace/
11.4 Application-Level Trace (Client Trace)
For IBM MQ client applications (Java, C, .NET):
# Enable client trace via environment variable
export MQCLNTCF=/opt/mqm/conf/mqclient.ini
# In mqclient.ini, add:
# [Trace]
# Output=FILE
# Path=/tmp/mqclienttrace/
# MaxFileSize=20
# TraceLevel=ALL
11.5 Java / JMS Trace
# Enable JMS/Java trace
export MQJMS_TRACE_LEVEL=BASE
export MQJMS_TRACE_DIR=/tmp/mqjmstrace/
# Or programmatically via JVM properties
java -DMQJMS_TRACE_LEVEL=DETAIL \
-DMQJMS_TRACE_DIR=/tmp/mqjmstrace/ \
-jar MyApp.jar
11.6 Gathering Trace Best Practices
· Always reproduce the problem with the trace running — do not start trace after the problem has occurred.
· Use `-p <size_MB>` to limit file size; without this, a trace can fill the disk.
· Stop trace promptly after reproducing — never leave production trace running indefinitely.
· Collect the AMQERRxx logs from the same time period to correlate with trace.
· Compress trace files before sending to IBM Support: tar -czvf QM1_trace.tar.gz /var/mqm/trace/.
12. Backup and Recovery Using Scripts
12.1 Full Queue Manager Configuration Backup
#!/bin/bash
# Script: mq_backup_config.sh
# Purpose: Backup IBM MQ queue manager configuration to MQSC script
# Usage: ./mq_backup_config.sh <QMGR_NAME> <BACKUP_DIR>
QMGR=${1:-QM1}
BACKUP_DIR=${2:-/backup/mq}
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="${BACKUP_DIR}/${QMGR}_config_${TIMESTAMP}.mqsc"
mkdir -p "$BACKUP_DIR"
echo "Starting backup of ${QMGR} configuration..."
strmqm "$QMGR" 2>/dev/null || true
# Dump full queue manager configuration (MQ 9.x and later)
dmpmqcfg -m "$QMGR" -t all -x all -a > "$BACKUP_FILE"
echo "Configuration backed up to: $BACKUP_FILE"
echo "Lines written: $(wc -l < "$BACKUP_FILE")"
12.2 Message Backup (dmpmqmsg)
#!/bin/bash
# Script: mq_backup_messages.sh
# Purpose: Dump messages from a queue to a file for backup
QMGR=${1:-QM1}
QUEUE=${2:-Q.IN}
BACKUP_DIR=${3:-/backup/mq/messages}
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
MSG_FILE="${BACKUP_DIR}/${QMGR}_${QUEUE}_${TIMESTAMP}.mqmsg"
mkdir -p "$BACKUP_DIR"
# Dump messages from queue to file (non-destructive browse)
dmpmqmsg -m "$QMGR" -i "$QUEUE" -f "$MSG_FILE"
echo "Messages backed up to: $MSG_FILE"
12.3 Full Queue Manager Recovery — Step-by-Step
Step 1: Ensure the old queue manager is stopped and deleted (if on the same host)
endmqm -p QM1 2>/dev/null || true
dltmqm QM1
Step 2: Re-create the Queue Manager
# Basic re-creation
crtmqm QM1
# Production re-creation with explicit paths (match original sizing)
crtmqm -lf 4096 -lp 5 -ls 7 \
-ld /MQ/MQLogs/ \
-md /MQ/MQData/ \
-p 1414 \
QM1
Step 3: Start the Queue Manager
strmqm QM1
Step 4: Apply the Configuration Backup
runmqsc QM1 < /backup/mq/QM1_config_20250101_120000.mqsc
Step 5: Restore Messages (if message backup was taken)
# Restore messages from file to queue
dmpmqmsg -m QM1 -o Q.IN -f /backup/mq/messages/QM1_Q.IN_20250101_120000.mqmsg
# Copy messages from one queue to another
dmpmqmsg -m QM1 -i Q.IN -o Q.IN.RESTORE
Step 6: Verify the Recovery
runmqsc QM1 << 'EOF'
DISPLAY QMGR ALL
DISPLAY QLOCAL(*) CURDEPTH
DISPLAY CHANNEL(*) CHLTYPE
DISPLAY LISTENER(*) ALL
END
EOF
# Start all listeners and sender channels
runmqsc QM1 << 'EOF'
START LISTENER(LISTENER.TCP)
START CHANNEL(QM1.TO.QM2)
END
EOF
12.4 Scheduled Backup Script (Cron — Linux/AIX)
# Add to crontab: daily backup at 2:00 AM
# crontab -e
# 0 2 * * * /opt/scripts/mq_backup_config.sh QM1 /backup/mq >> /var/log/mq_backup.log 2>&1
#!/bin/bash
# Script: mq_scheduled_backup.sh
# Backs up all running queue managers
BACKUP_DIR="/backup/mq/$(date +%Y%m%d)"
mkdir -p "$BACKUP_DIR"
for QMGR in $(dspmq | grep -oP 'QMNAME\(\K[^)]+'); do
STATUS=$(dspmq -m "$QMGR" | grep -oP 'STATUS\(\K[^)]+')
if [[ "$STATUS" == "Running" ]]; then
dmpmqcfg -m "$QMGR" -t all -x all -a > "${BACKUP_DIR}/${QMGR}_${QMGR}_config.mqsc"
echo "$(date): Backed up $QMGR" >> /var/log/mq_backup.log
fi
done
# Retain only the last 30 days of backups
find /backup/mq/ -maxdepth 1 -type d -mtime +30 -exec rm -rf {} +
12.5 Windows — PowerShell Backup Script
# Script: mq_backup_config.ps1
# Usage: .\mq_backup_config.ps1 -QMgrName QM1 -BackupDir C:\MQBackup
param(
[string]$QMgrName = "QM1",
[string]$BackupDir = "C:\MQBackup"
)
$timestamp = Get-Date -Format "yyyyMMdd_HHmmss"
$backupFile = "$BackupDir\${QMgrName}_config_${timestamp}.mqsc"
New-Item -ItemType Directory -Force -Path $BackupDir | Out-Null
& dmpmqcfg -m $QMgrName -t all -x all -a | Out-File -FilePath $backupFile -Encoding UTF8
Write-Host "Configuration backed up to: $backupFile"
Write-Host "Lines written: $((Get-Content $backupFile).Count)"
13. Summary
This document provides a comprehensive reference and operational guide for IBM MQ 9.4.x administration, troubleshooting, and critical situation management.
Key themes covered:
|
Topic
|
Summary
|
|
Command Reference
|
Full IBM MQ control commands (`crtmqm`, `strmqm`, `endmqm`, `dspmq`, `dspmqver`, etc.) updated for v9.4.x, including listener, security, and fix pack management
|
|
MQSC Reference
|
Complete MQSC verb coverage for queues, channels, listeners, CHLAUTH, AUTHINFO, topics, services, and cluster management — aligned with IBM MQ 9.4.x capabilities
|
|
Cross-Platform Client
|
Detailed guided steps for IBM MQ Server–to–Client connectivity on Windows and Linux in both directions, including TLS configuration and CCDT usage
|
|
MQ Explorer
|
End-to-end guided setup for remote administration through MQ Explorer, including CHLAUTH, `setmqaut` grants, and connection troubleshooting
|
|
Log Locations
|
Definitive log path reference for Linux, AIX, Windows (v7–v9.4), and iSeries AS400
|
|
Diagnostics
|
Expanded FFST/FDC table, AMQ message range guide, and MQRC reason code quick reference covering the most commonly encountered codes
|
|
Log Analysis
|
Structured methodology for reading AMQERRxx and FDC files, including command-line analysis tools
|
|
Troubleshooting
|
Guided step-by-step procedures for the six most common IBM MQ CritSit scenarios
|
|
Best Practices
|
Configuration, performance, and security best practices with updated IBM MQ 9.4.x reference URLs
|
|
Preliminary Checks
|
Structured triage checklist and pre-support evidence collection guide
|
|
Trace Gathering
|
Multi-platform trace guide (Linux, AIX, Windows, IBM i, Client, JMS) with size-sliced trace instructions
|
|
Backup & Recovery
|
Production-ready shell scripts and PowerShell scripts for configuration backup, message backup, and full queue manager recovery
|
Recommended workflow for any IBM MQ problem:
1. Check AMQERRxx logs → 2. Check FDC files → 3. Use preliminary checklist
↓
4. Follow the relevant troubleshooting section
↓
5. If unresolved: gather trace (sliced), collect evidence, open IBM PMR/Case
14. Bibliography and References
IBM Documentation (IBM MQ 9.4.x)
1. IBM MQ 9.4 Product Documentation: https://www.ibm.com/docs/en/ibm-mq/9.4
2. IBM MQ 9.4 — MQSC Command Reference: https://www.ibm.com/docs/en/ibm-mq/9.4?topic=reference-mqsc-commands
3. IBM MQ 9.4 — Control Commands Reference: https://www.ibm.com/docs/en/ibm-mq/9.4?topic=reference-control-commands
4. IBM MQ 9.4 — API Completion and Reason Codes (MQRC): https://www.ibm.com/docs/en/ibm-mq/9.4?topic=reference-api-completion-reason-codes
5. IBM MQ 9.4 — Troubleshooting and Support: https://www.ibm.com/docs/en/ibm-mq/9.4?topic=mq-troubleshooting-diagnostic-information
6. IBM MQ 9.4 — Security: https://www.ibm.com/docs/en/ibm-mq/9.4?topic=mq-security
7. IBM MQ 9.4 — Channel Authentication Records (CHLAUTH): https://www.ibm.com/docs/en/ibm-mq/9.4?topic=authentication-channel-records
8. IBM MQ 9.4 — Using TLS Security: https://www.ibm.com/docs/en/ibm-mq/9.4?topic=tls-using-security-in-mq
9. IBM MQ 9.4 — Performance: https://www.ibm.com/docs/en/ibm-mq/9.4?topic=mq-performance
10. IBM MQ 9.4 — IBM MQ on IBM i: https://www.ibm.com/docs/en/ibm-mq/9.4?topic=mq-administering-i
11. IBM MQ — Fix Central Download (latest fix packs): https://www.ibm.com/support/fixcentral/swg/selectFixes?product=ibm/WebSphere/WebSphere+MQ
IBM Technotes and APARs
12. IBM Support — MQ FixPack List : https://www.ibm.com/support/pages/fix-list-ibm-mq-version-94-lts
13. IBM MQ FAQ — Frequently Asked Questions: https://www.ibm.com/support/pages/ibm-mq-faq-long-term-support-and-continuous-delivery-releases
14. IBM MQ — Gathering IBM MQ Trace: https://www.ibm.com/docs/en/ibm-mq/9.4?topic=information-tracing
15. IBM MQ — First Failure Support Technology (FFST): https://www.ibm.com/docs/en/ibm-mq/9.4?topic=information-first-failure-support-technology-ffst
Community and Additional Resources
16. IBM MQ Community — IBM Developer: https://community.ibm.com/community/user/integration/communities/community-home?CommunityKey=183ec850-4947-49c8-9a2e-8e7c7fc46c64
17. IBM Redbooks — IBM MQ Best Practices: https://www.redbooks.ibm.com/ *(search: "IBM MQ")*
18. IBM MQ, IBM MQ for z/OS and IBM MQ Appliance firmware 9.4.5 Continuous Delivery releases are available: https://community.ibm.com/community/user/blogs/ian-harwood1/2026/01/30/mq945ga