home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
BURKS 2
/
BURKS_AUG97.ISO
/
BURKS
/
SOFTWARE
/
LIBS
/
BPLUS11.ZIP
/
BPLUS.DOC
(
.txt
)
< prev
next >
Wrap
Text File
|
1988-12-06
|
25KB
|
640 lines
\033(s10H
THE B-PLUS PROGRAM
A B-TREE INDEXING FILE MODULE
FOR C PROGRAMMERS
by
Hunter and Associates
B-PLUS is a versatile, carefully designed module for C
programmers who need a fast, efficient program for indexing
data files. B-PLUS allows data records to be retrieved based
on a key value without regard to their position in the data
file. The data records can also be accessed in sequential
order in either a forward and reverse direction.
The B-PLUS Program Module is based on the famous and
widely used b-tree algorithm and has a number of useful
extensions which are not found in many programs of this type.
Some of its features are the following:
- Variable length keys are allowed
- File size limited only by DOS or by disk space
- All functions are non-recursive so very little stack
space is required
- The most recently used key values are stored in a
cache buffer in main memory for fast access
- Duplicate keys are allowed
The B-PLUS program has been tested using the Microsoft C
Compilers, Versions 4.0, 4.5 (OS2 Beta release), 5.0 and the
Borland Turbo C Compiler Version 1.0. The compiled object
file is less than 9.4K bytes in length for these compilers.
See the instructions at the end of this user's guide for a
special note regarding Microsoft C Version 5.0 and Quick C.
Version 1.1 has several new features that were not in
Version 1.0. The next_key and prev_key routines can now be
called immediately after adding or deleting an index key. It
is no longer necessary to "reset" the index file with a
find_key or locate_key function call after adding or deleting
keys. Several minor bugs that were discovered in Version 1.0
have been corrected in Version 1.1.
LICENSE AND REGISTRATION
B-PLUS is distributed as a "share ware" program. Please
help us get it known by giving unmodified copies of the
HUNTER AND ASSOCIATES B-PLUS FILE INDEXING PROGRAM
-------------------------------------------------------------
program and documentation to other programmers who may find
B-PLUS useful.
B-PLUS is copyright (C) 1987 by Hunter and Associates.
It is not public domain or free software. Non-registered
users are granted a limited license to use B-PLUS on a trial
basis for determining whether or not it is suitable for their
needs. Registration permits the use of B-PLUS on one CPU and
allows the use of the compiled B-PLUS modules in programs for
general sale and/or distribution.
The registration fee is $25 or $35. Users who pay the
$35 fee will be sent a disk containing a fully commented
listing of the latest source code, the user documentation,
and a number of useful sample programs. Users who pay the
$25 fee are not sent a new disk but are included in the
mailing list for announcements about both current and future
products. Your prompt registration of your copy of the B-
PLUS program is appreciated.
A trial disk with supporting documentation is available
directly from Hunter and Associates for $10.
Register your usage of B-PLUS by sending the registra-
tion fee to:
Hunter and Associates
7050 NW Zinfandel Lane
Corvallis, OR 97330
Telephone: (503) 745-7186
Your comments regarding the B-PLUS program or any suggestions
you have for extensions or for other programs that would be
useful to you are welcomed.
Hunter and Associates makes no warranties whatsoever
regarding the B-PLUS computer programs or the supporting
documentation.
USING B-PLUS IN YOUR PROGRAMS
The B-PLUS File Indexing Module contains twelve
functions that handle the retrieval of data records by key
value. The keys that are used to locate records are null
terminated strings. The data structures and constants that
are used are defined in the header file bplus.h.
If the data record field that you want to use as a key
contains numeric data, you can use one of the library
Page 2
HUNTER AND ASSOCIATES B-PLUS FILE INDEXING PROGRAM
-------------------------------------------------------------
conversion routines (fcvt, evct, sprintf) to convert the data
to string format.
The connection between a key and its reference is
formalized as a structure of type ENTRY. This structure
contains three elements:
typedef struct
{
RECPOS idxptr; /* long pointer to next index
level */
RECPOS recptr; /* long pointer to the file
position of data record */
char key[MAXKEY]; /* with this key value */
} ENTRY;
The application program uses only the recptr and key[]
fields. The idxptr is used and maintained by the B-PLUS
modules.
A variable of type IX_DESC is declared for each open
index file. See the header file bplus.h if you are
interested in the elements of this structure. ENTRY and
IX_DESC are the only two data types that are normally used by
application programs.
Here is a sample program stub which calls the open_index
and find_index subroutines.
Example:
#include "bplus.h"
main()
{
ENTRY e;
IX_DESC names;
/* open index file called NAMES.IDX */
open_index("NAMES.IDX", &names, 0);
/* find an index record for John Smith */
strcpy(e.key, "SMITH JOHN");
if(find_key(&e, &names))
printf("Data record address is %ld", e.recptr);
else
printf("Cannot find record for that key");
}
Page 3
HUNTER AND ASSOCIATES B-PLUS FILE INDEXING PROGRAM
-------------------------------------------------------------
Each of the twelve subroutines is now described.
int cdecl open_index(name, pix, dup);
char *name; File path name
IX_DESC *pix; Pointer to index file variable
int dup; 0 - no duplicate keys allowed
1 - allow duplicate keys
Description: The open_index function is used to open
and initialize an existing index file specified by name
and prepares the file for subsequent reading or writing.
The file structure variable pix is defined in the
application program. Duplicate keys are allowed or not
allowed depending on whether dup has the value of 0 or
1. The open_index function returns the value IX_OK (1)
if the file is opened successfully. If the file cannot
be opened, an error message is displayed and the program
is aborted.