DIAGNOSE facility

The DIAGNOSE facility offers powerful diagnostic capabilities for BMC AMI Utilities. It is triggered from a message-ID or an abend code and when triggered it can take actions like abending the job, creating a dump, executing a REXX exec, or going into a wait state. Filters are also available to limit when the diagnostic is triggered. You can filter by jobname, which file the message is in, which module wrote the message, which instance of the message, etc. An alternate, little-used function, is to suppress messages from the output.

To activate the DIAGNOSE facility, include a DIAGNOSE DD in your utility job with either instream DIAGNOSE commands or with DIAGNOSE commands in a dataset.

The dataset can be any output sequential file defined with a record format (RECFM) of FB, VB, F, V, or U. If the file has a fixed format and a logical record length (LRCEL) of 80, the diagnose facility processes only columns 1 through 72.

To add textual comments in the diagnose file, enclose them in the delimiters /* and */. You can nest comments within other comments.

Best practice
Adding a DIAGNOSE DD DSN=diagnose_dataset to every utility job or proc makes it easy to use the facility when needed. Rather than changing the job, or all jobs, you can then just add a statement to the otherwise empty diagnose_dataset. This can simplify obtaining dumps if requested by BMC Support. A filter can be used to limit the Diagnose statement to one jobname.

Important

Not all utility messages can be used as diagnose triggers. DIAGNOSE is rarely used and usually initiated by BMC Support to obtain diagnostics for an issue.

MSGID messageID

Specifies the message event that causes BMC AMI Utilities to perform the specified filtering and action

A message event occurs when BMC AMI Utilities issue a message with the specified messageID to CDBPRINT, SYSERROR, or SUMMARY DD statements.

The messageID value must be a valid NGTUTIL message ID and not exceed seven characters. A messageID value of fewer than seven characters matches against any message ID that starts with those characters. To match against all messages, code MSGID(*).

The number of MSGID events cannot exceed 200.

ABEND abendCode

Specifies that abend event that causes BMC AMI Utilities to perform the specified filtering and action

An abend event occurs when NGTUTIL encounters an abend with the specified abendCode.

The abendCode value must be a six-digit hexadecimal string. The first three digits represent the system abend code; the last three digits represent the user abend code.

To specify an abendCode mask, enclose it in single quotation marks (' ', not " "). You can use the following escape characters:

Percent sign (%) for one or more characters
Underscore symbol (_) for a single character

Example

The following syntax traps any abend beginning with 0C:

DIAGNOSE ABEND('0C%') ACTION(action)...

The following syntax traps any abend beginning with 0C that also ends in 000:

DIAGNOSE ABEND('0C_000') ACTION(action)...

The number of abend events cannot exceed 200.

Filter block

JOB jobName	Specifies the job name of the JOB from which the event has originated
MODULE moduleName	Selects only events generated by a specific NGTUTIL module name or a REXX EXEC name
INSTANCE integer	Specifies the number of times the specified event must occur The integer value specified must be greater than 0.
MATCHLIM integer	Specifies the maximum number of actions on a specified event. The default integer value is 1. MATCHLIM does not apply when suppressing messages.
FILE ddName	Specifies the ddname of the file to which messages are targeted Valid ddname values are CDBPRINT, SYSERROR, and SUMMARY.
TASK taskID	Specifies the BMC AMI Utilities task ID from which the event has originated
BLANKS	Allows only blank lines that match the MSGID() event specification You can use BLANKS to eliminate an excessive number of blank lines. Important* BMC AMI Utilities print certain blank lines to improve readability of the output file. You cannot suppress these blank lines.

Action block

ACTION specifies the action that you want BMC AMI Utilities to perform when an event has matches the filter criteria.

When you specify multiple actions for an event, BMC AMI Utilities execute them in the following order:

SNAP
SVCD
WAIT
EXEC
ABEND
SUPPRESS

ABEND

Causes the current job step to abend

ABEND is a default option.

WAIT

Issues a WTOR message to the operator and requests a reply

SNAP

Takes a snap dump of the current issuer to the LOGPDS data set

EXEC name

Invokes a REXX EXEC and passes to it the following variables:

TYPE	Event type—either MSGID or ABEND
ID	Event ID—either messageID or abendCode
MESSAGE	If this is a message event—the message text If this is an abend event—blanks
INSTANCE	Number of times this event has occurred
FILE	ddname of the target file for the message
MODULE	Name of the program or REXX EXEC that issued the event
TASK	BMC AMI Utilities task ID

Important

BMC AMI Utilities might not execute the EXEC statement if the environment is restricted, for example, the event has originated from a REXX EXEC or the event environment is internally locked. If BMC AMI Utilities do not execute the EXEC statement, the utilities issue message NGTU793 and processing continues.

SUPPRESS

Removes the message from the BMC AMI Utilities output files

If this is a message event, it removes the message from the BMC AMI Utilities output files. If this is an abend event, it suppresses LOGPDS dump and issues message NGTU797 to show the name of the abending module.

SVCD block

Use the SVCD option to capture an SVC dump of the current job for a specific location in a module by using the OFFSET(hex) and MODULE(moduleName) operands. You can also request a dump of the Db2 and BMC AMI Utilities subsystems.

*OFFSET(hex)*	Offset of four hexadecimal digits (for example, 0A03)
*MODULE(moduleName)*	Module name of up to eight characters (for example, RRGSAMPL)
*DATASPACE(dataSpaceName)*	Data space name of up to eight characters You can use an asterisk (*) to request all data spaces for the job.
Db2	Captures a dump of the Db2 subsystem
NGTSS	Captures a dump of the BMC AMI Utilities subsystem

Example

An example of DIAGNOSE command syntax follows:

DIAGNOSE MSGID(*) ACTION(SUPPRESS) MODULE(RWRBFMGR) TASK(LOGR)
        MSGID(NGTR452) ACTION(SUPPRESS) JOB(THISJOB)
        MSGID(NGTR426) ACTION(SUPPRESS) FILE(SYSERROR)
        MSGID(NGTR806) ACTION(SUPPRESS)
        MSGID(NGTC180) INSTANCE(1) ACTION(WAIT)
        MSGID(NGTC180) INSTANCE(5) ACTION(SNAP ABEND)
        ABEND(0C3000) MODULE(NGTXLIST) ACTION(SVCD SUPPRESS)
        ABEND(0C1000) ACTION(EXEC(HELP0C1) SVCD)

DIAGNOSE ACTION(SVCD OFFSET(001E))
        MSGID(NGTU990) ACTION(SVCD MODULE(RRGSAMPL) DB2)
        MSGID(NGTB991) ACTION(SVCD OFFSET(07CD) NGTSS)
        MSGID(NGTB991) ACTION(SVCD DB2 DATASPACE(*))
        MSGID(NGTC992) ACTION(SVCD OFFSET(081F) MODULE(RRGSAMPL) DB2 NGTSS)

DIAGNOSE facility

Filter block

Action block

SVCD block

On this page