Usage Monitor commands

The Usage Monitor commands are passed to the Usage Monitor from the HZAZIN input file, or by an operator MODIFY command.

The syntax rules are as follows:

All commands are three characters long.
Operands or subparameters are specified in parentheses.
Multiple subparameters are separated by commas.
The command must not contain any embedded blanks.
Commands must start in column one.

To record the settings the Usage Monitor is using, place the display commands at the end of the HZAZIN file.

Details of each command follow.

CAP - Set hardware capacity collection status

CAP is used to specify if the Usage Monitor is to produce records containing information about the hardware capacity of the system. Collecting this information is important when hardware capacity changes dynamically.

A change to this setting does not take effect until the next collection repository switch.

Y: Specifies that hardware capacity data is collected and written out.
N: Specifies that hardware capacity is not collected or written out.

If no CAP command is issued, the default is CAP(Y).

Table 1. Examples of using the CAP command
CAP command examples to collect hardware capacity data or not to collect hardware capacity data
Command purpose	Example code
Collect hardware capacity data.	`F HZAJMON,CAP(Y)`
Do not collect hardware capacity data.	`F HZAJMON,CAP(N)`

CIC - Allow or disable program usage data from CICS® regions

The CIC command provides a system-wide control mechanism to allow or disallow program usage data to be collected by the Usage Monitor CICS® global user exit (GLUE) program.

Y: Specifies that customized CICS® regions are able to present program usage data to the Usage Monitor for collection.
N: Specifies CICS® program usage monitoring is disabled throughout the operating system image.

If no CIC command is issued, the default is CIC(Y).

D-A - Display output allocation parameters

D-A is used to display dynamic allocation details to be used in the creation of output data files. The data set name, DCB attributes, primary and secondary space quantities, and unit and optional volume serial number are shown.

The following code example displays the current dynamic allocation values.

F HZAJMON,D-A

D-C - Display the counters and statistics

D-C is used to display the Usage Monitor activity and status indicators. The purpose of this command is to assist technical support in problem diagnosis. The meaning of the output generated by this command is not published.

The following code example displays the current value of internal Usage Monitor counters.

F HZAJMON,D-C

D-D - Display the data set name inclusion and exclusion lists

D-D is used to display the data set name masks in the inclusion list, followed by the data set name masks in the exclusion list.

The inclusion and exclusion lists do not need to be populated in order to collect data. The absence of any entries in the exclusion list means that data collection is not filtered by program library data set names.

The following code example displays the current data set name inclusion and exclusion lists.

F HZAJMON,D-D

D-I - Display the system identifier

D-I is used to display the system identifier, which is written in the output header record. It can be altered by the SID command.

The following example code displays the current system identifier used by the Usage Monitor.

F HZAJMON,D-I

D-L - Display long-running program names

D-L is used to list the program names currently considered to be long-running. The initial list is formed from the system’s program properties table active when the Usage Monitor initializes. Names can be added to the list by the LRP command, and removed from the list by the LRD command.

When the name of the job step program of a started task or batch job matches an active entry in this list, detailed CPU time consumed by programs in this step is not tracked, but the step’s CPU time consumed each SMF interval is attributed to the job step program, allowing some tracking of consumed CPU time for rarely-ending address spaces.

D-S - Display the status settings

D-S is used to display several miscellaneous settings. Other commands are used to alter the individual settings, but this command provides a convenient way to list the current values.

Place at the end of the HZAZIN file to confirm monitoring settings.

The following example code displays the current values of settings.

F HZAJMON,D-S

D-T - Display the automatic switch-and-write time setting

D-T is used to display the time-of-day specified for automatic collection repository switching and consequent writer task creation. When data from after this time-of-day is detected, data collection is automatically switched to a new repository, and write-out of data in the old repository is started.

The UTC or GMT switch time is calculated using local time current at collection repository creation time. The time when a collection repository is terminated is set when it is created. Changes to the system local time offset, such as those caused by a change to daylight saving time, do not alter the UTC or GMT that the current collection repository is closed. The time of the switch after the next switch is calculated using the new local time.

The following example code displays the current automatic switch-and-write time setting.

F HZAJMON,D-T

D-X - Display the active exclude list

D-X is used to display the active program name mask exclude list. Data is not collected for programs with names that match the mask in any active entry in the exclude list.

The following example code displays the current exclude list entries.

F HZAJMON,D-X

DCB - Set output DCB attributes

DCB is used to set DCB attributes, which are optimal for a specific device type.

If no DCB command is issued, the default is DCB(3390).

DCB(3390)

Sets the output DCB to

RECFM=VB,LRECL=27994,BLKSIZE=27998

Use when the output device has 3390 compatible geometry.

DCB(3380)

Sets the output DCB to

RECFM=VB,LRECL=23472,BLKSIZE=23476

Use when the output device has 3380 compatible geometry.

DCB(UNKN)

Sets the output DCB to

RECFM=VBS,LRECL=32756,BLKSIZE=0

The system determines the optimal block size for the device used by dynamic allocation. Use when the output device type is not known until allocation time.

Some FTP products do not process a file with RECFM=VBS correctly, even when no records are actually spanned.

DCL - Set the data set SMS data class

The DCL command is used to override the data class that is assigned to dynamically created output data sets by the system’s ACS routines. You may use this, for example, to assign a data class that is not eligible to be marked SMS compressible so that the Usage Monitor can output zipped data.

dataclas: specifies a 1 – 8 character SMS data class name

DEL - Deleting program mask entries

DEL is used to remove program name masks from filter tables. Both default and user-added entries can be removed. The required operand specifies one or more program name masks.

mask: Specifies a 1 - 8 character program name mask. Any wildcard characters in the mask are treated as literals for the purposes of finding the mask to delete.
*ALL*: Specifies every currently active mask. This mask cannot be specified with any other mask.

Except for short test periods, it is expected that default exclusion masks such as IGG* remain active.

Table 2. Examples of using the DEL command
DEL command examples for removing all entries or removing exclusion masks.
Command purpose	Example code
Remove all entries, so that all possible programs are monitored.	`F HZAJMON,DEL(ALL)`
Remove exclusion masks to monitor LE and REXX™ modules.	`F HZAJMON,DEL(CEE,IRX)`
Remove an exclusion mask to monitor the program called CEE.	`F HZAJMON,DEL(CEE)`

DSN - Setting the data set name prefix

DSN is used to specify the first part of the data set names used for the output files. The prefix is specified in the required operand. The HZAZIN file must contain a DSN command.

You can use symbols in the construction of the data set name prefix. Available symbols include all z/OS® static symbols, &SMF, the SMF identifier for the system, and &SYSLPAR, the logical partition name for the system.

dsnpref: Specifies a 1 - 26 character data set name prefix. It can contain one or more data set qualifiers, and must not end in a period after any symbol substitution.

Usage Monitor needs RACF® ALTER access to the data sets to be able to create them.

The following example code shows how to get output files with names of the form SYS3.HZA.HZAJMON.Dyyyyddd.Thhmmsst:

F HZAJMON,DSN(SYS3.HZA.HZAJMON)

DUR - Set execution duration

DUR is used to specify a fixed short-term execution duration of the Usage Monitor started task. When the specified time has elapsed the Usage Monitor will terminate automatically. The Usage Monitor stop time is calculated by adding the specified duration to the current time when the command is processed.

Any subsequent WRT commands are ignored.

The DUR command is not normally used in standard operations where the Usage Monitor is to remain active until system shutdown. When it is used, it is normally placed in the HZAZIN file to specify a predetermined length of execution for sampling or testing purposes.

hhmm: Specifies a time duration in hour and minute notation. The value must be four decimal digits. The minimum value is 0001 and the maximum value is 2400. The last two digits (mm) must be in the 00 - 59 range.

The following example code instructs the Usage Monitor to stop after 150 minutes.

F HZAJMON,DUR(0230)

EXC - Adding program mask exclusion entries

EXC is used to add program name masks to the exclusion table. The required operand specifies one or more program name masks.

mask: Specifies a 1 - 8 character program name mask. If the mask ends in an asterisk only, characters before the asterisk are compared. Otherwise, an exact program name is deemed to have been specified.
*DFLT*: Specifies every supplied default entry in the exclusion table is to be made active, and all user-added entries are to be removed from the exclusion table. This mask cannot be specified with any other mask.

Except for short test periods, it is expected that default exclusion masks such as IGG* would remain active.

Table 3. Examples of using the EXC command
EXC command examples for resetting the exclusion table or excluding the collection of data.
Command purpose	Example code
Reset the exclusion table to its default status.	`F HZAJMON,EXC(DFLT)`
Exclude the collection of data for Language Environment® modules and REXX™ modules.	`F HZAJMON,EXC(CEE,IRX)`
Exclude the collection of data for the program CEE.	`F HZAJMON,EXC(CEE)`

HOF - Adjust for hypervisor STCK TOD clock offset

HOF is used to control whether the TOD clock offset in a logical partition is to be applied to collected data, or not. When HOF(N) is set, data timestamps are derived from the local time as supplied by z/OS®. When HOF(Y) is set, the hypervisor STCK date and time offset from field SMF89HOF in SMF type 89 records is subtracted from z/OS® local time to form the collected timestamp values.

For Usage Monitor data, the HOF setting at the time that the writer task is attached after the closure (or switch) of a collection repository is used.

For Inquisitor data, the HOF setting active at the time of the Inquisitor program initialization is used.

HOF(Y) will not cause any change to data timestamp values unless the Usage Monitor has processed a type 89 SMF record. For this to occur, SMF parameter settings must specify the collection of type 89 records, and at least one SMF interval must have ended while the Usage Monitor is active before the ouput file data generation commenced.

If the Usage Monitor has been stopped before an Inquisitor scan commences, the Inquisitor program uses the HOF status current at the time of Usage Monitor termination.

Y: Specifies the hypervisor STCK TOD clock offset will be used to adjust date and time values present in collected data.
N: Specifies the date and time values present in collected data will be based wholly on the local time, as maintained by z/OS®.

HOF(N) is the default setting that will be used if no HOF command has been issued since IPL.

IDD - Deleting data set name inclusion entries

IDD is used to remove data set name masks previously added by the IDS command. If a mask of *ALL* is specified then all data set inclusion masks are deactivated.

mask: Specifies a 1 - 44 character data set name mask. Any wildcard characters in the mask are treated as literals for the purposes of finding the mask to delete.

The following example code deactivates the SYS3.LINKLIB inclusion mask.

F HZAJMON,IDD(SYS3.LINKLIB)

IDS - Adding data set name inclusion entries

IDS is used to supply data set name masks, which specify data set names to be excluded from exclusion processing. Program usage data fetched from data sets with names matching inclusion masks, is collected without reference to the data set name mask exclusion list.

Inclusion masks only affect data collection if there are active user-specified exclusion masks. An inclusion mask is normally expected to match a subset of data set names that would match an exclusion mask.

mask: Specifies a 1 - 44 character data set name mask. Generic wildcard matching allows a percent sign to match any single character, and an asterisk to match any group of zero or more characters. If the mask contains a slash character (/), the value is processed as a UNIX® path name mask rather than a data set name mask.

You can use the following example code if your intention is to not collect program usage data for data sets with a high-level qualifier of SYS3, except for SYS3.LINKLIB. SYS3.LINKLIB is the only data set with a high-level qualifier of SYS3 for which program usage data is to be collected.

XDS(SYS3.*)
IDS(SYS3.LINKLIB)

IMS - Set IMS-managed program usage collection status

Many programs in IMS address spaces are managed by IMS itself rather than by the operating system’s program management component. The IMS command provides a system-wide setting to enable or disable the collection of usage of these IMS-managed programs.

Y: Specifies that IMS-managed program usage is to be collected.
N: Specifies that IMS-managed program usage is not to be collected.

If no IMS command is issued, then IMS-managed program usage is collected. IMS(Y) is the default setting.

IPH - Control collection of TCPIP Host details

JIPH is used to control the reporting of the TCPIP host name and IP address. Program usage data sets created by the Usage Monitor will normally have the TCPIP host details present in the header information, but this data can be suppressed by specifying IPH(N).

Y: Specifies that the Usage Monitor will call HZAPHOST to procure TCPIP host details.
N: Specifies that the Usage Monitor will not report TCPIP host details in the program usage files.

If no IPH command is issued, the default is IPH(Y).

JAC - Set job account collection status

JAC is used to specify if the Usage Monitor is to consider the account code of jobs significant when aggregating data. The Usage Monitor normally aggregates data based on the program name, the job name, and the user ID. This setting is used to add the job account, truncated after 20 characters, to the aggregation key.

Do not instruct the Usage Monitor to collect and preserve all job account codes if they are not important to the administration of your system. Collecting and preserving job accounts can significantly increase data volumes.

A change to this setting does not take effect until the next collection repository switch.

Y: Specifies that job account codes are used.
N: Specifies that job account codes are ignored.

If no JAC command is issued, then job accounts are used. The default is JAC(N).

JID - Control the preservation of batch job identifiers

JID is used to control whether all batch job identifiers are to be preserved or not. Normally usage data for each program is aggregated by job name and user ID, with only the most recent job identifier being retained. JID provides the option of keeping all batch job identifiers so that the number of jobs using a program can be counted, and usage can be attributed to specific individual jobs. Job identifier aggregation for started tasks and TSO user sessions is always equivalent to JID(N) and is not affected by this setting.

Y: Specifies that batch job identifiers should not be overlaid and that different batch job identifiers should prevent data aggregation.
N: Specifies that normal aggregation by job name and user ID is to proceed without considering job identifier differences.

The default setting of JID(N) applies each time the Usage Monitor is started.

JNM - Control the collection of job names

JNM is used to specify whether the Usage Monitor collects the names of jobs which use programs or not. If the names of jobs which use the various programs are not considered to be important, you can dispense with the collection of these names. The advantage of not collecting individual job names is the reduction in processing times and data volumes caused by the aggregation of data into fewer records. When individual job names are not collected, usage is summed over broad address space categories, such as JOB, STC, TSO, and SYS. The total usage counts collected by the Usage Monitor for each program are not affected by this setting.

A change to this setting takes effect at the next collection repository switch.

Y: Specifies that the name of each job running a program is to be collected.
N: Specifies that only a broad address space category of each job running a program is to be collected, instead of the individual job name.

If no JNM command has been issued, then job names are collected. JNM(Y) is the default.

LDD - Deactivate LOAD exclusion entries

LDD is used to deactivate a LOAD exclusion entry previously activated by the LDX command. Names specified as operand values should exactly match names already used in LDX commands.

pgm-name: Specifies a 1 - 8 character program name.

LDX - Add or activate a LOAD exclusion

The Usage Monitor tracks programs that are given control as well as those that are loaded into storage even if they are not explicitly given control. When these events occur, the programs involved are deemed to be used. However, there are some auditing and administration software components which bring modules into storage for the purposes of analysis or extracting product enablement status information. In these cases, it is not helpful to say that the target programs were used.

The LDX command is used to exclude these cases from collected usage data. The relevant program names are supplied as values in LDX commands. The programs named in LDX commands are those programs which perform the analysis or which issue the status request of numerous and perhaps varying subject programs.

Programs which are the subject of LINK or LOAD and DELETE requests issued by a program named in an active LDX setting are excluded from usage data collection.

pgm-name: Specifies a 1 - 8 character program name.

LPA - Set link pack area program monitoring status

LPA is used to specify whether the monitoring of programs in the Link Pack Area (LPA) is to occur or not. All types of LPA are included in this category.

Y: Specifies that LPA program usage is to be monitored.
N: Specifies that LPA program usage is not to be monitored.

If no LPA command is issued, then LPA program usage data is collected. LPA(Y) is the default setting.

A change to this setting does not take effect until the next collection repository switch.

LRD - Deactivate a long-running program entry

LRD is used to deactivate an entry created by a previous LRP command, or an entry created from the system program properties table. Job step programs with names matching inactive entries will not be treated as long-running programs by the Usage Monitor. Names specified as operand values should exactly match names specified either in a previous LRP command or in the system’s program properties table.

pgm-name: Specifies a 1 - 8 character program name.

LRP – Specify long-running program

LRP is used to inform the Usage Monitor that the named program is to be considered as long-running and that the CPU time for the address space is to be entirely attributed to the named program. While this does mean that CPU time for dynamically invoked programs will not be tracked, it does mean that CPU consumption can be monitored without having to wait until the job step terminates. You can use the LRP(*DFLT*) command to undo any LRD and LRP commands that have been processed.

pgm-name: Specifies a 1 - 8 character program name.

The initial list of long-running program names is formed from the system’s program properties table active at the time that the Usage Monitor is started.

MCL – Set the data set SMS management class

The MCL command is used to override the management class that is assigned to dynamically created output data sets by the system’s ACS routines. You may use this, for example, to inhibit backing up the data sets, or to assign a relevant space management policy.

mgmtclas: Specifies a 1 - 8 SMS management class name.

PAK – Set the zip compaction level

The PAK command is used to set the level of zip compaction that the writer task will use when writing to the dynamically created output data sets. The level is specified as a single decimal digit in the 0 to 9 range. Level 0 specifies that the zip shrink method is used. Levels 1 to 9 specify that the corresponding compaction level of the deflate method is used. The default is 1 which is the fastest deflate compaction level.

Larger PAK values will increase data compression but will also consume disproportionately more CPU time.

n: specifies a single decimal digit from 0 to 9.

If no PAK command is issued then PAK(1) will be used, resulting in a fast deflate zip file.

PLN - Set the sysplex name

PLN is used to override the name of the sysplex contained in the output header record. The actual sysplex name is used as a norm, but an override allows control over which systems have their inventory updated when the PLX=Y Inquisitor setting is used. The value specified here should match the PLEXNAME= value specified for the corresponding Inquisitor scans. Overriding the sysplex name is not usually needed unless PLX=Y is used and the sysplex grouping does not match the shared DASD grouping. Symbols can be employed in the construction of the sysplex name. Available symbols include all z/OS® system symbols, &SMF, the SMF identifier for the system, and &SYSLPAR, the logical partition name for the system.

plexname: Specifies a string which is to be resolved to an identifier 1-8 bytes in length.

PRE - Collect usage for long running programs

PRE is used to specify if the Usage Monitor is to collect usage for programs which started before the current collection cycle. Without this data collection a Usage Monitor collection cycle will have no usage data for programs which started running before the cycle started and remain running when the cycle ends. If a job or task runs for more than two days, most days will not have any usage recorded for the main program unless this additional data collection is enabled.

When the additional data collection is enabled, previously fetched programs resident in the regions of started task and batch job address spaces where SMF interval recording is active have usage recorded in each collection cycle which encompassed the end of at least one SMF interval.

This setting can affect usage figures. For example, the main program of a constantly running task can accrue a usage count of around 30 over a month even though it was really only used once for an extended period.

Y: Specifies that usage for previously running programs is to be collected.
N: Specifies that usage for previously running programs is not to be collected.

The default setting of PRE (Y) applies each time the Usage Monitor is started.

PRI - Set the data set space primary allocation

PRI is used to specify the primary space allocation quantity in tracks. It is used for output data set allocations.

trks: Specifies a number of tracks from 0 to 150,000.

If no PRI command is issued, the primary space allocation is 750 tracks. The Usage Monitor uses the RLSE space allocation attribute.

The following example code sets the primary space allocation to 900 tracks.

F HZAJMON,PRI(900)

PRS - Set registered software activity data collection status

PRS is used to specify if the Usage Monitor is to output records containing information about the activity of registered software. Registered software uses the system Register service. The data contains information about the usage of registered software, and information about software registration settings from the PARMLIB member IFAPRDxx.

A change to this setting does not take effect until the next collection repository switch.

Y: Specifies that registered software information is collected and output.
N: Specifies that registered software information is neither collected or output.

If no PRS command is issued, then registered software data is collected. PRS(Y) is the default.

QSZ - Specify collection element queue area size

QSZ is used to specify the virtual storage size of the SCOPE=COMMON memory object which forms the area where collected usage data is queued to the Usage Monitor address space for storing into the collection repository. The QSZ value specifies the number of storage segments the area occupies, where a segment is one megabyte in size.

The QSZ value used is fixed for the life of the Usage Monitor address space. To change the QSZ value the Usage Monitor started task must be recycled.

segments: Specifies a number of segments from 1 to 200.

If no QSZ command is issued, a 10MB queue area will be used. The queue area is processed as a LIFO stack, which means that only the necessary number of pages needed to hold the peak queue length will need to be backed by physical storage, no matter how large the QSZ value is set.

REF - Refresh Usage Monitor settings

REF is used at any time to reset Usage Monitor settings according to commands in the HZAZIN file, without stopping and starting the Usage Monitor. The detailed results of the refresh operation are written to the HZAZMSG file.

The processes of a refresh operation include:

Verify that HZAZIN is still allocated.
Open HZAZIN.
Set the program exclusion list to the default list.
Deactivate all data set exclusion list elements.
Deactivate all data set inclusion list elements.
Process the commands in HZAZIN.
Close HZAZIN.
Issue either HZAZ059I or HZAZ060I, as appropriate.

The following example code changes Usage Monitor settings to updated values from HZAZIN.

F HZAJMON,REF

SCL – Set the data set SMS storage class

The SCL command is used to override the storage class that is assigned to dynamically created output data sets by the system’s ACS routines.

storclas: specifies a 1 – 8 character SMS storage class name.

SEC - Set the data set space secondary allocation

SEC is used to specify the secondary space allocation quantity in tracks. It is used for output data set allocations.

trks: Specifies a number of tracks from 0 to 150,000.

If no SEC command is issued, the secondary space allocation is 300 tracks. The Usage Monitor uses the RLSE space allocation attribute.

The following example code sets the secondary space allocation to 600 tracks.

F HZAJMON,SEC(600)

SID - Set the Usage Monitor system identifier

SID is used to override the system identifier contained in the output header record. The SMF system identifier is used as a norm, but an override enables the data from separate systems to be differentiated in all instances where duplicate SMF identifiers are in use. Symbols can be employed in the construction of the system identifier. Available symbols include all z/OS® system symbols, &SMF, the SMF identifier for the system, and &SYSLPAR, the logical partition name for the system.

sid: Specifies a string which is to be resolved to an identifier 1-4 bytes in length.

Table 4. Examples of using the EXC command
EXC command examples for resetting the exclusion table or excluding the collection of data.
Command purpose	Example code
Set the output system identifier to PROD.	`F HZAJMON,SID(PROD)`
Set the header record system identifier to the current LPAR name. The LPAR name must not exceed four characters in length.	`F HZAJMON,SID(&SYSLPAR)`

SIZ - Set the data space repository size

SIZ is used to specify the maximum number of entries that the collection repository can hold.

entries: Specifies a number of entries from 100 to 6,000,000.

If no SIZ command is issued, a data space capacity of 200,000 entries is used. Each entry occupies 232 bytes and contains a pointer to a separate part of the repository dedicated to holding data set and UNIX® file names. Storage is conserved by only storing a single copy of each collected data set and UNIX® file name. As each repository page has data placed in it for the first time, that page must be backed physically by the system. When a collection repository is full, a repository switch is triggered automatically. A repository switch also occurs when data stamped after the switch time is detected, or when a manual switch is requested by the SWI command.

The following example code sets the size of future collection repositories to 1,000,000 entries.

F HZAJMON,SIZ(1000000)

SJS - Controlling spawned job suffix preservation

When a spawned address space is created by a unit of work with a job name that is shorter than eight characters, the system appends a sequence digit in the 1 to 9 range to the job name, and this becomes the job name of the spawned address space. This approach means that the usage of programs generated by jobs with a specific name can be logged under as many as ten different job names. The system-generated job names usually do not assist in identifying the source of the work because there is often no other reconciliation data which also uses these generated names.

The SJS setting can be used to remove the spawned sequence number suffix so that all usage events for programs are logged under the original job name, resulting in fewer Usage Monitor records and reduced processing time. If the spawning job name is eight characters long and ends in a digit in the 1 to 9 range, then activity in spawned address spaces (but not the original address space) can be reported under a job name which is only the first seven characters of the original job name. If this is likely to present a problem then use SJS(N).

Y: Spawned job name suffix digit is truncated.
N: No editing is performed of spawned address space job names.

SJS(Y) is the default if no SJS command has been issued since the Usage Monitor started.

SWI - Switch to a new collection repository

SWI causes a new collection repository to be created and used for subsequent data collection. A writer task processes the data contents of the repository that is being used at the time that the SWI command is issued.

The SWI command has no operands. It is invalid in the HZAZIN initial command file. As well as the switch caused by an explicit SWI command, automatic switches occur when a repository becomes full, and when data stamped after the switch time is detected. The SWI command might be rejected if the writer task is busy.

The following example code manually switches to a new repository.

F HZAJMON,SWI

TMP - Set temporary data set collection status

TMP is used to specify how program libraries with system generated names are to be processed. Normally the Usage Monitor discards information about programs fetched from temporary data sets since the library will no longer exist after the job ends and so will not form part of the persisting software inventory. However, if you wish to collect usage data from programs residing in temporary data sets then you can set TMP(Y).

Y: Specifies that usage containing temporary data set names is collected.
N: Specifies that usage containing temporary data set names is discarded.

If no TMP command is issued, then program usage events pertaining to temporary data sets are discarded. TMP(N) is the default setting.

UID - Control the collection of user details

UID is used to specify whether the Usage Monitor collects the identifiers and names of users who use programs or not. If the details of users who use the various programs are not considered to be important, then you can dispense with the collection of this information. The advantage of not collecting user information is the reduction in processing times and data volumes.

When user information is not collected, the user ID data item remains blank, and user names are not output, regardless which UNM setting is current. The total usage counts collected by the Usage Monitor for each program are not affected by this setting.

If you want program usage attributed to individual users but do not want the names of users to be retained, use UID(Y) and UNM(N).

A change to this setting does not take effect until the next collection repository switch.

Y: Specifies that details of each user using a program are to be collected.
N: Specifies that details of each user using a program are not to be collected.

If no UID command is issued after IPL, user details are collected. UID(Y) is the default.

UNK - Set the unknown event collection switch

UNK is used to specify whether events with incomplete data are to be collected or not. The database content is not affected. Collecting extra data is useful in determining why some usage events are not captured. It must be set only when requested by support.

Y: Specifies that the "unknown" events are to be collected.
N: Specifies that the "unknown" events are not to be collected.

If no UNK command is issued, the unknown events are not collected. UNK(N) is the default setting.

A change to this setting does not take effect until the next collection repository switch.

UNM - Set user name collection status

Software security packages, such as RACF®, have a name field for each user ID defined to the system. The Usage Monitor collects the user ID (up to eight characters long), and the contents of the name field (up to 20 characters long), as part of the data collection performed when programs are used. UNM is used to specify whether the names of users collected from the security package are output. The output of the user ID is controlled by the UID setting. This setting is checked by the writer task when the data in a collection repository is being processed for output.

Y: Specifies that collected user names are written to the output file.
N: Specifies that collected user names are discarded.

If no UNM command is issued, then user names are collected. UNM(Y) is the default.

A change to this setting does not take effect until the next collection repository switch.

UNT - Set the data set allocation unit

UNT is used to specify the allocation unit to be used for output data set allocations.

Unitname: Specifies a 1 - 8 character long unit name.

If no UNT command is issued, SYSALLDA is used.

The following example code sets the allocation unit to WORKDA.

F HZAJMON,UNT(WORKDA)

USS - Set UNIX® program monitoring status

USS is used to determine if the programs retrieved from Hierarchical File System (HFS) files are to be monitored.

Y: Programs fetched from HFS files are to be monitored.
N: Programs fetched from HFS files are not to be monitored.

If no USS command is issued, the programs retrieved from HFS files are not monitored. USS(N) is the default setting.

A change to this setting does not take effect until the next collection repository switch.

VOL - Set the data set allocation volume

VOL is used to specify the allocation volume to be used for output data set allocations. The explicit nomination of a specific volume is necessary when there are no PUBLIC or STORAGE volumes in the allocation unit pool.

volume: specifies a 1 - 6 character long volume serial number.

If no VOL command is issued, a specific volume is not explicitly requested. You must then have PUBLIC or STORAGE volumes in the public allocation pool, unless the data sets are managed by SMS.

The following example code sets the allocation volume to SCR001.

F HZAJMON,VOL(SCR001)

WRT - Set the automatic switch-and-write time of day

WRT is used to specify a time-of-day to end data collection for the current collection repository, and automatically switch to a new one. The data write-out for the closed repository is also initiated at the same time. These events are triggered when data from after the specified time is detected.

The UTC or GMT switch time is calculated using the local time when the repository is created. The time that a data space is terminated is set when it is created. Changes to the system local time offset, such as those caused by a change to daylight saving time status, do not alter the UTC or GMT time that the current repository is closed. The time of the switch, after the next switch, is calculated using the new local time.

hhmm: Specifies a 24-hour time-of-day in hour and minute notation. The value must be four decimal digits. The first two digits (hh) must be in the 00 - 23 range. The last two digits (mm) must be in the 00 - 59 range.

If no WRT command is issued, the automatic switch time of midnight is used. That is, WRT(0000) is the default.

The following example code sets the automatic switch-and-write time to 10 minutes before midnight.

F HZAJMON,WRT(2350)

XDD - Deleting data set name exclusion entries

XDD is used to remove data set name masks which were added by the XDS command. XDD can also deactivate entries from the default exclusion list that was automatically created by the Usage Monitor.

If a mask of *ALL* is specified then all (both default and user) data set exclusion masks are deactivated.

mask: Specifies a 1 - 44 character data set name mask. Any wildcard characters in the mask are treated as literals for the purposes of finding the mask to delete.

The following example code deactivates the SYS3.* exclusion mask.

F HZAJMON,XDD(SYS3.*)

XDS - Adding data set name exclusion entries

XDS is used to supply data set name masks which specify data set names to be excluded from data collection. Program usage data for programs fetched from data sets with names matching exclusion masks is discarded. When the captured data set name has been matched to an inclusion mask set by the IDS command, the data is collected without reference to the user-defined exclusion mask list. Usage data matching active default data set exclusion masks is discarded before inclusion masks created by IDS commands are examined. Any inactive default exclusion masks can be reactivated by the XDS(*DFLT*) command which does not affect user-specified data set filtering.

mask: Specifies a 1 - 44 character data set name mask. Generic wildcard matching allows a percent sign to match any single character, and an asterisk to match any group of zero or more characters. If the mask contains a slash character (/), the value is considered to be processed as a UNIX path name mask rather than a data set name mask.

The following example code excludes program usage data from collection for programs fetched from data sets with a high-level qualifier of SYS3.

F HZAJMON,XDS(SYS3.*)

ZIP - Set the compressed output data switch

ZIP is used to control whether the writer task is to compress output data or not. Compressing the output data reduces data volume, in turn reducing data transfer time and storage space requirements.

Y: Specifies that output data is to be compressed.
N: Specifies that output data is not to be compressed.

If no ZIP command is issued, then compressed data is output. ZIP(Y) is the default setting.

If abend S213-C8 occurs when the writer task opens the output data set, ZIP(N) will be issued internally and the data will be written without being zipped. In this case, the following WTO message will be issued:

HZAZ033I UMON-WTR ZIP(N) COMMAND PROCESSED