tcl+ndbm was hacked together by John.Ellson@att.com
It was derived from tcl+gdbm by Christian Lindig <lindig@ips.cs.tu-bs.de>

Tclndbm and Wishndbm (tcl+ndbm 0.1)
-----------------------------------

This directory contains the source of tclndbm and wishndbm, two tcl/tk
extensions for accessing ndbm files from tcl/tk. ndbm files
provide persistent mappings from arbitrary keys to values. tclndbm and
wishndbm use these features to provide mappings from (short) key
strings to (larger) data strings. The following example illustrates
the basic new commands, see below for details:

##
## open database "test.data" for read/write (create if not existent)
##

set db [ndbm open test.data rwc];
foreach i {1 2 3 4 5 6} {
   # key is $i, store string "This data for $i"
   ndbm store $db $i "This data for $i" ;
}

##
## ndbm list $db gives list of all keys in $db
##
foreach key [lsort [ndbm list $db]] {
   # retrieve each content and display it
   puts stdout "$key [ndbm fetch $db $key]" ;
}

ndbm close $db ;

Requirements & Installation
---------------------------

For successfull compilation of tclndbm and wishndbm you need:

	Tcl 7.3 installed (tcl.h and libtcl.a)
	Tk 3.6 installed (tk.h and libtk.a)
	X11 installed (libX11.a - only for wishndbm)
	Ansi or K&R C compiler like gcc

Edit the Makefile to fit your needs, and simply type `make`. Ignore
the %.pro rule and CPROTO variable settings. This should give two
executable files wishndbm and tclndbm. For a simple test run test.tcl
directly or by calling `./tclndbm test.tcl`.

This distribution has been successfully compiled on:

	SunOS Release 4.1.1, SPARC , cc
	SunOS Release 4.1.1, SPARC , gcc 2.5.8

Commands
--------

ndbm open <file> [r|rw|rwc|rwn]

Opens a ndbm database <file> with an optional mode. If the mode is not
given it is opened for reading (r). The mode can be (r) (read only),
(rw) (read,write), (rwc) (read,write and create if not already
existent), and (rwn) (read,write and create a new database regardless
if one exists). The command returns a handle <name> which is used to
refer to the open database.
 
ndbm close <name>  

Close a ndbm database with the name <name>.
 
ndbm insert <name> <key> <content>  

<name> is the name of a ndbm database previously opened with ndbm
open.  Inserts the data <content> giving it the key <key>.  If data
with <key> is already in the database an error is generated. Nothing
returned.
 
ndbm store  <name> <key> <content>  

<name> is the name of a ndbm database previously opened with ndbm
open.  Inserts <content> to the database. If <key> already exists
the new <content> replaces the old. Nothing returned.
 
ndbm fetch  <name> <key>  
 
<name> is the name of a ndbm database previously opened with ndbm
open .  Searches for <key> in the database and if found returns its
contents. Returns the contents of <key> or if not found, the empty
string.
 
ndbm delete  <name> <key> 
 
 <name> is the name of a ndbm database previously opened with ndbm
open.  Searches for <key> and deletes it in the database.  If <key> is
not found an error is generated.  Nothing returned.
 
ndbm list  <name>  

<name> is the name of a ndbm database previously opened with ndbm
open.  Returns a list of all keys in the database.
 
ndbm firstkey <name> 
ndbm nextkey <name> <lastkey>

A fist/next scheme permits to retrieve all keys from a database in
sequential (but unsorted!) order. ndbm firstkey <name> returns a
starting key, which may be used to retrieve the following key with
nextkey. nextkey returns the next key to a given previous key. When no
next key is available, the empty string is returned.


Speed
-----

Here are some (real) execution times on a SparcStation 2 (SunOS
4.1.1). The file was stored on a local and a remote filesystem.
See torture.tcl for details.

				local fs	network fs

create 1000 short entries	2.2 sec		50.0 sec
read 1000 entries (first/next)	1.2 sec		1.5 sec
read 1000 entries (list)	1.1 sec		1.3 sec
delete 100 entries out of 1000	8.7 sec		23.2 sec
lookup 1000 keys out of 900	0.63 sec	0.82 sec

Summary: write access is expensive, especially on remote file
systems. 

Copyright
---------

see the file COPYRIGHT

History
-------

The first version was derived from tclndbm1.0 by
<tdoan@x400gate.bnr.ca> from the tcl distribution. The actual version
is nearly totally rewritten and uses much more of the data structures
provided by tcl.

Future Plans
------------

The current version maps a key string to a data string. Future
versions should map a key string to a list of datastrings i.e.:

ndbm store <db> <key> <list of strings>		
ndbm fetch <db> <key> 				returns a list

Credits
-------

Juergen Schoenwaelder <schoenw@ibr.cs.tu-bs.de> gave much hints that
improved portability and elegance of the code.

Bugs
----

- <key> strings are not allowed to be longer than 1023 Bytes. 	
- No man page yet - any volunteers?
- not extensively tested yet

Report bugs, ports, improvements and successfull compilation on
platforms different from the ones mentioned above to the author.


Author
------

Christian Lindig <lindig@ips.cs.tu-bs.de>
TU Braunschweig
Institut fuer Programmiersprachen
Abteilung Softwaretechnologie
D-38106 Braunschweig	
Germany