Generating IBM MQ trace on IBM i

Answer

• IBM MQ for IBM i Server and Client Installations
• Tracing using the IBM i Command Line
• Tracing using the IBM i Qshell
• Additional Information

IBM MQ for IBM i Server and Client Installations

IBM MQ V8.0 and WebSphere MQ V7.1 for IBM i provide a native client installation. An MQ server installation on IBM i may include the client, or you may choose to install a stand-alone client on IBM i with no MQ server functionality.

Tracing is nearly identical between server and client installations. At WebSphere MQ V7.1 and later, both the server and client support tracing at the IBM i command line by calling the QMQM/STRMQTRC and QMQM/ENDMQTRC programs, and both support tracing at the IBM i Qshell using the STRMQTRC, ENDMQTRC and DSPMQTRC commands.

However, only the MQ server for IBM i provides the TRCMQM command. Furthermore, a stand-alone client does not support the '-m' option on either the start or end trace commands, since there are no queue managers. The runmqras '-qmlist' option is not valid on a stand-alone client for the same reason.

Back to top

Tracing using the IBM i Command Line

The TRCMQM command is the most commonly used method, and is available if you have an MQ server installation on IBM i. If you have an MQ client on IBM i you must use the STRMQTRC, ENDMQTRC and DSPMQTRC programs instead.

1. Before starting a new trace, clean up any old files on your system.



2. Start tracing using either the TRCMQM command, which is available for full MQ server installations, or if you are running WebSphere MQ V7.1 or later, by calling the QMQM/STRMQTRC program which is available in both MQ client and server installations. You can enter the either command manually, as shown in the examples below. Alternatively, you can type TRCMQM and press F4 followed by F9 to enable tracing using the TRCMQM panel:



The TRCMQM panel




Starting a default detail trace


===> TRCMQM SET(*ON)

Alternatively (MQ V7.1 and later only):

===> CALL PGM(QMQM/STRMQTRC)



Starting a default detail trace of queue manager QMA


===> TRCMQM SET(*ON) MQMNAME(QMA)

Alternatively (MQ V7.1 and later only):

===> CALL PGM(QMQM/STRMQTRC) PARM('-m' 'QMA')



Starting a default detail trace of queue manager QMB with no message data included




Prior to WebSphere MQ fix packs 7.0.1.13 and 7.1.0.6, the TRCMQM option DATASIZE(*NONE) may trace up to 128 bytes of message data. Upgrade your fix pack level if you need to exclude all message data, or if you are running WebSphere MQ V7.1 or later, call the STRMQTRC program rather than TRCMQM to exclude all message data.

===> TRCMQM SET(*ON) MQMNAME(QMB) DATASIZE(*NONE)

Alternatively (MQ V7.1 and later only):

===> CALL PGM(QMQM/STRMQTRC) PARM('-m' 'QMB' '-d' '0')



Starting an API trace of jobs named AMQSPUT with all data


===> TRCMQM SET(*ON) TRCTYPE(*API) JOB(AMQSPUT) DATASIZE(*ALL)

Alternatively (MQ V7.1 and later only):

===> CALL PGM(QMQM/STRMQTRC) PARM('-t' 'api' '-p' 'AMQSPUT' '-d' 'all')



Starting a high detail early trace with files that wrap at 16MB


===> TRCMQM SET(*ON) TRCEARLY(*YES) TRCLEVEL(*DETAIL) MAXSTG(16)

Alternatively (MQ V7.1 and later only):

===> CALL PGM(QMQM/STRMQTRC) PARM('-e' '-t' 'all' '-t' 'detail' '-l' '16')




3. Reproduce the problem while tracing is active, making every attempt to keep the trace as short as possible. MQ V7.0 and later provides the following commands to check the trace status:



Checking the trace status


===> TRCMQM SET(*STS)
===> WRKSPLF SELECT(QMQM)

Use option 5 to view the TRCMQM spool file, which contains the trace status. Alternatively, if you are running WebSphere MQ V7.1 or later you can run:

===> CALL PGM(QMQM/STRMQTRC) PARM('-s')




4. As soon as the problem has occurred, stop tracing immediately! If you wait to stop the trace, the data IBM Support needs may be lost or overwritten. Stop tracing by calling the QMQM/ENDMQTRC program, or if you have an MQ server installation, you may instead use the TRCMQM command instead. Alternatively, you can enter TRCMQM and press F4 followed by F9 to disable tracing using the TRCMQM panel.



Stopping all traces


===> CALL PGM(QMQM/ENDMQTRC) PARM('-a')

There is no equivalent in the TRCMQM command.



Stopping a default detail trace


===> TRCMQM SET(*OFF)

Alternatively (MQ V7.1 and later only):

===> CALL PGM(QMQM/ENDMQTRC)



Stopping a trace of queue manager QMA


===> TRCMQM SET(*OFF) MQMNAME(QMA)

Alternatively (MQ V7.1 and later only):

===> CALL PGM(QMQM/ENDMQTRC) PARM('-m' 'QMA')



Stopping a trace of jobs named AMQSPUT


===> TRCMQM SET(*OFF) JOB(AMQSPUT)

Alternatively (MQ V7.1 and later only):

===> CALL PGM(QMQM/ENDMQTRC) PARM('-p' 'AMQSPUT')



Stopping an early trace


===> TRCMQM SET(*OFF) TRCEARLY(*YES)

Alternatively (MQ V7.1 and later only):

===> CALL PGM(QMQM/ENDMQTRC) PARM('-e')





5. The trace files generated by IBM MQ are binary, and must be formatted before they can be read. You can send the binary traces to IBM, or you can format them at the Qshell at a time when your system is not under heavy load. If you format the traces yourself, delete the binary trace files before sending your files to IBM:



Deleting IBM MQ binary trace files


===> RMVLNK OBJLNK('/QIBM/UserData/mqm/trace/AMQ*.?.TR?')




6. IBM MQ V8.0, WebSphere MQ V7.1.0.1 or later and V7.0.1.8 or later provide the runmqras command to collect your MQ traces and other data, but it must be run at the Qshell using the instructions below rather than at the IBM i command line. If you are running an older version of WebSphere MQ, create a save file containing all the traces. For example, if your IBM Problem Management Record is 12345,67R,890 you might run:



Creating a save file with traces


===> CRTSAVF FILE(QGPL/P12345TRC) TEXT('Save file for PMR P12345,67R,890')
===> SAV DEV('/QSYS.LIB/QGPL.LIB/P12345TRC.file') OBJ(('/QIBM/UserData/mqm/trace' *INCLUDE)) SAVACT(YES) DTACPR(*HIGH)




7. Clean up the trace directory to reclaim space and also to make sure you are ready to generate new traces in future, if necessary. For example:



Cleaning up the trace directory at the Command Line


===> RMVLNK OBJLNK('/QIBM/UserData/mqm/trace/AMQ*.*')

Back to top

Tracing using the IBM i Qshell

To use the IBM Qshell, type STRQSH at the IBM i command line. You can exit and return to the IBM Command Line at any time by pressing F3.


You can add the IBM MQ directories /QSYS.LIB/QMQM.LIB and /QIBM/ProdData/mqm/bin to your PATH in order to avoid typing the full path to commands line STRMQTRC.PGM and runmqras. The examples below give the full path names for all commands, but you will not need to type them out if you update your PATH:

Adding IBM MQ directories to the Qshell PATH


export PATH="$PATH:/QSYS.LIB/QMQM.LIB:/QIBM/ProdData/mqm/bin"

1. Before starting a new trace, clean up any old files on your system.



2. Start tracing by calling running the STRMQTRC program, for example:



Starting a default detail trace


===> /QSYS.LIB/QMQM.LIB/STRMQTRC.PGM



Starting a default detail trace of queue manager QMA


===> /QSYS.LIB/QMQM.LIB/STRMQTRC.PGM -m QMA



Starting a default detail trace of queue manager QMB with no message data included


===> /QSYS.LIB/QMQM.LIB/STRMQTRC.PGM -m QMB -d 0



Starting an API trace of jobs named AMQSPUT with all data


===> /QSYS.LIB/QMQM.LIB/STRMQTRC.PGM -t api -p AMQSPUT -d all



Starting a high detail early trace with files that wrap at 16MB


===> /QSYS.LIB/QMQM.LIB/STRMQTRC.PGM -e -t all -t detail -l 16




3. Reproduce the problem while tracing is active, making every attempt to keep the trace as short as possible. IBM MQ V8.0 and WebSphere MQ V7.0 and later provide the following command to check the trace status:



Checking the trace status


===> /QSYS.LIB/QMQM.LIB/STRMQTRC.PGM -s




4. As soon as the problem has occurred, stop tracing immediately! If you wait to stop the trace, the data IBM Support needs may be lost or overwritten. Stop tracing by running the ENDMQTRC program, for example:



Stopping all traces


===> /QSYS.LIB/QMQM.LIB/ENDMQTRC.PGM -a



Stopping a default detail trace


===> /QSYS.LIB/QMQM.LIB/ENDMQTRC.PGM



Stopping a trace of queue manager QMA


===> /QSYS.LIB/QMQM.LIB/ENDMQTRC.PGM -m QMA



Stopping a trace of jobs named AMQSPUT


===> /QSYS.LIB/QMQM.LIB/ENDMQTRC.PGM -p AMQSPUT



Stopping an early trace


===> /QSYS.LIB/QMQM.LIB/STRMQTRC.PGM -e



5. The trace files generated by IBM MQ are binary, and must be formatted before they can be read. The binary trace files are named like AMQ*.TRC, and if you started a wrapping trace, some may also be named like AMQ*.TRS. You can send the binary traces to IBM, or you can format them by running the DSPMQTRC program at a time when your system is not under heavy load. If you format the MQ traces, delete the binary files before sending the traces to IBM:



Formatting IBM MQ trace files and deleting the binary traces


===> cd /QIBM/UserData/mqm/trace
===> /QSYS.LIB/QMQM.LIB/DSPMQTRC.PGM AMQ*.TR?
===> rm -f AMQ*.?.TR?





6. IBM MQ V8.0, WebSphere MQ V7.1.0.1 or later and V7.0.1.8 or later provide the runmqras command to collect your MQ traces and other data by specifying the "trace" section name. If the traces are very large, you may need to use the "-workdirectory" option to package the files in a directory with plenty of free space. If you are running an older version of WebSphere MQ, create a save file at the IBM command line using the instructions given above. Otherwise, run the following command to collect data about queue manager QMA for your IBM Problem Management Record 12345,67R,890 for example, but recall that client-only installations will not use the -qmlist option:



Using runmqras to collect IBM MQ traces and other data


===> /QIBM/ProdData/mqm/bin/runmqras -section trace,defs,cluster -pmrno 12345,67R,890 -qmlist QMA





7. Clean up the trace directory to reclaim space and also to make sure you are ready to generate new traces in future, if necessary. For example:



Cleaning up the trace directory


===> cd /QIBM/UserData/mqm/trace
===> rm -f AMQ*.*

Back to top

Additional Information

• Using runmqras to collect data from IBM MQ V8.0, WebSphere MQ V7.1.0.1 or later and V7.0.1.8 or later
• Manually packaging IBM MQ data to send to IBM
• Cleaning up IBM MQ files