runmqras (collect IBM MQ troubleshooting information)

Keywords and parameters

All parameters are required unless the description states they are optional.

In every case, QMgrName is the name of the queue manager to which the command applies.

-application application

Collects information about valid applications.

-caseno caseNo

A valid Salesforce case number.

Use this option to ensure that the output is prefixed with your case number, so that when the information is sent to IBM, the information is automatically associated with that case number.

Note: If you want to specify a PMR number, use the -pmrno parameter, not the -caseno parameter.

It is not permitted to supply both the -caseno and -pmrno parameters together.

-custominput CustomInputFileName

Fully qualified name of an additional XML input file

-demo

Run in demonstration mode where no commands are processed, and no files gathered.

By running in demonstration mode, you can see exactly which commands would have been processed, and what files would have been gathered. The output .zip file contains a console.log file that documents exactly what would have been processed and gathered, should the command be run normally.

-ftp ibm|custom

Allows the collected archive to be sent through basic FTP to a remote destination.

At the end of processing, the resultant archive can be sent through basic FTP to a site of your choosing.

Important: From IBM MQ 9.3.0, the -ftp IBM option is no longer available. If you select this option, the following message is generated:

The FTP IBM option will no longer work as the IBM FTP servers have been disabled

-ftpdirectory path

The directory on the FTP server to place the resulting .zip file into, used when an FTP custom option is used.

-ftppassword password

The password to log in to the FTP server with, when an FTP custom option is used.

-ftpserver server

An FTP server name to connect to, when an FTP custom option is used.

-ftpusername userid

The user ID to log in to the FTP server with, when an FTP custom option is used.

-help

Provide simple help.

-inputfile InputFileName

Fully qualified name of the XML input file

-noqmdata

From IBM MQ 9.3.0, setting -noqmdata captures installation-level diagnostics only, skipping any queue manager-specific diagnostics.

The -qmlist parameter and the -noqmdata parameter cannot be used together. If both parameters are specified, the following error is returned:

Argument error: At most one of -noqmdata or -qmlist may be supplied

-outputdir path

The directory in which the resulting output file is placed.

By default, the output directory is the same as the work directory.

-pmrno 12345,678,9AB

A valid IBM PMR number (problem record number) against which to associate the documentation.

Use this option to ensure that the output is prefixed with your PMR number, so that when the information is sent to IBM, the information is automatically associated with that problem record.

Note: If you want to specify a Salesforce case number, use the -caseno parameter, not the -pmrno parameter.

It is not permitted to supply both the -caseno and -pmrno parameters together.

-qmlist QMA[,QMB]

A list of queue manager names on which the runmqras command is to be run.

This parameter does not apply to a client product because there are no queue managers from which to request direct output.

By supplying a comma-separated list, you can restrict the iteration across queue managers to a specific list of queue managers. By default, iteration of commands is across all queue managers.

-section SectionA,SectionB

The optional sections about which to gather more specific information. You must use a comma as the separator character between sections, with no spaces. For example:

runmqras -qmlist ESBSTGAPPQMVH2 -section defs,trace,cluster -caseno TEST123

By default, a generic section of documentation is collected, whereas more specific information can be gathered for a specified problem type; for example, a section name of trace gathers all of the contents of the trace directory.

The default collections can be avoided by supplying a section name of nodefault.

IBM Support generally supplies you with the sections to use. Example available sections are:

all

Gathers all possible information, including all trace files, and diagnostics for many different types of problems. You must use this option only in certain circumstances and this option is not intended for general use.

cluster

Gathers cluster configuration and queue information.

dap

Gathers transaction and persistence information.

default

IBM MQ logs, FDC files, basic configuration, and status.

Note: Always gathered unless you use the section name nodefault. Some information about the current environment (saved in env.stdout on Linux, AIX and IBM i, and in set.stdout on Windows) and current user limits (saved in mqconfig.stdout on AIX and Linux) might be altered by the runmqras command. If necessary, run the env, set, or mqconfig commands manually in your environment to check the actual values.

On the IBM MQ Appliance, any files other than queue manager trace files present in the mqtrace: filesystem are now captured in the default section.

Note: You should continue to specify the trace section if you need to obtain any queue manager trace files present in the mqtrace: filesystem.

defs

Gathers the queue manager definitions and status information.

kernel

Gathers queue manager kernel information.

leak

Gathers IBM MQ process resource usage information.

This section applies to Linux and AIX.

logger

Gathers recovery logging information.

mft

Captures the data obtained by the fteRas command.

Note: -section mft only collects information for the default coordination queue manager topology.

mqweb

Gathers trace and configuration data for the mqweb server.

nativeha

Gathers diagnostic information from a native HA queue manager instance. It is useful to gather information from all instances to view recent history of activity and communication between the instances.

nodefault

Prevents the default collections from occurring, but other explicitly requested sections are still collected.

QMGR

Gathers all queue manager files: queues, logs, and configuration files.

topic

Gathers topic tree information.

trace

Gathers all the trace file information plus the default information.

Note: Does not enable tracing.

For more information, see Choosing sections to gather, in the IBM technote on using the IBM MQ runmqras command to collect data.

-sub

Shows the keywords that will be substituted in the xml.

-timeout secs

The default timeout to give an individual command before the command stops waiting for completion.

By default, a timeout of 10 seconds is used. A value of zero means wait indefinitely.

-v

Extends the amount of information that is logged in the console.log file, contained in the output .zip file.

-workdirectory path

The directory that is used for storing the output from commands that are run during the processing of the tool. If supplied, this directory must either not exist, in which case it is created, or must be empty.

If you do not supply the path, a directory whose name starts with runmqras and is suffixed by the date and time is used:

• On AIX and Linux, the directory is under /tmp.
• On Windows, the directory is under %temp%.

-zipfile ZipFileName

Supply the file name of the resulting archive.

runmqras appends the hostname to the name of the archive file. For example, if you run the following command:

runmqras -zipFile diagnostics.zip

the resulting archive file is called diagnostics-hostname.zip.

By default, the name of the archive file is runmqras-hostname.zip where hostname is the hostname that runmqras appends to the file name.

Return codes