runmqras

Purpose

The runmqras command is used to gather troubleshooting information from a machine into a single archive. You can use this command to gather information about an application or IBM WebSphere MQ failure, possibly for submitting to IBM when you report a problem.

Running without requesting more sections is intended as a starting point for general problem diagnosis, however, you can request more sections through the command line.

These additional sections gather more detailed information, depending on the type of problem being diagnosed. If non-default sections are needed by IBM support personnel, they will tell you.

The runmqras command can be run under any user ID, but the command only gathers information that the user ID can gather manually. In general, when debugging IBM WebSphere MQ problems, run the command under the mqm user ID to allow the command to gather queue manager files and command outputs.

From IBM WebSphere MQ Version 7.5.0, Fix Pack 9, the runmqras command, by default, retrieves the environment variable information. This applies to Linux®, Solaris, and AIX®.

From IBM WebSphere MQ Version 7.5.0, Fix Pack 9, the runmqras command retrieves a listing of the queue manager's data directory by default. This applies to distributed platforms.

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.

-zipfile ZipFileName

Supply the file name of the resulting archive.

By default, the name of the output archive is runmqras.zip.

-outputdir path

The directory in which the resulting output file is placed.

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

-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 under /tmp is used on UNIX systems, and under %temp% is used on Windows, whose name starts with runmqras and is suffixed by the date and time.

-section SectionA, SectionB

The optional sections about which to gather more specific information.

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.

default

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

Note: Always gathered unless you use the section name nodefault.

nodefault

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

trace

Gathers all the trace file information plus the default information.

Note: Does not enable tracing.

defs

Gathers the queue manager definitions and status information.

cluster

Gathers cluster configuration and queue information.

From IBM WebSphere MQ Version 7.5.0, Fix Pack 1 you can also specify the following sections:

dap

Gathers transaction and persistence information.

kernel

Gathers queue manager kernel information.

logger

Gathers recovery logging information.

topic

Gathers topic tree information.

From IBM WebSphere MQ Version 7.5.0, Fix Pack 2 you can specify the following section:

QMGR

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

From IBM WebSphere MQ Version 7.5.0, Fix Pack 9, you can specify the following sections

leak

Gathers IBM WebSphere MQ process resource usage information.

This section applies to Linux, HP-UX, Solaris, and AIX.

mft

Captures the data obtained by the fteRas command.

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

For more information, see Section names and descriptions, in the IBM WebSphere MQ technote on using the IBM WebSphere MQ runmqras command to collect data.

-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.

-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.

-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.

-v

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

-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, either directly into IBM, or to a site of your choosing. If you select the ibm option, anonymous FTP is used to deliver the archive into the IBM ECuRep server. This process is identical to submitting the file manually using FTP.

Note if you select the ibm option, you must also provide the pmrno option, and all other FTP* options are ignored.

-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.

-ftppassword password

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

-ftpdirectory path

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

-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 into IBM, the information is automatically associated with that problem record.

-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 into IBM, the information is automatically associated with that case number.

Note: -caseno is equivalent to -pmrno and both are optional parameters, but it is not permitted to supply both together.

-help

Provide simple help.

-sub

Shows the keywords that will be substituted in the xml.

Return codes

A non zero return code indicates failure.