Tclgdbm 0.10

홈페이지 : http://www.graphviz.org/pub/tclgdbm/

Tcl의 GDBM 인터페이스로 tcl/tk에서 GNU gdbm 파일에 액세스 하기 위해 동적으로 로드되는 확장 프로그램입니다. GNU gdbm 파일은 임의의 키에서 값으로의 매핑을 제공합니다. tclgdbm은 이러한 기능을 사용하여 (짧은) 키 문자열에서 (큰) 데이터 문자열로의 매핑을 제공합니다.

Tclgdbm was hacked together by John Ellson (ellson@lucent.com)
additions by H.-Juergen Godau (JG)
It was derived from tcl+gdbm by Christian Lindig
Major rewrite by Dave Bodenstab (DB)

The latest version of Tclgdbm is kept at:

    http://www.graphviz.org/pub/tclgdbm/


tclgdbm 0.1.3  - JE - upgrade to tcl7.5 loadable library
tclgdbm 0.2    - JE - upgrade to tcl7.6 package (loadable library)
tclgdbm 0.3    - JE - fixes for tcl8.0
tclgdbm 0.4    - JE - fix mem leak with patch from: t-tange@ats.nis.nec.co.jp
tclgdbm 0.5    - JE - add gdbm error, and gdbm writemode
                      with patch from: Scott Beasley
tclgdbm 0.6    - JE - support for Stubs (8.0.6, 8.1.1, or later)
tclgdbm 0.7    - JG - support for strings with NUL-Bytes / Not terminated
                      use the new Obj-Style Tcl-Interface
tclgdbm 0.8    - JE - add rpm support

tclgdbm 0.9    -  DB - major rewrite
            - converted fully to Tcl_Obj's
            - able to handle keys and data with embedded NUL's
            - deal with Tcl's internal UTF string encoding
            - put in own namespace tclgdbm::gdbm
            - remerge of changes from tcl+gdbm-0.4 (insert/store
              accept multiple args for data)
            - updated man pages
            - add test driver tclshgdbm
            - add gdbm.test which uses standard tcltest package
        - JE - repackage Dave's changes into rpm

NOTE: Dynamic loading requires that libgdbm.a be built with -fpic
   otherwise you may get all kinds of relocation errors from ld.

Tclgdbm
-------

This directory contains the source of tclgdbm, a dynamically loaded
extension for accessing GNU gdbm files from tcl/tk. GNU gdbm files
provide persistent mappings from arbitrary keys to values. tclgdbm
uses 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:

##
## load dll
##
package require Tclgdbm
namespace import tclgdbm::gdbm

##
## 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 you need:

    Tcl 8.3, or later,  installed (tcl.h and tclsh)
    GNU gdbm 1.7.1, or later, (gdbm.h and libgdbm.a N.B. built with -fpic)
    ANSI C compiler like gcc

You will need to provide the correct GNU_PREFIX so that
make can find $(GNU_PREFIX)/include/gdbm.h and $(GNU_PREFIX)/lib/libgdbm.a

To make type:
        ./configure
        make
        make install

The generated Makefile looks in $PREFIX/include for tcl.h and in
$PREFIX/lib for tclConfig.sh.

The Makefile generates pkgIndex.tcl files that are compatible with
tcl8.3 and later.

For a simple test run test.tcl directly or by calling `./tclgdbm test.tcl`.

This distribution has been successfully compiled on:

    Linux   RedHat 7.0

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  or [list  ...] 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  or [list  ...] to the database. If
already exists the new  replaces the old or an error
is returned depending on the current setting of write mode.  Nothing
returned.

gdbm fetch

is the name of a gdbm database previously opened with gdbm
open.  Searches for  in the database and returns the associated
contents, or returns a tcl error if the key is not found.

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 error number|text
Return the value of the last GDBM error as either a number or a text
string.

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 first/next scheme permits retrieving 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.

gdbm writemode  replace|insert

Set the default write mode for the database referred to by  to
GDBM_REPLACE or GDBM_INSERT.  Defaults to GDBM_REPLACE for backwards
compatibility. Subsequent gdbm store commands will use this write mode.

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 COPYING

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.

Credits
-------

Juergen Schoenwaelder  gave much hints that
improved portability and elegance of the code.

John Ellson  with additions by H.-Juergen Godau

Dave Bodenstab  completely reworked the source converting
it to use Tcl_Obj's and incorporating version 0.4 of Christian Lindig's
tcl+gdbm.

Bugs
----

Report bugs, ports, improvements and successful compilation on
platforms different from the ones mentioned above to ellson@lucent.com.

Author
------

Christian Lindig
TU Braunschweig
Institut fuer Programmiersprachen
Abteilung Softwaretechnologie
D-38106 Braunschweig
Germany