MA_INITIALIZE


     NAME
	  MA_init - initialize the memory allocator

     C SYNOPSIS
	  #include "macdecls.h"

	  Boolean MA_init(datatype, nominal_stack, nominal_heap)
	      Integer	  datatype;	  /* read-only */
	      Integer	  nominal_stack;  /* read-only */
	      Integer	  nominal_heap;	  /* read-only */

     FORTRAN SYNOPSIS
	  #include "mafdecls.h"

	  logical function MA_init(datatype, nominal_stack,
	  nominal_heap)
	      integer	  datatype
	      integer	  nominal_stack
	      integer	  nominal_heap

     DESCRIPTION
	  MA_init() initializes	the memory allocator by	requesting
	  from the operating system a single segment of	memory that is
	  used to satisfy allocations for both the heap	and the	stack.
	  The memory segment is	large enough to	hold nominal_heap
	  elements of type datatype in the heap	and nominal_stack
	  elements of type datatype in the stack, plus the overhead
	  for two allocations (one heap	and one	stack);	if more	than
	  two allocations will exist concurrently, overhead may	be
	  computed using MA_sizeof_overhead() and factored into
	  nominal_heap and nominal_stack.  If nominal_heap is less
	  than zero, a default total size for the heap is used.	If
	  nominal_stack	is less	than zero, a default total size	for
	  the stack is used.

	  MA_init() must be called before any other MA routine is
	  called, except MA_set_auto_verify(), MA_set_error_print(),
	  MA_set_hard_fail(), MA_sizeof(), or MA_sizeof_overhead().

     USAGE
	  The following	FORTRAN	code illustrates the use of MA_init()
	  by computing the space required for 100 integers in 5
	  allocations in the heap, 200 logicals	in 4 allocations in
	  the heap, 300	reals in 3 allocations in the stack, and 400
	  doubles in 2 allocations in the stack.

	  #include "mafdecls.h"

	      logical ok
	      integer heap_bytes_data
	      integer heap_bytes_overhead
	      integer heap_bytes_total
	      integer stack_bytes_data
	      integer stack_bytes_overhead
	      integer stack_bytes_total

	      heap_bytes_data =	MA_sizeof(MT_INT, 100, MT_BYTE)
			      +	MA_sizeof(MT_LOG, 200, MT_BYTE)
	      heap_bytes_overhead = (5 + 4) *
	                            MA_sizeof_overhead(MT_BYTE)
	      heap_bytes_total = heap_bytes_data + heap_bytes_overhead
	      stack_bytes_data = MA_sizeof(MT_REAL, 300, MT_BYTE)
			       + MA_sizeof(MT_DBL, 400,	MT_BYTE)
	      stack_bytes_overhead = (3	+ 2) *
	                            MA_sizeof_overhead(MT_BYTE)
	      stack_bytes_total	= stack_bytes_data +
	                            stack_bytes_overhead
	      ok = MA_init(MT_BYTE, stack_bytes_total,
	                            heap_bytes_total)

     DIAGNOSTICS
	  unable to set	sizes of FORTRAN datatypes
	       This indicates either that the internal state of	MA is
	       corrupted or that there is a problem in the C-FORTRAN
	       linkage.
	  MA already initialized
	       MA_init() may not be called after it has	returned
	       successfully.
	  invalid datatype: %d
	       datatype	must be	one of those listed in macdecls.h or
	       mafdecls.h.
	  could	not allocate %d	bytes
	       The request for memory to the operating system failed.
	       Recovery	may be attempted by calling MA_init() again
	       and requesting less memory.

     RETURN VALUE
	  C: MA_TRUE upon success, MA_FALSE upon failure.
	  FORTRAN: .true. upon success,	.false.	upon failure.

     SEE ALSO
	  MA(3), MA_sizeof(3), MA_sizeof_overhead(3)

     AUTHOR
	  Gregory S. Thomas, Pacific Northwest Laboratory