
COMMENT @%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

	Copyright (c) Berkeley Softworks 1991 -- All Rights Reserved

PROJECT:	PC GEOS
FILE:		hugearr.def

REVISION HISTORY:
	Name	Date		Description
	----	----		-----------
	Jim	8/91		Initial revision

DESCRIPTION:
	This file contains constants and exported routine defintions
	for the HugeArray code in the kernel.
		
	$Id: hugearr.def,v 1.1 97/04/04 14:23:00 newdeal Exp $

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%@

SetDef	__HUGEARR

StartKernel

;-----------------------------------------------------------------------------
;		Constants and Structures
;-----------------------------------------------------------------------------

;	This structure is allocated at the beginning of the directory block
;
HugeArrayDirectory	struct
    HAD_header	LMemBlockHeader <>	; 
    HAD_data	word 			; VM block link to first data block
    HAD_dir	lptr.ChunkArrayHeader	; chunk handle to ChunkArray
    HAD_xdir	word 			; link to next dir block (not used yet)
    HAD_self	word 			; vm block handle of self
    HAD_size	word 			; element size, 0=variable
HugeArrayDirectory	ends


;-----------------------------------------------------------------------------
;		Routines
;-----------------------------------------------------------------------------


global	HugeArrayCreate:far
;	
;	Create a Huge Array
;	
;	PASS:	bx	- VM file handle in which to create the array
;			  (not required if TPD_vmFile is set)
;		cx	- #bytes to allocate per element (0=variable size)
;		di	- #bytes extra to allocate in the array header
;	
;	RETURN:	di	- Huge Array Handle (this is a VM block handle)
;	


global	HugeArrayDestroy:far
;	
;	Destroy a Huge Array
;	
;	PASS:	bx	- VM file handle in which to create the array
;			  (not required if TPD_vmFile is set)
;		di	- VM block handle (returned by HugeArrayCreate)
;	
;	RETURN:	nothing


global	HugeArrayLock:far
;	
;	Dereference a Huge Array element.  
;	Should be used with HugeArrayUnlock
;	
;	PASS:	bx	- VM file handle in which to create the array
;			  (not required if TPD_vmFile is set)
;		di	- VM block handle (returned by HugeArrayCreate)
;		dx.ax	- element number to dereference
;	
;	RETURN:	ds:si	- pointer to requested element 
;		ax	- #consecutive elements available with returned pointer
;		cx	- #consectuve elements available before (and including)
;			  the requested element, in the same block.
;		dx	- size of the locked element
global	HugeArrayLockDir:far
;	
;	Lock the HugeArray directory block
;	Should be used with HugeArrayUnlockDir
;	
;	PASS:	bx	- VM file handle in which to create the array
;			  (not required if TPD_vmFile is set)
;		di	- VM block handle (returned by HugeArrayCreate)
;	
;	RETURN:	ax	- segment address of block

global	HugeArrayUnlock:far
;	
;	Unlock a dereferenced Huge Array element.  
;	Should be used with HugeArrayLock
;	
;	PASS:	ds	- sptr to element block (returned by HugeArrayLock)
;	
;	RETURN:	nothing


global	HugeArrayUnlockDir:far
;	
;	Unlock the HugeArray directory block
;	Should be used with HugeArrayLockDir
;	
;	PASS:	ds	- points at dir block
;	
;	RETURN:	nothing

global	HugeArrayAppend:far
;	
;	Append element(s) to the end of a HugeArray
;	
;	PASS:	bx	- VM file handle in which to create the array
;			  (not required if TPD_vmFile is set)
;		di	- VM block handle (returned by HugeArrayCreate)
;		cx	- number of elements to append (fixed size elements)
;			  OR
;			  size of element in at ds:si (variable size elements)
;		bp.si	- fptr to buffer holding element data.  
;			  If (bp=0), space is allocated, but not initialized
;	
;	RETURN:	dx:ax	- new element number (if multiple elements appended,
;			  this is the number of the first element appended)
;	

global	HugeArrayInsert:Far

;	Insert element(s) into a HugeArray
;	
;	PASS:	bx	- VM file handle in which to create the array
;			  (not required if TPD_vmFile is set)
;		di	- VM block handle (returned by HugeArrayCreate)
;		cx	- number of elements to insert (fixed size elements)
;			  OR
;			  size of element in at ds:si (variable size elements)
;		dx:ax	- element number. New element will be inserted before 
;			  this one
;		bp.si	- fptr to buffer holding element data
;			  If (bp=0), space is allocated, but not initialized
;	
;	RETURN:	nothing
;	

global	HugeArrayReplace:far
;	
;	Replace element(s) in a HugeArray
;	
;	PASS:	bx	- VM file handle in which to create the array
;			  (not required if TPD_vmFile is set)
;		di	- VM block handle (returned by HugeArrayCreate)
;		cx	- number of elements to replace (fixed size elements)
;			  OR
;			  size of element in at ds:si (variable size elements)
;		dx:ax	- element number. Elements will be replaceed 
;			  starting with this one
;		bp.si	- fptr to buffer holding element data
;			  If (bp=0) element(s) is(are) initialized to zero.
;	
;	RETURN:	nothing
;	

global	HugeArrayDelete:far

;	Delete element(s) in a HugeArray
;	
;	PASS:	bx	- VM file handle in which to create the array
;			  (not required if TPD_vmFile is set)
;		di	- VM block handle (returned by HugeArrayCreate)
;		cx	- number of elements to delete
;		dx:ax	- element number. New element will be deleted starting
;			  with this one.
;	
;	RETURN:	nothing
;	

global	HugeArrayGetCount:far

;	Get the number of element(s) in a HugeArray
;	
;	PASS:	bx	- VM file handle in which to create the array
;			  (not required if TPD_vmFile is set)
;		di	- VM block handle (returned by HugeArrayCreate)
;	
;	RETURN:	dx.ax	- number of elements in array
;	

global	HugeArrayNext:far
;	
;	Lock the next HugeArray element
;	
;	PASS:	ds:si	- pointer to HugeArray element
;		bx	- VM file handle (not req'd if TPD_vmFile is set)
;
;	RETURN:	ds:si	- pointer to prev element (may be diff block)
;		ax	- #consecutive elements available with pointer
;			- returns zero if we were at the last element of array
;		dx	- Size of the element (if variable sized)
;	

global	HugeArrayPrev:far
;	
;	Lock the previous HugeArray element
;	
;	PASS:	ds:si	- pointer to HugeArray element
;		bx	- VM file handle (not req'd if TPD_vmFile is set)
;	
;	RETURN:	ds:si	- pointer to prev element (may be diff block)
;		ds:di	- pointer to first element in block
;		ax	- #elements available from first element to desired
;			  element (eg, if si == di, then ax=1)
;			- returns zero if we were at the first element of array
;		dx	- Size of the element (if variable sized)
;

global	HugeArrayExpand:far
;	
;	Insert one or more new elements at a specific place in a HugeArray.
;	If the elements are fixed sized, then multiple elements can be inserted
;	with one call.  If the elements are variable sized, then only one
;	element can be inserted at a time.
;	
;	PASS:	ds:si	- Pointer to locked HugeArray element
;		cx	- number of elements to insert (fixed size elements)
;			  OR
;			  size of data (variable sized elements)
;		bp:di	- pointer to data for element(s).  If bp=0, then space
;			  will be allocated, but not initialized.
;	
;	RETURN:	ds:si	- pointer to first element of previous block 
;			  (ds may have changed)
;		ax	- #consecutive elements available with returned pointer

global	HugeArrayContract:far
;	
;	Delete one or more new elements from a HugeArray.
;	
;	PASS:	ds:si	- Pointer to locked HugeArray element
;		cx	- number of elements to delete 
;	
;	RETURN:	ds:si	- still points at same element number (ds may have
;			  changed)

global	HugeArrayDirty:far
;	
;	Mark the currently locked HugeArray VM block as dirty
;	
;	PASS:	ds:si	- Pointer to locked HugeArray element
;	
;	RETURN:	nothing

global	HugeArrayResize:far
;	
;	Resize a huge-array element. If it gets smaller then data at the end
;	is truncated (and therefore lost). If it gets larger the new data is
;	zero-initialized.
;	
;	PASS:	bx	- VM file handle in which to create the array
;			  (not required if TPD_vmFile is set)
;		di	- VM block handle (returned by HugeArrayCreate)
;		dx:ax	- element number.
;		cx	- new element size.
;	
;	RETURN:	nothing
;

global	HugeArrayEnum:far
;	
;	Enumerate the elements in a huge-array to a callback routine.
;
;	The callback is not allowed to modify the elements in any way
;	it can only examine them.
;	
;	PASS:	On stack:
;			File				(pushed first)
;			Array				(pushed second)
;			Callback routine		(pushed third)
;			Element to start at		(pushed fourth)
;			Number of elements to process	(pushed fifth)
;		bx, cx, dx, bp, es = Set for callback
;	RETURN:	carry set if callback aborted
;		bx, cx, dx, bp, es = Returned from callback
;	DESTROYED: bx
;
;	Callback should be defined as:
;		Pass:	ds:di	= Pointer to element
;			ax	= Element size (if variable sized)
;			bx, cx, dx, bp, es - Passed by caller or callback
;		Return:	carry set to abort
;			ax, bx, cx, dx, bp, es - Data for next callback
;		Destroyed: nothing
;

;----------------
global ECCheckHugeArray:appfar
;	
;	Validate an entire HugeArray data structure
;	
;	PASS:	bx.di	VM File and Block handle
;	
;	RETURN:	nothing

global HugeArrayCompressBlocks:far
;	
;	Compress all the free space out of VM blocks containing HugeArray data
;	
;	PASS:	bx.di	VM File and Block handle
;	
;	RETURN:	nothing

;----------------

global HUGEARRAYCREATE:far
global HUGEARRAYDESTROY:far
global HUGEARRAYLOCK:far
global HUGEARRAYLOCKDIR:far
global HUGEARRAYUNLOCK:far
global HUGEARRAYUNLOCKDIR:far
global HUGEARRAYAPPEND:far
global HUGEARRAYINSERT:far
global HUGEARRAYREPLACE:far
global HUGEARRAYDELETE:far
global HUGEARRAYGETCOUNT:far

global HUGEARRAYDIRTY:far
global HUGEARRAYNEXT:far
global HUGEARRAYPREV:far
global HUGEARRAYEXPAND:far
global HUGEARRAYCONTRACT:far
global HUGEARRAYRESIZE:far

global ECCHECKHUGEARRAY:far
global HUGEARRAYCOMPRESSBLOCKS:far
global HUGEARRAYENUM:far
EndKernel
