skpr.txt

提供文件数据库的API的程序

                                    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: [phone]


                 or


                      Dial [phone]

                      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.