NAME       : HCPFREBK
 DESCRIPTION: FREE STORAGE BLOCK
 DSECT      : FREBK
 FUNCTION   :
              MAPS A FREE STORAGE BLOCK HEADER AND TRAILER
              FOR BOTH ACTIVE AND INACTIVE FREE STORAGE BLOCKS.
 CREATED BY : HCPFREE OR HCPFREVM WHEN A BLOCK IS
              REQUESTED.  THIS BLOCK IS NEVER ALLOCATED
              AS A SEPARATE BLOCK.
 DELETED BY : HCPFRET WHEN A BLOCK IS RETURNED TO
              FREE STORAGE.  THIS BLOCK IS NEVER
              DEALLOCATED AS A SEPARATE BLOCK.
 SERIALIZED :
              IT IS THE RESPONSIBILITY OF THE REQUESTOR TO
              ENSURE THAT ACCESS TO THE FREE STORAGE BLOCK IS
              SERIALIZED.
 RELOCATION CONSIDERATIONS : None
 NOTES      : WHEN A FREE STORAGE BLOCK IS ISSUED TO SATISFY A
              FREE STORAGE REQUEST, THE FREE STORAGE MANAGER
              PLACES A ONE DOUBLEWORD HEADER AND A TWO
              DOUBLEWORD TRAILER AROUND THE BLOCK. THESE AREAS
              ARE USED FOR DEBUGGING PURPOSES.
              WHEN THE BLOCK IS RETURNED, THESE AREAS ARE
              EXAMINED.  IF EITHER OR BOTH HAVE BEEN CORRUPTED, AN
              ABEND IS ISSUED.

 FREBK DSECT
Top of page

Hex   Dec Type/Val   Lng Label (dup)    Comments
---- ---- --------- ---- -------------- --------
0000    0 Structure      FREBK          FREE STORAGE BLOCK
      This is a picture of how the fields in this DSECT are
      actually used:
    +----------------------------------------------------+
  0 |                     FREHEADR                       |
    +----------------------------------------------------+
  8 :                                                    :
    :                  (control block)                   :
    :                                                    :
    +----------------------------------------------------+
 xx |                     FRETRALR                       |
    |                                                    |
    +----------------------------------------------------+
 xx+10
      The free storage header (FREHEADR) and free storage
      trailer (FRETRALR) areas are maintained both for internal
      functional uses and as debugging aids for free storage
      related problems.  The free storage header immediately
      precedes the start of the free storage block returned in
      response to an obtain free storage request (HCPGETST).
      The trailer, when present (which is always, except for
      Fast Allocated Blocks), follows the end of the free
      storage requested by the caller (there may be a gap
      between the end of the size of block requested by the
      caller and the free storage trailer, as we round the
      requested size up to a convenient boundary in certain
      cases).  The exact format and content of these fields
      depends on the type of free storage being used and whether
      the free storage block is active or inactive:
                    +- free storage block itself in here
                    |
                    V
 <----FREHEADR-----> <-------------FRETRALR-------------->
      Normal (non-subpooled):
      In use (for undefined blocks, cbi == '<<<')
      +--------+--------+ +--------+--------+--------+--------+
      |0000rqsz|  >>>>  |-|  >>>  |-|  <--obtainer->|
      Normal subpooled (non-FAB) free storage:
      In use (normal):
      +--------+--------+ +--------+--------+--------+--------+
      | >> rqsz|1 subbk@|-|  > rqsz|0 subbk@|-|  <--obtainer->|
      Available (on collection pile):
      +--------+--------+ +--------+--------+--------+--------+
      |  fpnt  |0 subbk@|-|  <--obtainer->|
      Fast Allocated Block free storage:
      In use (normal):
      +--------+--------+ +--------+--------+--------+--------+
      |sli 0FAB|1 subbk@|-|xxxxxxxx|xxxxxxxx|xxxxxxxx|xxxxxxxx|
      +--------+--------+ +--------+--------+--------+--------+
      In use (flagged for collection pile):
      +--------+--------+ +--------+--------+--------+--------+
      |sli 0FAB|0 subbk@|-|xxxxxxxx|xxxxxxxx|xxxxxxxx|xxxxxxxx|
      +--------+--------+ +--------+--------+--------+--------+
      Available (normal):
      +--------+--------+ +--------+--------+--------+--------+
      |  fpnt  |1 subbk@|-|xxxxxxxx|xxxxxxxx|xxxxxxxx|xxxxxxxx|
      +--------+--------+ +--------+--------+--------+--------+
      Available (on collection pile):
      +--------+--------+ +--------+--------+--------+--------+
      |  fpnt  |0 subbk@|-|xxxxxxxx|xxxxxxxx|xxxxxxxx|xxxxxxxx|
      +--------+--------+ +--------+--------+--------+--------+
      Notes      : Free storage trailer not maintained and is
            unreliable for Fast Allocated Blocks!
0000    0 Dbl-Word     8 FRESTRT (0)    START OF VARIABLE LENGTH DATA
0000    0 Dbl-Word     8 FREHEADR       FREE STORAGE BLOCK HEADER
          00000008       FREHEADL       *-FREHEADR LENGTH OF HEADER IN
                                        BYTES
0000    0 Dbl-Word     8 FRETRALR (2)   FREE STORAGE BLOCK TRAILER
          00000010       FRETRALL       *-FRETRALR LENGTH OF TRAILER IN
                                        BYTES
          00000003       FRERECL        (FREHEADL+FRETRALL+7)/8 SIZE IN
                                        DOUBLE WORDS
0000    0 Signed       4 FREESIZE (0)   # OF DWORDS OF STORAGE REQUESTED
0000    0 Signed       2 FREHSPSE (0)   Mini-eyecatcher for non-FAB SPS,
                                        0 for normal non-subpooled free
                                        storage, or SLI for FAB SPS:
0000    0 Signed       2 FREHFSLI       System Location Identifier (SLI)
                                        for Fast Allocated Block
                                        subpooled free storage
0002    2 Signed       2 FREHSIZE       Actual count of DWs requested
      Notes      :  The maximum allowable size value for FREESIZE /
             FREHSIZE is the number of doublewords which can fit
             into a single 4K page (not counting the free storage
             header and trailer), or 509 doublewords, x'1FD'.  For
             normal non-subpooled free storage, the high order
             halfword of FREESIZE (aka FREHSPSE) must be zero; for
             normal (non-FAB) subpooled free stg, FREHSPSE has the
             mini- eyecatcher '>>' == x'6E6E'.  For Fast Allocated
             Block subpooled free storage, FREHSPSE contains the
             System Location Identifier (SLI) number, which
             identifies where in the system the block was obtained.
             A FREHSIZE value of x'FAB' in active subpooled free
             storage blocks is not a size, but is used to indicate
             that the block is an active "fast allocated block".
0004    4 Signed       4 FRESUBBK (0)   Address of SUBBK for subpool blk
                                        The high order bit of FRESUBBK is
                                        normally 1, and is set to 0 by
                                        garbage collection (HCPFRFDX) to
                                        indicate that the block should be
                                        queued on the collection pile
                                        when freed (to attempt to reclaim
                                        the frame)
0004    4 Character    4 FREESFLG       ALLOCATED BLOCK CHARACTER STRI
0000    0 Character    4 FREEID         CONTROL BLOCK'S IDENTIFIER (THE
                                        FIRST CHARACTER IS '<', AND
                                        THE ID FOR UNDEFINED BLOCKS IS
                                        '<<<<' )
0004    4 Signed       4 FREFSCBK (0)   Addr of storage obtainers FSCBK
0004    4 Character    4 FREEEFLG       CHARACTER STRING '<<<
0008    8 Signed       4 FREEDISP       REQUEST'S OFFSET IN CALLING
                                        MODULE (1ST HALF WORD = X'00 00')
000C   12 Character    4 FREEMOD        MODULE ID OF CALLING MODULE THE
                                        FIRST BYTE'S ALWAYS SET TO 0
0000    0 Signed       4 FREEPNT        PNTR TO NEXT BLOCK IN FREE
                                        STORAGE CHAIN OR 0 (IF
                                        END-OF-CHAIN)
0004    4 Signed       4 FRETSIZE       Size of available block in DWs or
                                        the size in bytes for a larger
                                        than subpool size block that is
                                        on the free storage chain
      Notes      :  For for subpooled free storage, FRETSIZE as such is
             not used.  Instead the address of the SUBBK which
             represents this subpool remains here in the second
             word of the free storage header (as field FRESUBBK).
             Since the maximum allowable value for FRETSIZE for
             normal (non-FAB) free storage is 509 (x'1FD'), any
             larger value in this field indicates that the block
             in question is in a frame used for subpooled free
             storage (since SUBBKs can't reside in low prefix page
             addresses like x'1FD' and below).  However, in order
             to use this fact to distinguish between types,
             caution must be used, since the high order bit of the
             SUBBK address is used as a free storage garbage
             collection flag.
             Also note that in *active* subpooled free storage
             blocks, a value of x'FAB' in the actual requested
             size in dws (in FREHSIZE) is not a size, but an
             indicator that the block is an active "fast allocated
             block" (the requested size is not kept for fast
             allocated blocks, we know the actual size allocated
             because we know which subpool it's from).
      Note that the free storage trailer is not maintained, and
      may not even exist in some cases, and is therefore
      unreliable for available blocks that were last used as Fast
      Allocated Blocks.
0000    0 Character    4 FRETID         CONTROL BLOCK'S IDENTIFIER (THE
                                        FIRST CHARACTER IS '<', AND
                                        THE ID FOR UNDEFINED BLOCKS IS
                                        '<<<<' ) THIS FIELD
                                        IS PRESERVED FROM THE HCPFREE
                                        CALL WHICH ORIGINALLY OBTAINED
                                        THIS CONTROL BLOCK
0004    4 Character    4 FRETMOD        MODID OF HCPFRET CALLER THE FIRST
                                        BYTE'S ALWAYS SET TO 0
0008    8 Signed       2 FRETDISP       DISPL INTO MODID OF HCPFRET CALL
000A   10 Bitstring    1 FREECALL (6)   LOW-ORDER 2 BYTES OF "FREEDISP"
                                        AND "FREEMOD PRESERVED FROM THE
                                        HCPFREE CALL WHICH ORIGINALLY
                                        OBTAINED THIS CONTROL BLOCK

          
*** FREBK - FREE STORAGE BLOCK
*
*
*** FREBK - FREE STORAGE BLOCK
          
*** Overlay for FRESTRT in FREBK
*
*     +-------------------------------------------------------+
*   0 |                       FREHEADR                        |
*     +-------------------------------------------------------+
*   8
*
*** Overlay for FRESTRT in FREBK
          
*** Overlay for FRESTRT in FREBK
*
*     +-------------------------------------------------------+
*   0 |                       FRETRALR                        |
*     |                                                       |
*     +-------------------------------------------------------+
*  10
*
*** Overlay for FRESTRT in FREBK
          
*** Overlay for FREHEADR in FREBK
*
*     +-------------+-------------+---------------------------+
*   0 |  FREHFSLI   |  FREHSIZE   |         FREESFLG          |
*     +-------------+-------------+---------------------------+
*   8
*
*** Overlay for FREHEADR in FREBK
          
*** Overlay for FRETRALR in FREBK
*
*     +---------------------------+---------------------------+
*   0 |          FREEID           |         FREEEFLG          |
*     +---------------------------+---------------------------+
*   8 |         FREEDISP          |         FREEMOD           |
*     +---------------------------+---------------------------+
*  10
*
*** Overlay for FRETRALR in FREBK
          
*** Overlay for FREHEADR in FREBK
*
*     +---------------------------+---------------------------+
*   0 |         FREEPNT           |         FRETSIZE          |
*     +---------------------------+---------------------------+
*   8
*
*** Overlay for FREHEADR in FREBK
          
*** Overlay for FRETRALR in FREBK
*
*     +---------------------------+---------------------------+
*   0 |          FRETID           |         FRETMOD           |
*     +-------------+-------------+---------------------------+
*   8 |  FRETDISP   |                FREECALL                 |
*     +-------------+-----------------------------------------+
*  10
*
*** Overlay for FRETRALR in FREBK

 
Symbol         Dspl Value
-------------- ---- -----
FREECALL       000A
FREEDISP       0008
FREEEFLG       0004
FREEID         0000
FREEMOD        000C
FREEPNT        0000
FREESFLG       0004
FREESIZE       0000
FREFSCBK       0004
FREHEADL       0000 00000008
FREHEADR       0000
FREHFSLI       0000
FREHSIZE       0002
FREHSPSE       0000
FRERECL        0000 00000003
FRESTRT        0000
FRESUBBK       0004
FRETDISP       0008
FRETID         0000
FRETMOD        0004
FRETRALL       0000 00000010
FRETRALR       0000
FRETSIZE       0004