home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Media Share 9
/
MEDIASHARE_09.ISO
/
cprog
/
skpr115c.zip
/
SKPR.TXT
< prev
Wrap
Text File
|
1992-03-31
|
28KB
|
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.