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

#### MRSYTCPM

Prolog
Control Block Contents
Cross Reference

#### MRSYTCPM Prolog

####

####

     DSECT NAME - SYTCPM
     FUNCTION - Map a Monitor record.
     LOCATED BY -
            Through the Monitor Control Area
     REFERENCED CONTROL BLOCKS -
            MRRECHDR    Monitor Record Header
     NAME - MRSYTCPM
     DESCRIPTIVE NAME - Monitor Sample Record
            Domain 0  - System Domain
            Record 18 - Channel Path Measurement Data
     DESCRIPTION - Provide utilization data for each channel path.
     NOTES:
       -  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

    Offsets
    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
                                                    SYTCPM_DATA.
     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