Usage Monitor trace commands

The commands are:

TRCD-A: Display data set allocation parameters.
TRCD-J: Display trace selection job name masks.
TRCD-P: Display trace selection program name masks.
TRCDCL: Set output data set SMS data class.
TRCDSN: Set output data set name.
TRCEXC: Control tracing of excluded events
TRCJOB: Specify job name trace selection filter.
TRCJOD: Delete job name trace selection filter.
TRCMCL: Set output data set SMS management class.
TRCOFF: Terminate tracing.
TRCON: Initiate tracing.
TRCPGD: Delete program name trace selection filter.
TRCPGM: Specify program name trace selection filter.
TRCPRI: Set output data set primary space in tracks.
TRCSCL: Set output data set SMS storage class.
TRCSEC: Set output data set secondary space in tracks
TRCSTA: Set output data set initial disposition.
TRCUNIT: Set output data set device allocation unit.
TRCVOL: Set output data set volume serial.

The syntax rules described under Usage Monitor general commands also apply to these commands.

A description of each command follows.

TRCD-A - Display data set allocation parameters

TRCD-A is used to display dynamic allocation details to be used in the creation of trace output data sets. The data set name, primary and secondary space quantities, and optional SMS class names, unit and volume serial number are shown.

TRCD-A

TRCD-J – Display trace selection job name masks

TRCD-J is used to list the active trace job name selection masks. Events for any program in address spaces (except some excluded system address spaces) with names matching any mask in this list will be logged to the trace data set.

TRCD-J

TRCD-P – Display trace selection program name masks

TRCD-P is used to list the active trace program selection masks. Events in any address space (except some excluded system address spaces) for programs with names matching any mask in this list will be logged to the trace data set. Only 8-byte MVS program names (as opposed to UNIX path names) are examined for this selection filtering.

TRCD-P

TRCDCL – Set output data set SMS data class

The TRCDCL command is used to specify the SMS data class for the trace output data set.

TRCDCL ( dataclas )

dataclas: specifies a 1 – 8-character SMS data class name – omit to clear a previous setting.

TRCDSN – Set output data set name

The TRCDSN command is used to specify the name of the trace output data set.

Symbols can be used to form the data set name used at allocation time. Available symbols are system symbols, &SYSLPAR and &SMF. &SYSLPAR (the current LPAR name) may resolve to a null string when z/OS is running under z/VM. &SMF resolves to the SMF identifier of the system.

Unlike the DSN command, the symbols are resolved each time a trace session is initiated, meaning that dynamic system symbols can be used to generate a unique data set name for each trace session.

TRCDSN ( dsname )

dsname: specifies a 1 – 44-character data class name.

If no TRCDSN command is issued, a data set name of NULLFILE will be used.

The following example sets the output data set name to SYS2.UMTRACE:

TRCDSN(SYS2.UMTRACE)

The following example uses symbols to make the data set name reflect where and when the trace data was collected:

TRCDSN(UMONHLQ.Z&SMF..UMTRACE.D&LDATE..T&LTIME.)

Note the following points pertaining to the previous example:

If this command is passed to the Usage Monitor using the system MODIFY command, system symbols will be resolved by the system before the Usage Monitor receives the command string. In this example, &LDATE and &LTIME will each be converted to a 6-numeric character constant, while &SMF will remain unresolved by the system because it is not a system symbol.
To have system symbols dynamically interpreted at the time the data set is allocated, the TRCDSN command must be passed to the Usage Monitor via the HZAZIN DD, either at initialization time, or by using the REF command to refresh settings.
TRCDSN command processing attempts to resolve the symbols to validate the command, and any success message such as message HZAZ033I will echo the resolved name, but the name to be used when the TRCON command is issued will be stored with symbols unresolved.
For system levels prior to z/OS version 2 release 5, replace &LDATE with &LYYMMDD and replace &LTIME with &LHHMMSS.

TRCEXC – Control tracing of excluded events

TRCEXC is used to control the tracing of events that are excluded from the normal data collection intended for the data base.

TRCEXC ( { Y | N } )

Y: Specifies that excluded events are to be traced.
N: Specifies that excluded events are not to be traced.

If no TRCEXC command is issued, then excluded events are not traced. TRCEXC(N) is the default setting.

When considering the use of TRCEXC(Y), be aware of the potential increase in overhead due to the processing of additional events that would normally be excluded.

TRCJOB – Specify job name trace selection filter

TRCJOB allows additional job name trace selection filters to be activated. Program usage events detected in an address space (apart from various system address spaces) with a name that matches any of the active job name selection masks will be traced.

TRCJOB ( { job - mask | ,job - mask | ,job - mask } )

job-mask: specifies a 1 – 8-character job name mask. Each mask can be made generic by including one or more generic masking characters. A percent sign (%) may be used in the mask to match any value of the corresponding single job name character. The mask may also end with an asterisk (*), indicating all further characters until the end of the job name are considered to match. Note that a mask of only a single asterisk will match all job names, meaning that all detected events will be traced. Depending on system workloads, tracing all detected events may add noticeable overhead to system and/or application processing.

TRCJOD – Delete job name trace selection filter

TRCJOD is used to deactivate one or more job name trace selection filters that were added by previous by a TRCJOB command. The mask value(s) specified must exactly match an active job name filter. If necessary, use the TRCD-J command to display active job name filters.

TRCJOD ( { job - mask | ,job - mask | ,job - mask } )

job-mask: specifies a 1 – 8-character job name mask.

Use the command TRCJOD(*ALL*) to deactivate all trace job name selection filtering.

TRCMCL – Set output data set SMS management class

The TRCMCL command is used to specify the SMS management class for the trace output data set.

TRCMCL ( mgmtclas )

mgmtclas: specifies a 1 – 8-character SMS data class name – omit to clear a previous setting.

TRCOFF – Terminate tracing

TRCOFF is used to end an active trace, causing the Usage Monitor to close and deallocate the output data set. Issuing TRCOFF when tracing is inactive has no effect.

TRCOFF

TRCON – Initiate tracing

TRCON is used to initiate an active trace, causing the Usage Monitor to attach a trace subtask which will allocate the output data set using the current value of relevant settings, and open the data set for output. When the subtask indicates that data set is ready to accept data, tracing will commence. Issuing TRCON when tracing is already active has no effect.

TRCON

TRCPGD – Delete program name trace selection filter

TRCPGD is used to deactivate one or more program name trace selection filters that were added by previous by a TRCPGM command. The mask value(s) specified must exactly match an active program name filter. If necessary, use the TRCD-P command to display active program name filters.

TRCPGD ( { pgm - mask | ,pgm - mask | ,pgm - mask } )

pgm-mask: specifies a 1 – 8-character program name mask.

Use the command TRCPGD(*ALL*) to deactivate all trace program name selection filtering.

TRCPGM – Specify program name trace selection filter

TRCPGM allows additional program name trace selection filters to be activated. Program usage events detected for programs with a name that matches any of the active program name selection masks in any address space (apart from various system address spaces) will be traced. Only 8-byte program names (and not UNIX program path names) are examined.

TRCPGM ( { pgm - mask | ,pgm - mask | ,pgm - mask } )

pgm-mask: specifies a 1 – 8-character program name mask. Each mask can be made generic by including one or more generic masking characters. A percent sign (%) may be used in the mask to match any value of the corresponding single program name character. The mask may also end with an asterisk (*), indicating all further characters until the end of the program name are considered to match. Note that a mask of only a single asterisk will match all program names (including UNIX programs), meaning that all detected events will be traced. Depending on system workloads, tracing all detected events may add noticeable overhead to system and/or application processing.

TRCPRI – Set output data set primary space

TRCPRI is used to specify the primary space allocation quantity in tracks for the trace output data set.

TRCPRI ( trks )

trks: specifies the initial number of tracks from 0 to 150,000.

If no TRCPRI command is issued, a primary space quantity of 750 tracks is used. Unused space is not released when the trace ends so that a practice of retaining a permanent trace data set would be feasible.

TRCSCL – Set output data set SMS storage class

The TRCSCL command is used to specify the SMS storage class for the trace output data set.

TTRCSCL ( storclas )

storclas: specifies a 1 – 8-character SMS storage class name – omit to clear a previous setting.

TRCSEC – Set output data set secondary space

TRCSEC is used to specify the secondary space allocation quantity in tracks for the trace output data set.

TRCSEC ( trks )

trks: specifies the secondary number of tracks from 0 to 150,000.

If no TRCSEC command is issued, a secondary space quantity of 300 tracks is used. Unused space is not released when the trace ends so that a practice of retaining a permanent trace data set would be feasible.

TRCSTA – Set output data set initial disposition

TRCSTA is used to set the initial status of the trace output data set. This is the same data set initial status that is specified by the first subparameter of DISP in a DD statement of JCL.

TRCSTA ( { NEW | OLD | MOD | SHR } )

If no TRCSTA command is issued, a value of NEW will be used. For more information including a discussion on serialization implications, see the section for DISP in z/OS MVS JCL Reference.

TRCUNIT – Set output data set device allocation unit

TRCUNIT is used to specify the unit name to be used when allocating the trace output data set.

TRCUNIT ( unitname )

unitname: specifies the 1 – 8-character unit name.

If no TRCUNIT command is issued, a unit name of SYSALLDA will be used.

TRCVOL – Set output data set volume

TRCVOL is used to direct the allocation of the trace output data set to a specific volume.

TRCVOL ( volser )

volser: specifies the 1 – 6-character volume serial number of the trace data set volume.

If no TRCVOL command is issued then no specific volume is requested. You must then have PUBLIC or STORAGE volumes in the public allocation pool, unless the data set is managed by SMS.