Introduction to data areas, control blocks, and monitor records for z/VM V5R3.0

These web pages contain descriptions of the major data areas and control blocks used by CMS and CP for communication between components and program modules of z/VM Version 5 Release 3.0. Note that the CP image in z/VM Version 5 is 64-bit only.

The web page for Performance Toolkit for VM describes the layout of the information in the discontiguous saved segment (DCSS) when Performance Toolkit is enabled to work with a formatted output collector.

The monitor records data is communicated to application programs by the *Monitor CP system service and is reflected in domain numbers and associated records.

The data areas, or scratch areas that exist only during the execution of a particular module are not included with this information.

Programming interface information

These web pages primarily document information that is NOT intended to be used as a Programming Interface of z/VM.

These web pages also document intended Programming Interfaces that allow the customer to write programs to obtain the services of z/VM. This information is identified where it occurs by an introductory statement.

Intended audience

The data areas and control block information is intended for use by people responsible for interpreting CMS and CP storage dumps and for determining the status of the program or system at the time of a problem.

The Performance Toolkit data area is intended for use by a formatted output collector (such as OMEGAMON XE on z/VM and Linux).

The monitor records information is intended for use by people responsible for the diagnosis of the CP component of z/VM as well as those that monitor system performance.

Prerequisite knowledge

Persons using this information are expected to be knowledgeable with the CMS and CP components of z/VM and with assembled code.

The following is a list of suggested prerequisite reading:

  • IBM Enterprise Systems Architecture/370 Principles of Operation
  • IBM Enterprise Systems Architecture/390 Principles of Operation, SA22-7201
  • IBM Enterprise Systems Architecture/Extended Configuration Principles of Operation, SC24-6094
  • IBM z/Architecture Principles of Operation, SA22-7832
  • IBM OS/VS, DOS/VSE and VM/370 Assembler Language
  • IBM System/370 Extended Architecture Principles of Operation
  • IBM System/370 Architecture Principles of Operation, GA22-7000
  • z/VM Performance, SC24-6109
  • z/VM Performance Toolkit Guide, SC24-6156
  • z/VM Performance Toolkit Reference, SC24-6157

How the data areas and control block information is organized

This information is arranged in alphabetic order by the DSECT name. If the DSECT is part of a larger control block, the larger will be displayed. Most data areas or control blocks include a brief description at the beginning which is called a Prolog. If such a Prolog exists, it is followed by the Control Block Content, which describes the fields of the data area or control block in the following manner:

  • The displacement in both hexadecimal and decimal

  • The type/value

  • Its length in decimal bytes (An asterisk in this column indicates there is no symbol name. This usually means that the field is reserved.) If there is a duplication factor, it will be enclosed in parenthesis after the name of the field.

  • The name of the field

  • A brief description

The Control Block Content is followed by a graphic representation of the Storage Layout. And finally, an alphabetic Cross Reference is included which lists the labels in the data area. For general equates, the hexadecimal value is listed along with a displacement that refers to the position in the main Control Block Content for which the full information for that label can be found.

Understanding the Storage Layout

The Storage Layout provides an aid in locating fields within a control block. These graphic representations become valuable to those who can read and understand them. They display the hexadecimal displacements and field names in the respective locations. However, there are a few special elements that you need to know about. Let's take a look at them.

    ****       XMPBK - Example Block
    *     +------+------+-------------+------+------+------+------+
    * 190 |:FSYNC|:FTPNL|                                         |
    *     +------+------+                                         |
    *     |                                                       |
    *     =                        XMPFTPN                        =
    *     |                                                       |
    *     |             +-----------------------------------------+
    * 1D0 |             |/////////////////////////////////////////|
    *     +-------------+/////////////////////////////////////////|
    *     |///////////////////////////////////////////////////////|
    *     |////////////////////////////////////////////////+------+
    * 1E0 |////////////////////////////////////////////////|:FLUWL|
    *     +------------------------------------------------+------+
    * 1E8 |                                                       |
    *     =                        XMPFLUWI                       =
    *     |                                                       |
    *     |             +------+----------------------------------+
    * 200 |             |:FCCL |             XMPFCC-              |
    *     +-------------+------+------+-------------+------+------+
    * 208 |      -XMPFCC       |:CFLAG|   XMPCPLEN  |//////|(20F)-|
    *     +--------------------+------+-------------+------+------+
    * 210 |     -XMPCPADR      | 213
    *     +--------------------+

In order to read this more accurately, you should understand the following field aids:

The colon represents the first three letters of the control block's name. In this example, you would replace the colon with XMP and the field names are XMPFSYNC and XMPFTPNL.
    * 190 |:FSYNC|:FTPNL|                                         |
    *     +------+------+                                         |

The equals shows the field spans several lines and not all of the lines are displayed. For example:
    *     +------+------+                                         |
    *     |                                                       |
    *     =                        XMPFTPN                        =
    *     |                                                       |
    *     |             +-----------------------------------------+
    * 1D0 |             |/////////////////////////////////////////|

The repeated slash shows that the area is reserved or not used. For example:
    *     |             +-----------------------------------------+
    * 1D0 |             |/////////////////////////////////////////|

The hyphen is used to extend a field onto an additional line. When a field spans multiple lines and space is limited, the field position is shown in parentheses followed by a hyphen to show that the field extends onto the next line (20F)-. For example:
    *     |             +------+----------------------------------+
    * 200 |             |:FCCL |             XMPFCC-              |
    *     +-------------+------+------+-------------+------+------+
    * 208 |      -XMPFCC       |:CFLAG|   XMPCPLEN  |//////|(20F)-|
    *     +--------------------+------+-------------+------+------+
    * 210 |     -XMPCPADR      | 213
    *     +--------------------+

How the monitor records information is organized

This material is divided into sections. Each section contains a description of a single record. The sections are arranged in numeric order by domain number then by record number. The main part of each record describes the fields of that record in the following manner:

  • The offset in both decimal and hexadecimal
  • The type
  • Its length in decimal bytes
  • The name of the field (sometimes with a multiplying factor in parentheses one space to the right)
  • A brief description.
A cross-reference table ends each section. This table contains an alphabetic listing of all the labels in the record. For general equates the hexadecimal value is listed along with an offset that refers to the position in the main table that the full information for that label can be found.

Keep in mind that these monitor records may not exactly match what is on your system, especially if z/VM service has been applied in a selective manner. The information presented here reflects the code as it existed at the time the product tape was prepared for General Availability.

General description of the monitor records

The monitor records generated by the z/VM Monitor Facility are placed in the saved segment defined for Monitor. The starting and ending addresses of the data is communicated to application programs by the *MONITOR CP system service.

The records are shown by domain number and, within each domain, by record number. The domains associated with each number are:

Domain Number  Domain
0 System
1 Monitor
2 Scheduler
3 Storage
4 User
5 Processor
6 I/O
7 Seek
8 Virtual Network
10 Application Data

The placement of the records within the saved segment is not guaranteed to be in any particular order by domain or within domains. This is especially true for event processing. Unless otherwise stated, all counters are cumulative counters. That is, the application program processing the data must subtract an interval's data from the previous interval value to determine how much a particular counter changed from one interval to the next. Cardinal counters are counters whose values are incremented or decremented, such as the number of logged-on users. Cardinal counters, therefore, represent a state of the system at the time it is sampled.