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

#### MRPRCSMT

Prolog
Control Block Contents
Cross Reference

#### MRPRCSMT Prolog

     DSECT NAME - PRCSMT
     FUNCTION - Map a Monitor record.
     LOCATED BY -
               Through the Monitor Control Area
     REFERENCED CONTROL BLOCKS -
            MRRECHDR    Monitor Record Header
     NAME - MRPRCSMT
     DESCRIPTIVE NAME - Monitor Event Record
                        Domain 5 - Processor Domain
                        Record 21 - Multithreading config change event
     DESCRIPTION - Records parameters of a successful SET MULTITHREAD
                   command and the resulting configuration settings.
                   This record will be generated only if multithreading
                   is enabled.

                   For each multithreading Configuration change,
                   this record is generated once at the start of
                   the change and again at the end of the change.
                   Both the start and end records describe the
                   new configuration details.

                   Values for use with PRCSMT_CAL_STATUS:
                   x'80' - Multithreading config change processing
                           has started. Another record of this type with
                           PRCSMT_CAL_END set will indicate the end of the
                           transition.
                   x'40' - Multithreading config change processing
                           has finished. An earlier record of this type
                           with PRCSMT_CAL_START set indicates the start
                           of the transition.

     IMPLICATIONS OF MULTITHREADING CONFIGURATION CHANGES.
                   The SET MULTITHREAD command allows the
                   requested number of threads per core to be
                   changed.  Changes to the requested number
                   of threads do not necessarily cause changes
                   to the number of activated threads per core
                   of any CPU type for several reasons:
                   - The SET MULTITHREAD command was successful
                     but it did not cause an actual change to
                     any of the requested thread counts. For
                     example, SET MULTITHREAD INITIAL was issued
                     but the multithreading configuration had
                     never been modified by a previous SET
                     MULTITHREAD command.
                   - The requested thread counts changed, but
                     did not cause a change in activated thread
                     counts for one of the following reasons:
                     - A change between MAX and a number, but
                       both of the values result in the same
                       effective requested thread count.
                     - The previous and new requested thread
                       counts are greater than the supported
                       thread count for the CPU type so the
                       resulting activated thread count does
                       not change.
                       - At this time, z/VM only supports IFLs
                         for multithreading so activated thread
                         count changes can only occur for the
                         IFL CPU type.

                   When the activated thread count per core of
                   a CPU type changes, each online core of the
                   CPU type will have threads either activated
                   or deactivated. If there are no online cores
                   of the CPU type then the change will not
                   result in a processor configuration change.

                   Activation and deactivation of threads cause
                   processors associated with those threads to
                   be logically varied on or off, respectively.
                   Processors associated with thread 0 are never
                   activated or deactivated as a result of a
                   multithreading configuration change. Monitor
                   is notified about each thread activation or
                   deactivation by event records MRPRCVON
                   and MRPRCVOF which will indicate that the
                   reason is because of thread activation or
                   deactivation. Those event records are
                   generated between the start and end copies
                   of this record as indicated by the value in
                   PRCSMT_CAL_STATUS.

                   After threads are activated or deactivated:
                   - The total number of logical processors is
                     increased or decreased accordingly.
                     Therefore more or fewer per processor
                     Monitor records will be generated per
                     sample interval.
                   - The number of threads/logical processors
                     per core changes. Therefore any data that
                     is sensitive to threading levels will be
                     affected.

                   Sample intervals that end or start between the
                   start and end of the multithreading transition
                   reported by the start and end versions of
                   this record will contain data that spans
                   different configurations. The times of the
                   start and end records can be used to bound
                   the interval affected. Sample records that
                   contain data related to multithreading contain
                   additional flags and indicators to describe
                   the implications of the configuration change
                   on the data.
                   - MRPRCMFM
                     - These are per processor records so the
                       number of records generated will change
                       due to thread activations/deactivations.
                       However, the metrics are repeated in
                       records for the same core.
                     - PRCMFM_CORTHRDS increases or decreases
                       due to activations/deactivations.
                     - PRCMFM_CORTLSEQ provides information on
                       the number of times the core threading
                       level changed.
                   - MRSYTPRP
                     - These are per processor records so the
                       number of records generated will change
                       due to thread activations/deactivations.
                     - SYTPRP_CAL_MTSFLGS.SYTPRP_CAL_HISSFCC will
                       be set when a multithreading configuration
                       change occurs during the interval.
                     - Cores that had a threading level change
                       during the interval will report
                       SYTPRP_KNODATA_TRANSITION in data values
                       affected by the transition.
                     - SYTPRP_CAL_MTSFLGS.SYTPRP_CAL_HISSFCC will
                       be set when a multithreading configuration
                       change occurs during the interval.
                     - Several fields report the time of the
                       threading level change for the core, the
                       amount of time at each threading level,
                       as well as SYTPRP_CORTHRDS and
                       SYTPRP_CORTLSEQ.

                   Sample records that are generated during
                   the transition for different cores of a CPU
                   type may report different CORTHRDS values.
                   Per processor records are generated at
                   different times, and it is possible that
                   when a record for one thread of a core is
                   generated the threading level was different
                   than when the record for the other processor
                   is generated.

                   It is possible that the core threading level
                   changed and returned to the original value
                   during the interval. Although the prior and
                   final configurations look the same, there
                   were multithreading configuration changes
                   that would affect the reported data. Any of
                   the processors that were deactivated and then
                   activated again would appear as having been
                   brought online during the interval. CORTHRDS
                   would report the same value before and after
                   the transition.  Therefore it is recommended
                   that the CORTLSEQ field in records should be
                   used to determine whether a multithreading
                   configuration change has occurred.  If the
                   value is odd then a core threading-level
                   transition is in progress.  The value is
                   incremented back to an even number at the
                   completion of the threading-level change.
                   If it is even and unchanged from the
                   previous record then there have been no
                   changes to the multithreading configuration
                   for the core reported in the record.

                   For these and other reasons, caution should
                   be used in interpreting data from Monitor
                   records during the transition if there is an
                   actual change in threading level. It would be
                   reasonable to treat the periods prior to and
                   after the multithreading configuration change
                   as completely different configurations for
                   analysis purposes and completely exclude the
                   period of the transition.

#### MRPRCSMT Control Block Contents

    Offsets
    Dec  Hex  Type        Len  Name (Dim)             Description

       0   0  Structure    36+ PRCSMT                 Start of monitor record.
       0   0  Character     0  PRCSMT_MRHDR           Record header.
       0   0  Character    20  MRHDR
       0   0  Unsigned      2  MRHDRLEN
       2   2  Unsigned      2  MRHDRZER
       4   4  Unsigned      1  MRHDRDM
       5   5  Unsigned      1  *
       6   6  Unsigned      2  MRHDRRC
       8   8  Character     8  MRHDRTOD
      16  10  Character     4  *
      20  14  Character     0  MRHDR_END

    The multithreading configuration change sequence number is
    incremented twice per configuration change. Therefore,
    (PRCSMT_RCCSMTSQ+1)/2 is the number of configuration changes
    since IPL.

      20  14  Unsigned      4  PRCSMT_RCCSMTSQ        Multithreading config
                                                      change sequence number. Odd
                                                      when a SET MT command is in
                                                      progress and even otherwise.
                                                      When 0, the multithreading
                                                      config has not been modified
                                                      by SET MT. Always odd and the
                                                      same value in the start and
                                                      end records for the same
                                                      transition.

    Information describing the MULTITHREADING configuration change.

    These records are issued as a start/end pair to bound the
    multithreading config transition interval. During that interval,
    logical processors may be added or removed as a result of
    thread activation or deactivation, respectively.

    Unless fields state otherwise, the content of the start and
    end records will match, describing the target configuration.

      24  18  Unsigned      1  PRCSMT_CAL_STATUS      Status codes. Different
                                                      flags may be set in the start
                                                      and end records.

    Fields and arrays that contain thread counts might have values
    from 0 to the configured max threads value (PRCSMT_CALMAXTC) or
    the value 255 (x'FF) to indicate that MAX was specified for
    that CPU type or for ALL.

    Multithreading enablement setting which limit possible config
    changes.
    - When multithreading is enabled, the maximum thread count is
      set. The SET MULTITHREAD command cannot allow requests for
      activated thread counts larger than that value.

      25  19  Unsigned      1  PRCSMT_CALMAXTC        Configured maximum thread
                                                      count.

    Parameters from MULTITHREADING configuration statement and
    most recent completed SET MULTITHREAD command along
    with the resulting activated thread counts.

    See the CPUTINFO description for a detailed description
    of array entry contents.

      26  1A  Unsigned      1  PRCSMT_RCCCOALL        Thread count specified on
                                                      ALL parameter of the
                                                      Multithreading Statement.
      27  1B  Unsigned      1  PRCSMT_RCCSMALL        Thread count specified for
                                                      ALL parameter of SET
                                                      MULTITHREAD command.
      28  1C  Bitstring     1  PRCSMT_RCCSMSET        SET MULTITHREAD flags.
              1... ....        PRCSMT_RCCSMINI         SET MULTITHREAD INITIAL
                                                      was specified.
              .1.. ....        *
              ..1. ....        *
              ...1 ....        *
              .... 1...        *
              .... .1..        *
              .... ..1.        *
              .... ...1        *
      29  1D  Unsigned      1  PRCSMT_CAL_CPUTACNT    Number of entries in
                                                      PRCSMT_CPUTINFO array.
      30  1E  Unsigned      2  PRCSMT_CAL_CPUTAESZ    Size of an entry in the
                                                      PRCSMT_CPUTINFO array.
      32  20  Unsigned      2  PRCSMT_CAL_CPUTAOFF    Offset to array
                                                      PRCSMT_CPUTINFO of numbers
                                                      for threads per core by CPU
                                                      type.
      34  22  Unsigned      2  *                      Reserved for IBM use.
      36  24  Character     0  PRCSMT_END             End of record

    Array of per-CPU-type data. Each CPU type entry includes
    number of threads per core as specified on SET MULTITHREAD
    command and MULTITHREADING statement, resulting requested
    values, hardware and z/VM supported thread counts, and
    activated thread counts given the requested multithreading
    configuration.

    This is a variable length array with one entry per CPU
    type. The entries are ordered by the numeric CPU type ID
    but are not indexed by that value because entries are note
    included for unused numeric CPU type IDs. Therefore the CPU
    type ID is included in each array entry.

    PRCSMT_CPUTINFO describes the structure of one array entry.

    Use PRCSMT_CAL_CPUTAOFF to determine the offset within this
    monitor record to the beginning of the PRCSMT_CPUTINFO array.

    Use PRCSMT_CAL_CPUTACNT to determine the number of entries
    present in the array.

    Use PRCSMT_CPUTAESZ to determine the size of each entry.

     The most recent successful SET MULTITHREAD command
     overrides setting from the MULTITHREADING statement and
     any previous SET MULTITHREAD Command.

    For the SET MULTITHREAD Command parms in _RCCSMMNT:
    - If MAX is specified for any operand, the operand
      value will be set to X'FF'.
    - If ALL was not specified, any unspecified CPU type
      will have a value of x'00'.
    - If INITIAL was specified, the ALL and all CPU type
      values will be x'00'.

    The results of the multithreading config change are described by
    _RCCCRMNT - current requested values. These are from the most
                recent SET MULTITHREAD command (_RCCSMxxx)
                if issued, otherwise from the Multithreading
                statement (_RCCCOxxx). For SET MULTITHREAD
                without ALL specified, any unspecified CPU
                types retain the previous requested value.
    _RCCACMNT - actual activated thread counts given current
                requested values (RCCCRMNT), and the supported
                threading level for hardware (_RCCHWMNT) and
                z/VM (_RCCSYMNT).

    Offsets
    Dec  Hex  Type        Len  Name (Dim)             Description

       0   0  Structure     8  PRCSMT_CPUTINFO
       0   0  Unsigned      1  PRCSMT_CAL_CPUTYPE     CPU Type for this entry.
       1   1  Unsigned      1  PRCSMT_CAL_RCCCOMNT    Requested threads for this
                                                      CPU type on the
                                                      Multithreading Statement.
       2   2  Unsigned      1  PRCSMT_CAL_RCCHWMNT    Maximum number of threads
                                                      supported by hardware for
                                                      this CPU type.
       3   3  Unsigned      1  PRCSMT_CAL_RCCSYMNT    Maximum number of threads
                                                      supported by z/VM for this
                                                      CPU type.
       4   4  Unsigned      1  PRCSMT_CAL_RCCACMNT    Number of activated threads
                                                      for this CPU type. The start
                                                      record contains the values
                                                      from before the change and
                                                      the end record contains the
                                                      new values.
       5   5  Unsigned      1  PRCSMT_CAL_RCCSMMNT    Specified threads for this
                                                      CPU type requested on the
                                                      most recent SET MULTITHREAD
                                                      command.
       6   6  Unsigned      1  PRCSMT_CAL_RCCCRMNT    The current requested
                                                      threads for this CPU type.
                                                      The values are from the most
                                                      recent SET MULTITHREAD
                                                      command if issued, or the
                                                      Multithreading statement. The
                                                      start record contains the
                                                      values from before the change
                                                      and the end record contains
                                                      the new values.
       7   7  Unsigned      1  *                      Reserved for IBM use.
       8   8  Character     0  PRCSMT_CPUTINFO_END    End of CPUTINFO entry

#### MRPRCSMT 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
    PRCSMT                     0     36+
    PRCSMT_CAL_CPUTACNT       1D      1
    PRCSMT_CAL_CPUTAESZ       1E      2
    PRCSMT_CAL_CPUTAOFF       20      2
    PRCSMT_CAL_CPUTYPE         0      1
    PRCSMT_CAL_RCCACMNT        4      1
    PRCSMT_CAL_RCCCOMNT        1      1
    PRCSMT_CAL_RCCCRMNT        6      1
    PRCSMT_CAL_RCCHWMNT        2      1
    PRCSMT_CAL_RCCSMMNT        5      1
    PRCSMT_CAL_RCCSYMNT        3      1
    PRCSMT_CAL_STATUS         18      1
    PRCSMT_CALMAXTC           19      1
    PRCSMT_CPUTINFO            0      8
    PRCSMT_CPUTINFO_END        8      0
    PRCSMT_END                24      0
    PRCSMT_MRHDR               0      0
    PRCSMT_RCCCOALL           1A      1
    PRCSMT_RCCSMALL           1B      1
    PRCSMT_RCCSMINI           1C           80
    PRCSMT_RCCSMSET           1C      1
    PRCSMT_RCCSMTSQ           14      4

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

    Last updated on 08 June 2021 at 16:10:20.

    Copyright IBM Corporation, 1990, 2021