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
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 ContentsOffsets 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 ReferenceHex 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 V4R3.0.
Last updated on 1 May 2002 at 16:20:33.
Copyright IBM Corporation, 1990, 2002