Sdbm routines: BETA**2 release (Aug 1989)
Copyright 1989 Ozan S. Yigit

***********************************************************************
Note: if you use this code to create production-level databases, be
forewarned that the final release may have a bitmap slightly incompatible
with the current one, and thus be prepared to convert.
***********************************************************************

This is the beta release of ndbm/dbm clone, sdbm, as promised. 
Please note that this beta distribution is copyright (see sdbm.c), to avoid
un-intentional slippage, and to cover my rear against any reverse claims
once it becomes PD. It *will* be PD (real PD, not copyleft) once we are
through this beta.

Somebody once asked "how beta" was this beta. Simply put, it works very
well and in fact better than ndbm. I do not know of any major bugs, but no
doubt you will find some.  [that is the idea I think :-]. Another good
reason for this "beta" is to get the necessary portability changes for
other un*x variants. I have access to SunOS 3.5 and RISC-OS 1.0 for now.
AIX to come soon.  You can also help by pointing out possible areas of
optimization (for example, take a look at splpage routine(s)), or by
helping me make the code more readable, maintainable, etc. I hope to get
some useful feedback from all of you.

Sdbm is based on a 1978 algorithm by Per-Ake Larson, called "Dynamic
Hashing". A document (somewhat unfinished) describing (in excruciating
detail) how one can derive such a database implementation from Larson's
paper is included. [After examining two public accounts of Bell labs dbm
algorithm, I have reason to believe that it also is based on Larson's
work. The subtle portion of dbm/ndbm is how it traverses the tree, (I
suspect it requires good Number Theory to derive the equivalence) but it
is quite irrelevant now.]

Included in this package:

	README		this file.
	WISHLIST	as it says
	dba.c		a very crude dbm page file analyser
	dbm.c		a very crude dbm utility
	howtodbm.txt	algorithm in great detail
	makefile	guess.
	pair.c		page-level routines (posted earlier)
	pair.h		header file for the above
	port.h		this is where portability thingies should go
	sdbm.c		the real thing
	sdbm.h		header file for the above
	hash.c		hashing function

I use dbm to test out the routines: it takes (from stdin) tab separated
key/value pairs for things like "build" or "insert" or takes keys for
things line "delete" or "look".

usage: dbm <build|creat|look|insert|cat|delete> dbmfile

dba is a crude analyser of dbm/sdbm/ndbm page files. It scans the entire
page file, reporting page level statistics, and totals at the end. I am
re-writing this one to do things like "directory" recovery, and other
stats reporting.

dbd is a crude dump program for ndbm/sdbm databases. It ignores the
bitmap, and dumps the data pages in sequence. It can be used to create
input for dbm. Note that dbd will skip any NULLs in the key and data
fields.

Hash functions: sdbm needs a good bit-scrambling hash function to be
effective. I have discovered a simple and effective one (seems to perform
better than ndbm hash function for various inputs) quite by accident (in
AHO & SETHI & ULLMAN) but you may know of better ones. Try your favorite,
and check page stats with dba. If the page file contains too many pages
with too many holes, (compare to this one for example) you have struck
out. If you do better, then send me the algorithm, and I will put it
through the infamous /usr/lib/news/history test.

PLEASE NOTE:

When it is officially released, this code will be in Public Domain.  Until
that time, only those who have received this code directly from the author
have the right to modify and use it in a form suitable to a beta-test
release. Please especially note the following:

- The author is not responsible for the consequences of use of
  this software, no matter how awful, even if they arise from defects 
  in it.

- This code must NOT be distributed without prior permission from 
  the author.

enjoy...	oz

--
use the source, luke !!     	        Usenet:    oz@nexus.yorku.ca
uh... we forgot to tell you...          ......!uunet!utai!yunexus!oz
it is unintelligible, but hey, you      Bitnet: oz@[yulibra|yuyetti]
got it, for free (!).                   Phonet: +1 416 736-5257x3976
