IBM Support

MH06: WebSphere MQ - Trace Tools



This SupportPac provides simple command line tools (mqtrcfrmt, mqoptions, and mqapitrcstats) to aid in using MQ traces.

Download Description

The tools provided in this SupportPac aid in formatting MQ data structures and fields into a more human-readable format. The mqtrcfrmt tool takes a distributed MQ trace as input and writes out as output the trace file contents but with MQ data structures and fields (i.e. msgdesc, objdesc, reason code) expanded into human-readable lines that show the individual data fields and also what constants the numerical values represent.

The mqoptions tools take the numerical value of an MQ option field (i.e. GMO) and display the MQ constant values (i.e. MQGMO_WAIT) that the numerical value represents.

The mqapitrcstats tool produces a performance statistics report from the trace.

Possible Uses:
Aid for reading MQ traces.
Aid for converting MQ options numerical values to their constant values.
Aid for getting performance statistics reports from distributed trace.
Skill Level Required:
This SupportPac requires a working knowledge of WebSphere MQ administration.

New in this Release:


  • Fixed issue with message buffer functionality losing data with buffers with duplicate lines.
  • Fixed issue with formatting when data structure returned NULL.
  • Improved string formatting from dump when working with unprintable bytes.
  • Improved error message when required file input is not provided.



  • Supports MQ 9.1.
  • mqtrcfrmt is now also provided as a Java jar with source code included.
  • mqtrcfrmt Java version provides a global feature to copy all messages in a trace to a set of files.
  • MQFile2Msg provides a feature to read a set of trace files and put them onto a queue.


  • mqtrcfrmt now reports when unknown constants are encountered and also supports 819 for message parsing.
  • mqtrcfrmt and mqapitrcstats now support large files (>=2GB) for the 32 bit unix executables.


  • Support for IBM MQ v9.


  • mqtrcfrmt has a new message search option to allow you to search for hex and character strings in the message data of a distributed or application activity trace.
  • mqsc_qmgrs - A new Unix bash script that allows you to execute runmqsc client mode commands against a group of queue managers and then return the individual results in a single line format for searching capabilities.

Message parsing in mqtrcfrmt.  Message parsing provides the ability to do byte analysis on a message in a strmqtrc or activity trace, and find out information such as how much of the message is ASCII, the offset location and numbers of multi-byte 1208 characters, the offset location and numbers of surrogate pairs, the offset locations and numbers of invalid bytes if the message was marked as 1208 or 1200, and so on.  This tool could be used to do investigations such as "does this message contain surrogate pairs?" (which is not supported by MQ) and "where are the surrogate pairs located in the message?", "has the message been incorrectly marked as 819 when it has a 1208 make up?", "does the message contain non-ASCII bytes that could potentially cause a data conversion issue if the application is ported between servers with a different default CCSID for the queue manager?", and so on.
Msg2File in mqtrcfrmt.  This provides the ability to put a special tag above a message in a strmqtrc or activity trace output, and then have the mqtrcfrmt write the contents of the message to a file.  This file could then be used to PUT the message back onto a queue.  As a convenience, a java program called MQFile2Msg is provided to PUT the file onto a queue. 
amqsactz activity trace tool.  amqsact is an IBM supplied sample for formatting activity trace records. amqsactz takes the amqsact sample and provides some usability enhancements for working with activity trace data.  The amqsactz source and a sample Linux executable is provided in the SupportPac.

  • Mqoptions executable has been changed to a Java MQOptions.class that is more portable and robust when working with deciphering MQ options.


  • Pub/Sub support for distributed traces.
  • Pub/Sub and Callback support for z/OS traces.
  • Report option added to mqoptions.
  • Manual in PDF format.

Author: Tim Zielke, CICS/MQ Systems Programmer for Aon
 Category: 4
Released: 26Nov13
Last updated: 23Aug18
Current SupportPac Version: 1.3
»Please note that the version number shown in the right-hand pane is the version of the WebSphere MQ or WebSphere Message Broker product that this SupportPac applies to. The date is the last webpage refresh.

To view the complete portfolio of WebSphere MQ SupportPacs please visit the WebSphere MQ SupportPacs homepage.


This SupportPac requires WebSphere MQ V7 running on the supported Operating System platforms.

Installation Instructions

1. Download to a temporary location.
2. Uncompress with your favorite tool to a location of your choice.
3. This will create the necessary files and directory.
4. The readme.txt explains how to use the mqoptions, mqtrcfrmt, and mqapitrcstats tools.

Download RELEASE DATE LANGUAGE SIZE(Bytes) Download Options 23 Aug 2018 US English 751654 FTP

Technical Support

Category 4 SupportPacs are provided by third party suppliers (for example, customers, business partners, vendors) and not from IBM. The material is provided without any warranty or support from IBM. Any special support arrangements may be described within any downloaded material or on the third party supplier's Web site.

By making any material available for downloading from this site, IBM is making no endorsement of any of these third party suppliers, or of their products.

Document information

More support for: WebSphere MQ

Component: SupportPac

Software version: 7.1, 7.5, 8.0, 9.0, 9.1

Operating system(s): Linux, Solaris, Windows, z/OS

Reference #: 4036430

Modified date: 23 August 2018

Translate this page: