The generic tracker facility

The intended purpose of generic tracker is to be a migration aid and to help assess exploitation of old and new function. For example, you can assess use of interfaces you intend to make obsolete, and assess exploitation of old and new function in general. For functions that are already obsolete in a new release, you can use generic tracker to assess their use on previous releases.

The generic tracker Facility is a tracking facility that provides theses services.

A callable tracking service that users can instrument code with:
- The caller passes an event address and other related information to the service.
- The service attempts to resolve the event address to a program name and store it with the other information for later analysis.
Provides a callable “query” service that extracts previously stored track records and tracking facility information.
Provides operator commands to display and maintain tracking facility information and configuration details.
Supports parmlib members for easy reuse of tracking facility configuration statements.
Provides more tools to aid in the use of the tracking facility and the information it stores.

The generic tracker Facility replaces the Console Tracking Facility, which was available in releases before z/OS® V2R1. The Console Tracking Facility operator commands are available only in releases before z/OSV2R1. Macro CNZTRKR continues to be supported, but the recommendation is to use macro GTZTRACK instead. Any information CNZTRKR collects is stored in the new tracking facility. Do not continue touse service CNZTRKR. When possible, replace existing CNZTRKR invocations with GTZTRACK invocations.

The generic tracker consists of the following parts:

A system parameter named GTZ - see z/OS MVS Initialization and Tuning Guide.
Support for GTZPRMxx parmlib members. See z/OS MVS Initialization and Tuning Guide
- Shipped with GTZPRM00, which includes an exclusion list.
Operator commands. See z/OS MVS System Commands.
- SET GTZ – add GTZPRMxx members
- SETGTZ – control the tracking facility
- DISPLAY GTZ – report tracking facility information.
Callable macro services. See z/OS MVS Programming: Assembler Services Reference ABE-HSP.
- GTZTRACK – track an event
  - Associated mapping macro GTZZTRK
- GTZQUERY – report tracking facility information
  - Associated mapping macros for Assembler (GTZZQRY) and METAL-C (GTZHQRY)
Utility programs
- GTZPRINT – report tracking facility information
  - Associated mapping macro GTZZPRT
- GTZCNIDT – create GTZPRMxx from CNIDTRxx
  - Associated mapping macro GTZZCNI
Samples – see SYS1.SAMPLIB
- GTZCNIDJ – start utility program GTZCNIDT
- GTZPRNTJ – start utility program GTZPRINT
- GTZSHCK – a sample health to report tracked events
- GTZSHCKJ – build health check GTZSHCK.

The generic tracker is a system address space that starts automatically during the IPL of the system. A restart is not required or recommended unless it is explicitly requested, for example to apply service. The source of the IBM® supplied started procedure GTZ can be modified to configure the MEMLIMIT, which determines how much information the tracking facility can store.

Actual tracking (that is, recording track events) is disabled by default. When tracking is disabled, invocations of GTZTRACK are allowed, but ignored by the system. Use the SETGTZ TRACKING=ON operator command to enable tracking.

Before you enable tracking and allow the tracking facility to store data and report it back to the users, consider protecting the DISPLAY GTZ and SETGTZ operator commands. As mentioned in z/OS MVS System Commands, these GTZ commands can be protected by RACF® resource profiles for the OPERCMDS class. The security administrator can for example take the following steps to give a user profile access to the MVS™.SETGTZ.GTZ resource:

Ensure that the OPERCMDS class is active:

SETROPTS CLASSACT(OPERCMDS) RACLIST(OPERCMDS)

Create the MVS.SETGTZ.GTZ resource profile and require explicit access to be given:
```
RDEFINE OPERCMDS MVS.SETGTZ.GTZ UACC(NONE)
```

Grant individual access to the resource:

PERMIT MVS.SETGTZ.GTZ CLASS(OPERCMDS) ID(user) ACCESS(UPDATE)

Refresh the OPERCMDS class to activate the changes:
```
SETROPTS RACLIST(OPERCMDS) REFRESH
```

All SETGTZ operator commands can be used in GTZPRMxx parmlib members. For example, you can put a TRACKING=ON statement into a GTZPRMxx parmlib member.

System parameter GTZ can be set to one or more suffixes, which identify the GTZPRMxx parmlib members that the tracking facility must process at startup. See the description of system parameter GTZ in z/OS MVS Initialization and Tuning Reference. It contains requirements and details on how to grant the tracking facility permission to access the parmlib members at start-up. If you do not specify system parameter GTZ, or specify PARM='GTZPRM=*NONE' in procedure GTZ, the tracking facility will start without reading any parmlib members initially.

You can add more GTZPRMxx parmlib members later with the operator command SET GTZ.

You can use the SETGTZ CLEAR operator command to remove configuration data previously added via GTZPRMxx members and to remove previously recorded track data.

To prevent certain “known” track events from recording any data, you can add EXCLUDE statements. The tracking facility will ignore any future track data that matches such EXCLUDE filters and it will remove any matching previously recorded track data. Typically EXCLUDE statements are provided in GTZPRMxx parmlib members and can be specified via the SETGTZ EXCLUDE operator command as well.

A standard list of EXCLUDE statements for known track events is shipped in parmlib member GTZPRM00. You can download it from the z/OS Downloads website, http://www.ibm.com/systems/z/os/zos/downloads/. It is recommended that you use the GTZPRMxx parmlib member as is and enable it by default by adding the 00 suffix to the system parameter GTZ in IEASYSxx using GTZ=(00,<your suffixes>). Keeping GTZPRM00 separate allows for easier updates when z/OS releases a new GTZPRM00 version. More GTZPRMxx parmlib members would then have any additional EXCLUDEs and for example a TRACKING=ON, if wanted.

If you used the Console Tracking Facility and its CNIDTRxx parmlib members for exclusion lists before, you can use the GTZCNIDT utility program to create GTZPRMxx parmlib members from existing CNIDTRxx parmlib members. The sample JCL GTZCNIDJ explains how to start GTZCNIDT.

A unique tracked event is identified by the following fields, which are referenced by the EXCLUDE filters. The tracking facility increments an associated occurrence count if a GTZTRACK call results in an identical set of unique fields:

The program name and program offset as resolved from the passed in event address.
The name of the “owner” and “source” of the track event.
The event description text.
The (binary) event data.
Job names and ASIDs associated with the track event.
The authorization state that is associated with the track event.

For events that are difficult to track, where the program name cannot be determined by the system from the passed in event address, you can define DEBUG filters using the SETGTZ DEBUG operator command or in a GTZPRMxx parmlib member. The DEBUG statement allows for example to trigger a non-percolating ABEND, code E77, with custom reason codes, that you can define SLIP traps for to collect dumps

You can use the DISPLAY GTZ operator command to display:

General status and statistics for the tracking facility – DISPLAY GTZ[,STATUS].
All or a subset of the track data that is currently stored in the tracking facility – DISPLAY GTZ,TRACKDATA[(filters)].
All the EXCLUDE statements – DISPLAY GTZ,EXCLUDE.
All the DEBUG statements – DISPLAY GTZ,DEBUG.

Using the utility program GTZPRINT, you can collect information in a data set instead of reading it on the console or in the system LOG. The sample JCL GTZPRNTJ explains how to use GTZPRINT.

Here are some typical scenarios

Use GTZPRINT to preserve tracking information for later analysis. This helps when you must submit the information to IBM, or an independent software vendor (ISV) product to have them analyze the output or diagnose problems.
Use DISPLAY GTZ for quick interactive access. Certain command line and output length limits might apply.
Use callable macro service GTZQUERY when you want to access tracking facility information from a program. For example, for a custom reporting tool or for a health check for the IBM Health Checker for z/OS. See the sample health check GTZSHCK shipped in SAMPLIB. This can be built with the sample JCL GTZSHCKJ. While local health checks run authorized, other uses of GTZQUERY require the calling user ID to have access to the GTZ.<sysname>.QUERY RACF profile that is used similar to how the GTZ operator commands are protected.

References for IBM tracked events

Event description starting with SMS-
- See the “EAV migration assistance tracker” section in z/OS DFSMSdfp Advanced Services.
Event description 'IEFALC 01: <step name> <DD name>’
- See message IEF384I “WARNING: VOLUME NOT RETRIEVED FROM catalog”.