ITRBK Back to Index page
 
Prolog 
Control Block Contents 
   ITRBK DSECT
Storage Layout 
Cross Reference (Contains links to field and bit definitions)
Programming Interface Information:
This information is NOT intended to be
used as Programming Interfaces of z/VM.


  ITRBK Prolog Top of page
 
 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.
 RELOCATION CONSIDERATIONS : None
 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 Top of page
 

 ITRBK DSECT Top of page
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' ITRLVSEG Iterate at segment table level 00000004 ITRLVRTT X'04' ITRLVRTT Iterate at region third table level 00000008 ITRLVRST X'08' ITRLVRST Iterate at region second table level 0000000C ITRLVRFT X'0C' ITRLVRFT Iterate at region first table level 00000010 ITRLVPAG X'10' ITRLVPAG 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' ITROPTE Iterate on table entries at the specified level. Target routine is called once per table entry 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 in R1. .1.. .... ITROPTBL X'40' ITROPTBL 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 in R1. 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' ITROPPTV 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' ITROPCRI May only be set if ITROPTE 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 attribute SAVE=DYNamic. 0030 48 Bitstring 1 * (4) 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' TRGRTERR 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 Top of page
 
          
*** ITRBK - Host DAT Table Iterator Control Block
*
*     +-------------------------------------------------------+
*   0 |                       ITRSVADD                        |
*     +-------------------------------------------------------+
*   8 |                       ITREVADD                        |
*     +------------------------------------------------+------+
*  10 |////////////////////////////////////////////////|:LEVB7|
*     +------------------------------------------------+------+
*  18 |                       ITRCRMBZ                        |
*     +-------------------------------------------------------+
*  20 |                       ITRCRMBO                        |
*     +------+--------------------+---------------------------+
*  28 |:OPTS |////////////////////|         ITRTARG           |
*     +------+--------------------+---------------------------+
*  30 |///////////////////////////|         ITRTROPT          |
*     +---------------------------+---------------------------+
*  38 |         ITRTRTOK          |         ITRASCBK          |
*     +---------------------------+---------------------------+
*  40 |///////////////////////////|///////////////////////////|
*     +---------------------------+---------------------------+
*  48 |                       ITRCALCT                        |
*     +------+------------------------------------------------+
*  50 |:STAT |////////////////////////////////////////////////|
*     +------+--------------------+---------------------------+
*  58 |         ITRTRGCC          |         ITRTRGRC          |
*     +---------------------------+---------------------------+
*
*** ITRBK - Host DAT Table Iterator Control Block
 
 
  ITRBK Cross Reference Top of page
 
 
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
ITRTRGCC       0058
ITRTRGRC       005C
ITRTROPT       0034
ITRTRTOK       0038
TRGRTERR       0050 80
 
This information is based on z/VM 7.3.0 Last updated on 22 Jun 2022 at 15:53:30 EDT.
Copyright IBM Corporation, 1990, 2022