Programming Interface Information: This information is NOT intended to be used as Programming Interfaces of z/VM.

#### ITRBK

Prolog

Control Block Contents
ITRBK DSECT

Storage Layout

Cross Reference (Contains links to field and bit definitions)

#### ITRBK Prolog

     Name       : HCPITRBK
     Description: Host DAT Table Iterator Control Block
     DSECT      : ITRBK
     Function   : Contains information for a specific call to
                  the Host DAT Table Iterator, HCPHDITR,
                  particularly parameters and match criteria for
                  the routine to be called.
     Located by : Local register usage in HCPHDITR and HCPHDITR's
                  callers
     Created by : Callers of HCPHDITR
     Deleted by : Callers of HCPHDITR
     Serialized : Local task serialization (only the owning task has
                  the address of the corresponding ITRBK), called
                  routine serialization is the responsibility of
                  HCPHDITR's caller.
     Comments   : Used to pass input parameters to HCPHDITR, and
                  to pass output from the called routine back out
                  to HCPHDITR's callers.  Also used to save HCPHDITR
                  internal information for lower level iterator
                  routines (iterator uses recursive descent to
                  traverse multi-level host DAT tables; by saving
                  the information in the ITRBK, we only have to
                  pass one pointer down in a register, instead of
                  passing everything in registers).

#### ITRBK Control Block Content

#### ITRBK DSECT

    Hex   Dec Type/Val   Lng Label (dup)    Comments
    ---- ---- --------- ---- -------------- --------
    0000    0 Structure      ITRBK          Host DAT Table Iterator Control
                                            Block
          HCPHDITR input parameter section.  To be filled in by
          callers of HCPHDITR.
    0000    0 Signed       8 ITRSVADD       HCPHDITR input starting virtual
                                            address. If ITRLVPAG was not
                                            specified, PX and BX bits will be
                                            ignored, the address will be
                                            rounded down to a segment
                                            boundary by HCPHDITR. If ITRLVPAG
                                            was specified, only the BX bits
                                            will be ignored, the address will
                                            be rounded down to a 4K page
                                            boundary HCPHDITR.
    0008    8 Signed       8 ITREVADD       HCPHDITR input ending virtual
                                            address. If ITRLVPAG was not
                                            specified, PX and BX bits will be
                                            ignored, will be rounded up to
                                            the highest address in the ending
                                            segment (that is, the next higher
                                            segment boundary address minus
                                            one) by HCPHDITR. If ITRLVPAG was
                                            specified, only the BX bits will
                                            be ignored, the address will be
                                            rounded up the highest address in
                                            the ending 4K page (that is, the
                                            next higher 4K page boundary
                                            address minus one) by HCPHDITR.
    0010   16 Signed       8 ITRLEVEL (0)   Defines iteration target level.
                                            Similar in definition to TT bits
                                            in R*TE/STE, with the addition of
                                            an additional (mutually
                                            exclusive) bit to indicate page
                                            table level iteration.
              00000000       ITRLVSEG       X'00' Iterate at segment table
                                            level
              00000004       ITRLVRTT       X'04' Iterate at region third
                                            table level
              00000008       ITRLVRST       X'08' Iterate at region second
                                            table level
              0000000C       ITRLVRFT       X'0C' Iterate at region first
                                            table level
              00000010       ITRLVPAG       X'10' Iterate at page table level
                Allowable ITRLEVEL values and corresponding target
                levels:
                x'0000000000000000' - ITRLVSEG:
                                      Iterate at segment table level
                x'0000000000000004' - ITRLVRTT:
                                      Iterate at region third table
                                      level
                x'0000000000000008' - ITRLVRST:
                                      Iterate at region second table
                                      level
                x'000000000000000C' - ITRLVRFT:
                                      Iterate at region first table
                                      level
                x'0000000000000010' - ITRLVPAG:
                                      Iterate at page table level
    0010   16 Bitstring    1 * (7)          Reserved for IBM use
    0017   23 Bitstring    1 ITRLEVB7       Defines iteration target level:
    0018   24 Signed       8 ITRCRMBZ       HCPHDITR table entry match
                                            criteria "Must Be Zero" bit mask
                                            (if both ITROPTE and ITROPCRI
                                            were specified). Bits which are
                                            one in this mask must be zero in
                                            a table entry for the target
                                            routine to be called for that
                                            table entry.
    0020   32 Signed       8 ITRCRMBO       HCPHDITR table entry match
                                            criteria "Must Be Ones" bit mask
                                            (if both ITROPTE and ITROPCRI
                                            were specified). Bits which are
                                            one in this mask must also be one
                                            in a table entry for the target
                                            routine to be called for that
                                            table entry.
    0028   40 Bitstring    1 ITROPTS        Option flags for HCPHDITR
              1... ....      ITROPTE        X'80' Iterate on table entries at
                                            the specified level. Target
                                            routine is called once per table
                                            found at the specified level
                                            which represents virtual
                                            addresses within the input
                                            virtual address range; the table
                                            entry address is passed as an
                                            argument to the target routine.
              .1.. ....      ITROPTBL       X'40' Iterate on tables at the
                                            specified table level. Target
                                            routine is called once per table
                                            found at the specified level
                                            which represents virtual
                                            addresses within the input
                                            virtual address range; the table
                                            designation is passed as an
                                            argument to the target routine.
                                            Notes : One of ITROPTE or
                                            ITROPTBL *MUST* be specified,
                                            although they are mutually
                                            exclusive. Calls with both or
                                            neither set will result in an
                                            ABEND.
              ..1. ....      ITROPPTV       X'20' Only has meaning if
                                            ITRLEVEL is set to indicate
                                            iteration at the page table
                                            level, or if ITRLEVEL is set to
                                            indicate iteration at the segment
                                            table level with ITROPTE set to
                                            indicate iteration at the segment
                                            table entry level. ITROPPTV set
                                            indicates that any page tables
                                            which have been paged out should
                                            be validated during processing.
              ...1 ....      ITROPCRI       X'10' May only be set if ITRITTE
                                            is also set, to indicate
                                            iteration on table entries. The
                                            ITRCRMBZ and ITRCRMBO inputs
                                            specify table entry match
                                            criteria: ITRCRMBZ is a bit mask
                                            specifying bits which much be
                                            zero in a target table entry for
                                            the entry to be considered a
                                            match (bits which are one in
                                            ITRCRMBZ must be zero in a target
                                            table entry for it to be
                                            considered a match). ITRCRMBO is
                                            a bit mask specifying bits which
                                            much be ones in a target table
                                            entry for the entry to be
                                            considered a match (bits which
                                            are one in ITRCRMBO must also be
                                            one in a target table entry for
                                            it to be considered a match). The
                                            target routine is called only if
                                            the table entry matches the
                                            criteria.
    0029   41 Bitstring    1 * (3)          reserved for IBM use
    002C   44 Signed       4 ITRTARG        Address of target routine to be
                                            called for host DAT tables (or
                                            entries) which match the
                                            specified input criteria. Routine
                                            must have attributes RESident,
                                            DYNamic, LONGreg, and can be MP
                                            (the default) or non-MP (if
                                            ITRTRNMP is set in ITRTRATT)
    0030   48 Bitstring    1 ITRTRATT       Target routine attribute flags
              1... ....      ITRTRNMP       X'80' Target routine is non-MP
                                            (master only). If not set, the
                                            target routine is assumed to be
                                            MP.
    0031   49 Bitstring    1 * (3)          reserved for IBM use
    0034   52 Signed       4 ITRTROPT       Target routine R2 parameter
                                            options. Will be passed to the
                                            target routine in R2.
    0038   56 Signed       4 ITRTRTOK       Target routine parameter token.
                                            Will be passed to the called
                                            routine in R3. If parameters are
                                            to be passed to, or back from,
                                            the called routine, this field
                                            may be used to pass a 32 bit
                                            parameter value, or may be used
                                            to pass the address of a
                                            parameter data area (obtaining,
                                            releasing, and serializing such a
                                            data area is entirely the
                                            responsibility of the caller and
                                            the called routine, not the
                                            iterator).
    003C   60 Signed       4 ITRASCBK       Address of ASCBK from original
                                            HCPHDITR R8 input.
    0040   64 Signed       4 *              Reserved for IBM use
          HCPHDITR output section.  Contains HCPHDITR processing
          information for return to HCPHDITR's caller.
    0048   72 Signed       8 ITRCALCT       Running count of calls made to
                                            the target routine by HCPHDITR.
                                            Is only incremented, is not
                                            initialized to 0 by HCPHDITR,
                                            allowing the caller to use it as
                                            a running count of calls to the
                                            target routine across multiple
                                            invocations of HCPHDITR.
          HCPHDITR internal usage section.  Should not be used by
          callers of HCPHDITR.
    0050   80 Bitstring    1 ITRSTAT        Iterator status byte
              1... ....      TRGRTERR       X'80' The target routine returned
                                            a non-zero condition code or R15
                                            return code
    0051   81 Bitstring    1 * (7)          Reserved for IBM use
    0058   88 Signed       4 ITRTRGCC       Target routine condition code
                                            (saved in IPM/SPM format)
    005C   92 Signed       4 ITRTRGRC       Target routine R15 return code
          End of ITRBK
    0060   96 Signed       4 ITR$END (0)    End of ITRBK control block
              00000060       ITRLEN         *-ITRBK Length of ITRBK in bytes
              0000000C       ITRSIZE        (ITRLEN+7)/8 Size of ITRBK in
                                            doublewords

#### ITRBK Storage Layout

    *** ITRBK - Host DAT Table Iterator Control Block
    *
    *     +-------------------------------------------------------+
    *   0 |                       ITRSVADD                        |
    *     +-------------------------------------------------------+
    *   8 |                       ITREVADD                        |
    *     +------------------------------------------------+------+
    *  10 |////////////////////////////////////////////////|:LEVB7|
    *     +------------------------------------------------+------+
    *  18 |                       ITRCRMBZ                        |
    *     +-------------------------------------------------------+
    *  20 |                       ITRCRMBO                        |
    *     +------+--------------------+---------------------------+
    *  28 |:OPTS |////////////////////|         ITRTARG           |
    *     +------+--------------------+---------------------------+
    *  30 |:TRATT|////////////////////|         ITRTROPT          |
    *     +------+--------------------+---------------------------+
    *  38 |         ITRTRTOK          |         ITRASCBK          |
    *     +---------------------------+---------------------------+
    *  40 |///////////////////////////|///////////////////////////|
    *     +---------------------------+---------------------------+
    *  48 |                       ITRCALCT                        |
    *     +------+------------------------------------------------+
    *  50 |:STAT |////////////////////////////////////////////////|
    *     +------+--------------------+---------------------------+
    *  58 |         ITRTRGCC          |         ITRTRGRC          |
    *     +---------------------------+---------------------------+
    *
    *** ITRBK - Host DAT Table Iterator Control Block

#### ITRBK Cross Reference

    Symbol         Dspl Value
    -------------- ---- -----
    ITR$END        0060
    ITRASCBK       003C
    ITRCALCT       0048
    ITRCRMBO       0020
    ITRCRMBZ       0018
    ITREVADD       0008
    ITRLEN         0060 00000060
    ITRLEVB7       0017
    ITRLEVEL       0010
    ITRLVPAG       0010 00000010
    ITRLVRFT       0010 0000000C
    ITRLVRST       0010 00000008
    ITRLVRTT       0010 00000004
    ITRLVSEG       0010 00000000
    ITROPCRI       0028 10
    ITROPPTV       0028 20
    ITROPTBL       0028 40
    ITROPTE        0028 80
    ITROPTS        0028
    ITRSIZE        0060 0000000C
    ITRSTAT        0050
    ITRSVADD       0000
    ITRTARG        002C
    ITRTRATT       0030
    ITRTRGCC       0058
    ITRTRGRC       005C
    ITRTRNMP       0030 80
    ITRTROPT       0034
    ITRTRTOK       0038
    TRGRTERR       0050 80

This information is based on z/VM V5R2.0. Last updated on 12 Apr 2006 at 17:00:09 EDT.
Copyright IBM Corporation, 1990, 2005