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

#### MRSYTEPM

Prolog
Control Block Contents
Storage Layout
Cross Reference

#### MRSYTEPM Prolog

####

####

     DSECT NAME - SYTEPM
     FUNCTION - Map a Monitor record.
     LOCATED BY -
          Through the Monitor Control Area
     REFERENCED CONTROL BLOCKS -
          MRRECHDR    Monitor Record Header
     NAME - MRSYTEPM
     DESCRIPTIVE NAME - Monitor Sample Record
          Domain 0  - System Domain
          Record 20 - Extended Channel Measurement Data (per channel)
     DESCRIPTION - Provide utilization data & measurement characteristic
                 data for a valid channel path in the channel subsystem
     NOTES:
     -  This record is generated for a valid channel path defined
        in the channel subsystem only when the Channel-Path
        Measurement Facility (CPMF) with extended channel measurements
        (MTRSYS_SYSECPMF is on) is installed on the system.
        If it isn't installed, but CPMF without extended channel
        measurements (MTRSYS_SYSCPMF is on) is installed, then the
        MRSYTCPM Monitor record will be generated instead of this one.
        If both are installed, CPMF with extended channel measurements
        (MRSYTEPM) will be used exclusively.
        A key difference between the two records is that an MRSYTCPM
        contains information for all chpids, while MRSYTEPM contains
        information for only one valid chpid.
     -  When VM is running native, this record will be
        generated only when the Channel-Path Measurement
        Facility with extended channel measurements is installed.
     -  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 (as well as data for the whole CPC).
     -  When VM is running second level, the Channel-Path
        Measurement Facility with extended channel measurements
        is not installed.  Thus this record will not be generated.
     -  SYTEPM_CALOFST1 should always be used to locate the
        Channel Utilization Entry (SYTEPM_ECMENTRY) area.
     -  SYTEPM_CALOFST2 should always be used to locate the
        Channel Measurement Characteristics (SYTEPM_CSCCMCBD) area.
     -  A channel utilization 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 data in a channel utilization
        entry, subtract from them the corresponding values in
        the previous record, and then divide to get the data
        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 data for the
        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 SYTEPM_CALINIT bit is ON, 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 SYTEPM record. That is, the
        timestamp and data 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 channel utilization entry recorded for each
        channel path will always have SYTEPM_CALINIT ON in the
        channel measurement characterisitics.
     -  The data in this record contains information specific to the
        channel measurement group (CMG) type. To determine the CMG
        type look at SYTEPM_CSCCMCMG field. This value determines the
        contents and format of the CMG-dependent channel-measurement-
        characteristics area (SYTEPM_CSCCMCMD), and the contents and
        format of the channel-utilization entry for the associated
        channel path (SYTEPM_ECMCMGD).

    MRSYTEPM Control Block Contents

    Offsets
    Dec Hex  Type       Len  Name (Dim)         Description

      0   0  Structure   40  SYTEPM
      0   0  Character    0  SYTEPM_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  Character    1  SYTEPM_CALCHPID     Channel Path ID
     21  15  Character    3  *                   Reserved and available for IBM
                                                 use.
     24  18  Signed       4  SYTEPM_CALOFST1     Byte offset, relative to the
                                                 start of this record, to
                                                 SYTEPM_ECMENTRY.
     28  1C  Signed       4  SYTEPM_CALLEN1      Byte size of SYTEPM_ECMENTRY
     32  20  Signed       4  SYTEPM_CALOFST2     Byte offset, relative to the
                                                 start of this record, to
                                                 SYTEPM_CSCCMCBD
     36  24  Signed       4  SYTEPM_CALLEN2      Byte size of SYTEPM_CSCCMCBD
     40  28  Character    0  *
      0   0  Structure   32  SYTEPM_ECMENTRY
    Channel Utilization Entry

    Offsets
    Dec Hex  Type       Len  Name (Dim)         Description

      0   0  Bitstring    1  SYTEPM_ECMCUIV      Channel-Utilization-Information
                                                 Validity (CUIV) - bits of the CUIV
                                                 map indicate which words in the
                                                 Channel-Utilization Entry contain
                                                 valid channel- utilization
                                                 information.
              1... ....      SYTEPM_ECMCUIVW0    Bytes 1-3 of Word 0 contain
                                                 valid info (the contents of Byte 0
                                                 of Word 0 are always valid).
              .1.. ....      SYTEPM_ECMCUIVW1    Word 1 contains valid info
              ..1. ....      SYTEPM_ECMCUIVW2    Word 2 contains valid info
              ...1 ....      SYTEPM_ECMCUIVW3    Word 3 contains valid info
              .... 1...      SYTEPM_ECMCUIVW4    Word 4 contains valid info
              .... .1..      SYTEPM_ECMCUIVW5    Word 5 contains valid info
              .... ..1.      SYTEPM_ECMCUIVW6    Word 6 contains valid info
              .... ...1      SYTEPM_ECMCUIVW7    Word 7 contains valid info
      1   1  Bitstring    3  SYTEPM_ECMTSTMP     Timestamp in units of 128
                                                 microseconds. It identifies when
                                                 info was last stored in the
                                                 channel-utilization entry
      4   4  Character   28  SYTEPM_ECMCMGD
      4   4  Unsigned     4  SYTEPM_ECMCPBT_CPC  CMG 1 - Word 1 Channel-Path-Busy
                                                 Time (CPC) - contains the
                                                 accumulation of all measured
                                                 channel-path-busy intervals for
                                                 the associated channel path. If
                                                 the CPC is in LPAR mode, this
                                                 value includes channel-path-busy
                                                 intervals associated with all
                                                 LPARs having access to this
                                                 channel path.
      4   4  Unsigned     4  SYTEPM_ECMCBC_CPC   CMG 2 Word 1 Count of Bus Cycles
                                                 (CPC) - accumulated count of the
                                                 internal bus cycles that have been
                                                 used for I/O operations on this
                                                 channel path. If the CPC is in
                                                 LPAR mode, this count includes the
                                                 internal bus cycles that were used
                                                 for I/O operations for all LPARs
                                                 having access to this channel
                                                 path.
      4   4  Unsigned     4  SYTEPM_ECMMSNT      CMG 3 Word 1 Message-Units Sent -
                                                 accumulated count of the number of
                                                 message units that have been sent
                                                 by programs, in the issuing
                                                 logical partition, when using the
                                                 associated channel path.
                                                 NOTE: See SYTEPM_CSCCMCMS
      8   8  Unsigned     4  SYTEPM_ECMCPBT      CMG 1 - Word 2 -
                                                 Channel-Path-Busy Time - When the
                                                 CPC is in LPAR mode this field
                                                 contains the accumulation of all
                                                 measured channel-path-busy
                                                 intervals for this channel path
                                                 that are associated with the LPAR
                                                 that has access to this
                                                 channel-utilization block. If the
                                                 CPC is operating in basic mode,
                                                 then this field has no meaning.
      8   8  Unsigned     4  SYTEPM_ECMCCWU_CPC  CMG 2 Word 2 - Count of
                                                 Channel Work Units (CPC) -
                                                 accumlated count of the number
                                                 of channel work units that have
                                                 been performed by this channel
                                                 path. If the CPC is in LPAR mode
                                                 the count includes the channel
                                                 work units that were performed
                                                 for all LPARs that have access
                                                 to this channel.
      8   8  Unsigned     4  SYTEPM_ECMMSNT_CPC  CMG 3 Word 2 - Message-Units
                                                 sent(CPC) - accumulated count of
                                                 the number of message units that
                                                 have been sent when using the
                                                 associated channel path. The
                                                 count includes messages sent
                                                 for all logical partitions
                                                 that have access to the
                                                 associated channel path.
                                                 NOTE: See SYTEPM_CSCCMCMP
     12   C  Unsigned     4  *                   CMG 1 Word 3 - Reserved and
                                                 available for IBM use.
     12   C  Unsigned     4  SYTEPM_ECMCCWU      CMG 2 Word 3 Count of Channel
                                                 Work Units - When the CPC is in
                                                 LPAR mode this field contains the
                                                 accumulated count of the number of
                                                 channel work units that have been
                                                 performed by this channel path for
                                                 the LPAR that has access to this
                                                 channel- utilization block. If the
                                                 CPC is operating in basic mode,
                                                 then this field has no meaning.
     12   C  Unsigned     4  SYTEPM_ECMUATS      CMG 3 Word 3 - Unsuccessful
                                                 Attempts to Send - accumulated
                                                 count of the number of
                                                 unsuccessful attempts to send
                                                 messages by programs in the
                                                 issuing logical partition when
                                                 using the associated channel path.
                                                 This count includes all
                                                 unsuccessful attempts to send
                                                 messages.
     16  10  Unsigned     4  *                   CMG 1 Word 4 - Reserved and
                                                 available for IBM use.
     16  10  Unsigned     4  SYTEPM_ECMCDUW_CPC  CMG 2 Word 4 - Count of Data
                                                 Units Written(CPC) accumulated
                                                 count of the number of data units
                                                 that have been written using this
                                                 channel path. Note: The
                                                 channel-measurement-
                                                 characteristics block (see
                                                 HCPCSCBK) for the associated
                                                 channel path specifies the number
                                                 of bytes contained in a data unit.
                                                 If the CPC is in LPAR mode, the
                                                 count includes the data units that
                                                 were written for all LPARs that
                                                 have access to this channel path.
     16  10  Unsigned     4  SYTEPM_ECMURB       CMG 3 Word 4 - Unavailable
                                                 Receive Buffers - accumulated
                                                 count of the number of times
                                                 messages sent to the issuing
                                                 partition failed due to
                                                 unavailable receive buffers in the
                                                 issuing logical partition.
     20  14  Unsigned     4  *                   CMG 1 Word 5 - Reserved and
                                                 available for IBM use.
     20  14  Unsigned     4  SYTEPM_ECMCDUW      CMG 2 Word 5 - Count of Data
                                                 Units Written - When the CPC is in
                                                 LPAR mode this field contains the
                                                 accumulated count of the number of
                                                 data units that have been written
                                                 using this channel path for the
                                                 LPAR that has access to this
                                                 channel- utilization block. If the
                                                 CPC is operating in basic mode,
                                                 then this field has no meaning.
     20  14  Unsigned     4  SYTEPM_ECMURB_CPC   CMG 3 Word 5 - Unavailable
                                                 Receive Buffers(CPC) accumulated
                                                 count of the number of times
                                                 messages sent to a target
                                                 partition failed due to
                                                 unavailable buffers in in the
                                                 target partition. The count
                                                 includes all unsuccessful attempts
                                                 by programs in all logical
                                                 partitions that have access to the
                                                 associated channel path.
     24  18  Unsigned     4  *                   CMG 1 Word 6 - Reserved and
                                                 available for IBM use.
     24  18  Unsigned     4  SYTEPM_ECMCDUR_CPC  CMG 2 Word 6 - Count of
                                                 Data Units Read (CPC) -
                                                 accumulated count of the number
                                                 of data units that have been
                                                 read using this channel path.
                                                 Note: The channel-measurement-
                                                 characteristic block (see
                                                 (HCPCSCBK) for the associated
                                                 channel path specifies the
                                                 number of bytes contained in a
                                                 data unit. If the CPC is in LPAR
                                                 mode the count includes the data
                                                 units that were read for all
                                                 LPARs that have access to this
                                                 channel path.
     24  18  Unsigned     4  SYTEPM_ECMDUS       CMG 3 Word 6 - Data Units Sent -
                                                 accumulated count of the number of
                                                 data units that have been sent by
                                                 programs in the issuing logical
                                                 partition when using the
                                                 associated channel path.
                                                 NOTE: See SYTEPM_CSCCMCDU
     28  1C  Unsigned     4  *                   CMG 1 Word 7 - Reserved and
                                                 available for IBM use.
     28  1C  Unsigned     4  SYTEPM_ECMCDUR      CMG 2 Word 7 Count of Data Units
                                                 Read - When the CPC is in LPAR
                                                 mode this field contains the
                                                 accumulated count of the number of
                                                 data units that have been read
                                                 using this channel path for the
                                                 LPAR that has access to this
                                                 channel-utilization block. If the
                                                 CPC is operating in basic mode,
                                                 then this field has no meaning.
     28  1C  Unsigned     4  SYTEPM_ECMDUS_CPC   CMG 3 Word 7 - Data Units Sent
                                                 (CPC) - accumulated count of the
                                                 number of data units that have
                                                 been sent using the associated
                                                 channel path. The count includes
                                                 all data units sent by all logical
                                                 partitions that have access to the
                                                 associated channel path.
                                                 NOTE: See SYTEPM_CSCCMCDP
      0   0  Structure   32  SYTEPM_CSCCMCBD
    Channel-Measurement Characteristics

    Offsets
    Dec Hex  Type       Len  Name (Dim)         Description

      0   0  Bitstring    1  SYTEPM_CSCCMCFL     Flags
              1... ....      SYTEPM_CSCCMCNV     CHPID not valid, no info
              .1.. ....      SYTEPM_CSCCMCSH     Shared Channel Path
              ..1. ....      *
              ...1 ....      *
              .... 1...      *
              .... .1..      *
              .... ..1.      *
              .... ...1      SYTEPM_CALINIT      Initial data flag. When this bit
                                                 is ON, and SYTEPM_CMCNV 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 SYTEPM
                                                 record to deduce usage in the
                                                 previous interval, because a
                                                 discontinuity may have occurred in
                                                 the timestamp and data
                                                 accumulation.
      1   1  Character    2  *                   Reserved and available for IBM
                                                 use.
      3   3  Character    1  SYTEPM_CSCCMCCP     CHPID
      4   4  Bitstring    1  SYTEPM_CSCCMCCV     Chan-Meas-Chars Validity
              1... ....      SYTEPM_CSCCMCV3     Word 3 had valid info
              .1.. ....      SYTEPM_CSCCMCV4     Word 4 had valid info
              ..1. ....      SYTEPM_CSCCMCV5     Word 5 had valid info
              ...1 ....      SYTEPM_CSCCMCV6     Word 6 had valid info
              .... 1...      SYTEPM_CSCCMCV7     Word 7 had valid info
              .... .1..      *
              .... ..1.      *
              .... ...1      *
      5   5  Character    1  *                   Reserved and available for IBM
                                                 use.
      6   6  Bitstring    1  SYTEPM_CSCCMMGQ     Channel Measurement Group
                                                 Qualifier (CMGQ)
      7   7  Bitstring    1  SYTEPM_CSCCMCMG     Channel Meas Group (CMG)
      8   8  Character    4  *                   Reserved and available for IBM
                                                 use.
     12   C  Character   20  SYTEPM_CSCCMCMD     CMG Dependent Area
     12   C  Unsigned     4  SYTEPM_CSCCMCMB     CMG 2 Word 3 Maximum internal
                                                 bus cycles per second,
                                                 available for I/O operations
                                                 on the specified channel
                                                 path
     12   C  Unsigned     4  SYTEPM_CSCCMCDU     CMG 3 Word 3 The number of
                                                 bytes of data that are contained
                                                 in a data unit for the specified
                                                 channel path
                                                 NOTE: When this field is invalid
                                                 (SYTEPM_CSCCMCV3 = 0), then the
                                                 associated count, Word 6 in a
                                                 CMG=3 channel-utilization entry
                                                 (SYTEPM_ECMDUS), is a count in
                                                 bytes.
     16  10  Unsigned     4  SYTEPM_CSCCMCMC     CMG 2 Word 4 Maximum number
                                                 of channel work units that can
                                                 be performed per second by the
                                                 specified channel path
     16  10  Unsigned     4  SYTEPM_CSCCMCDP     CMG 3 Word 4 The product of
                                                 the number of bytes of data that
                                                 are contained in a data unit for
                                                 the specified channel path
                                                 multiplied by a model-dependent
                                                 scaling factor
                                                 NOTE: When this field is invalid
                                                 (SYTEPM_CSCCMCV4 = 0), then the
                                                 associated count, Word 7 in a
                                                 CMG=3 channel-utilization entry
                                                 (SYTEPM_ECMDUS_CPC), is a count
                                                 of data units whose size is
                                                 determined by the
                                                 SYTEPM_CSCCMCDU field.
     20  14  Unsigned     4  SYTEPM_CSCCMCMW     CMG 2 Word 5 Maximum number
                                                 of data units that can be
                                                 written per second using the
                                                 specified channel path
     20  14  Unsigned     4  SYTEPM_CSCCMCMS     CMG 3 Word 5 The number of
                                                 bytes that are contained in a
                                                 message-unit for the specified
                                                 channel path
                                                 NOTE: When this field is invalid
                                                 (SYTEPM_CSCCMCV5 = 0), then the
                                                 associated count, Word 1 in a
                                                 CMG=3 channel-utilization entry
                                                 (SYTEPM_ECMMSNT) is a count of
                                                 bytes.
     24  18  Unsigned     4  SYTEPM_CSCCMCMR     CMG 2 Word 6 Maximum number
                                                 of data units that can be
                                                 read per second using the
                                                 specified channel path
     24  18  Unsigned     4  SYTEPM_CSCCMCMP     CMG 3 Word 6 The product of
                                                 the number of bytes of data that
                                                 are contained in a message-unit
                                                 for the specified channel path
                                                 multiplied by a model-dependent
                                                 scaling factor
                                                 NOTE: When this field is invalid
                                                 (SYTEPM_CSCCMCV6), then the
                                                 associated count, Word 2 in a
                                                 CMG=3 channel-utilization entry
                                                 (SYTEPM_ECMMSNT_CPC), is a count
                                                 of message units whose size is
                                                 determined by the
                                                 SYTEPM_CSCCMCMS field.
     28  1C  Unsigned     4  SYTEPM_CSCCMCMU     CMG 2 Word 7 The number of
                                                 bytes of data that are contained
                                                 in a data unit for the specified
                                                 channel path
     28  1C  Unsigned     4  *                   CMG 3 word 7 Reserved and
                                                 available for IBM use

    MRSYTEPM 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
    SYTEPM                  0     40
    SYTEPM_CALCHPID        14      1
    SYTEPM_CALINIT          0           01
    SYTEPM_CALLEN1         1C      4
    SYTEPM_CALLEN2         24      4
    SYTEPM_CALOFST1        18      4
    SYTEPM_CALOFST2        20      4
    SYTEPM_CSCCMCBD         0     32
    SYTEPM_CSCCMCCP         3      1
    SYTEPM_CSCCMCCV         4      1
    SYTEPM_CSCCMCDP        10      4
    SYTEPM_CSCCMCDU         C      4
    SYTEPM_CSCCMCFL         0      1
    SYTEPM_CSCCMCMB         C      4
    SYTEPM_CSCCMCMC        10      4
    SYTEPM_CSCCMCMD         C     20
    SYTEPM_CSCCMCMG         7      1
    SYTEPM_CSCCMCMP        18      4
    SYTEPM_CSCCMCMR        18      4
    SYTEPM_CSCCMCMS        14      4
    SYTEPM_CSCCMCMU        1C      4
    SYTEPM_CSCCMCMW        14      4
    SYTEPM_CSCCMCNV         0           80
    SYTEPM_CSCCMCSH         0           40
    SYTEPM_CSCCMCV3         4           80
    SYTEPM_CSCCMCV4         4           40
    SYTEPM_CSCCMCV5         4           20
    SYTEPM_CSCCMCV6         4           10
    SYTEPM_CSCCMCV7         4           08
    SYTEPM_CSCCMMGQ         6      1
    SYTEPM_ECMCBC_CPC       4      4
    SYTEPM_ECMCCWU          C      4
    SYTEPM_ECMCCWU_CPC      8      4
    SYTEPM_ECMCDUR         1C      4
    SYTEPM_ECMCDUR_CPC     18      4
    SYTEPM_ECMCDUW         14      4
    SYTEPM_ECMCDUW_CPC     10      4
    SYTEPM_ECMCMGD          4     28
    SYTEPM_ECMCPBT          8      4
    SYTEPM_ECMCPBT_CPC      4      4
    SYTEPM_ECMCUIV          0      1
    SYTEPM_ECMCUIVW0        0           80
    SYTEPM_ECMCUIVW1        0           40
    SYTEPM_ECMCUIVW2        0           20
    SYTEPM_ECMCUIVW3        0           10
    SYTEPM_ECMCUIVW4        0           08
    SYTEPM_ECMCUIVW5        0           04
    SYTEPM_ECMCUIVW6        0           02
    SYTEPM_ECMCUIVW7        0           01
    SYTEPM_ECMDUS          18      4
    SYTEPM_ECMDUS_CPC      1C      4
    SYTEPM_ECMENTRY         0     32
    SYTEPM_ECMMSNT          4      4
    SYTEPM_ECMMSNT_CPC      8      4
    SYTEPM_ECMTSTMP         1      3
    SYTEPM_ECMUATS          C      4
    SYTEPM_ECMURB          10      4
    SYTEPM_ECMURB_CPC      14      4
    SYTEPM_MRHDR            0      0

    This information is
    based on z/VM V4R4.0.

    Last updated on 22 Jul 2003 at 10:00:00.

    Copyright IBM Corporation, 1990, 2003