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 V4R4.0.

    Last updated on 22 Jul 2003 at 15:04:23.

    Copyright IBM Corporation, 1990, 2003