home *** CD-ROM | disk | FTP | other *** search
03 / 20 / 1991 FILE : READ.ME *************************************************************************** DISCLAIMER : This file and its related contents are to be used at the risk of those using it. None of these routines are guaranteed to work and any damage resulting from the use of anything included is the sole responsibility of those USING IT. This file and all source provided are considered copyrighted. You are encouraged to use this material provided it is for non- commercial use. Those wishing ( for some reason :-) ) to use this for a commercial product, please contact the author. You are encouraged to give this package away AS A PACKAGE. The source is not to be modify before exchange; however, feel free to modify for personal use only. Contact the author with any changes please as I like to see good improvements! Finally, if you wish to send anything ( other source code included ) for good faith, joy & money accepted ;-), Please send to : Thomas Jenkins ( USA ) 9732 Windsor Lake Blvd. Columbia, SC 29223 E-Mail : BITNET : C0361 @ UNIVSCVM INTERNET : C0361 @ UNIVSCVM.CSD.SCAROLINA.EDU Comments : ( 803 ) 777-6666 wk ( USA ) ( 803 ) 788-7179 hm *************************************************************************** SECTION ONE: IndexedFiles *************************************************************************** ** From version 1.7 to version 1.8 there have been Major changes to ** ** IndexedFiles. I've had to delete the encryption section to make ** ** file available on as many sites as possible. I apologize for any ** ** inconvenience this may cause. If anyone wishes to ask me about my ** ** Encryption schemes, please feel free to contact me since this is not ** ** considered illegal ( just actually providing code *sigh* ). ** ** ** *************************************************************************** The following is the variable exported by IndexedFiles: fileError : WORD ; The following is a list of all error codes returned in fileError: NO_ERROR = 0 NOT_ENOUGH_MEMORY = 1 READ_LESS_BYTES_THAN_EXPECTED = 2 INDEX_NOT_FOUND = 3 LESS_BYTES_WRITTEN_THAN_EXPECTED = 4 INVALID_FILE_NAME = 5 Of course the standard error variables in Turbo will report errors as well: EX, DOSError. The following is a list of types exported by IndexedFiles: IndexStr = STRING [ 010 ] ; IFile = RECORD baseFile : FILE ; indexFile : FILE ; fileName : STRING ; END ; { IFile } IndexType = RECORD index : IndexStr ; position : LONGINT ; END ; { IndexType } These types are required to use UNIT IndexedFiles. Include IndexStr as the first field in the record to be indexed or strange things will happen! Do not refer to a file created with IndexedFiles with any of the standard file variables except in a read only mode. The following is a list of PROCEDUREs and FUNCTIONs exported by IndexedFiles: **** IMPORTANT NOTE ********* Below are notes to be careful with the SizeOf function. These are generic routines that care little if you use the correct size in calls as they will gladly read less bytes than actual record size, read more bytes ( overwriting data at best, code at worse, etc. This is bad! and good. Used correctly, these routines can write several record types to one file! And index them! The only requirement is a ten byte string ( ok 11 counting length! ), you can use the first X bytes to identify the record type, etc. All is up to how clever you are at coding....Enjoy. ******************************** ------------------------------------------------------------------------------ PROCEDURE ReadIndexed ( VAR f : IFile ; VAR buffer ; size : WORD ) ; This procedure will read size bytes into buffer from the file represented in f. You must place the index you want in buffer before making the call. Example, anyRec.index := '0000056790' ; ReadIndexed ( indexFile , anyRec , SizeOf ( AnyRecType ) ) ; I STRONGLY recommend using the RECORD TYPE in the SizeOf function. This will in sure the correct number of bytes are read. ReadIndex has no way of insuring anyRec is the correct type for the file. BE CAREFUL. ----------------------------------------------------------------------------- PROCEDURE WriteIndexed ( VAR f : IFile ; VAR buffer ; size : WORD ) ; This procedure will write size bytes from buffer to the file represented in f. You must place the index you want in buffer before making the call. If index is found, the file pointed to by index will be replaced. If the index is new, the record is appended to the base file and a new index is written to the index file. Example, anyRec.index := '1000000000' ; WITH anyRec DO BEGIN { Make assignments } END ; { WITH } WriteIndexed ( indexFile , anyRec , SizeOf ( AnyRecType ) ) ; I STRONGLY recommend using the RECORD TYPE in the SizeOf function. This will in sure the correct number of bytes are written. WriteIndex has no way of insuring anyRec is the correct type for the file. BE CAREFUL. ------------------------------------------------------------------------------ PROCEDURE ResetIndexed ( VAR f : IFile ) ; This procedure will Reset the data file and the index file. ------------------------------------------------------------------------------ PROCEDURE ReWriteIndexed ( VAR f : IFile ) ; This procedure will ReWrite all files used for indexing. This is required to create the indexed file. ------------------------------------------------------------------------------ PROCEDURE CloseIndexed ( VAR f : IFile ) ; This procedure will close both files involved with the indexing. ------------------------------------------------------------------------------ FUNCTION FilePosIndexed ( VAR f : IFile ; size : WORD ) : LONGINT ; This function will report the current position in indexed file f of given size. I'm not really sure why one would want to know, but the feature is here. ------------------------------------------------------------------------------ PROCEDURE AssignIndexed ( VAR f : IFile ; indexFile : STRING ) ; This procedure will assign the files to the base file given in indexFile. paths are accepted, but extensions are not. Three files are built from the supplied name. ------------------------------------------------------------------------------ FUNCTION FileSizeIndexed ( VAR f : IFile ; size : WORD ) : LONGINT ; This function will return the number of record of size bytes held in the main file. This number does not take into account either index file, but these are relatively small ( 15 bytes per entry ). ------------------------------------------------------------------------------ FUNCTION IndexFileSize ( VAR f : FILE ) : LONGINT ; This function is included for completeness. It merely calls FileSize on the main file. The answer returned is in bytes and represents the total file size of the main file ( IE, excluding index files ). ------------------------------------------------------------------------------ -- -- -- The following PROCEDURES and FUNCTIONS added with VERSION 1.5 -- -- -- ------------------------------------------------------------------------------ PROCEDURE DeleteIndexed ( VAR f : IFile ; VAR buffer ; size : WORD ) ; OK, I forgot this PROCEDURE in version 1.0 :-). Call this procedure to remove the index entry and the record from the base file. This is an involved process! The index file must be updated since it relies on the binary location of files in the base file. I decided the extra overhead in deleting the record now was justified since it frees us of having to mark deleted record, keep track of them, and finally remove them ( or waste time when inserting new records looking for them. Most operations will be inserting and update - ReadIndexed and WriteIndexed do this as quickly as possible. ------------------------------------------------------------------------------ FUNCTION IndexFileSize ( VAR f : FILE ) : LONGINT ; This FUNCTION will return the number of index records in the index file. Besides being a handy way to determine the number of records in you file, It is the only way to really sequentially process the file. See IndexRead below. ------------------------------------------------------------------------------ PROCEDURE IndexSeek ( VAR f : FILE ; position : LONGINT ) ; This procedure will position the index file pointer in the index file. ------------------------------------------------------------------------------ PROCEDURE IndexRead ( VAR f : FILE ; VAR tempIndex : IndexType ) ; This PROCEDURE will allow you to Read an index record from the index file. Combined with the IndexFileSize FUNCTION, you can easily process your file sequentially. EX, .... numberRecords := IndexFileSize ( f.indexFile ) ; idx := 0 ; WHILE ( ( NOT ( EOF ( f.indexFile ) ) ) AND ( idx <= numberRecords ) ) DO BEGIN IndexSeek ( f.indexFile , idx ) ; IndexRead ( f.indexFile , tempIndex ) ; yourRecord.index := tempIndex.index ; ReadIndexed ( f , yourRecord , SizeOf ( yourRecord ) ) ; .... PROCESS DATA ....... END ; { WHILE } ------------------------------------------------------------------------------ ------------------------------------------------------------------------------ -- -- -- The following FUNCTION added with VERSION 1.7 -- -- -- ------------------------------------------------------------------------------ FUNCTION IndexedError ( errorNum : WORD ; : STRING ; This FUNCTION will return text explaining the error in simple terms. ------------------------------------------------------------------------------ ****************************************************************************** @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ ****************************************************************************** SECTION TWO : Files ****************************************************************************** ** ** ** No changes from version 1.7 to version 1.8 ** ** ** ****************************************************************************** There are only two exported procedures. These will allow you to delete or insert any number of bytes into a file. It takes available memory into account ( up tp 64K limit ) in the BlockRead/BlockWrites and is very quick. As with all the units included here, be careful! With versatility usually comes danger if one is not careful, but there is an equal potential with a little care and common sense! ****************************************************************************** Below is a list of the possible errors reported by this unit. FILE_POSITION_OUT_OF_RANGE = 1 ; FILE_READ_ERROR = 2 ; FILE_WRITE_ERROR = 3 ; Below is the general purpose error variable exported by this unit. When using the unit in a program that USES IndexedFiles ( or another of my UNITS ), be sure to use Files.fileError or IndexedFiles.fileError so the compiler will resolve your reference as you meant, and not by the order you USEd the Units!! fileError : WORD ; Finally, here are the PROCEDUREs exported by the UNIT. PROCEDURE InsertRecord ( VAR f : FILE ; VAR buffer ; position : LONGINT ; lRecL : WORD ) ; This procedure will insert lRecL bytes from buffer into file f at binary position. What's that mean? It will place lRecL bytes into file f at absolute position ( lRecL * position ). All records from this position to the end of the file will be shifted down lRecL bytes. ----------------------------------------------------------------------------- PROCEDURE DeleteRecord ( VAR f : FILE ; position : LONGINT ; lRecL : WORD ) ; This procedure will remove lRecL bytes from file f at absolute position ( lRecL * position ). All bytes following this will be shifted over this record and the file length will be truncated by lRecL bytes. ****************************************************************************** @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ ****************************************************************************** SECTION THREE : AsmRoutines ****************************************************************************** ** ** ** Sorry this Missing UNIT might have caused some problems. TEJ ** ** ** ****************************************************************************** This is a new section. There are several useful routines here. As was stated earlier in this file, two of the routines are modified from Borland personnel code. Please remember that the original ideas there are not mine. ****************************************************************************** Here are the FUNCTIONs exported by this UNIT: FUNCTION HexStr ( VAR num ; numberOfBytes : BYTE ) : STRING ; This FUNCTION will return a string of HEX digits that equals the number passed into num. This will work for any valid number ( even arrays of numbers ). Remember that a string can hold 255 characters maximum, so this FUNCTION is limited to HEXing 128 bytes at a time MAX ( two hex digits per byte ). The assembly PROC used was created by Borland personnel and adapted to the TPascal MODEL by me. ----------------------------------------------------------------------------- PROCEDURE Exchange ( VAR var1 ; VAR var2 ; count : WORD ) ; This PROCEDURE will exchange any to variables ( max 64K size ) using NO temp variable. How? It uses string instructions to load a register at a time meaning no temp storage needed and a great speed dividend. This assembly PROC was created by Borland personnel and adapted to the TPascal MODEL by me. ----------------------------------------------------------------------------- FUNCTION Compare ( VAR var1 ; VAR var2 ; strng : BOOLEAN ; count : WORD ) : INTEGER ; This FUNCTION will compare any two variables. It returns -1 if var1 < var2, 0 if var1 = var2, and 1 if var1 > var2. If strng is set to TRUE, the assembly PROC will skip the length BYTE to compare only the actual contents of the strings. Be sure to Use the Length FUNCTION and give the shorter length as size to avoid comparing garbage. ----------------------------------------------------------------------------- ****************************************************************************** EOF ( for now :-) !! ) 
