 Directory Manipulation
 Directory Buffer Structure
 How To Use These Routines
 Buffer Allocation           - DBUFFER
 Disk Free Space             - DFREE
 Directory Alphabetization   - DIRALPHA
 Generalized Dir Routines    - DIRF, DIRFS
 Directory Load Routines     - DIRLOAD, DIRSLOAD
 Directory Pack Routines     - DIRPACK, DIRNPACK
 Optimal Directory Routines  - DIRQ, DIRQS
 Entry Selection Routine     - DIRSEL
 Disk Parameter Information  - DPARAMS
 File Size Computation       - FSIZE
:           Directory Manipulation Routines 

This set of SYSLIB routines concerns itself with the loading
of and access of a disk directory for the general purposes
of the user.  Included in this set of routines are the
functions of:

    - Preallocation of buffer space for the routines
    - Loading of all undeleted directory entries into a
        buffer, constantly checking for memory overflow
    - Determining the amount of free space on the disk
    - Computing the size of a file in Kilobytes (K)
    - Sorting a loaded directory by file name and type or
        by file type and name
    - Selecting (by marking) a set of directory entries
        which match a given ambiguous file spec
    - Packing the loaded directory, leaving in it only
        those entries marked by the select routine


The majority of these routines is intended to be used to
provide a flexible directory access system which can be
tailored by the user to his specific needs.  For instance, with
the DIRLOAD routine separated from the rest, several different
loads of the directory (from, for instance, different ambiguous
file specs) can be performed, and then one selection and one
sort on all file specs loaded can be done.

The DIRQ/DIRQS pair are intended for those applications which
do not need this kind of flexibility.  DIRQ (quick) and DIRQS
(quick with sizing information) perform a load, select, and
sort based on only one file specification.  Using DIRQ/DIRQS
instead of DIRF/DIRFS results in less code being generated and
(generally) faster execution.

:              Directory Buffer Structure 

DIRLOAD and DIRSLOAD are used to load a directory from disk
into memory.  The entries loaded are all non-deleted entries
in either a particular user area or all user areas on the
disk which is currently logged in.

Each file entry is 16 bytes long, structured as:

 Byte                                    1  1  1  1  1  1
  offset   0  1  2  3  4  5  6  7  8  9  0  1  2  3  4  5
 
 Example  00  T  E  S  T              C  O  M 01 00 00 79
     User_/  \______________________/\_______/ |  |  |  |
                    File Name           Type   /  |  |  |
                             * Extent Number__/  S2 DM  |
                                         Record Number__/

*  Ext is the file extent; for DIRLOAD, it is the first 
extent number of the file; for DIRSLOAD, it is the last 
extent number of the file
:               How To Use These Routines 

The DIRF or DIRFS routines will probably be used to perform
your directory access functions the vast majority of the time.
Given a buffer, an ambiguous file spec, and a selection flag,
DIRF and DIRFS load the desired files for you and then you can
work with the 16-byte file entries from there.  A typical
calling sequence for DIRF or DIRFS is:

	CALL	CODEND		; Point to buffer space
	LD	DE,FCB		; Point to FCB of File Spec
	LD	A,11000000B	; Select all files in User 0
	CALL	DIRF		; Load entries
	JR	Z,TPAOVFL	; ..jump if error
	...			; HL pts to 1st entry, BC=
				;   Number of files

 If you wish to deviate from the "normal" use for DIRF and
DIRFS, access to the routines used by DIRF and DIRFS is
available.  A case in which you may want to do this is when you
are interested in files which match more than one file spec,
such as *.ASM and *.TXT.  A typical calling sequence for this
type of access is:

 ; Setup
	CALL	CODEND		; Point to buffer space
	CALL	DBUFFER		; Get internal info and ptrs
	CALL	DIRLOAD		; ..or DIRSLOAD to load names
	JR	Z,TPAOVFL	; Jump if error condition
	...

 ; Select first set of files

	LD	DE,FCB1		; Pt to first FCB to match
	LD	A,11000000B	; Select all files in User 0
	CALL	DIRSEL		; Select entries from Buffer


 ; Repeat the following 2 lines as necessary

	LD	DE,FCB2		; Pt to 2nd FCB to match
	CALL	DIRSEL		; select again

 ; Finish up

	CALL	DIRPACK		; Pack the file entries,
				; ..leaving only the valid
				; ...entries in the buffer
	LD	A,0		; alphabetize
	CALL	DIRALPHA

 ; Done -- HL pts to first file entry, BC=number of entries

:DBUFFER - Buffer Allocation Routine

  ENTER: HL = Address of Buffer start (usually CODEND to CCP)
  EXIT : HL = Points to first byte at which DIR entries loaded
	  A <> 0, Zero Flag Clear (NZ) if Ok
              A = 0, Zero Flag Set (Z) if CCP overwritten
  USES : AF,HL

 Usage:  This routine allocates the buffer space necessary for
  the set of directory functions in general.  In particular, it
  allocates the necessary space for the alphabetization func-
  tion as well as the loaded directory itself.  This routine
  must be used if the DIRALPHA routine is to be later used to
  sort the directory; this routine allocates all the space
  necessary by DIRALPHA to sort the routine (pointer space).
  If this routine is called, it is not necessary to call the
  DPARAMS routine.

:DFREE - Free Space Computation Routine    (CP/M 2.2 & 3.x)

  ENTER: None
  EXIT : DE = Free Disk Space in K Bytes on current disk
  USES : DE
  REQUIREMENTS: DPARAMS (or DBUFFER which calls DPARAMS)
	must be called before using this routine under CP/M
	2.2 compatible systems.

 Usage: This routine is commonly used in directory listing
  routines to obtain the amount of free space on the logged
  disk.  It may also be used before a file copy to insure
  that adequate space exists on the destination drive.

  Under CP/M Plus (CP/M 3.x), BDOS Function 46 is automatically
  used to properly return file size in a banked system.

:DIRALPHA - Directory Alphabetization Routine

  ENTER: HL = Pointer to first directory entry
                 (usually set by DBUFFER)
         BC = Number of files to sort
                 (usually set by DIRLOAD or DIRSLOAD)
          A = Sort Flag; 0 = Sort by file name then type
                     Non-0 = Sort by file type then name
  EXIT : None (directory list is sorted)
  USES : AF

 Usage:  To alphabetize the files in the directory pointed to
  by HL by either file name and type (STEST.ASM goes before
  TEST.AAA) or by file type and name (TEST.AAA goes before
  STEST.ASM).

  In the unlikely event that an internal error is detected in
  the internal sort routine, DIRALPHA will send a BELL
  character to the console and abort to the Operating system
  via the BDOS Warm Boot Vector.

:DIRF  - Generalized Directory Routine without Sizing
 DIRFS - Generalized Directory Routine with Sizing Data

  ENTER: HL = Pointer to Buffer Area after user code
	 DE = Pointer Selection FCB (first 12 bytes used)
	  A = Selection flag structured as:
		Bit 7 - Set to Select Non-System Files
		Bit 6 - Set to Select System Files
		Bit 5 - Set to Select All User Areas
		Bits 4-0 - If Bit 5 Reset (0), contains
			  Number of User Area to Select
  EXIT : HL = Pointer to First 16-byte File Entry in buffer
	 BC = Number of files selected
	  A <> 0, Zero Flag Clear (NZ) if Ok
	      A = 0, Zero Flag Set (Z) if TPA Overflow
  USES : AF,BC,HL

 Usage:  These routines are the most flexible, though slowest,
  of the Directory routines in SYSLIB.  Both routines initial-
  ize the Buffer area, load a Disk Directory, select a
  specified set of files, pack and sort the list of files.
  DIRF executes slightly faster since it does not obtain sizing
  information, while DIRFS obtains all information which may be
  passed to the FSIZE routine to determine the size of each
  entry in the Directory.

  For entry parameters, the address for the Buffer is usually
  obtained from a call to CODEND which returns the address of
  free memory above your program.  The FCB used for selection
  need not be a complete FCB since only the characters in the
  Filename and Type fields are used.  It may therefore be as
  short as 12 bytes (Drive byte, Filename and Type).


:DIRLOAD  - Directory Load Routine without Sizing
 DIRSLOAD - Directory Load Routine with Sizing Data

  ENTER: HL = Pointer to Buffer Area after user code
  EXIT : BC = Number of 16-byte file entries loaded in Buffer
	  A <> 0, Zero Flag Clear (NZ) if Load Ok
	      A = 0, Zero Flag Set (Z) if TPA Overflow Error
  USES : AF,BC

 Usage:  These routines load entries for all undeleted files on
  the currently logged drive for later selection, sorting or
  other actions.  DIRLOAD is faster than DIRSLOAD since it does
  not have to load sizing information, while the latter returns
  information which will allow FSIZE to return the file size.

  If sorting is to be done, the value returned in HL from
  the DBUFFER routine is a correct input for these routines.

:DIRPACK  - Pack Dir Buffer retaining Selected Entries
 DIRNPACK - Pack Dir Buffer retaining Non-Selected Entries

  ENTER: HL = Pointer to Directory Buffer (from DBUFFER)
	 BC = Number of files in Buffer (from DIRLOAD)
  EXIT : BC = Number of files remaining in Buffer
  USES : BC

 Usage:  These routines are used after selection of Direc-
  tory routines with DIRSEL or equivalent to delete all
  files which have not been selected by setting the Most
  Significant bit of the first byte in each entry.  DIRPACK
  removes references to those files NOT marked, while
  DIRNPACK removes those entries which ARE marked, keeping
  those which are NOT marked (Negative Pack).

  Note:  DIRSEL MUST be called before DIRNPACK is used
  since DIRNPACK uses an internal flag set by DIRSEL (for 
  SYSTEM and R/O information).

:DIRQ  - Quick Access Directory Routine without Sizing
 DIRQS - Quich Access Directory Routine With Sizing Data

  ENTER: HL = Pointer to Buffer Area  (from CODEND)
	 DE = Pointer to 12-byte Select FCB
	  A = Selection Flag
		Bit 7 - If Set, Select Non-System Files
		Bit 6 - If Set, Select System Files
		Bit 5 - If Set(1), Sort by File Type and Name
			If Reset(0), Sort by Name and Type
		Bits 4-0 - Unused
  EXIT : HL = Points to first 16-byte Buffer Entry
	 BC = Number of Files Selected
	  A <> 0, Zero Flag Clear (NZ) if Load Ok
	      A = 0, Zero Flag Set (Z) if TPA Overflow
  USES : AF,BC,HL

 Usage:  These routines are commonly used where a simple
  sorted directory list is needed with minimum time and code
  overhead.


  Information is gathered by DIRQS which will allow FSIZE
  to calculate file sizes, while DIRQ does not.  Since
  DIRQS obtains sizing information as it loads the Directory
  Information, it runs slightly slower.

  In the unlikely event of an internal pointer sort error,
  a BELL character will be sent to the Console and the
  program will be aborted with a Warm Boot.

:DIRSEL - Directory Entry Selection Routine

  ENTER: HL = Pointer to Directory Buffer (set by DBUFFER)
	 DE = Pointer to 12-byte Selection FCB
	 BC = Number of files in Directory (from DIRLOAD(S))
	  A = Selection Flag as:
		Bit 7 - Set to Select Non-System Files
		Bit 6 - Set to Select System Files
		Bit 5 - Set to Select All User Areas
		Bits 4-0 - If Bit 5 Reset (0), contains
			  Number of User Area to Select
  EXIT : None.  MSB set on first byte of selected entries
  USES : None

 Usage:  DIRSEL marks all files in the Directory Buffer
  matching the specified criteria by setting the MSB of the
  first byte.  It may be used after any of the SYSLIB Dir-
  ectory routines (DIRF/DIRFS/DIRQ/DIRQS) to select a
  subset of all entries in the Directory Buffer.

:DPARAMS - Disk Parameter Information Extraction Routine

  ENTER: None
  EXIT : None  (Information is placed in local Buffers)
  USES : None

 Usage:  This routine extracts necessary information from
  the Disk Parameter Block (DPB) and stores it away for use
  by other Disk Directory Routines.  If DBUFFER (or any of
  the SYSLIB Directory Routines) is called, it is not
  necessary to call DPARAMS again.

  The following Global Variables are set from DPB info:

	BLKSHF <-- Block Shift Factor (1 Byte)
	BLKMSK <-- Block Mask (1 Byte)
	EXTENT <-- Extent Mask (1 Byte)
	BLKMAX <-- Max Number of Blocks on Disk (2 Bytes)
	DIRMAX <-- Max Number of Dir Entries (2 Bytes)

:FSIZE - File Size Computation Routine

  ENTER: HL = Pointer to First Byte of 16-byte File Entry
  EXIT : DE = File size in KiloBytes (K)
  USES : DE
  REQUIREMENTS: DPARAMS (or DBUFFER, DIRFS, DIRQS, DIRSLOAD)
	must be called before FSIZE so that the correct disk
	parameter information is established.

 Usage:  This routine is normally used to compute the size
  of a file contained in a Directory produced by DIRSLOAD
  or DIRQS.  This routine will generally work, but return
  incorrect results, if the entry was loaded by DIRLOAD or
  DIRQ which do not return sizing information.
