Previously, I’ve covered IBM’s CPU Measurement Facility (CPU-MF), which was introduced with the z10 mainframe. This month, I will discuss how to use hardware instrumentation services (HIS) to
The hardware instrumentation task
CPU-MF operates through the hardware instrumentation services (HIS) started task and must be executed on the LPAR for which you want to get statistics. HIS records the hardware instrumentation data to Unix System Services (USS) files and SMF type 113 records.
Note that HIS does not automatically record data when started. Instead you must use a series of commands for:
- Specifying the type of data to be collected
- Stopping and starting data collection
- Accessing the USS path for the output files
- Choosing which counters sets to collect
- Sampling frequency
Alternatively, you may specify a DD card pointing to a dataset containing HIS commands.
HIS output files
HIS writes three types of USS files, which follow the naming convention of SYSHISyyyymmdd.hhmmss.xxx.type, where “yyyymmdd” is the date, “hhmmss” is the time and “xxx” is a sequence number incremented for every state change during the collection run. The “type” is the file type, either CNT, MAP or SMP, as explained below. Note that the SMP, or sampling report, files have an additional node on the end, signifying the logical processor number for which HIS recorded the data.
Advice for interpreting these reports is somewhat improbably included in the z/OS MVS Systems Command manual.
- Counter Set Data File (CNT). This file lists the counter sets that HIS collected. For
each counter set, there are identifiers for each counter as well as the start and end times of the
recording interval. The actual double-word counter values follow in hex, one set for each logical
It’s a little difficult to interpret the data from this report, as you must either have a hexadecimal calculator or copy the values into a spreadsheet. However, the set and counter IDs in this report will be important, especially in interpreting the SMF type 113 records.
- Load Module Mapping File (MAP). MAP files list the virtual addresses of system-loaded
programs in any number of address spaces. These addresses may be used to cross reference the SMP
and match instruction address to modules. In addition to load modules, the report lists important
virtual storage boundaries, such as CSA and the nucleus.
The load module report itself is not readable by humans, but its fixed format is readily interpreted by a post-processor -- for instance, a Rexx program. The report includes the libraries that the modules were loaded from, so HIS must be authorized to read any STEPLIB or JOBLIB datasets in the sampled address spaces.
HIS’s dependency on system-loaded modules probably means the MAP file will be incomplete for any subsystem that does its own program management, like CICS.
- Sampling report files (SMP). HIS generates one SMP file for each logical processor. This
file is binary and not human-readable. Furthermore, IBM warns that it can become quite large and
users should be sure to allocate plenty of space to the file system that receives the output.
There are two types of entries, basic and diagnostic. The basic entry, included by default if diagnostic sampling is enabled, is 32 bytes long and contains a lot of detailed program status word (PSW) information, including instruction addresses. The actual format of the 32-byte block is in the commands manual. Note that interpretation can be a bit tricky for system code, so users must be cognizant of the address space, wait and problem state flags.
A diagnostic entry is model-dependent and must be enabled through the service element. IBM doesn’t say much about these types of entries, which I interpret to mean, “Don’t try this at home.”
Type 113 records
HIS writes counter information to SMF type 113 records at either the SMF interval (SMFINTVL) or every 15 minutes. There is one record subtype, 2.
The SMF header is standard stuff. Most importantly, the heading information contains the offset, length and number of data sections that follow. There is one data section, or subtype 2 record, for each logical processor in the LPAR.
Each data section begins with a header identifying the processor number and type along with the counters recorded for it. A sequence flag indicates if HIS recorded the data at the beginning, middle or end of a data collection run. A couple of other fields contain counter version numbers, which become important if you mix processor models in the Sysplex. Finally, there are two more triplets describing the size, number and offset of the counter set and counter sections.
The counter set section describes the counters in the corresponding counter section. Important fields include the counter set ID (e.g., basic, problem, crypto, etc.) along with a bit pattern that identifies which counters are included.
Finally, the counter section contains the array of 8-byte counters themselves. The counters have no identifying information attached to them, which makes the CNT report invaluable for interpreting the counters as they come off of the SMF record.
ABOUT THE AUTHOR: For 24 years, Robert Crawford has worked off and on as a CICS systems programmer. He is experienced in debugging and tuning applications and has written in COBOL, Assembler and C++ using VSAM, DLI and DB2.
What did you think of this feature? Write to SearchDataCenter.com's Matt Stansberry about your data center concerns at firstname.lastname@example.org.
This was first published in November 2010