DBM - DBM interface for STk

version 0.2

Shiro Kawai (shiro@acm.org)

Table of Contents

Copyright (C) 2000 Shiro Kawai (shiro@acm.org)

1. Overview

DBM-like libraries provides an easy way to store values to a file, indexed by keys. You can think it as a persistent associative memory. This package provides a generic interface to the various dbm-like libraries. Current version hass bridges to gdbm, ndbm and legacy dbm libraries.

1.1 Requirements

You need STk version 4.0.1 or later. STk is available at http://kaolin.unice.fr/stk/. Also a generic serializer package for STk (after 0.3) is required. It is available at http://pracitcal-scheme.net/.

You should have at least one of dbm, ndbm or gdbm library. Gdbm is available at http://www.gnu.org/software/gdbm/gdbm.html.

1.2 Installation

The most recent version of the document and the package is available at the following URLs. (The package tarball includes the html document).

After ungzip and untar the package, you'll find a directory dbm. Just type


to create a Makefile. Then


compiles necessary files. If you like to confirm everything is OK, type

make test

to do some test. You can install the package to the site-scheme location by

make install

2. Common Interface

The <dbm> abstract class defines a common interface to use various DBM-type database packages.

Just to operate on the already created and opened database, require "dbm" module.

(require "dbm")

To create or open a database, you need to load at lease one of the following modules. Each module defines its own low-level accessing functions as well as the common interface.

GDBM library. Besides the common interface, all of the options GDBM provides are available. See section 3. GDBM bridge for details.
NDBM library. See section 4. NDBM bridge for details.
DBM library. See section 5. Original DBM bridge for details.

By default, only strings are allowed to keys and values. You can use other Scheme types for keys and values, however, by specifying a serializer class upon the creation of the <dbm> instance. See section 2.5 Object serialization for details.

2.1 Opening a database

By instantiating a subclass of the <dbm> class, you can either open an existing database or create a new database.

Generic method: make class &key :path :rw-mode :file-mode :serializer
Create a new dbm object associated to the database file path if class is one of subclasses of the class <dbm>.

Depending on the actual implementation, path may be used literally as a database filename (gdbm) or some suffixes are added (odbm, ndbm).

The keyword argument rw-mode takes one of the following values:

Opens a database for read-only. If the specified database file does not exist, an error is signalled.
Opens a database for read and write. If the specified database file does not exist, a new empty database is created. This is the default.
Creates a database for read and write. If the specified database file already exists, its content is cleared.

The keyword argument file-mode takes a number representing unix file mode to be used when make needs to create a new database. The default is #o664. This value may be masked by the user's umask setting.

DBM interface only takes strings for keys and values by default. If you need to store other types of objects to the database, you need to tell the DBM instance how to convert those objects by serializer keyword argument. It may take a class object which is a subclass of <serializer>, or a value #t. If it is a subclass of <serializer>, a serializer instance of the class is used to convert Scheme objects. If it is #t, the standard external representation is used. See section 2.5 Object serialization for details how this mechanism works.

2.2 Accessing a database

Once a database object is created, you can use the following methods to access individual key/value pairs. Note that, unless you specify serializer argument when you create the dbm object, keys and values must be strings. See section 2.5 Object serialization for details.

Generic method: dbm-put! (dbm <dbm>) key value
Put a value with key.

Generic method: dbm-get (dbm <dbm>) key &optional default
Get a value associated with key. If no value exists for key and default is specified, it is returned. If no value exists for key and default is not specified, an error is signalled.

Generic method: dbm-exists? (dbm <dbm>) key
Return true if a value exists for key, false otherwise.

Generic method: dbm-delete! (dbm <dbm>) key
Delete a value associated with key.

2.3 Iterating on a database

To walk over the entire database, following methos are provided.

Generic method: dbm-for-each (dbm <dbm>) procedure
For each key/value pair in the database dbm, procedure is called. Two arguments are passed to procedure---a key and a value. The result of procedure is discarded.

Generic method: dbm-map (dbm <dbm>) procedure
For each key/value pair in the database dbm, procedure is called. Two arguments are passed to procedure---a key and a value. The result of procedure is accumulated to a list which is returned as a result of dbm-map.

2.4 To close a database

Database file is closed when it is garbage collected. However, to ensure the modification is properly synchornized, you may want to close the database explicitly

Generic method: dbm-close (dbm <dbm>)
Closes a database dbm. Once the database is closed, any operation to access the database content raises an error.

Generic method: dbm-closed? (dbm <dbm>)
Returns true if a database dbm is already closed, false otherwise.

2.5 Object serialization

The low-level interface to the dbm libraries only deals with strings. If you want to store general Scheme objects, you need to specify how to convert back and forth between objects and strings. Different applications need different requirements, so it's not good to implement one specific way in this library.

With :serializer parameter in the constructor of dbm class, you can specify your serialization scheme.

No conversion is done. You must pass a string as a key or a value. Keys are effectively compared by string=?.
DBM interface applies write* to get a string representation of the object, and read to get the original object back. This means:
a class derived from <serializer>
An abstract base class <serializer> defines a common interface for object serialization. You can pass a serializer implemenation of your choice. See http://practical-scheme.net/vault/serializer.html about the details of serializer.

3. GDBM bridge

Module GDBM provides a bridge to the GDBM library. To use GDBM interface, require it as follows:

(require "gdbm")

3.1 GDBM-specific options

The GDBM module defines a class <gdbm>.

3.2 GDBM low-level interface

These functions are direct interface to the gdbm library. See gdbm manpage for

Function: gdbm-open path &optional size rwmode fmode error-callback

Constant: |GDBM_READERT|

Constant: |GDBM_WRITER|

Constant: |GDBM_WRCREAT|

Constant: |GDBM_NEWDB|

Constant: |GDBM_FAST|

Constant: |GDBM_SYNC|

Constant: |GDBM_NOLOCK|

Function: gdbm-close gdbm-object

Function: gdbm-closed? gdbm-object

Function: gdbm-store key value &optional flag

Constant: |GDBM_INSERT|

Constant: |GDBM_REPLACE|

Function: gdbm-fetch gdbm-object key

Function: gdbm-delete gdbm-object key

Function: gdbm-firstkey gdbm-object

Function: gdbm-nextkey gdbm-object key

Function: gdbm-reorganize gdbm-object

Function: gdbm-sync gdbm-object

Function: gdbm-exists gdbm-object key

Function: gdbm-strerror errno

Function: gdbm-setopt gdbm-object option value






Function: gdbm-version

Variable: *gdbm-errno*

4. NDBM bridge

(require "ndbm")

4.1 NDBM-specific options

4.2 NDBM low-level interface

Function: ndbm-open path flags mode

Function: ndbm-close ndbm-object

Function: ndbm-closed? ndbm-object

Function: ndbm-store ndbm-object key content &optional flag

Function: ndbm-fetch ndbm-object key

Function: ndbm-delete ndbm-object key

Function: ndbm-firstkey ndbm-object

Function: ndbm-nextkey ndbm-object

Function: ndbm-error ndbm-object

Function: ndbm-clear-error ndbm-object

5. Original DBM bridge

(require "odbm")

5.1 DBM-specific options

5.2 DBM low-level interface

Function: odbm-init path

Function: odbm-close

Function: odbm-store key value

Function: odbm-fetch key

Function: odbm-delete key

Function: odbm-firstkey

Function: odbm-nextkey key


Jump to: * - d - g - m - n - o - |


  • *gdbm-errno*
  • d

  • dbm-close
  • dbm-closed?
  • dbm-delete!
  • dbm-exists?
  • dbm-for-each
  • dbm-get
  • dbm-map
  • dbm-put!
  • g

  • gdbm-close
  • gdbm-closed?
  • gdbm-delete
  • gdbm-exists
  • gdbm-fetch
  • gdbm-firstkey
  • gdbm-nextkey
  • gdbm-open
  • gdbm-reorganize
  • gdbm-setopt
  • gdbm-store
  • gdbm-strerror
  • gdbm-sync
  • gdbm-version
  • m

  • make
  • n

  • ndbm-clear-error
  • ndbm-close
  • ndbm-closed?
  • ndbm-delete
  • ndbm-error
  • ndbm-fetch
  • ndbm-firstkey
  • ndbm-nextkey
  • ndbm-open
  • ndbm-store
  • o

  • odbm-close
  • odbm-delete
  • odbm-fetch
  • odbm-firstkey
  • odbm-init
  • odbm-nextkey
  • odbm-store
  • |


  • This document was generated on 11 February 2000 using texi2html 1.56k.