.* .pm 5 :gdoc sec='' :frontm :titlep :title.FASTOPEN UTILITY HIGH LEVEL DESIGN :date. :author.J. K. :ETITLEP :toc :body .DH NUM .*.pa &SYSDATE. .*:H1.INTRODUCTION .*:H1.ARCHITECTURE OVERVIEW :H1.FASTOPEN DESIGN :H2.FASTOPEN UTILITY :H3.FASTOPEN Overview FASTOPEN is a utility that allows DOS to maintain the information about files that have been opened. The purpose is to reduce the number of times DOS has to look into the directory area of the disk for information on the file once the information is stored by FASTOPEN. In real life, many application programs, especially current database systems on the market, tend to open the same file repeatedly and every open operation needs an access to the disk if the information does not exist in the DOS buffer. The FASTOPEN utility will eliminate these disk accesses, and hence will increase the efficiency of DOS performance. :H3.FASTOPEN Operational Description Conceptually FASTOPEN itself is a database maintained by DOS. The data will be stored and maintained in the system RAM. FASTOPEN is a user-installable, stay resident utility loaded by entering a command .fo off 1). FASTOPEN D:{=L} ... where "..." means a possible repetition. "D:" is a drive letter for a non_removable media. "L" is the maxium number of files and subdirectories that can be stored in the drive cache. The default value is 34, minimum value, 10. The total number for all the drives is less than 1000. .fo on :H4.Name Caching FASTOPEN will keep the history of the accessed subdirectory and file information in LRU fashion. The data are stored in a partial tree structure that represents all the recently accessed files and subdirectories of that drive. The number of entries entered by the user, or the default number of 34, represents the maximum number of nodes and leaves of the tree. As it suggests, the bigger the number is, the more the efficient it will be. Currently each additional increase of the entry will take 36 bytes, which is the fixed length of a node. The number entered by the user should be bigger than the deepest nesting of path entries in the drive. The operation on this name cache is similar to the operation on the physical drive. With the look up request, FASTOPEN will traverse the name cache tree from the root to the bottom to find the requested path, filename. If found, then the pointer to the file or subdirectory information packet will be returned, else FASTOPEN will return the string pointer that points up to the matching subdirectory name. In this case, if DOS wants to insert the rest of the subdirectory/file information an insert operation should be requested for every subdirectory/file. FASTOPEN will use the information from the previous Look_up operation for a sequence of Insert operations. At this moment, if there are any free entries left, then it will be used. Otherwise, FASTOPEN will delete the least recently used leaf. Any node cannot be deleted until the node becomes an empty leaf, i.e., without children. If a file or a directory has been removed, then DOS will update the name cache tree with the Delete request. The path, file will be looked up first, and if found, then the corresponding entries will be free to the free entry chain. If not found, then still it is O.K. since the matching file entries had been removed by the LRU scheme. :H3.Fastopen Interface When installed, by the nature of the functionality, FASTOPEN becomes a part of DOS and a private communication mechanism will be established. Inside DOS, vector pointers are established for FASTOPEN and will be initialized by the call "CALLinstall" macro by the FASTOPEN initialization. The structure of the FASTOPEN entry will look like; .fo off FASTOPEN_ENTRY struc FASTOPEN_ENTRY_SIZE dw 4 ;size of the following FASTOPEN_NAME_CACHING dd ? ;FASTOPEN_FATCHAIN_CACHING dd ? ;not for DOS 3.3 ;NUMBER_OF_SFTS dw ? ;# of files - 3 FASTOPEN_ENTRY ends .fo on The initial vector pointer for FASTOPEN_NAME_CACHING points to a dummy routine in DOS which simply set the carry flag and set AX to 0FFFFh. When FASTOPEN is installed, then this vectors table will be established to point to the matching procedures in FASTOPEN module. The register AL will contain subfunction value on entry to FASTOPEN. .fo off ;FASTOPEN NAME CACHING Subfunctions fastopen_name_look_up equ 1 fastopen_name_insert equ 2 fastopen_name_delete equ 3 ;fastopen_name_purge equ 4 ;Not for DOS 3.3 .fo off 1. Name Caching a. Look up IN) DS:SI -> d:path ES:DI -> DIR_INFO buffer in DOS to be filled by FASTOPEN ES:CX -> Extended_Info buffer in DOS to be filled by FASTOPEN OUT) if found, DS:SI -> the last character of the path, i.e., 0. ES:DI -> DIR INFO ES:CX -> Extended INFO (explained in the data structure) else if there exist the name cache for the drive, but could not completely find the matching path, DS:SI -> "\" following the directory that FASTOPEN can find the match, Will points to "\" after "d:" if no matching root directory is found. ES:DI -> Compct_Dir_Info of the subdirectory FASTOPEN can find the match. ES:CX -> the matching directory's Extended INFO If cannot find the matching root directory entry, then ES:DI, ES:CX are undetermined. else carry flag set and AX = 0FFFFh. b. Insert IN) DS:DI -> DIR info ES:BX -> Extended info OUT) If failed, then carry flag set and AX = 0FFFFh. Insert operation handles only one file or subdirectory at a time. So, usually insert operations are performed in a sequential manner. A look up operation should be performed before any new sequential insert operation. FASTOPEN will keep the information of the pervious look up operation in CURRENT_NODE. The CURRENT_NODE points to the matching directory node of the previous Look up operation. The next insert operation will use this CURRENT_NODE information to insert the directory or file information. So, DOS will call only one Look_ up operation and possibly several Insert operation to insert the path. For example, suppose DOS wants to look up C:\DIR1\DIR2\FILE1 and FASTOPEN only has the inforamtion up to C:DIR1. After the look up operation, FASTOPEN will return with DS:SI points "\" following C:\DIR1. At this moment, if DOS decides to insert this information,then it sets DS:DI to DIR_INFO, and ES:BX to EXTENDED_INFO of the subdirectory DIR2, and will request an insert operation. When control returned back to DOS, then it will set this time DS:DI and ES:BX to those of FILE1, and will call an another insert operation. At the first insert operation, FASTOPEN automatically knows that those informaton given by DOS belong to the child of C:\DIR1, and will install it as a child. In the second operation, again FASTOPEN knows that it is for the child of C:\DIR1\DIR2 and will accordingly install the information for FILE1. c. Delete IN) DS:SI -> d:path OUT) If failed, then carry flag set and AX = 0FFFFh. .fo on :H3.FASTOPEN Special Considerations FASTOPEN uses the following DOS function calls in its initialization rouitine. No DOS or BIOS function calls are allowed inside the main routine that is resident once installed. :ul :li.AH = 40h, Int 21h; Write to device for the messages, :li.AH = 31h, Int 21h; Terminate Process and Remain Resident, :li.AH = 48h, AH = 49h, AH = 4Ah, Int 21h; Allocate, free and modify memory block. :eul :p. To prevent the corruption of any DOS operation, once FASTOPEN is loaded it cannot be reloaded. :H4.FASTOPEN Top Level Design :H5.Data Structure The structures of the records in FASTOPEN are: .fo off NAME_record struc LRU_pointer dw -1 Child_pointer dw -1 Sibling_pointer dw -1 MRU_pointer dw -1 Compct_Dir_info db 22 dup (?) Extended_Info db 5 dup (?) NAME_record ends Extended_Info struc dirpos db 0 dirsec dw 0 clusnum dw 0 Extended_Info ends Drive_cache_header struc LRU_ROOT dw 0 ;Start of LRU chain for this Name cache Child_ptr dw -1 ;points to the name cache Sibling_ptr dw -1 ;points to the next drive header MRU_ROOT dw 0 ;set to the end of LRU chain Drive_letter db 'C' Num_Entries dw 0 Name_Cache_start dw 0 ;Start of name cache for this drive Drive_cache_header ends Cmpct_Dir_Info struc CD_File_name db 11 dup (0) CD_File_attr db ? CD_time dw ? CD_date dw ? CD_cluster dw ? CD_Filesize dd ? Cmpct_Dir_Info ends Dir_Info struc ;= full directory entry information. DI_head db 12 dup (?) DI_skip db 10 dup (0) ;reserved area. All the time 0. DI_tail db 10 dup (?) Dir_Info ends .fo :H5.FASTOPEN Hierarch :H6.FASTOPEN Components .fo off   旼컴컴컴컴컴컴커  � FASTOPEN �  읕컴컴컫컴컴컴켸  �  �  旼컴컴컴컴컴컴컴컴컨컴컴컴컴컴컴컴컴컴�  � �  V V 旼컴컴컴컴컴컴커 旼컴컴컴컴컴컴커 � INIT � � MAIN � 읕컴컴컴컴컴컴켸 읕컴컴컫컴컴컴켸  �  V  旼컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴커  � �  � LOOK_UP, INSERT, DELETE, INIT_TREE �  � �  � (SUPPORTING MODULES) �  � �  � GET_FREE_NODE, PRE_LRU_STACK, �  � SET_LRU, MAKE_NAME_RECORD, �  � UNFOLD_NAME_RECORD, PACK_DIR_NAME, �  � REMOVEFROMLRUCHAIN �  읕컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴켸  .fo :H6.FASTOPEN Memory Structure .fo off  Lo_memory 旼컴컴컴컴컴컴컴컴컴컴컴컴컴� 컫�  � LOOK_UP, � �  � INSERT, � M  � DELETE, � A  � & Supporting Routines � I  � � N  쳐컴컴컴컴컴컴컴컴컴컴컴컴컴� �  � INIT_TREE � �  쳐컴컴컴컴컴컴컴컴컴컴컴컴컴� 컵�  � DRIVE_CACHE_HEADER � I  � (After Init, this � N  � area will be used � I  � for name caches.) � T  � SHOW_ERR_MESSAGE � �  읕컴컴컴컴컴컴컴컴컴컴컴컴컴� 컨�   High_memory .fo .pa :H5.FASTOPEN Component Interfaces .fo off ;************************************************************************* ; ;SUBROUTINE: INIT ; ;INPUT: ; ;OUTPUT: ; ;DESCRIPTION: ; ; 1:(Installation check) ; { Get the entry pointer of FASTOPEN from DOS. ; Check the signature ($FASTOPEN01$) ; If already installed, ; then Show 'FASTOPEN already installed'; Exit ; } ; ; 2:(Parse the command line) ; Input: User input ; ; Output: Total_Entry_Num. ; Drive_Cache_Headers set. ; End_Cache_Header. ; ; { For every drive entered ; { Drive sanity check; ; Get_Num; ; if success and Total_Entry_Num < 1000, then ; Set Drive_Cache_Header; ; } ; } ; ; 3:(Check the system memory) - Check if the system has enough ; memory for the Name caches. ; Name cache will start from the ; End_Cache_Header. ; ; Input: Total_Entry_Num, End_Cache_Header, End_Init, ; Output: End_Caches ; { ; Needed_space = size of (Name_Record) * Total_Entry_Num; ; Needed_space = Needed_space - (End_Init - End_Cache_Header); ; Free allocated memory from End_Init (AH = 4Ah); ; Set memory block from End_Init to Needed_Space (AH = 48h); ; if fail, Show 'Insufficient memory for FASTOPEN cache'; ; Set End_Caches; ; } ; ; 4: jmp to INIT_TREE ; ;************************************************************************* .pa .fo off ;************************************************************************* ; ;SUBROUTINE: INIT_TREE ; ;INPUT: Drive_cache_header, End_Caches ; ;OUTPUT:Name_cache entries installed for every drive requested. ; LRU chain established for every drive. ; FASTOPEN entry pointer set in DOS. ; Terminate & stay resident. (Up to End_Caches) ; ;DESCRIPTION: ; ; 1:(Install_Name_Cache) ; Input: Drive cache header, End_cache_header (= Name cache start) ; Output:According to the information in the header, ; the name cache entries will be established. ; Also, LRU chain, MRU_pointer are established. ; ; { Buffer_start = End_cache_header; ; For every drive header ; { LRU_ROOT = Buffer_start; ; For (i=1;i=Num_Entries;i++) ; { MRU_pointer = Buffer_start; ; Buffer_start= Buffer_start + size_of (Name_record); ; if i = Num_Entries then LRU_pointer = -1 ; else LRU_pointer = Buffer_start; ; } ; } ; } ; ; 2:(Set FASTOPEN entry pointer in DOS) ; Use CALL INSTALL macro. ; ; 3: Terminate and stay resident up to Buffer_start; ; ;************************************************************************* .pa .fo off ;************************************************************************* ; ;SUBROUTINE: MAIN ; ;INPUT: Called by DOS throught Look_up, Insert, Delete requests. ; ;OUTPUT:Request performed based on LRU scheme. ; CX, DX, DS, ES, BP value saved. Other register are destroyed. ; ;DESCRIPTION: ; Call Pack_Dir_Name ;get the drive letter in BL ; Call Get_Drive_Cache_Header ;find the matching drive header ; if not found, then AX = 0ffffh, Carry set ; else if AL = Look_up then Call Look_up ; else if AL = Insert then Call Insert ; else if AL = Delete then Call Delete ; else AX = 0ffffh, Carry set. ; ; MAJOR SUBROUTINES: ; (Look_up) - Refer to Look_up subroutine. ; (Delete) - Refer to Delete subroutine. ; (Insert) - Refer to Insert subroutine. ; ; SUPPORTING SUBROUTINES: ; 1:(Get_Free_Node) - Get the entry from the LRU_ROOT, ; Set LRU_ROOT to the next entry of the ; LRU chain ; Input: none ; Output:Entry address. LRU_ROOT updated to the next entry. ; ; 2:(Pre_LRU_Stack) - This is needed to implement LRU scheme in ; a tree structure. Since the order of traversing a tree is ; from the root to bottom and from left to right, the direct ; implementation of LRU will result the parent the least mostly ; used one instead of the child. This is exactly in the reverse ; order to what had been expected. This procedure will ; solve this problem without loss of any efficiency. In the ; Look_up operation and found the match, the found entris will ; be saved with each of its LRU, MRU pointer modified to reflect ; the desired LRU order. ; These created mini LRU chain will be attached to the ; LRU chain again by SET_LRU. SET_LRU and PRE_LRU_STACK ; should work in a synchronized fashion. SET_LRU routine ; will be called in the beginning of every Look_up, Insert ; operation. PRE_LRU_Stack will be called whenever a matching ; entry is found in a Look_up operation, or whenever a new ; entry is inserted by the Insert operation. ; Input: Current_Drive,Target node. ; Output:Depth, Top, Bottom set ; ; 3:(SET_LRU) ; Input: Depth, Top, Bottom, Current_Drive ; Output:Mini LRU chain created by Pre_LRU_Stack will be ; placed at the end of LRU chain. ; ; 4:(MAKE_NAME_RECORD) - At Insert time, BOS will give ; two types of information. DS:DI -> Dir_Info, ES:BX -> Extended_ ; Info. The Name_Record is composed of Cmpct_Dir_Info and ; Extend_Info. MAKE_NAME_RECORD will simply make a Name_Record ; from the informations from DOS. ; Input: Dir_Info, Extended_Info ; Output:Name_Record ; ; 5:(UNFOLD_NAME_RECORD) - Inverse function of above. When Look_up ; operation finishes, then unfold the Name_Record of the current_ ; node for DOS. If the Current_Node is a drive_cache_header, ; then will just return. ; Input: CS:Current_Node, ES, DI, BX set for the buffer ; Output:ES:DI->Dir_Info, ES:BX->Extended_Info buffer in DOS. ; ; 6:(PACK_DIR_NAME) - At Look_up or Delete operation, DS:SI points ; to the requested full path, for ex., "C:\DIR1.EXT\DIR2\FILE.EXT", ; 0. This routine is smart enough to recognize ":","\" and 0 as ; a delimeter and will parse until the next delimeter and leave ; SI to the next delimeter found. Also, if it is a drive name ; it will set SI to the "\" after ":" for consistency and ; it will set BL to the drive letter. ; The main function of this routine is "pack" the given directory ; name into 11 bytes format. PACKED_NAME will be filled with ; the result. For example, when it is called the first time, ; DL = "C" and SI will point to "\" before DIR1.EXT. ; The second time, PACKED_NAME will be filled with ; "DIR1 EXT" and SI will points to "\" before "DIR2". ; Likewize, if this routine is called the fourth time, ; FILE.EXT has been parsed and DS:SI will points to 0. ; When this routine is called again, then it will return ; with carry signaling that it has reached the end. ; The user is required to call this routine consequtively ; until it returns with carry. ; Input: ; Output: ; ;************************************************************************* .pa .fo off ;************************************************************************* ; ;SUBROUTINE: LOOK_UP ; ;INPUT: DS:SI -> path ; ES:DI -> DIR_INFO buffer in DOS to be filled by FASTOPEN ; ES:CX -> Extended_Info buffer in DOS to be filled by FASTOPEN ; CS:BP -> Matching Drive_cache_header ; ;OUTPUT:if found, DS:SI -> the last character of the path, i.e., 0. ; ES:DI -> DIR_INFO ; ES:CX -> Extended_INFO (explained in the data structure) ; else if there exist the name cache for the drive, but could not ; completely find the matching path, ; DS:SI -> "\" following the directory that FASTOPEN can ; find the match, ; Will points to "\" after "d:" if no matching ; root directory is found. ; ES:DI -> Dir_Info of the subdirectory FASTOPEN ; can find the match. ; ES:CX -> the matching directory's Extended INFO ; If cannot find the matching root directory entry, then ; ES:DI, ES:BX are undetermined. ; If the requested path is "D:\,0" then FASTOPEN will ; return with carry flag set and, AX = 0ffffh. ; else carry flag set and AX = 0FFFFh. ; ;GLOBAL VARIABLES: ; CURRENT_NODE, ; CURRENT_SIBLING, ; ;DESCRIPTION: ; Save Dir_Info, Extended_Info buffer address in DOS. ; Set ES to Name_Cache_Seg ; SET_LRU; ; 1: ; Current_Node = BP ; Current_Sibling = 0 ; PACK_DIR_NAME (from the path); ; if CX = 0, then jmp to 3 /*Found*/; ; Find_child (from the current_node); ; if not found then jmp to 3 ; 2: Compare Packed_name with Child_pointer.CD_filename ; if yes, then PRE_LRU_STACK; JMP to 1 ; else Find_Sibling;Current_sibling=Sibling_pointer ; if found a sibling, then Current_Node = Current_Sibling ; jmp to 2 ; else jmp to 3; ; 3: UNFOLD_NAME_RECORD /*for the info packet to DOS */ ; Exit ; ;************************************************************************* .pa .fo off ;************************************************************************* ; ;SUBROUTINE: INSERT ; ;INPUT: DS:DI -> DIR info ; ES:BX -> Extended info ; ;OUTPUT:Automatic insertion based on CURRENT_NODE, CURRENT_SIBLING ; If failed, then carry flag set and AX = 0FFFFh. ; Insert operation handles only one file or subdirectory at a time. ; So, usually insert operations are performed in a sequential manner. ; A look up operation should be performed before any new sequential ; insert operation. ; ;GLOBAL VARIABLES: ; CURRENT_NODE, ; CURRENT_SIBLING, ; ;DESCRIPTION: ; ; Make_Name_Record ;Make Name Record from the input ; Get_Free_Node ; Set_LRU ;(from TEMP_LRU_STACK) ; if current_sibling <> 0 (or current_sibling=0FFh) ; then Install as a sibling of Current_Node ; else Install as a child under Current_Node; ; Pre_LRU_stack ;(pre operation for LRU) ; Exit ; ;************************************************************************* .pa .fo off ;************************************************************************* ; ;SUBROUTINE: Delete ; ;INPUT: DS:SI -> d:path ; ;OUTPUT: If found, then remove the item from the Tree and from the ; LRU chain. Move that slot to the Top of the LRU chain. ; ;GLOBAL VARIABLES: ; ;DESCRIPTION: ; Look_Up ; If ds:si -> 0, then Remove that entry from Tree, LRU chain, ; Put that entry to the top of LRU chain ; else AX = 0FFFFh, Carry set, ; Exit ; ;************************************************************************* .fo :egdoc.