Setting up the Usage Monitor

Files used by the Usage Monitor

Output files containing program usage data are dynamically allocated by the Usage Monitor. The data set name prefix, the allocation unit, and the primary and secondary space allocation quantities (in tracks), need to be customized for the target system. This is done in the PARMLIB member HZASMNPM.

Using exclusion masks to reduce data

The data from a significant number of program usage events does not contribute meaningfully to the task of managing the software inventory. To reduce the processing of this unnecessary data, two mechanisms that allow some data to be excluded from collection are provided. They are exclusion masking based on program name, and exclusion masking based on data set name.

Filtering by program name

A program name exclusion table exists which contains program name masks. When a program usage event is detected by the Usage Monitor, the program name is checked against entries in the program name exclusion table. When a match is found, the usage event data is discarded. Program name exclusion filtering occurs before the data set name of the program library is determined by the Usage Monitor, which makes it more efficient than data set name filtering.

Each table entry contains a program name comparison string up to 8 bytes long. The string is either an 8-byte program name, or a shorter program name prefix. When entering these strings with the EXC command, a prefix is denoted by using an asterisk as the last character.

The program name exclusion table resides in key zero common storage, and its size is always a multiple of 4,096 bytes. The minimum table size can house up to 253 entries, and the table size increases dynamically, as required. The default program name exclusion table contains entries to exclude data pertaining to the usage of many programs which are part of the operating system.

Filtering by calling program name

For program use events resulting from LINK, LOAD and DELETE requests (but not from ATTACH requests) an additional filtering check is made against the name of the program that issued the request. This facility allows the exclusion of usage generated by software auditing and reporting tools, as well as other administrative tools which invoke programs to report whether the owning component is enabled or disabled.

To state it another way, this is an indirect filtering facility where usage of the named program is not excluded, but programs fetched by the named program do have their usage excluded no matter what names those programs have.

There are no default entries for this filtering – all entries in this filter list are supplied via the LDX command. The LDD command is available to deactivate previously added entries. Exact program names (with no masking) up to 8 characters long must be specified when using LDX and LDD commands.

Filtering by data set name

After the Usage Monitor has ascertained the name of the data set from which a used program is fetched, it is used to decide if the usage data is retained for collection or discarded. To perform this process, three lists of data set name masks are scanned; the first is the default data set name exclusion list, the second is the dynamic data set name inclusion list, and the third is the dynamic data set name exclusion list.

The default data set name exclusion list is built during Usage Monitor initialization, and consists of the SCEERUN library, the SCEERUN2 library, SYS1.CMDLIB (containing TSO commands), SYS1.CSSLIB (containing callable services modules), and masks for data set names ending with DBDLIB and PSBLIB. The data set names of the SCEERUN and SCEERUN2 Language Environment® libraries are determined by searching the link list for specific LE modules. You can use the XDD command to deactivate any of these default exclusion entries. You can use the XDS(*DFLT*) command to reactivate the default data set exclude list without affecting the status of masks in other lists.

The other two lists are constructed from commands you specify either in the HZAZIN file or dynamically via the system MODIFY command.

To avoid excessive storage and processor resource consumption, keep the number of elements in each list to a minimum. This is achieved by using generic masks to cover many data set names. The inclusion mask list is provided so that specific exceptions to broad exclusion rules can be specified. If you do not supply any data set name exclusion masks, the inclusion list does not affect data collection, but can still be used as a convenient way to collect relative usage statistics from the regular Usage Monitor status reports.

Data set mask elements reside in key zero common storage. Each element occupies 64 bytes, and contains a data set name mask up to 44 bytes in length. You can use a percent sign as a wildcard to match any single character. You can use an asterisk as a wildcard to match any group of zero or more characters. Before the mask is stored, all occurrences of *% are changed to %*, and then all occurrences of multiple consecutive asterisks are changed to a single asterisk.

In order to add, reset, remove, or display the entries to the tables, use these commands:

XDS

To add a data set name mask to the exclusion list.

IDS

To add a data set name mask to the inclusion list.

XDD

To deactivate a data set name exclusion mask.

IDD

To deactivate a data set name inclusion mask.

D-D

To display all active data set name masks.

Both of the non-default lists have no elements until an XDS or IDS command is processed. Storage is dynamically acquired for each element as required. To ensure system integrity, XDD and IDD commands do not cause the storage of a deactivated element to be freed, but mark the element as inactive. When a deactivated mask is reactivated, the existing entry is marked as active without the further acquisition of storage.

You can use the XDD(*ALL*) command to deactivate all data set exclusion masks, including those in the default list. You can use the IDD(*ALL*) command to deactivate all data set inclusion masks.

When the Usage Monitor address space first initializes, all elements of lists that remain in storage from a previous run are freed before the processing of initial commands and the commencement of data collection.

The default exclusion list is provided to reduce overhead by discarding data that does not assist with product use identification, and while additional data set filtering is provided for local use, it is expected that for many systems no customization of data set filtering would be necessary.

Filtering by UNIX® path name

If the mask value specified in an IDS, XDS, IDD, or XDD command contains at least one slash, the value is deemed to be a UNIX® path name mask and not a data set name mask. During processing, multiple consecutive slashes are reduced to a single slash.

UNIX® path name masks entered via IDS and XDS commands are compared to the path names specified by applications at run time and may not correspond to the path names against which usage is attributed. The main cause for this difference in path names is the use of symbolic links. The Usage Monitor writer task converts path names with symbolic links to real path names in order to match inventory discovered by the Inquisitor.

Do not use an IDD or XDD command that specifies a UNIX® path name mask because the only use for such a command is to dynamically delete a UNIX® path name mask. Most UNIX® path name masks contain lowercase alphabetic characters. The system MODIFY command interface usually changes lower case characters to upper case which prevents the mask matching the relevant active mask. To delete a UNIX® path name mask you must either recycle the Usage Monitor or use the REF command to refresh the settings from the HZAZIN file. In either case, all UNIX® path name masks are deactivated and the necessary change is to remove the IDS or XDS command that you want to deactivate from the HZAZIN file.

Similarly, because of the prevalence of lower case alphabetics in UNIX® path names, you only specify IDS and XDS commands with path name masks as HZAZIN file input rather than via the MODIFY system command interface.

The length limit of 44 characters also applies to UNIX® path name masks.

Recording CPU time

The Usage Monitor will attempt to record the CPU time used by each program. This is only done for task-type programs that receive control from the operating system’s contents supervisor. Programs which are pre-loaded and then branched to will not accrue any recorded CPU time. Recorded CPU time for a program may include time for programs and services that it has invoked, including programs that have been excluded from collection, but will not include time attributed to other monitored programs.

Accumulated CPU time is logged in the collection repository when a monitored program ends. This means that CPU time for long-running jobs will either not be collected, or will be collected once when the component is shutdown, perhaps even with the bulk of the CPU time being due to activity in prior collection cycles, which could compromise the value of that data.

For this reason, the Usage Monitor can collect consumed CPU time differently for those address spaces which are classed as being long-running. For these address spaces, all the consumed CPU time will be attributed to the job step program, with the CPU time values being sourced from the SMF30CPT field of type 30, subtypes 2 and 3 SMF records. The previously described CPU time tracking at the request block level will not be performed for these address spaces.

Long-running address spaces are recognized by their job step program name. The initial list of long-running program names is formed from the system’s program properties table at the time that the Usage Monitor is started. Additional names can be added by issuing the LRP command. Existing entries in the long-running program name list can be deleted by the LRD command. The Usage Monitor will deem an address space to be long-running if its job step program name matches any active entry in this name list. The Usage Monitor does not check whether any of the properties described by the PPT entry are actually assigned. Only started task and batch job address spaces are checked for being long-running.

This facility allows the Usage Monitor to report CPU time used by CICS, IMS control region, DB2 and MQ subsystem, and various other address space types without having to wait until those address spaces terminate.

In order to add, remove, or display the entries in the long-running program name list, use these commands:

LRP

To add one or several entries to the long-running program list.

LRD

To remove one or several entries from the long-running program list.

D-L

To display active long-running program name entries.