Power-Programmierung

home *** CD-ROM | disk | FTP | other *** search

/ Power-Programmierung / CD1.mdf / pascal / library / dos / arrays / larry / larry.doc next >

Wrap

Text File | 1990-07-15 | 14.1 KB | 395 lines

Larry.DOC Documentation for Large ARRaY access by Kent Grundström 1990. Copyright: This package and the herein enclosed procedures/functions and the corresponding documentation is the property of: KaG-Teknik Kent Grundström Kläppavägen 1 S-890 14 Köpmanholmen SWEDEN Disclamer: This package is distributed as it is, the author is not responsible to any kind of damage whatsoever caused by using herein enclosed procedures and function. The author does not guarantee the operation of the routines. It is only guaranteed to occupy diskspace. As for the documentation it is not guaranteed to be accurate and the author should not be hold responsible for any damage caused by this documentation beeing inaccurate. Release: This package is hereby released into PUBLIC DOMAIN, you are free to use it or to throw it in the trashcan at will. You are free to distribute this package along with it's documentation in it's unmodified form. I strongly urge you to distribute it to your friends/enemys or other persons whom you are in contact with. When distributing this package it should contain; 1) The unmodified documentation. 2) The unmodified PASCAL source code. If you make modifications to the source you must also make modifications in the documentation stating what was done and when. When distributing such modified package it should contain the following; 1) The unmodified documentation. 2) The unmodified PASCAL source code. 3) The modified documentation. 4) The modified PASCAL source code. Contribution: If you find this package useful you may, if you like to, contribute the author of this package, adress found above. --------------------------------------------------------- Revision history. Date Action Person ----- ------- ------- Jun 1990 Wrote this package. KG Jun 1990 Release to PD KG --------------------------------------------------------- Description: The intention with this package is to support a simple way of accessing large arrays in small memory environments. The basic idea is that a pointer in PASCAL always yield a valid memory-location, and that such pointer when returned by a function can be used as a variable. The main part of this package is the GetPointer function that is used for locating data and supporting the pointer to that, it's return value is a generic pointer wich should be converted to specific type with a user supplied function of the following format; Type MyType=( declaration of your data ) Var MyArrayHandle:ArrayHandle; Function MyArrayEntry(Index:Indextype):^MyType; Begin MyArrayEntry=GetPointer(MyArrayHandle,Index) end; Where MyType is your datatype and MyArrayHandle should contain the number returned by the OpenArray,LArray or DArry functions and Index is the entry- number desired. OpenArray function: This is the main initializer, it builds the internal structures of the array and sets ut the bucket-stack wich is an last-used table of entries. Each memory-bucket will contain an item or be empty. Syntax; Handle:=OpenArray(FName,EntrySize,NumEntries,NumBuckets,PurgeFlag, ReuseFlag,Mode); Description of parameters; Parameter Descr ------------------------------------------------------------------- FName Filename of datafile containing the entries in the array not presently in ram. EntrySize Size of each item in the array. Preferable the value returned from the SizeOf pseudo- function. NumEntries The size of the array in items. Supporting this parameter with 1000 will create an array containing 1000 items numbered from 0 to 999. NumBuckets The number of items that the stack can hold for this array. The larger this value is the greater the chance is that an requested item is in ram. This value should not be less than 3! PurgeFlag Specifies what should be done with the data- file when calling the CloseArray procedure. If this is set to Purge the file will be deleted, if you would like to save the file for future use this should be set to NoPurge. ReuseFlag Tells the unit what it should do with an old datafile if one exists. Setting this to ReUse it will open the old file trying to use this as the array, if none found it would be created. Setting this to Create a new file will be create whether an old one exists or not. Mode Tells what initial access mode should be used for the array. The modes is as follows; ReadWrite: Full access with reading and writing allowed (Default mode) NoRead: Prevents the unit from reading in an old value from the file thus immediatley creating a NEW entry. NoWrite: Prevents the unit from writing out values to the file. This can be used to simulate constant arrays and preventing update in the file. An item in memory can be changed however but it will NOT be written out to the file. The getpointer function will run slightly faster in the NoRead and NoWrite modes. Return value: This function returns a number serving as a handle, the actual value is an index into the header table and should not be modified by the user program. This value should be supplied as the Handle parameter to the other functions/procedures. Larry/Darry Functions Theese two serves as easier_to_use interfaces into the OpenArray function LArry: Creates a new array giving it a temporary name with a datafile that will be deleted upon closure. DArry: Opens an old array if exist or creates a new one if not. The datafile will be saved when closed. Syntaxes: Handle:=LArry(EntrySize,NumEntries); Handle:=DArry(FName,EntrySize,NumEntries); Parameters: See the OpenArray Function Return Values: See the OpenArray Function CloseArray Procedure: This procedure is used to terminate the use of an array and to remove the datafile from disk if the Purge option is in affect. Syntax: CloseArray(Handle); Parameters: Handle The return value from the OpenArray function FlushArray Procedure: This procedure is used to write out ALL information from the ram buckets into the file and marking all memorybuckets as free. It is used to ensure all data is written onto disk. It will also close the file to ensure that DOS buffers are properly written. This procedure will also UnFreeze all frozen entries. Syntax: FlushArray(Handle); Parameters: Handle The return value from the OpenArray function FlushAllArrays Procedure: Procedure that calls the FlushArray procedure flushing ALL open arrays to disk. Syntax: FlushAllArrays; Parameters: None. Procedure WriteMode: Used for setting the access mode for an open array. This can be very useful when you for example have generated a large array containg say, all the names from the phonebook and want to search it. If you then set the NoWrite mode on the array it will speed up the search. NOTE: You should flush the array BEFORE you change the mode to NoWrite or you may have data in ram than never will be written to disk, and thereby lost. Syntax: WriteMode(Handle,Mode); Parameters: Handle ArrayHandle returned by OpenArray function Mode New mode to assign the array. Se Function OpenArray for details on this parameter. GetPointer function: This is the function that does the job, it's purpose is to return a pointer to the data, it will read in the data from disk if it is not already in memory and it will write out data that has not been used recently in order to free a bucket for the new data. It will act according to the mode of the array, meaning if the array has been marked as ReadOnly it will NOT write to disk and if it is marked WriteOnly it will NOT read from disk. Syntax: Pointer:=GetPointer(Handle,Index); Parameters: Handle ArrayHandle from OpenArray function. It will be checked for validation and the program will abort if it is invalid. Index Index number for the item desired. This corresponds with the values 0 to NumEntries-1 for this array. it will be rangechecked and the program will abort if it is not within proper range. Return value: A generic pointer to the memory containing the desired entry. This pointer should be converted with a usersupplied function into the proper type (see earlier description). Note: The pointer returned here is NOT suitable for storing into another pointer and using again since the data might have dissapeared from ram. If you need to store the pointer away for later retrival with a copypointer you must Freeze the entry, such frozen entry will not leave ram or move in ram until UnFrozen or Flushed. Example: With MyType(Freeze(MyHandle,100))^ Do (* Freeze entry 100 in ram *) Begin (* Operate on the fields of MyType *) end; UnFreeze(MyHandle,100); (* Release the entry again *) Freeze Function: This function is similar to GetPointer but with the difference that the entry is locked in place and will stay in until UnFreeze of Flush is called. This is useful for With statements where you access other entries also. Remember a frozen entry will use the same bucket and will not be unloaded from ram. This means that if you freeze up the whole stack there will not be any available buckets left to store new entries into (=Program ABORTS). Syntax: Pointer:=Freeze(Handle,Index); Parameters and return values same as for the GetPointer function. UnFreeze Procedure: The opposite of Freeze. Used to release a previously frozen entry. If the entry is unfrozen it will remain that way. If you dont use this procedure on an entry it will not leave ram holding a bucket until UnFrozen or Flushed. Syntax: UnFreeze(Handle,Index); Parameters: Same as for Freeze and GetPointer Functions. ==================================================================== Further notes The supplied sourcecode is written for TurboPascal V 4.0 or later. TurboPascal is a trademark of Borland Intl. The function MaxAvail has been used instead of MemAvail in order to see if it is possible to allocate an entire datablock as a contigous chunk of bytes. This is due to the possibility that MemAvail may report enough memory but fragmentation causes the impossibility to allocate the bucket. Bucket: The space allocated for an item is called bucket, It is a contigous set of bytes holding data of a format unfamiliar to the unit itself. Initilaization: The unit uses an autoinit procedure installing an autoexit procedure used to automatically close an array that was not properly closed and to clean up the array header structure. Constants: The constant MaxArraysOpen contains the maximum number (-1) of arrays to be open at the same time. Handle: This is an integer in the interval of 0 (zero) to MaxArraysOpen-1. Index: This is an longint used for identification of an item. Further documentation of the source refer to the comments in the pascal source code. ====================================== Program termination: This unit will abort the program with a call to the HALT procedure on several conditions. A message will be printed in the following format: "LARRY: <message>" where <message> is one of the following: Critical I/O error #<number> An I/O error have occured when there is a total disaster for the program to have one. Too many buckets. Reported by OpenArray if the number of buckets supplied ecceeds the maximum set by the BucketMax constant. No available handle All the entries in the header area is already used. The solution to this problem is to raise the MaxArraysOpen constant. not enough disk space The selected drive cant hold the datafile required for this array Can't create file for READ ONLY array The flag NoWrite was supplied for a Reuse where there is no old file. Can't create disk file Unable to generate the data file. I/O error creating file Some error occured while building the datafile. Possible caused by the disk beeing full. Mode for NEW array can't be READ ONLY Specified CREATE for an new array when mode is READ ONLY. Not enough memory for datastructs Out of memory when allocating space for databuckets. Note; this may be caused by severe fragmentation and MemAvail may report enough memory but none of the areas is large enough. Unable to generate name for array Couldnt build a unique name for the array, reported by the LArry function only. Attempt FREEZE on WRITE ONLY array In order to Freeze you must have an array with Read access. Can't scratch file The file could not be removed when closing an array. All entries LOCKED in stack When requesting an empty bucket all where found to be frozen in mem. This could be caused by an absent UnFreeze call or the number of buckets is too small. Invalid array handle The number supplied as the Handle parameter does not yield an open array.