Programming Interface Information:
The Monitor Records are intended Programming Interfaces that
allow the customer to write programs to obtain services of z/VM.


Control Block Contents
Cross Reference


 FUNCTION - Map a Monitor record.
        Through the Monitor Control Area
        MRRECHDR    Monitor Record Header
 DESCRIPTIVE NAME - Monitor Sample Record
        Domain 0  - System Domain
        Record 18 - Channel Path Measurement Data
 DESCRIPTION - Provide utilization data for each channel path.
   -  This record is generated only when the Channel-Path
      Measurement Facility (without extended channel
      measurements) is installed on the system.
      If the Channel-Path Measurement Facility with
      extended channel measurements is installed, then
      the MRSYTEPM Monitor record (Domain 0, Record 20)
      will be generated instead of this one.
   -  When VM is running native, this record will be
      generated only when the Channel-Path Measurement
      Facility (without extended channel measurements)
      in installed on the system.
   -  When VM is running in an LPAR in Multiple Image Facility
      mode, physical channel paths may be shared with other
      partitions. The data provided in this record represents
      channel utilization attributable to the logical partition
      in which VM is running.
   -  When VM is running second level, the Channel-Path
      Measurement Facility is not installed. Thus this
      record will not be generated.
   -  SYTCPM_CALOFFST should always be used to locate the
      SYTCPM_DATA area.
   -  A SYTCPM_CHPATH entry contains valid data only when its
      SYTCPM_INVALID bit is OFF.
   -  Each channel path entry is constructed independently, on a
      schedule chosen by the channel subsystem (CSS), rather than
      at the monitor sample interval. Thus, the analysis program
      must look at the timestamp and busy time in *each* channel
      path entry, subtract from them the corresponding values in
      the previous record, and then divide to get the busy time
      as a fraction of the interval between the two samplings
      *by the CSS* of that channel path's statistics. Two
      consequences of this extra "layer" of sampling are:
      1) Reducing the monitor sample interval will not necessarily
      give finer-grained statistics for channel path usage.
      2) Depending on when the monitor samples occur with respect
      to the channel subsystem's samples, the intervals between
      successive records may vary substantially. For example,
      if the channel subsystem samples every 5 seconds and monitor
      writes a sample record every 8 seconds, then on average,
      three out of five times, the difference between monitor
      records will represent 5 seconds of channel-path activity,
      and the other two out of five times, the difference will
      represent 10 seconds of activity.
      Finally, note that the timestamp and busy time for a given
      channel path might be identical to that in the previous
      record, if the CSS has not updated the information in the
      interval. In this case, there is effectively no interval
      reported on between this pair of records, a later record
      with a different timestamp must be used to compute usage
      for the channel path.
   -  If the SYTCPM_INVALID bit is OFF but the SYTCPM_INIT bit is
      ON in a SYTCPM_CHPATH entry, then the entry represents the
      start of a new reporting "epoch" for the channel path. A
      discontinuity in the timer values may have occurred since
      the sample in the previous SYTCPM record. That is, the
      timestamp and busy time in this entry are valid, but are not
      related to the corresponding values in the previous monitor
      record. The values in this record can only be used as a
      starting point for the interval between this record and the
      one after it. No information can be deduced about the
      activity during the period between the time of the previous
      record's sample for this channel path and that of this
      record's sample.
      The first valid SYTCPM_CHPATH entry recorded for each
      channel path will always have SYTCPM_INIT on, as will any
      entry which follows one or more entries with SYTCPM_INVALID
      ON (for the same channel path). It is also possible for
      SYTCPM_INIT to appear in an entry even when no preceding
      entry for the channel path shows SYTCPM_INVALID.

MRSYTCPM Control Block Contents

Dec Hex  Type       Len  Name (Dim)             Description
  0   0  Structure   32  SYTCPM                 
  0   0  Character    0  SYTCPM_MRHDR           Record header. See MRRECHDR
                                                for details.
  0   0  Character   20  MRHDR                  
  0   0  Unsigned     2  MRHDRLEN               record length in bytes
  2   2  Unsigned     2  MRHDRZER               field of zeros
  4   4  Unsigned     1  MRHDRDM                domain identifier
  5   5  Unsigned     1  *                      
  6   6  Unsigned     2  MRHDRRC                record identifier
  8   8  Character    8  MRHDRTOD               Time at which this record was
                                                built. In time-of-day (TOD)
                                                clock format. See IBM System
                                                370 XA Principle of Operation
                                                for explanation of format.
 16  10  Character    4  *                      
 20  14  Character    0  MRHDR_END              End of header
 20  14  Signed       4  SYTCPM_CHPATHCT        Number of SYTCPM_CHPATH
                                                entries in SYTCPM_DATA.
 24  18  Signed       4  SYTCPM_CHPATHLN        Length, in bytes of a
                                                SYTCPM_CHPATH entry.
 28  1C  Signed       4  SYTCPM_CALOFFST        Byte offset, relative to the
                                                start of this record, to
 32  20  Character    0  *                      

Channel Path Measurement Data area. Use SYTCPM_CALOFFSET to locate it.
Offsets Dec Hex Type Len Name (Dim) Description 0 0 Structure 8 SYTCPM_DATA
Channel path utilization data entries a separate entry for each channel path. Each index number in this array corresponds to its channel path number starting with zero (0). That is SYTCPM_CHPATH(0) represents channel path 0 SYTCPM_CHPATH(n) represents channel path n. A SYTCPM_CHPATH entry contains valid data only when its SYTCPM_INVALID bit is OFF.
Offsets Dec Hex Type Len Name (Dim) Description 0 0 Character 8 SYTCPM_CHPATH(0:*) Channel path entry. See SYTCPM_CHPATHLN for its length. 0 0 Signed 4 SYTCPM_CHPBUSY Cumulative channel path busy time. Each unit represents 128 microseconds. This field will wrap in approximately 76.36 hours. 1... .... SYTCPM_INVALID ON = this SYTCPM_CHPATH entry contains unpredictable data. OFF = this SYTCPM_CHPATH entry contains valid data. 4 4 Bitstring 1 SYTCPM_FLAG Flag byte. 1... .... SYTCPM_SHAR ON = this channel path 0 is shared, OFF = this channel path is not shared. .1.. .... SYTCPM_INIT Initial data flag. When this bit is ON, and SYTCPM_INVALID is OFF, the corresponding channel path data is valid only as the start of an epoch, i.e., the data in this entry cannot be used in conjunction with a previous SYTCPM record to deduce usage in the previous interval, because a discontinuity may have occurred in the timestamp and busy time accumulation. ..1. .... * ...1 .... * .... 1... * .... .1.. * .... ..1. * .... ...1 * 5 5 Unsigned 3 SYTCPM_TSTMP Channel path timestamp, in units of 128 microseconds. This timestamp identifies when the corresponding channel path busy time was recorded. This field will wrap in approximately 35.79 minutes.

MRSYTCPM Cross Reference

                      Hex           Hex
Name                 Offset Length Value
MRHDR                      0     20
MRHDR_END                 14      0
MRHDRDM                    4      1
MRHDRLEN                   0      2
MRHDRRC                    6      2
MRHDRTOD                   8      8
MRHDRZER                   2      2
SYTCPM                     0     32
SYTCPM_CALOFFST           1C      4
SYTCPM_CHPATH              0      8
SYTCPM_CHPATHCT           14      4
SYTCPM_CHPATHLN           18      4
SYTCPM_CHPBUSY             0      4
SYTCPM_DATA                0      8
SYTCPM_FLAG                4      1
SYTCPM_INIT                4           40
SYTCPM_INVALID             0           80
SYTCPM_MRHDR               0      0
SYTCPM_SHAR                4           80
SYTCPM_TSTMP               5      3

This information is based on z/VM V5R2.0.
Last updated on 11 Dec 2005 at 18:48:12.
Copyright IBM Corporation, 1990, 2005