Setting up the Usage Monitor

The Usage Monitor has three product-specific files. They are:

UMONIN

A sequential file consisting of fixed length 80 byte records. It contains initial commands which are run before data collection becomes active. It must contain the data set prefix to be used for dynamically created output files. The prefix can be changed later by an operator MODIFY command.

UMONIN is opened, read, and closed during initialization processing. Do not specify FREE=CLOSE in the JCL for UMONIN, or refresh processing is not possible.

Data set contains the high-level qualifier listing for products and is populated by the IQ Import job (HZASIQIM). To minimize the number of records to be created by the Usage Monitor, only usage events that match the list of products in this data set are generated. To activate this facility, in , uncomment data set as described in PROC HZAJMON.

UMONMSG

A log file which contains the initial commands issued, and which indicates their degree of success. It also contains regular status reports, writer reports, refresh reports (when appropriate), and a termination report. It consists of fixed-length 121-byte records.

DASDMAP

An optional file containing logical volume mapping assignment statements.

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.

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.

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 contains numerous default entries to exclude data pertaining to the usage of many programs which are part of the operating system. You can use the DEL(*ALL*) command to deactivate all default program filter entries, and the EXC(*DFLT*) command to reactivate all default program filter entries.

Unlike masks added by the EXC command, default program name exclusion masks do not exclude job step program usage events. For example, the IEF* default exclusion mask excludes dynamic calls and loads of program IEFBR14, but usages where IEFBR14 is invoked by JCL are not excluded by this mask.

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.

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 UMONIN 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 name mask values are specified as a character string 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.

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.

Both of the non-default lists have no elements until an XDS or IDS command is processed. 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.

However, if you want to take the approach of only monitoring programs from program libraries known to contain program product software, you can adopt the HLQIDS scheme that flows from the HZASCUST process which creates a UM.HLQIDS data set to be added to the UMONIN DD concatenation. UM.HLDIDS contains a XDS(*) setting to exclude all data sets followed by IDS settings with masks that include the high-level qualifiers of program libraries. You should verify that XDS(*) is not the only setting in the UM.HLQIDS data set before using it.

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 UMONIN 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 UMONIN 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 UMONIN file input rather than via the MODIFY system command interface.

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

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.