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. 

Related topic

Getting-started

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.

DIAGNOSE_command.png



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

DIAGNOSE_filterspec.png

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: 

  1. SNAP
  2. SVCD
  3. WAIT
  4. EXEC
  5. ABEND
  6. SUPPRESS

DIAGNOSE_actionspec.png

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. 

DIAGNOSE_ACTION_svcd.png


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)

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*