














                                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.