;
;	File:		BTScanPriv.a
;
;	Contains:	BTree scanner's private equates
;
;	Written by: Dave Feldman
;
;	Copyright:	© 1989-1990 by Apple Computer, Inc., all rights reserved.
;
;	Change History (most recent first):
;
;		 <3>	 8/20/90	gbm		(dnf and gbm, really) Change the name of LastTime to
;									LastGoodNode for clarity.  Also improve explanation of the
;									Physical Scanner
;		 <2>	 2/26/90	dnf		Add NoMoreReads bit, LastTime bit, cpGoodNodeCount
;	   <1.2>	  9/7/89	dnf		Added CatPosition record
;	   <1.1>	 7/31/89	dnf		Change ForceRead to FirstTime
;	   <1.0>	 5/30/89	dnf		Integrate CatSearch, FileID's and Desktop Database Mgr into one
;									ptch
;
;	To Do:
;

 ; State record on A6 stack while PScan is in progress
PSR			RECORD 0, Increment
fcbPtr		ds.l	1					; ptr(FCB) for catalog file under search
btcbPtr		ds.l	1					; BTCB for catalog file under search
curNodePtr	ds.l	1					; points to current node in read buffer
readBufPtr	ds.l	1					; the read buffer
readBufLen	ds.l	1					; length in bytes of read buffer
goodCount	ds.l	1					; # of good nodes we've seen so far
maxNodes	ds.l	1					; # of allocated nodes in tree (calc from btcb)
buf1stNode	ds.l	1					; node # of 1st node in read buffer
bufCount	ds.l	1					; # nodes in read buffer
curNode		ds.l	1					; node # of current node
curRec		ds.w	1					; record in current node (index)
flags		ds.b	1					; see flag bits
			align	2					; make size of state record even
size		equ	*-PSR
	ENDR

; The Physical Scanner
;
; The btree physical scanner scans any ROM-btree-manager-like btree and returns
; each of the records found in the leaf nodes to the caller.
;
; BTIPScan is required before any records are read.  It converts a catPosition 
; record into an internal state record to use while reading.
;
; BTGetPhys delivers the next record
;
; BTEndScan converts the internal state record back into a catPosition record
; that can be used to continue the search from the current position.
;
; The btree parser state machine uses a node and record index field to keep
; track of its position in the btree.  Each time BTGetPhys needs a record, the record
; index is incremented and validated.  If the index is off the end of the current
; node, the node number is incremented and validated (forced into the read buffer).
;
; There are several exceptions.  To allow a catPosition to specify the beginning
; of a btree, the record index is not incremented for the first record fetched
; on a scan.  To compensate for this BTEndScan increments the record index when 
; converting its state record into a catPosition.
;
; Optimizations:
;	There are two optimizations in the btree scanner
;
;	1) Even after a timer has expired, always use up the nodes already
;	   in the read buffer.  The NoMoreReads bit tells ValidateNode about this
;
;	2) Count the number of valid nodes of all types (header, map, index, leaf)
;	   and end the search when the count equals the number of allocated nodes
;	   indicated by the btree header.  
;			ValidateNode counts all valid non-leaf nodes
;			ValidateRecord counts leaf nodes as it increments the current
;			node counter.
;
; flag bits
; These three bits control the corner cases of the ValidateNode
;
; FirstTime 	Forces a read without trying to see if any nodes are already
;				in the buffer.  Tells BTGetPhys not to increment the record
;				index.
; NoMoreReads 	Indicates that the caller would not like to take any more disk hits
;				Nodes that are in the buffer (conceivably quite a few) are still
;				parsed and returned
; LastGoodNode	Indicates that the last valid node (determined by counting valid
;				nodes and comparing against the free space listed in the btree
;				header) was seen in the previous call to ValidateNode.  If this 
;				is set on entrance to ValidateNode we know to return an eofErr.
;				

FirstTime		equ		7
NoMoreReads		equ		6
LastGoodNode	equ		5
										
; the catalog position record
CatPosition		record	0, increment
cpWriteCount		ds.l	1				; catalog state for this position		<dnf 1.2>
cpNodeNumber		ds.l	1				; node number of record					<dnf 1.2>
cpRecNumber			ds.w	1				; record # within node					<dnf 1.2>
cpGoodNodeCount		ds.l	1				; # of good nodes we've seen
cpResrv				ds.b	2
size				equ		*-CatPosition
				endr

; HIOParam block
HIOP		RECORD 0, Increment
qLink		ds.l	1;
qType		ds.w	1;
ioTrap 		ds.w	1;
ioCmdAddr 	ds.l	1;
ioCompletion ds.l	1;
ioResult 	ds.w	1;
ioNamePtr 	ds.l	1;
ioVRefNum 	ds.w	1	; integer
ioRefNum 	ds.w	1	; integer
ioVersNum 	ds.b	1	; SignedByte
ioPermssn 	ds.b	1	; signedByte
ioMisc 		ds.l	1	; ptr
ioBuffer 	ds.l	1	; ptr
ioReqCount 	ds.l	1	; longint
ioActCount	ds.l	1	; longint
ioPosMode 	ds.w	1	; integer
ioPosOffset ds.l	1	; longint
size	equ		*-HIOP
	ENDR