kent@sparky.IMD.Sterling.COM (Kent Landfield) (01/03/91)
Submitted-by: rpj@pygmy.rice.edu (Richard Parvin Jernigan)
Posting-number: Volume 16, Issue 2
Archive-name: mbase/part01
So... who wants a database? No one? Well, this one won't do your
taxes or draw pretty pictures for you-- this is the engine, working
with relations faster than you can say HoHoHo (it's Santa time, isn't
it? 8-} ). Adds commands to C for adding, updating, deleting and
retrieving records from included-utility-built relations, designed
from close-to-english schemas. It actually looks/feels a good deal like
one of Informix (c)'s line of products, from what I've seen. But I
guarantee it costs less. :-)
Verified to work with Amigas (designed for 'em) and Unix V -- haven't
had a failure yet, actually. Technically it should work with IBM's
and Atari ST's and anything with a C compiler that does lseek and
read/write. There are no real compiler-dependent tricks used in the
code, so it should be terminally spread-around-able. There's a Makefile
included for Unix users, and a ReadMe for everyone.
-------------CUT HERE-----------
#! /bin/sh
# This is a shell archive. Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file". To overwrite existing
# files, type "sh file -c". You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g.. If this archive is complete, you
# will see the following message at the end:
# "End of shell archive."
# Contents: Makefile ReadMe mbase.dox
# Wrapped by rpj@pygmy on Sat Dec 15 19:06:11 1990
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'Makefile' -a "${1}" != "-c" ; then
echo shar: Will not clobber existing file \"'Makefile'\"
else
echo shar: Extracting \"'Makefile'\" \(637 characters\)
sed "s/^X//" >'Makefile' <<'END_OF_FILE'
X# NOT FOR USE WITH AMIGA SYSTEMS! This Makefile is for, obviously,
X# Unix only. See the ReadMe for instructions on installing/
X# compiling on an Amiga.
X
X# Replace LIBDIR with a period to put libmb.a in the current directory,
X# or make it /usr/lib/ or wherever it is you'd like your new library.
X
XLIBDIR = .
X
Xall: libmb.a build sample enctest
Xbuild: build.c stdinc.h
X cc -o build -O build.c
Xlibmb.a: mbase.c stdinc.h mbase.h
X cc -c -O mbase.c
X ar r ${LIBDIR}/libmb.a mbase.o
X ranlib ${LIBDIR}/libmb.a
Xsample: stdinc.h mbase.h sample.c libmb.a
X cc -L ${LIBDIR} -o sample sample.c -lmb
Xenctest: enctest.c
X cc -o enctest enctest.c
END_OF_FILE
if test 637 -ne `wc -c <'Makefile'`; then
echo shar: \"'Makefile'\" unpacked with wrong size!
fi
chmod +x 'Makefile'
# end of 'Makefile'
fi
if test -f 'ReadMe' -a "${1}" != "-c" ; then
echo shar: Will not clobber existing file \"'ReadMe'\"
else
echo shar: Extracting \"'ReadMe'\" \(4353 characters\)
sed "s/^X//" >'ReadMe' <<'END_OF_FILE'
X ___ ___ ,
X | | | | | ) ' ) ,'/
X |`'| _ -|- _ || | '_ _ .-. _ --< /
X | | ( ) | ( \ `| | ) ( \ `-. ( ) ) /
X | -'--`-- - `-' \/ ---' - - `-`- --'-- ( / <> /
X________________________/\_______________________`--'___ --'-- ____________
X
X Please read the dox (specifically the last paragraph or so) /
X '
X
X
X Ye Olde Database Installation Instructions
X
X ...and therefore it was known to Richid the Conqueror that you, the
Xmortal end-user, would eventually come across his code. It was then
Xdecided that instruction would be required if this code were to prove
Xfruitful, yea, if it were aun to be installed. And so it was written...
X
X -- UNIX SYSTEM (make, cc) --
X
X Steppe 1: Un-shar this, thy file, in thy favourite directory. This
X steppe hast thou already accomplished!
X Steppe 2: Edit-thou the file entitled "Makefile". Steppe 3 will have
X you run this file, producing a library. If you would have
X this file in any directory other than that in which this,
X thy file, resides, change-thou the variable named "LIBDIR"
X to reflect the choice directory.
X Steppe 3: Typest-thou the word "make".
X
X -- AMIGA SYSTEM (lattice C?) / PC --
X
X 'Ere a convention is chosen for home compilers, there is little
Xadvice which could be of use. Therefore, these following instructions
Xwill be written in terms of Richid the Conqueror's own choice of the
XLattice C compiler for the Amiga:
X 1> lc -cw mbase.c
X 1> oml lib:mbase.lib mbase.o
X 1> lc -cw build.c
X 1> blink from obj:c.o, build.o to build library lib:lc.lib,
X lib:amiga.lib
X 1> lc -cw sample.c
X 1> blink from obj:c.o, sample.o to sample library lib:lc.lib,
X lib:amiga.lib, lib:mbase.lib
X
X For reference, "lc -cw" is the equivalent of a simple "cc" command--
Xthe "-cw" simply supresses Lattice C's tendency to make useless warnings
Xabout main(). "blink" is the quivalent of "ld"--the linker.
X
X -- ALL SYSTEMS --
X
X It is now hoped that the following files have now been created:
X libmb.a || mbase.lib
X build
X sample
X And the following files of interest still exist:
X mbase.dox
X sample.s
X
X At this point, it is _strongly_ urged that the user take the time to
Xread ye olde database documentation. So strongly in fact that the aid of
Xone Mr. Guido has been enlisted. Do read the documentation now... the user
Xwill find it under the title "mbase.dox" .
X
X Having read the vital points of ye olde database documentation, let us
Xplay with our newly-acquired toys. To begin, we will need a relation to play
Xwith... luckily, the schema for one has been included for you, the user. Look
Xat the file "sample.s" to understand its content, then typest-thou the
Xfollowing:
X % build sample
X Build attaches ".s" to the end of the file if necessary, and creates the
Xrelation described in ye olde schema file "sample.s". This file contains the
Xdefinition for a relation titled "sample"... thus, build creates "sample.rel"--
Xa relation with no entries as yet.
X
X Edit the file sample.rel if you like -- it will prove rather boring.
XHowever, let us add a few records to this relation... type "sample". The
Xfile "sample", being recently-compiled C code, will execute, adding records
Xto the relation "sample.rel" and querying it. Examinest-thou this code
Xcarefully, for therein wilt thou find the key to the use of MetalBase... there
Xis nothing complicated about it.
X
X Now, shouldst thou be so inclined, edit-thou the file sample.rel, trying
Xto see how it is that "sample" can find meaningful text therein.
X
X
X Thus spake Richid the Conqueror.
X
X___________________________________________________________________________
X ___
X ___ | HE MAN WITH THE HAMMER
X .-',' /\
X / (_______.------------------. Richid < > Huan-Ti
X ( _______| | \/
X ) ( `------------------' rpj@owlnet.rice.edu
X '----`
X
END_OF_FILE
if test 4353 -ne `wc -c <'ReadMe'`; then
echo shar: \"'ReadMe'\" unpacked with wrong size!
fi
chmod +x 'ReadMe'
# end of 'ReadMe'
fi
if test -f 'mbase.dox' -a "${1}" != "-c" ; then
echo shar: Will not clobber existing file \"'mbase.dox'\"
else
echo shar: Extracting \"'mbase.dox'\" \(36649 characters\)
sed "s/^X//" >'mbase.dox' <<'END_OF_FILE'
X /\
X / \
X../ \....METALBASE release version 3.1......................................
X / \
X/ \ Written August 1989 through October 1990 by Huan-Ti
X\ /
X \ / Initially released December 10th 1990
X \ /
X \ /
X \/
X
X
X
X
X
X
X
X "And Calvin ate. And Food Lion went out of business. Amen."
X
X --1st Calvin 4:8
X
X
XWHY_METALBASE_?________________________________________________________________
X
X The Amiga 500 multi-tasks. Wow. It has great graphics. Yeah. Phenomenal
Xsound. Yippee. It costs $500. I bought one.
X A DBase package costs more than the computer. So does Paradox. And
XInformix. And almost every other database package on the market. I didn't
Xbuy one.
X But I needed a database for my system. Anybody who's ever worked with a
Xdatabase knows they're addictive--code that's written without a flexible
Xdatabase backing it up lacks something. And DBase wants $600 to put that
Xsomething back into programs. No thanks.
X That's why MetalBase was written... its forerunners (versions 1.0 and
X2.0, not available) were designed by the same author with the Amiga line's
Xneeds specifically in mind: relatively slow floppy drives (Compared to hard
Xdrives), so sparse read-head maneuvering was essential. Relatively small
Xmemory, when compared with the amounts of memory required by most C compilers
X(Lattice needs roughly 300k just to run, for example), so the code had to be
Xconsise, pure, and use few variables. Expansion was always available; hard
Xdrives, huge memory capacities, extra processors, ram drives -- so the system
Xhad to be readily expandible and flexible enough to meet the requirements of
Xboth a 512k, 1-drive machine and a 4-megabyte, 120-meg hard drive-driven
Xsetup. And they were.
X The problem was, Amigas can multi-task. So what is the rest of the
Xcomputer doing while a database runs around looking up records on one drive?
XNothing. Why not let it look up records on another drive? Fine... that works.
XWhat about on the same drive... using, say, a ram disk, so there are no real
Xread-heads to worry about positioning? That would mean each relation would
Xhave to support multi-user access... a requirement around which MetalBase
Xversions 3.0 and 3.1 focus. Not only can many terminals access many files at
Xonce, but on multi-terminal systems, each terminal can work simultaneously on
Xany given file. Terminals can each use as many relations as a system will
Xallow, and each relation can be used by over one hundred users at once. The
Xcode used to create MetaBase 3.X is completely compatible with the Unix )
Xoperating system and all of its derivatives, so its inherent multi-user
Xability places it in firm working footing on the most advanced systems on the
Xmarket.
X Relations are designed by a user to match his/her exact requirements,
Xindicies placed as needed on single or composite fields, and records can be
Xadded, retrieved, changed, and deleted as any C programmer so desires. The
Xinterface is as simple as possible, very fast in execution, and provides a wide
Xrange of error types for exact specification of problems. A user on any
Xterminal can choose to lock out other users from any number of relations, so
Xdata that is about to be changed will not be read by others before changes
Xtake place. Automatic temporary locks are placed on a relation which is about
Xto undergo a deletion or addition, thus delaying other users' access to files,
Xso that no data will be read until all indicies have been updated correctly.
XThis process is entirely system-driven; users never need worry about it at all.
XIf another user is adding a record to a relation, any terminal requesting a
Xrecord lookup will simply wait until the addition is complete before
Xproceeding. As records are deleted and added through normal use, the algorythms
Xused to update indicies automatically keep them at top operating speeds, so any
Xgiven relation's number of records can grow exponentially while causing only a
Xlinear increase in look-up time. Any relation can contain over four billion
Xrecords (Nearly four billion more than most systems will ever need), and each
Xrecord's length can be as large as its system's memory can handle. In
Xperspective, MetalBase is infinitely expandible, while requiring very little of
Xthe system on which it operates.
X
X
XRELATION_DESIGN________________________________________________________________
X
X A sample relation. Data Field # -> 1 2 3 4 5
X is read by selecting one Record # _____ ___ ____ ___ ___________
X record from the others by 1 |_____|___|____|___|___________|
X various criteria, and 2 |_____|___|____|___|___________|
X returning it to the user. 3 |Smith| 12| 114| A2|Houston, TX|
X Record 3 (In this example-- 4 |-----|---|----|---|-----------|
X actual MetalBase records need
X no such numbering system), if returned, would be placed in a string
X as "Smith| 12| 114| A2|Houston, TX|"
X
X A relation is a collection of records, each record consisting of the same
Xnumber of fields, character strings whose length remains constant from record
Xto record. Each field need not have the same length as the next in any given
Xrecord, but each record will contain the same fields as the others. The data
Xthe fields contain is, of course, the main purpose of a database--when
Xthousands of records exist, a system without a database would need vast amounts
Xof time to find any given record. Databases decrease dramatically record
Xretrieval time, while requiring as little additional time to add new and change
Xold records as possible.
X The key to a database is its indicies--pointers arranged in such a fashion
Xas to show the system where to look for the record for which it is searching.
XThe more of these collections of pointers, or indicies, a database has, the
Xgreater the number of different fields a system can search through in order to
Xfind a record meeting certain criteria for a field (Or fields... a single index
Xcan be used to first sort records by one field, and also sort duplicates with
Xrespect to a second field, etc. MetalBase allows these composite indicies to
Xkey off of as many as 5 different fields). However, databases require time to
Xupdate each index every time you add, delete, or change a field which has an
Xindex placed upon it. So although retrieval criteria possibilites are expanded
Xby using many indicies, the amount of time required to change the existing
Xrecords in a database will also increase. For this reason, the number of
Xindicies a relation will have should be considered carefully. Use what is
Xneeded, but no more.
X
X Relations for MetalBase take the following form (Words in brackets are
Xoptional syntax, words enclosed in <> are sample entries):
X
X [relation] <equipment>
X
X field <customer> [length] <5> [right]
X field <#_purchased> [length] <3> [<right>]
X field <part_number> [length] <4> [<right>]
X field <price_code> [length] <3> [<right>]
X field <shop_address> [length] <11> [right]
X
X index [on] customer [<with duplicates>]
X index [on] part_number|price_code [with duplicates]
X index [on] price_code [<with duplicates>]
X
X [end]
X
X Note that the relation-building program released with MetalBase 3.1 also
Xsupports comments at the end of the "field" and "index" lines, as in:
X field shop_address length 11 ; Comment here ;
X The semicolons must not touch text on either side. MetalBase 3.1's build
Xfunction also supports the ignored keyword "left" in place of "right", for
Xthose who put it there by instinct.
X
X The first line of a schema simply tells the computer what to call the new
Xrelation. The word 'relation' is optional, as is all text enclosed in
Xbrackets.
X The second section of a schema describes the fields of which every record
Xin the relation will be composed. The word immediately following 'field' is
Xsimply a name for the field. The next point of interest is the number after
X'length'... this number indicates the number of characters in that field.
XMetalBase will allow any positive integer here your computer can handle, and
Xif any length, or the sum of all lengths, is indeed large, BUILD will prompt
Xyou to add certain lines to the beginning of your code to warn the system of
Xexcessive-length records. The word 'right' immediately following the field
Xlength is optional--if it exists, any data placed in the field which does not
Xcontain enough characters to fill the field will be right-justified. This is
Xessential for number fields which will be indexed, as computers interperet
X"42" as a number which is much less than "7 " (Note the space to the right of
Xthe seven). Without the word 'right', all data will be left-justified in the
Xfield.
X After all fields have been declared, indicies are placed on fields and
Xcombinations of fields. MetalBase requires that you have at least one index
Xin any relation (This is only logical--a database without indicies is nothing
Xmore than a text file). After the word 'index' in each line, the names of
Xfields to be indexed appear, separated by vertical bars ("|"). If more than
Xone field name appears, MetalBase will declare that index composite. Making
Xindicies composite is encouraged--it adds no time to relation updates, but
Ximproves the appearance of output for nearly all purposes.
X Occasionally certain data should not be repeated... for instance, a
Xperson should not be able to visit a physicians office twice at the same time.
XIn this case, were a relation defined as consisting of the fields "name" and
X"visit_time", an index would be declared on "name|time" WITHOUT including the
Xwords 'with duplicates', as seen above. If such a relation were built,
XMetalBase would not allow the space-time continuum to be stretched, as
Xdescribed previously. Including the words 'with duplicates' after the
Xdefinition of an index remove this error-catching system, for that index alone.
XUse of the duplicate-catching system is entirely a case-to-case decision...
Xthere is little difference in the amount of time used between implementing and
Xnot implementing it.
X If the schema described previously exists as "/usr/joe/equip.s", the
Xcommand BUILD, a utility included for use with MetalBase, will create a
Xrelation called "equipment.rel" under the directory "/usr/joe". A sample
Xoutput of BUILD is as follows:
X
X % build /usr/joe/equip.s
X Building relation equipment under directory /usr/joe
X
X Fields___________________________________________________
X
X customer [5] L-Just #_purchased [3] R-Just
X part_number [4] R-Just price_code [3] R-Just
X shop_address [11] L-Just
X
X Indicies_________________________________________________
X
X customer..........................Duplicates allowed
X part_number|price_code............Duplicates not allowed
X price_code........................Duplicates allowed
X
X Do you wish to continue to build this relation [Y/n] ? <y>
X
X Relation created--zero entries.
X
X % ls -C /usr/joe
X equip.s equip.rel
X %
X
X Once a relation has been built, it contains no entries, and is ready for
Xuse. BUILD's sole use is the creation of relations... other utilities
X(discussed later) must be used for maintenance of relations (if needed).
X
X
XIMPLEMENTAION__________________________________________________________________
X
X A sample program implementing MetalBase follows:
X
X(*) #include <mbase.h>
X
X main ()
X {
X int file;
X char str [40];
X
X(**) if ((file = mb_inc ("/usr/joe", 128)) != 0)
X { printf ("File '/usr/joe.rel' cannot be found.\n");
X exit (1);
X };
X
X if ((mb_sel (file, 2, str, EQUAL, "114|A2") != 0)
X { printf ("Record cannot be found.\n");
X exit (1);
X };
X
X printf ("Record contains : %s\n", str);
X
X mb_upd (file, "Su | 14|112|C3|Dallas, TX");
X
X mb_sel (file, 1, str, CURRENT, "");
X
X printf ("Updated to : %s\n", str);
X
X mb_rmv (file);
X }
X
X Manipulation of relations using MetalBase is simple... by including the
XMetalBase header file in your programs (As line (*), above) and compiling using
Xthe option "-lmb" (Or "library ..., mbase.lib, ...", depending on your
Xcompiler), you add extra commands to C. A summary of these follows:
X
X - mb_inc (filename, int) -- this command includes a relation on your desktop,
X so that it becomes accessable. Any relation you wish to work with
X must be included, as in line (**) above. If mb_inc returns a negative
X number (Zero is a valid return code-- it does not indicate an error),
X an error has occurred (The most likely one is that the relation cannot
X be found under the given directory). Note that "filename" does NOT
X include the ".rel" suffix. BUILD, in analog, does not require that
X you include the ".s" suffix on the name of the schema you are working
X with, but the schema file must end in ".s", as relations must end in
X ".rel".
X The integer passed in is the encryption key for the relation--see the
X section on encryption for more information. Note that MetalBase 3.0,
X as it does not support encryption, does not require this integer.
X Sorry for the inconvenience.
X
X - mb_sel (file, index, buffer, action, comparison_value) -- this command
X searches a given relation for the record you desire, described by
X "action" and "comparison_value". "file" is the number returned by
X mb_inc... this code is used in all other functions to indicate which
X relation you intend to work with. "index" is the index number by which
X you wish to search... numbered sequentially by the order in which they
X were defined in the schema, starting with the number 1. "buffer" is
X merely a string into which MetalBase can return the record, when found.
X Note that the ENTIRE record will be returned, not just the fields
X indicated through the schema for use by the index. A list of valid
X actions follows:
X FIRST (or FRST) -- searches for the first record alphabetically.
X LAST -- similarly, seeks the last record alphabetically.
X NEXT -- searches for the next sequential record alphabetically.
X PREVIOUS (PREV) -- as NEXT, searches for the previous record.
X EQUAL (EQUL) -- seeks a record containing fields exactly those in
X "comparison_value". If the index used allows duplicates and
X some exist, EQUAL returns the first of these: all duplicates
X can be found by subsequent "NEXT" searches.
X GTEQ -- EQUAL returns a NOT_FOUND error if a record cannot be found
X to precisely match the comparison. GTEQ acts as EQUAL in all
X respects but this; GTEQ will find the record greater
X alphabetically, or precisely equal to (If one exists), the
X comparison.
X GTHAN (GTHN) -- Acts as GTEQ, except GTHAN will ignore precise
X matches. Useful if you wish to begin searching names, say,
X after the "Smith"'s. Another way to accomplish this would be
X to use LTEQ + "Smith", followed by a NEXT...
X LTEQ -- Searches for a record less alphabetically, or equal to (if
X one exists), the comparison. In the event that duplicates of
X the record about to be returned exist ("Duplicate" being
X defined locally by a record, whose fields used by a given
X index are precisely equal to another record's such fields on
X the same index), LTEQ returns the last of these: all
X duplicates can be found by subsequent "PREVIOUS" searches.
X LTHN (LTHAN) -- Similar to LTEQ in all but one regard: LTHAN will
X not return a precise duplicate, instead searching to its
X left for the record before it.
X CURR (CURRENT) -- After a record is found by a search, MetalBase
X remembers the location of the record. Searching with the
X action CURRENT re-reads this most recent record, and returns
X it in its entirety. As with FIRST, LAST, NEXT and PREVIOUS,
X the value of "comparison_value" is irrelevant in CURRENT --
X however, CURRENT is also oblivious to index used (As no
X actual searching takes place... MetalBase merely recalls a
X known record).
X Please note that the above-described action names merely stand for
X integers, and MetalBase will not understand if you use quotes around
X the names. These actions must also be written in upper-case.
X "comparison_value" is a string containing a record consisting only of
X the fields needed by an index... each field separated from the next
X by a vertical bar. The last field may optionally be terminated with
X a vertical bar, if desired.
X
X - mb_upd (file, new_rec, mode) -- After a record is found, it may be updated
X through mb_upd. MetalBase simply replaces the old record's fields with
X those indicated in "new_rec". This process usually requires more time
X than any other, as the record must be disconnected from each index in
X turn, changed, and reconnected. Occasionally, changing a record will
X not change certain indicies. When this occurs, the update would take
X less time if the index were skipped... and if you feel this extra time
X is necessary, type the word FAST for "mode". Like the actions for
X mb_sel, FAST and SLOW should not be surrounded in quotes.
X Disconnecting and reconnecting a record, to the contrary of the
X preceeding argument, is a very beneficial process, even for indicies
X which are not changed through a specific update. The algorhythm used
X for such updating is designed to help normalize the database, much as
X a kitchen-knife case which sharpens blades every time a knife is
X removed or inserted. A "normalized" index is one in which records have
X been packed as closely together as possible, minimizing lookup time.
X If "mode" is set to SLOW in mb_upd, ALL indicies will be updated in
X this way every time a record is updated.
X An update will be aborted if the changes would violate a non-duplicate
X index.
X
X - mb_del (file, verification) -- After a record is found, it may be removed
X completely by use of mb_del. Once a record is deleted thus, it CANNOT
X be retrieved. The "verification" argument should be NULL ("") -- its
X only purpose is to ensure that the command has not been confused with
X mb_rmv, described below. Due to C's handling of file-length limiting
X pointers, mb_del does not decrease the actual amount of storage space
X for a relation. Subsequent additions, however, will not increase
X allocation space for a relation until the number of records added
X exceeds the number previously deleted. To recover this space and
X physically remove deleted records, see the section on Utilities, below.
X
X - mb_add (file, new_rec) -- This command adds a new record to a relation. If
X adding the record described by "new_rec" would violate a non-duplicate
X index, the addition to the relation will be aborted and an error
X returned (See the section on Errors, below).
X
X - mb_lck (file) -- If, as an example, a program reads a record from a relation
X used by many terminals simulaneously, waits for a user to enter a new
X value for one of its fields, and updates the record, it could prove
X disastrous if the record was read by one terminal, then another...
X updated on one & re-written, and re-updated by the second terminal. To
X prevent this type of scenario, mb_lck, when used, excludes other users
X from including a relation on their desktop. Such a lock cannot be
X installed if more than one user is already using the relation.
X
X - mb_unl (file) -- Removes a lock placed on a relation by mv_lck.
X
X - mb_rmv (file) -- This command removes a relation from your desktop. If the
X file has been locked previously (Via mb_lck), the lock is removed.
X
X Note from the example program above that comparison values in mb_sel, and
Xnew_rec in mb_add and mb_upd need not be spaced correctly, or at all...
XMetalBase will automatically justify each field properly before implementing
Xit. However, if "7.3 |" (Note the trailing space) is included as, say, a six-
Xcharacter right-justified field, it will be spaced to " 7.3 |"... the trailing
Xspace remains intact. Left-justified fields similarly retain any leading
Xspaces.
X
X
XERRORS_________________________________________________________________________
X
XBuild / Errors :
X
X Cannot open <file.s>............The schema indicated to Build cannot
X be found.
X File <file.s> holds no schema...The schema indicated cannot be used
X definition as a definition of a relation. The
X most likely cause is that the file is
X empty.
X Field <field> declared after....All fields must be declared before any
X indicies indicies are declared.
X Field <field> declared twice....Field names must be unique. Spaces are
X not allowed in field names.
X No fields declared before.......A relation must contain fields, and these
X end reached must be declared before any indicies.
X Incorrect syntax................The definition of a field's length or
X justification has been entered
X incorrectly.
X Field <field> undefined.........An index has been placed on a non-
X existant field. Check spelling.
X No fields declared before end...The schema definition is incomplete: it
X reached must contain at least one field and
X one index.
X No indicies declared before.....See the above error description.
X end reached
X Identifier <?> not recognized...The only valid words for the beginning
X of a line are "relation" or a relation-
X name (As the first line), "field",
X "index", and (optionally) "end".
X Cannot open relation............The file <file.rel> cannot be written...
X possible causes are a media error or
X write-protection on the file.
X Relation is busy................Relations cannot be re-built until it is
X not being worked with by any users.
XBuild / Warnings:
X
X Please re-define BUF_LEN as.....If a relation's record length is
X excessive, you will receive this
X warning. The line "define BUF_LEN xx",
X with the x's representing the number
X described in the warning line, must be
X included before "#include <mbase.h>".
X Please re-define MAX_FLDS as....If any relation contains more than 30
X FIELDS (_not_ records), the line"
X #define MAX_FLDS xx" must be inserted
X at the beginning of your program, as
X with the previous warning.
X Please re-define MAX_CUT as.....If a relation's record length is greater
X than 80, you will need to insert the
X line "#define MAX_CUT xx", as with the
X previous warnings.
X Please re-define MAX_RPT as.....If the length of any field is greater
X than 240 characters, you will need to
X insert the line "#define MAX_RPT xx",
X as with the previous warnings.
X The file about to be created....If you build a relation where a relation
X already exists of the same name already exists, any
X data in the existing relation will be
X erased in favor of the new, empty
X relation.
XMetalBase / Errors :
X
X 0..OKAY...............This is the generic no-problem return code. All
X functions except mb_inc should return 0 if
X they have been able to function properly.
X -1000..NOT ENOUGH ROOM....Too many relations are open at once -- mb_inc
X cannot allocate enough space for the new
X relation. This error can be prevented by
X re-defining MAX_REL, as with build's warning
X messages, to a value greater than its default
X of 5. In addition, having many files open at
X once may require that you warn <stdio.h>...
X consult your system manuals.
X -1001..CANNOT OPEN........The file <file.rel>, where <file> is the name
X RELATION passed to mb_inc, cannot be opened. In all
X probability, it does not exist.
X -1002..RELATION_HUNG......A user has stopped a program during a record
X addition, deletion, or update. These functions
X place temporary locks on a file, which are
X removed at the end of their respective
X procedures. Normally other functions will
X simply wait for the file to be unlocked, but if
X the wait time becomes excessive, this error is
X returned and the function aborted. Try the
X function again, and if you recieve this error
X a second time, see the section on Utilites to
X remove the lock manually.
X -1003..CANNOT READ........The file <file.rel> cannot be read. This error
X RELATION is returned only from mb_inc, and is probably
X caused by read-protection placed on the file.
X -1004..RELATION BUSY......No more than 120 users may work simultaneously
X with a given file.
X -1005..RELATION LOCKED....The relation about to be opened has been locked
X intentionally by another user, and is
X unavailable for use by others. If no one is
X using this relation, see the section on
X Utilites in order to remove the lock on the
X relation.
X -1006..LOCK DENIED........A relation cannot be locked while more than one
X user is working with it. If no other users
X are on the relation and you still receive this
X error, see the section on Utilities in order to
X clean the user-count on the relation.
X -1007..ILLEGAL DUPLICATE..The record that has been offered for addition/
X update would violate an index that has been
X declared to not allow duplicates.
X -1008..CORRUPT INDEX......This relation has an error on an index. See the
X section on Utilites to repair it. Try to find
X which index you were working with at the time
X of the error, in order to speed repair.
X -1009..INVALID FILE CODE..Relation codes, the numbers returned by mb_inc,
X are always positive. This error is returned
X upon receipt of a negative relation code.
X -1010..NOT OPEN...........The relation with which you are trying to work
X has been closed.
X -1011..RECORD INVALID.....Not enough, or too many, fields have been given
X for update or addition of a record.
X -1012..INVALID COMP.......The comparison value submitted via mb_sel must
X contain exactly the number of fields required
X to complete a given index.
X -1013..UNKNOWN ACTION.....A very unlikely error, receipt of this code
X indicates you have passed a number greater than
X 12 or less than 0 to mb_sel as an action.
X -1014..NOT FOUND..........Generic code returned when the record described
X cannot be found in the relation searched. If
X you feel it should have been found, check the
X index number, action, and comparison value used
X in the search.
X -1015..NO CURRENT.........Update and delete act on the record which has
X RECORD been found most recently. When a relation has
X just been opened, and just after a record is
X deleted, there is no such record.
X -1016..INVALID INDEX......A bad index number has been passed to mb_sel.
X Valid numbers range 1 through the number of
X indicies in a relation.
X
X
XUTILITIES______________________________________________________________________
X
X The supporting utilities to MetalBase have not been released with this
Xpackage, primarily because I have not bothered to write them yet. See the
Xsection on SHAREWARE below to see how to register yourself with me (god), as
XI'll write any of the following upon request once you're registered.
X
X Utilities include:
X * Repair of bad indicies (Also normalizes relation for maximum speed)
X * Recovering lost space from previous deletes
X * Overhaul of relation (Last two, in one)
X * Removal user-placed locks
X * Removal system-placed locks
X
X
XENCRYPTION______________________________________________________________________
X
X MetalBase 3.1 (not 3.0) automatically encrypts all files. Users of version
X3.0 may just as well skip this section.
X When a relation is opened (using mb_inc() ), an integer encryption-key is
Xpassed in to MetalBase. Any records which are added to that relation are
Xencrypted using this key, and any records which are retrieved are decrypted
Xsimilarly before they are returned. In this way, any information which is
Xphysically stored is encrypted beyond recognition. As long as this integer key
Xis the same every time the relation is opened, the encryption is totally user-
Xtransparent: records are passed to mb_inc and mb_upd in normal text, and are
Xretrieved in normal text, but are stored garbled. If the key changes, however,
Xthe records retreived in the second session will be decrypted under the new
Xkey, whereas they were encrypted under the former... and the output will be
Xgarbage.
X The values of the integer determine the level of encryption to use (note
Xthat similar numbers, say, 140 and 141, give very different encryption
Xresults):
X 0- 64 : Only minimal encryption (Due to the way the encryption method
X works, every character is simply 2's-complimented. This is
X exceedingly simple to decode, but is easily sufficient to
X confuse any reader)
X 65-128 : Slight encryption -- characters are inverted as before, but every
X few characters will be garbaged.
X 129-192 : Medium encryption -- more frequent garbage than 65-128.
X 193-255 : Total garbage.
X
X
XSHAREWARE_(THE_IMPORTANT_PART)__________________________________________________
X
X My name is Richid Jernigan IV. In the past I have released several not-
Xterribly-popular programs through PD, the most popular were developed for the
X//e'ers of the day (when AE's were so popular) by myself and the Masked
XMarauder... Super VH Mod I and ][. Anything with The Eye (old handle) or
XHuan-Ti plastered all over it is mine (I _am_ a bit vain. Had you noticed?).
X I have designed and written all the versions of MetalBase and all
Xsupporting code. I claim this code as mine alone, in all ways, shapes, and
Xforms.
X HOWEVER, I learned most of what I know of programming through examples from
Xvarious people, which were distributed freely. As such, I feel it's only right
Xfor me to try to contribute this, the only thing I can think of which anyone
Xmight want, to the public. I would therefore like to distribute this freely
Xand without restriction.
X HOWEVER, I'm also broke. I've spent too long on this project to see it
Xsuddenly become part of everyone's wet dreams without any financial reward on
Xmy part. So, I'm releasing it as shareware. The conditions:
X
X * Give it to as many people as possible.
X * Leave the existing documentation intact. Add more if you'd like,
X but leave this. Feel free to add sample programs and relations
X if you like.
X * Leave the credits. I'm vain and I'm poor, and the publicity for
X me might do me good; if not for my wallet, at least for my ego.
X * Tell me about any bugs you find (God forbid -- you wouldn't
X _believe_ how many tests this thing has been through).
X * Send any modifications to me (as it sez in mbase.c, I'd like to see
X the improved code). More importantly, SEND IDEAS! If you'd like
X an improvement, tell me about it! Whether or not you modify the code
X yourself, I'd like to know what's being done to it.
X * If you find MetalBase useful, elegant (check out _search in mbase.c),
X or just plain worth it, and _certainly_ if you use it in any
X commercial or shareware programs, please send a donation ($5? $10?
X The more the better, really!) to the poor programmer's fund (hehehe):
X Richid Jernigan IV
X PO Box 827
X Norris, TN 37828 <- Yes, folks, he's from TN! <Speee-it!>
X Gimme a name and a mailing address (internet or bitnet account
X names are fine -- just so I can distribute code / information), and
X you'll receive the following:
X * Any new versions of MetalBase, whenever they pop up
X * The privilege of being able to request modifications or
X development of any of the previously-mentioned utilities
X (which will be sent to everyone on the list when available)
X * The privilege of being able to DEMAND fixes to any bugs you
X find (now wouldn't _that_ be fun?)
X * A big smile from me (worth it, isn't it? Wreeetch!)
X
X I can also be reached (during the school-year, save for Spring '90-91)
X at (now) rpj@owlnet.rice.edu, or (soon) at richid@owlnet.rice.edu .
X
XShare and enjoy! (God, did I just say that? Yeech! I'm quoting books again.)
X ___
X / / The man with the hammer,
X | (___________.----------------. Richid
X ( ___________| | (rpj@owlnet.rice.edu)
X ) ( `----------------' (Huan-Ti)
X '---`
X
END_OF_FILE
echo shar: 1 control character may be missing from \"'mbase.dox'\"
if test 36649 -ne `wc -c <'mbase.dox'`; then
echo shar: \"'mbase.dox'\" unpacked with wrong size!
fi
chmod +x 'mbase.dox'
# end of 'mbase.dox'
fi
echo shar: End of shell archive.
exit 0
--
/ (_________ The man with the hammer __________) \ "Lobbest-thou thy Holy
( ______ _______ ) Hand-Grenade of Antioch
) ( Richid rpj@owlnet.rice.edu ) ( towards thy foe..."
'---` '---` --Monty Python, HG.
exit 0 # Just in case...
--
Kent Landfield INTERNET: kent@sparky.IMD.Sterling.COM
Sterling Software, IMD UUCP: uunet!sparky!kent
Phone: (402) 291-8300 FAX: (402) 291-4362
Please send comp.sources.misc-related mail to kent@uunet.uu.net.