Power-Programmierung

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

/ Power-Programmierung / CD2.mdf / c / library / windows / database / skpr115c / skpr.txt < prev

Wrap

Text File | 1992-03-31 | 27.9 KB | 946 lines

CAM Technical Systems CTS 1991-1992 Presents : SKIPPER version 1.15c Flat File Database API for C++ DOS/Windows DLL Borland C++ version 3.0 is a registered trademark of Borland International Skipper is copyrighted intellectual Property of CTS - CAM Technical Systems and Cannot be reproduced,reverse engineered, or used in any manner that is inconsistent with the limited license that is granted to registered users with out the express written consent of CTS. Table of Contents: Introductions ................................2 Librarys and Data Integrity ..................2 System Design and Implementation .............3 Registration .................................4 Features and Functions: Master Contrutctor .................5 OpenDB .............................5 Master Destructor ..................6 CloseDB ............................6 Insert .............................7 LookUp .............................8 Extract ............................8 CheckInserts .......................9 Remove .............................10 Delete .............................11 GetNext ............................12 GetPrev ............................12 StepNext ...........................12 StepPrev ...........................12 Align ..............................13 PackDB .............................13 State ..............................14 ClearState .........................14 Switch Functions : NoDuplicates Duplicates PackOff PackOn AlignOff AlignOn .......................15 Version ............................16 VERROR .............................16 Disclaimer and Help ................17 Error Codes ........................18 Introduction : The SKIPPER system is a C++ implementation of a flat file database manager for the individual who needs an easy to use versatile Platform to build a C++ application that requires access to a database. SKIPPER is a powerful OOP model that allows the programmer to create or use pre- existing files as database platforms. The only requirement for an existing file to be used as a SKIPPER file is. 1] The file must be in a flat format and contain only Records of a consistent length. 2] The file must contain a key field and the file must be in ascending sequential order by that key field. If the file is to be created by SKIPPER these details can be overlooked as SKIPPER will handle the sequencing of the keys. Libraries : SKIPPER is comprised of a series of libraries SKIPPER[s c m l h] relating to the memory model of the application that is being designed. To use the SKIPPER libraries include in any source modules that will access the skipper system the include file : "SKIPPER.H" If using the IDE and a project file include the correct SKIPPER library file for the memory model being used in the application. If using the command line compiler include the library file for the correct memory model in the link step. Data Integrity : It is important to understand that with the flat file model used in skipper the integrity of the database is only as good as the programmer that writes a SKIPPER application. The functionality and Integrity of the data in a SKIPPER database are controlled by the original specifications of the data contained in the file(s) used by skipper. If an application program creates a database that doesn't allow duplicate key values and the same file is used in another application that does and a Duplicate key gets inserted into the data stream. The integrity of the original database application has been violated. As long as the SKIPPER API rules for creation and use of a data file are followed and a database is closed correctly after each use the integrity of the data will be maintained by SKIPPER. If the Integrity of a SKIPPER database is violated the resulting violation can cause missed extractions and other related data retrieval errors. Future versions of SKIPPER will control the integrity of the database more closely with the addition of external file definition records and the like. NOTE: Version 2.0 will improve on integrity with DBMS control files and other security measures. Supported Compilers : SKIPPER version 1.15c was engineered, written and tested on the Borland C++ version 3 compiler and has not been tested in any other environments(due to the cost of obtaining various vendors compilers). The source code for SKIPPER was written to be as compatible as possible with other vendors products based on the authors experience with the other vendors products. SKIPPER does have dependance on certain 'C' and 'C++' library functions contained in the Borland C++ package the functions are as listed. - memcpy(void *source,void *dest,size). - memcmp(void *source1,void *source2,size). - fstream and related stream functions. Any problems that arise with the use of the SKIPPER system or suggestions for future releases or any other contructive criticism can be directed as follows. BUFFALO CREEK BBS message to : Craig McNiel 515-225-8496 (8-N-1) or CAM Technical Systems Route #1 Box #3 Batavia, IA 52533-9701 Phone: (515)662-2507 NOTICE : SKIPPER can not be interfaced with 'C' source due to C++ name mangling. A registered user could create a 'C' version with a little effort but , a 'C' version is not currently planned. Registration : SKIPPER system is copyrighted software and is distributed under the SHAREWARE concept. If you find the SKIPPER database manager useful or use the SKIPPER system in an application or for anything other than evaluation purposes please register your copy. With your registration you will receive the following. 1. The most recent version of the SKIPPER system. 2. FREE unlimited technical support (not that it won't be provided during the trial period). 3. The chance to voice your opinion and an suggestions you would like to see in the next revision. (Unregistered users have NO say). 4. FREE minor upgrades and LOW COST major upgrades. 5. All memory models and DLL's and any other existing SKIPPER support material. Support the shareware concept and register by filling out the registration form REGISTER.DOC by typing : TYPE REGISTER.DOC >PRN at the command line and then mail the completed form with the registration fee of $35.00 in U.S. funds (NO CASH PLEASE!!) to : CAM Technical Systems Route #1 Box #3 Batavia, IA 52533-9701. Thank you for your support. SKIPPER FEATURES ,FUNCTIONS and SPECIFICATIONS : The current version of SKIPPER version 1.15c consists of 25 different functions excluding the constructor and destructor for SKIPPER. The class name for all of the SKIPPER functions that are user callable is "Master". The SKIPPER system also has provisions for a verbose error message system that aids in debugging Applications using the SKIPPER system. Currently SKIPPER requires the following for operation. * DOS 2.1 or Higher. * Free Disk space equal to the largest Database. * Borland C++ or compatible compiler. SKIPPER FUNCTIONS : Master::OpenDB(char *filename,int RecordSize, int KeyOffset,int KeyLength) and Master::Master(char *filename,int RecordSize, int KeyOffset,int KeyLength) Purpose : To create a Master object and open a SKIPPER file or to open a SKIPPER file for a pre-created Master object. Parameters: char *filename - Pointer to valid DOS filename of the SKIPPER database. int RecordSize - Unsigned length of the entire record. int KeyOffset - Unsigned 0 based offset from the beginning of each record. int KeyLength - Length of the records key in bytes. Specifications : Currently the SKIPPER systems include file that the system itself is compliled with contains define statements that must match certain parameters of the functions. These parameters are the RECORDSIZE,and KEYLENGTH. If the parameters don't match the system will report an error and halt execution of the application. Note : The SHAREWARE version is configured for 80 byte records. These limitations can easily be over come by registering. Master::CloseDB(void) and Master::~Master() Purpose : These functions systematically shut down the SKIPPER system and maintain the integrity of the database. If a user wants to Open another Database a quick call the CloseDB() function will allow another database to be opened by the Master Object as long as it falls within the parameters the Object was created under . (Key length, Record size) using smaller values will not endanger data integrity when passing parameters on opening the database. Parameters : None. Specifications : The Libraries that are the SKIPPER system were and can be compiled using different MAXIMUM parameters. These parameters can not be exceeded when opening a database but they can be smaller values. The only define statement that cannot be altered at runtime is the MAXINSERTIONS which controls the number of consecutive insertions that are allowed before the queue is full and the database must be "ALIGNED" or placed in ascending sequential key order. All other parameters can be overridden upon opening or calling the SKIPPER constructor. Master::Insert(void *Record) Purpose : Insert is used to add another record to a database. Insert is a queued operation and is very fast. When an insert operation passes beyond the maximum number of insertions allowed the database is "ALIGNED" which involves making the database into one contiguous file that has the key fields in ascending sequential order. If the NoDuplicates function has been called the Insert function first checks to see if the records key exists before insertion. If the key does exist the function returns an error and the insertion is aborted. Parameters : void *Record - A pointer to the area in storage that the record is stored. The Key is extracted from the Record. Specifications : The insert function places a record at the end of the database until the database is ALIGNED. The database is aligned automatically when a record is retrieved or when the database passes the maximum number of insertions. The key that is used in the insert function is grabbed out of the record that is pointed to by void *Record. Depending on if Duplicated keys are allowed or not the insert function will check for a duplicate prior to insertion and fail if a duplicate is found. Master::LookUp(char *key,void *Record) and Master::Extract(char *key,void *Record) Purpose: These two functions are used to retrieve records from the database. The only difference is the method used to search for the record. The LookUp function uses a linear search from the front to the back. and Extract uses a Binary search from the middle out. The main different is speed. LookUp is slower the longer the database is and the further to the end the record is contained. The advantage is that a LookUp doesn't require the overhead of an alignment to extract a record. Extract on the other hand is very fast but the records must be aligned. If an insertion or deletion has occurred prior to calling Extract the database will be aligned and/or packed prior to the search beginning. Parameters : char *key - Pointer to a field containing the key value of the record to be returned. void *Record - A pointer to an area in storage for the record to be returned to. Specifications : Depending on the size of the database and the number of records involved which function that is called is dependant on the number of insertions that occur between record seeks. If the size of the database is small and the number of inserts between records being returned is great a call to LookUp() may yield better results. Where as if a database is large and the inserts are few and far between an Extract() will certainly get the record first. Master::CheckInserts(char *key,void *Rec) Purpose : This function can be used to check the recently inserted records that haven't been aligned for a specific key. The purpose is to offset the overhead of an automatic call to align by Extract if inserted records are present. Parameters : char *key - Pointer to a field containing the key of the record to be returned. void *Rec - Pointer to an area in which the record will be placed if found. Specifications : The Automatic calls to align can be averted with the NoAlign() function. This will allow the use of the Extract function without the overhead of and align. If the record is not found in the main database then a call the CheckInserts() can be made to sequentially search the queue of recent unaligned inserts for a particular key value. The use of the NoAlign() function is not recommended for unexperienced database programmers as it can endanger the integrity of the database. It's use should be restricted to experts only. NoAlign() circumvents ALL of the database automatic alignment calls. Master::Remove(void) Purpose : Remove is the function that deletes the last record that was read from a particular database file. Remove cannot be called unless the last function called prior to remove() was a record read function (ie. Getxxx Stepxxx ect..). Parameters : None. Specifications : Remove physically deletes a record from the database structure by overwriting the record with a NULL value. The record is not stored anywhere and is not retrievable after being removed. A physical record get must be the last SKIPPER function called prior to Remove or the function will fail. Master::Delete(char *key) Purpose : Delete physically removes a record from the database structure by overwriting the record with a NULL value. The record is not stored and cannot be retrieved later. Parameters : char *key - A pointer to the key value of the record to be deleted. Specifications : Delete unlike Remove is called with a pointer to the value of the key that is to be deleted. In multiple key databases the first key is the one to be deleted and if a key with duplicates is to be deleted Remove is recommended. Master::GetNext(void *Record) - GetPrev(void *Record) and Master::StepNext(void *Record) - StepPrev(void *Record) Purpose : All of these functions step forward and backward through the database in the direction specified by the function name (Next - Forward;Prev - Backward). The main difference between the Getxxxx and Stepxxxx functions lies in that the Get functions stay within that key value of the Extract() or LookUp() function called before the function is called. The Stepxxxx functions are independent of key value and will step between key values. Parameters : void *Record - Pointer to where to place the record on success. Specifications : Each of the Getxxxx and Stepxxxx functions require that the programmer make a call to a LookUp() or Extract() function prior to calling. Each of the Get functions will step forward or backward within the same key value. Hence is not very useful in databases without duplicate keys. The Stepxxxx functions will go from the very first physical record to the very last physical record regardless of key value. Master::Align(void) and Master::PackDB(void) Purpose : These two functions are automatically called during certain operations on the database if certain conditions have been met. Align() is the function that insures that all inserted records are placed in the correct sequence of keys in the database. Align() is called automatically after MAXINSERTIONS is exceeded. PackDB() is the function that compresses the database and removes all of the NULL records that result from deletions. PackDB() is called Automatically on Extractions from the database. Parameters : None. Specifications : Usually these two functions should never need to be called unless they have been overridden by the functions (PackOff() and AlignOff() ) for some advanced operations. This should only be done by experienced programmers who know how to maintain the integrity of the database on their own. Master::State(void) and Master::ClearState(void) Purpose : State returns the Error status of the last call to the SKIPPER DBMS. The value returned is maintained until another call to the SKIPPER DBMS is made. All Skipper functions except the constructor and destructor return the same value as State() returns. ClearState() is used to return the state of SKIPPER to "OK" in the event that program logic requires or for functions that require state to be "OK" to function properly. Such as the Stepxxxx and Getxxxx functions which require that SKIPPER's State() be "OK". Parameters : None. Specifications : State is an internal variable that is private and maintained by all SKIPPER functions to insure that the status of a function is retained automatically between calls to the DBMS. Switch Functions : Master::Duplicates() * Master::NoDuplicates() Master::PackOn() * Master::PackOff() Master::AlignOn() * Master::AlignOff() * denotes the default behavior Purpose: Each of the switch functions toggle an attribute of the database or of the DBMS. Parameters : None. Specifications : The Duplicates() and NoDuplicates() determine the behavior of the DBMS in relation to duplicate key values. If Duplicates are NOT allowed the DBMS looks for the key value in the database prior to insertion and if found the insertion fails. Once a database is specified as NoDuplicates() it should always be accessed as such or the integrity of the database could be damaged. The PackOff() and PackOn() functions control if automatic calls to the PackDB() function are made to remove deleted (NULL) records. The AlignOn() and AlignOff() functions control if automatic calls to the Align() function are made to correctly insert the newly inserted record into the database. Master::Version(void) Purpose : To be able to check the SKIPPER version number and release information. Parameters : None. Specifications : Version returns a char* to a string with the value of "Skipper Version 1.15c\n" Master::VERROR() Purpose : To enable verbose error reporting of the DBMS status. Parameters : None. Specifications : When the SKIPPER DBMS is compiled with the #define DEBUG switch this function is enabled and will return a char* to a verbose error string describing the status of the last SKIPPER function call. DISCLAIMER : This software is presented to the public in an "AS IS" format and the author claims no responsibility for any damages ensued from the use of this software and any related products. In Case Of Trouble : If SKIPPER doesn't work correctly for you or you find an error in the software. Registered or not please report the error so that it can be fixed or incorporated into the next release of SKIPPER. Any errors in the software that cause SKIPPER to function other than intended by the author will qualify for a patch or a minor revision release. Such revisions will qualify for a FREE minor upgrade to all registered users. To report a problem : Write: CAM Technical Systems Route #1 Box #3 Batavia, IA 52533-9701 Phone: (515)662-2507 or Dial (515)225-8496 Buffalo Creek BBS (the Authors Favorite BBS!) and leave a message addressed to Craig McNiel. Error Codes Returned by SKIPPER : 0 .......................Ok. 1 .......................Not found. 2 .......................EOF. 3 .......................No records inserted since aligned. 4 .......................Memory allocation error. 5 .......................File creation error (TMP). 6 .......................File operation error (TMP). 7 .......................File creation error (MASTER). 8 .......................Definitions and file don't match. 9 .......................No records in the file. 10 ......................Duplicate record is not allowed. 11 ......................File operation error (MASTER). 12 ......................Operation out of sequence. 13 ......................File already packed. 14 ......................Catastrophic file system failure. 15 ......................Previous operation un-successful.