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 🙂 !! )