Guardian Procedure Calls Reference Manual

pool
input
INT .EXT:ref:*
specifies the address of the first word of the memory space to be used as the pool. An even-byte
address must be specified. The address of the actual beginning of the pool might be adjusted
for alignment.
pool-size
input
INT(32):value
specifies the size of the pool in bytes. This number must be a multiple of 4 bytes and cannot
be less than 32 bytes or greater than 127.5 megabytes (133,693,440 bytes). The address of
the end of the pool is always equal to the address specified for the pool parameter plus
pool-size. Pool space overhead and adjustments for alignment do not cause the pool to
extend past this boundary.
CAUTION: If a privileged process calls DEFINEPOOL and supplies an odd-byte address for
the pool or the pool-head parameter, a processor halt results.
Returned Value
INT
A status word containing one of these values:
No error.0
Bounds error on pool-head.1
Bounds error on pool.2
Invalid pool-size.3
pool-head and pool overlap.4
pool-head is not word-aligned.5
pool is not word-aligned.6
Considerations
• Stack addresses converted to extended addresses
If pool-head or pool is in the user data stack, the TAL compiler automatically converts data
stack addresses to extended addresses.
• Read-only segments
If you specify pool-head or pool in an extended data segment that is allocated as a
read-only segment, DEFINEPOOL returns error 1 or 2 (bounds error on pool-head or pool,
respectively).
• Dynamic memory allocation
Several Guardian procedures support the creation of memory pools and dynamic allocation
of variable-sized blocks from the pool. The calling program provides the memory area to be
used as the pool and then calls the DEFINEPOOL procedure to initialize a 19-word array, the
pool-header, that is used to manage the pool. The pool and the pool header can reside
in the user data stack or in extended memory. The pool routines accept and return extended
addresses that apply to both the stack and extended memory.
Once the pool is defined, the process can reserve blocks of various sizes from the pool by
calling the GETPOOL procedure and can release blocks by calling the PUTPOOL procedure.
DEFINEPOOL Procedure 275