NAME       : HCPGALPL
 DESCRIPTION: Generalized Associative Lookup
              Parameter List
 DSECT      : GALPL
 FUNCTION   : Provide the parameters, work area and root for
              hash table used by HCPGAL
 LOCATED BY : N/A
 CREATED BY : A program that needs it.
              It may also be permanently defined in a
              data module such as in HCPHSH.
 DELETED BY : A program when function not needed.
              It may also never be deleted even when all
              the entries have been deleted.  This is the
              case for the data module HCPHSH.
 RELOCATION CONSIDERATIONS : None
 COMMENTS   : This parameter list is used by the generalized
              associative lookup routine to both define a
              hash table and store its high level index
              The caller is responsible for defining the size
              of the key (GALKEYSZ) and providing sufficient
              space for the high level index (GALINDX)
              The remaining fields are work areas.
  ECOMMENDED USAGE -
              In order to define a new hash table, a new entry must be
              created in the file HCPHSH ASSEMBLE.  The entry should
              have the naming convention of HCPHSHxx. These entries are
              meant to serve as the root of the hash table, and can be
              referenced by other modules in CP as a DATA EXTERN.
              After defining a hash table within HCPHSH, all calls to
              the HCPGAL functions (such as inserting into the hash
              table) will require the address of the GALPL definition
              as input.  For example, this can be acquired by:
              HCPEXTERN HCPHSHxx       Reference to hash table
              ...
              L   Ry,=A(HCPHSHxx)      Point to the hash table
              HCPCALL HCPGALzz         Make a hash table call
              For further information on how hash tables managed by
              HCPGAL work, refer to HCPGAL ASSEMBLE.

 GALPL DSECT
Top of page

Hex   Dec Type/Val   Lng Label (dup)    Comments
---- ---- --------- ---- -------------- --------
0000    0 Structure      GALPL          Generalized Associative Lookup
                                       parameters
0000    0 Signed       4 GALLOCK        Hash table lock
0004    4 Signed       4 GALCNUM        The number of entries currently
                                        in the hash table
0008    8 Signed       4 GALCCAP        The current capacity of the hash
                                        table in slots
000C   12 Signed       4 GALEC          Total number of searches
0010   16 Signed       4 GALPC          Total number of probes
                                        GALPC/GALEC = probes per search
0014   20 Signed       4 GALTHRSH       The number of hash entries beyond
                                        which the table must grow by a
                                        page
0018   24 Signed       4 GALUNQID       Offset to unique identifier for
                                        hash tables using collision
                                        chaining
001C   28 Signed       4 GALNEXT        Offset to ptr to next node
0020   32 Signed       2 GALNEWPI       Offset to position in high level
                                        index for new hash page address
0022   34 Signed       1 GALKEYSZ       The number of bytes in the key
0023   35 Bitstring    1 GALFLAGS       Table property flag byte
          .... ...1      GALFLCHN       X'01' GALFLCHN This hash table
                                        allows for collision node
                                        chaining.
0024   36 Character   88 GALWORK        Workarea for HCPGAL entry pts
007C  124 Address      4 GALENDWD       Address of last word in GALINDX
          00000080       GALLENTH       *-GALPL Size of header in bytes
0080  128 Address      4 GALINDX (0)    High level index area NB: There
                                        must be one word here for every
                                        750 entries that can be in the
                                        largest possible hash table. The
                                        actual number is 763.5 but we
                                        allow a little breathing room.
                                        This number is 75% of the number
                                        of 4-byte entries that fit in a
                                        page minus 24 bytes (for free
                                        storage header/trailer), or:
                                        ((4096-24)/4*(.75)) entries.

          
*** GALPL - Generalized Associative Lookup
*
*     +---------------------------+---------------------------+
*   0 |         GALLOCK           |         GALCNUM           |
*     +---------------------------+---------------------------+
*   8 |         GALCCAP           |          GALEC            |
*     +---------------------------+---------------------------+
*  10 |          GALPC            |         GALTHRSH          |
*     +---------------------------+---------------------------+
*  18 |         GALUNQID          |         GALNEXT           |
*     +-------------+------+------+---------------------------+
*  20 |  GALNEWPI   |:KEYSZ|:FLAGS|                           |
*     +-------------+------+------+                           |
*  28 |                                                       |
*     =                       GALWORK                         =
*     |                           +---------------------------+
*  78 |                           |         GALENDWD          |
*     +---------------------------+---------------------------+
*
*** GALPL - Generalized Associative Lookup

 
Symbol         Dspl Value
-------------- ---- -----
GALCCAP        0008
GALCNUM        0004
GALEC          000C
GALENDWD       007C
GALFLAGS       0023
GALFLCHN       0023 01
GALINDX        0080
GALKEYSZ       0022
GALLENTH       007C 00000080
GALLOCK        0000
GALNEWPI       0020
GALNEXT        001C
GALPC          0010
GALTHRSH       0014
GALUNQID       0018
GALWORK        0024