$Id: README,v 1.6 1994/05/04 08:33:27 lindig Exp $ Tclgdbm and Wishgdbm (tcl+gdbm 0.1) ----------------------------------- This directory contains the source of tclgdbm and wishgdbm, two tcl/tk extensions for accessing GNU gdbm files from tcl/tk. GNU gdbm files provide persistent mappings from arbitrary keys to values. tclgdbm and wishgdbm 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 [gdbm open test.data rwc]; foreach i {1 2 3 4 5 6} { # key is $i, store string "This data for $i" gdbm store $db $i "This data for $i" ; } ## ## gdbm list $db gives list of all keys in $db ## foreach key [lsort [gdbm list $db]] { # retrieve each content and display it puts stdout "$key [gdbm fetch $db $key]" ; } gdbm close $db ; Requirements & Installation --------------------------- For successfull compilation of tclgdbm and wishgdbm 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 wishgdbm) GNU gdbm 1.7.1 (gdbm.h and libgdbm.a) 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 wishgdbm and tclgdbm. For a simple test run test.tcl directly or by calling `./tclgdbm 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 -------- gdbm open [r|rw|rwc|rwn] Opens a gdbm database 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 which is used to refer to the open database. gdbm close Close a gdbm database with the name . gdbm insert is the name of a gdbm database previously opened with gdbm open. Inserts the data giving it the key . If data with is already in the database an error is generated. Nothing returned. gdbm store is the name of a gdbm database previously opened with gdbm open. Inserts to the database. If already exists the new replaces the old. Nothing returned. gdbm fetch is the name of a gdbm database previously opened with gdbm open . Searches for in the database and if found returns its contents. Returns the contents of or if not found, the empty string. gdbm delete is the name of a gdbm database previously opened with gdbm open. Searches for and deletes it in the database. If is not found an error is generated. Nothing returned. gdbm list is the name of a gdbm database previously opened with gdbm open. Returns a list of all keys in the database. gdbm reorganize is the name of a gdbm database previously opened with gdbm open . This routine can be used to shrink the size of the database file if there have been a lot of deletions. Nothing returned. gdbm exists Returns "0" if is not found within the previously opened database , "1" otherwise. gdbm firstkey gdbm nextkey A fist/next scheme permits to retrieve all keys from a database in sequential (but unsorted!) order. gdbm firstkey 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 tclgdbm1.0 by 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.: gdbm store gdbm fetch returns a list Credits ------- Juergen Schoenwaelder gave much hints that improved portability and elegance of the code. Bugs ---- - 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 TU Braunschweig Institut fuer Programmiersprachen Abteilung Softwaretechnologie D-38106 Braunschweig Germany