RWS_$ALLOC_HEAP_POOL              Domain/OS               RWS_$ALLOC_HEAP_POOL


NAME
     rws_$alloc_heap_pool - allocate heap storage

SYNOPSIS (C)
     #include <apollo/base.h>
     #include <apollo/rws.h>

     void *rws_$alloc_heap_pool(
          rws_$pool_t &alloc_pool,
          long &storage_size)

SYNOPSIS (Pascal)
     %include '/sys/ins/base.ins.pas';
     %include '/sys/ins/rws.ins.pas';

     function rws_$alloc_heap_pool(
          in alloc_pool: rws_$pool_t;
          in storage_size: rws_$word_aligned_long): univ_ptr;

SYNOPSIS (FORTRAN)
     %include '/sys/ins/base.ins.ftn'
     %include '/sys/ins/rws.ins.ftn'

           integer*4 nwords
           parameter (nwords = 5000)

           integer*4 storage_size, storage_ptr
           integer*2 alloc_pool, dummy(nwords)
           pointer /storage_ptr/ dummy

           storage_ptr = rws_$alloc_heap_pool(alloc_pool, storage_size)

DESCRIPTION
     Rws_$alloc_heap_pool allocates storage_size bytes of heap storage from
     the pool specified by alloc_pool and returns a pointer to it.  It returns
     NULL, nil, or 0, when it cannot allocate the requested storage.

     alloc_pool
          The pool from which the storage will be allocated.  It can assume
          one of the following values:

          rws_$std_pool
               Storage allocated from the standard pool is private to the
               allocating process and is released during a UNIX exec(2) call.
               A pointer to storage allocated from the standard pool is not
               valid in another process.

          rws_$stream_tm_pool
               Storage allocated from the stream pool is private to the allo-
               cating process and is retained across a UNIX exec(2) call.  A
               pointer to storage allocated from the standard pool is not
               valid in another process.

          rws_$global_pool
               Storage allocated from the global pool is available to all
               processes running on a single node.  A pointer to storage allo-
               cated from the global pool may be used by all local processes
               to access a common storage area.

     storage_size
          The number of bytes of storage needed.

NOTES
     Unlike storage allocated with rws_$alloc_rw_pool, storage allocated with
     rws_$alloc_heap_pool can be released back to the system with
     rws_$release_heap_pool, though the storage requires slightly more over-
     head.

SEE ALSO
     rws_$alloc.