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.