Usage Monitor trace commands

Commands for the Usage Monitor Trace Facility are listed in this section.

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.

TRCUNX: Control UNIX syscall trace.

TRCVOL: Set output data set volume serial.

The syntax rules described in Usage Monitor general commands also apply to the trace commands.

The description of each trace 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-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-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

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.

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, &SYSPLAR and &SMF. &SYSLPAR (the current LPA 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.

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 UMONIN 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 HZAZ0331 will echo the resolved name, but the name to be used when the TRCON command is issued will be stored with symbols unresolved so that the symbols can be reevaluated at data set allocation time.
For system levels prior to z/OS 2.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 database.

Y: Specifies that excluded events are to be traced.
N: Specifies that excluded events are to not 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.

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.

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.

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.

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 the data set is ready to accept data, tracing will commence. Issuing TRCON when tracing is already active has no effect.

TRCPGD - Delete job 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.

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

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.

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.

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.

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.

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.

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

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

TRCUNX - Control tracing of UNIX syscalls

TRCUNX is used to control the tracing of z/OS UNIX system service calls or syscalls made by applications. For each traced call a trace record is written before the UNIX system service gets control and another record is written when the system service call completes and returns control to the application.

Y: Specifies that UNIX syscalls are to be traced.
N: Specifies that UNIX syscalls are to not be traced.

TRCUNX(N) is the default so if no TRCUNX command is issued, then UNIX syscalls are not traced.

Tracing UNIX syscall events is implemented using the BPX_PRE_SYSCALL and BPX_POST_SYSCALL system exit points. The call types that can be traced are controlled by the list of call stub names present in the EBCDIC text file (conventionally residing in the /etc directory) named in the SC_EXITTABLE setting of an active BPXPRMxx system PARMLIB member. If you change the stub list in the text file, you can get the system to process the update by issuing the SET OMVS=xx system command where xx is the suffix of the relevant BPXPRMxx PARMLIB member.

Trace records generated by the TRCUNX(Y) setting have the following properties:

Their generation is not affected by the TRCEXC setting.
They are only generated for callers in task mode.
They are only generated after a job name mask from a TRCJOB command matches the current address space name.
They are not affected by program name filtering even though the corresponding stub name is reported in the 8-byte program name field (even when such a stub is not used).
The first three characters of the 8-byte program name field will be Pre for pre-calls and BPX for post-calls.
The fourth character of the 8-byte program name field will be a 4 for 64-bit callers.
The provider field has a value of UNIX in EBCDIC.
Unlike other trace records and usage detail records, the CPU time fields (which have a resolution of hundredths of a second) represent the accumulated CPU time of the task at the time the information was collected.
Unlike other trace records and usage detail records, the program active time field contains the task address rendered in EBCDIC to assist post-processor data collation. (Use the STCK value in the record suffix to perform elapsed time analysis.)
For those syscalls passed a string such as a user or path name, the string is reported in the file name field. For other syscall types, the file name field contains Callxxxx where xxxx is the hexadecimal call type number. Read and write calls will also have the return value reported after the RV=indicator.
The volume serial field contains blanks except for those call types where a file descriptor is used. For open (post-call only), close, read, seek, and write call types, the 6-byte volume serial field contains x6FFD followed by the 4-byte file descriptor value to assist post-processor data collation.

TRCVOL - Set output data set volume

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

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.