SHEAP - Super Heap Routines
 	Version 1.0  31 January 1983
 
 
 	SHEAP requires that the following lines be in your .CMD file:
 
 	  Wndws = 5
 	  DefGbl = SHAREA:x	; (x) is the # of areas avail. for regions.
 	  DefGbl = SHAPR1:x	; (x) is the APR # of area 1.
 	  DefGbl = SHAPR2:x	; (x) is the APR # of area 2.
 	  DefGbl = SHAPR3:x	; (x) is the APR # of area 3.
 	  DefGbl = SHAPR4:x	; (x) is the APR # of area 4.
 	  DefGbl = SHAPR5:x	; (x) is the APR # of area 5.
 	  DefGbl = SHAPR6:x	; (x) is the APR # of area 6.
 	  DefGbl = SHAPR7:x	; (x) is the APR # of area 7.
 
 	Also, Pascal programs must preallocate their stack space with
 	the EXTSCT command, in order to stop the OTS from trying to put
 	its heap where the SHEAP will go.
 
 	All Procedures and Functions use the Pascal Calling Sequence.
 
 
 	Error Codes
 
	E.SUCC = 1	; Operation Successful
	E.PGLK = -1	; Page Locked 
	E.PGNM = -2	; Page Not Mapped 
	E.DIRE = -3	; Directive Error 
	E.PGUS = -4	; Page In Use 
    	E.NCON = -5	; Not Connected to Page 
	E.OUTR = -6	; Out of Regions
	E.NOSP = -7	; No space left in this region for allocate.
	E.NoRg = -10	; No Region List
	E.NSRg = -11	; No Such Region
 
 	Directive Numbers (for error messages)
 
	D.ATRG = 1
	D.CRRG = 2
	D.CRAW = 3
 	D.MAP  = 4
	D.DTRG = 5
 
 	Pre Defined Types
 
  type
    SHeapStatusType = packed array [1..3] of integer;
 
    SuperPointerType = 
      record
        Region : integer;
        Ptr    : ^integer;  { Program uses type casting to get real pointers }
      end;
 
 
  [External (SHCREA)]
  procedure Create_SuperHeap_Region(var SHeapStatus : SHeapStatusType;
 				    var RegionNumber : integer;
 					Area : integer := 1);
    external;
 
    This procedure creates a new 8Kb region, using the next available region
    number (gotten from SHP000).  The region is created with the name SHPxxx,
    where xxx is the RegionNumber.  The region header is then initialized.
 
  [External (SHCONN)]
  procedure Connect_To_Region(var SHeapStatus : SHeapStatusType;
 				  RegionNumber : integer;
 				  Area : integer := 1);
    external;
 
    This procedure attaches and maps to the region specified by RegionNumber, 
    and increments the Connect counter.   If there is already a region mapped
    at the time this procedure is called, it is unmapped.
 
  [External (SHDISC)]
  procedure Disconnect_From_Region (var SHeapStatus : SHeapStatusType;
 					RegionNumber : integer;
 					Area : integer := 1);
    external;
 
    This procedure disconnects (and de-attaches) from the region specified by
    RegionNumber.  Disconnecting is performed by decrementing the Connect 
    Counter.  If the Connect Counter is set to zero, then the region is deleted
    from the system.
 
  [External (SHMAP)]
  procedure Map_To_Region(var SHeapStatus : SHeapStatusType;
 			      RegionNumber : integer;
 			      Area : integer := 1);
    external;
 
    This procedure unmaps from the current region, if there is one, and then 
    maps to the new region.  If RegionNumber is currently mapped, then this
    routine has no effect.
 
 
  [External (SHNEW)]
  function SHeap_New (var SuperPointer : SuperPointerType;
 		          Size : integer;
 			  Area : integer := 1) : boolean;
    external;
 
    This function allocates a block of memory which is Size bytes long in
    the current page.  If there isn't enough space in the current page, the
    routine returns false, otherwise it returns true.  If it succesfully
    allocates the space, the SuperPointer is initialized to point to it.
 
    SHeap_New locks the current page before modifying it.  If the caller
    has already locked the page before calling New, the call will hang.
 
 
  [External (SHDISP)]
  procedure SHeap_Dispose(var SHeapStatus : SHeapStatusType;
 			      SuperPointer : SuperPointerType;
 			      Area : integer := 1);
    external;
 
    This function deallocates the block of memory at the location specified
    by SuperPointer, which is Size bytes long.  This space is then added to
    the free space list.
 
 
  [External (SHFREE)]
  function Free_Space(Area : integer := 1) : integer;
    external;
 
    This function returns the size of the largest allocatable space in the
    current region.
 
 
  [External (SHINIT)]
  procedure SHeap_Initialize (var SHeapStatus : SHeapStatusType;
 			      var NumOfAreas : integer);
    external;
 
    This procedure initializes the Super Heap system.  It performs the 
    following functions (not necessarily in the order stated):
 
      - Initialize static variables.
      - If it doesn't exist, create page SHP000 and initialize it.
      - Connect to SHP000.
 
    This procedure returns the Number of areas that the taskbuilder has
    specified (by the SHAREA global).
 
  [External (SHCURR)]
  function Current_Region(Area : integer := 1) : integer;
    external;
 
    This function returns the region number of the currently mapped region.
    A -1 means the area is not currently mapped to any regions.
 
 
  [External (SHLOAD)]
  function Region_Loaded (var SuperPointer : SuperPointerType;
 			      Area : integer := 1) : boolean;
    external;
 
    This function returns true if the region specified by SuperPointer is the
    currently mapped region.
 
  [External (SHLOCK)]
  function Lock_Current_Region(Area : integer := 1) : boolean;
    external;
 
    This function locks the current region for write access.  Theoretically,
    a task is not supposed to write into a region, unless it has it locked.
    This function returns true if it was able to lock the region.
 
 
  [External (SHUNLO)]
  procedure Unlock_Current_Region(Area : integer := 1);
    external;
 
    This function unlocks the current region, allowing other tasks to lock
    it.
 
 
  [External (SHLCKD)]
  function Region_Is_Locked(Area : integer := 1) : boolean;
    external;
 
    This function returns true if the current region is locked (not necessarily
    by this task).
 
 
  [External (SHWAIT)]
  procedure Wait_And_Lock(Area : integer := 1);
    external;
 
    This procedure waits until the current region is unlocked, and then locks
    it.
 
 
  [External (SHCONV)]
  procedure Convert_SuperPointer (var SuperPointer : SuperPointerType;
 				      Area : integer := 1);
 
  This procedure converts a given SuperPointer to use the region and base
  address that is in the specified Area.