2.1 Interface

The module may be imported as follows:

import Gdbm at 'x-oz://contrib/gdbm'

The interface provided is similar to dictionaries and allows to store stateless Oz terms under keys. A key is an arbitrary virtual string.

Gdbm.is

{Gdbm.is +X ?B}

Returns true iff X is a gdbm object.

Gdbm.new

{Gdbm.new +R ?DB}

This is the convenient way of creating a gdbm object DB. R is a record that describes how to open the database. The label is the opening method, e. g. read, write, create, or new. The first argument of the record is the file name. For example read('/usr/local/people.db') asks to open the database located in /usr/local/people.db for reading only. create('~/data') opens or creates the database data in the user's home directory and opens it both for reading and writing; new('~/data') is similar, but overwrites it if it already existed.

Optional feature mode indicates with what permissions the file should be created (this of course is only relevant for creating a new database). The mode may be specified as an integer, with the usual Unix meaning. It may also be specified symbolically, as a record or list of records:

[owner group(read)]

This indicates that the owner has all permission rights and that group members are granted read access. Others have no rights. To also grant write access to group members, you could say:

[owner group(read write)]

The default is 0644: owner has read and write access; all others have read access.

Optional feature boolean fast requests updates without disk synchronization. See the GDBM documentation for details. Default is false.

Gdbm.open

{Gdbm.open +FILE +FLAGS +MODE +BLOCK ?DB}

This is the more complicated way of opening a gdbm database. The FLAGS specify the opening method. This is an atom or list of atoms from the set: read, write, create (equivalently new or truncate). It may also include the atom fast (see above). Each symbol may be abbreviated to its initial letter. MODE was described above. BLOCK is an integer for the block size of transfers (see GDBM documentation): use 0 to get a system dependent appropriate default.

Gdbm.get

{Gdbm.get +DB +KEY ?VAL}

Retrieves the Oz value VAL stored under KEY. The latter may be an arbitrary virtual string. If there is no such KEY in DB, an exception is raised.

Gdbm.condGet

{Gdbm.condGet +DB +KEY DEFAULT ?VAL}

Similar to the above, but returns DEFAULT if there is no such KEY in DB.

Gdbm.put

{Gdbm.put +DB +KEY +VAL}

Stores Oz value VAL under KEY in DB. VAL must be ground and stateless.

Gdbm.firstkey

Gdbm.firstkeyBS

{Gdbm.firstkey +DB ?KEY}

Returns a KEY in DB (see below). There is absolutely no guarantee as to which key this is going to be. Returns unit if the database is empty. Gdbm.firstkey returns KEY as an atom, Gdbm.firstkeyBS as a bytestring.

Gdbm.nextkey

Gdbm.nextkeyBS

{Gdbm.nextkey +DB +KEY ?NEXT}

Returns the NEXT key after KEY. Again, there is no guarantee as to which key this is going to be. The only guarantee is that if you continue in this manner, you will enumerate all the keys in the database, in some order, without repeats. Returns unit when there are no more keys. Gdbm.nextkey returns NEXT as an atom, Gdbm.nextkeyBS as a bytestring.

Gdbm.close

{Gdbm.close +DB}

Closes the database. Subsequent access attempts raise an exception.

Gdbm.remove

{Gdbm.remove +DB +KEY}

Deletes the entry for KEY if it exists.

Gdbm.reorganize

{Gdbm.reorganize +DB}

see the GDBM documentation.

Gdbm.keys

Gdbm.keysBS

{Gdbm.key +DB ?KEYS}

Returns the lazy list of all KEYS in the database. Gdbm.keys returns each key as an atom, Gdbm.keysBS as a bytestring.

Gdbm.entries

Gdbm.entriesBS

{Gdbm.entries +DB ?ENTRIES}

Returns the lazy list of all pairs KEY#VALUE in the database. Gdbm.entries returns each key as an atom, Gdbm.entriesBS as a bytestring.

Gdbm.items

Gdbm.itemsBS

{Gdbm.items +DB ?ITEMS}

Returns the lazy list of all values stored in the database. Gdbm.items returns each key as an atom, Gdbm.itemsBS as a bytestring.

Gdbm.forAll

Gdbm.forAllBS

{Gdbm.forAll +DB +P}

Calls {P VALUE} for every entry in the database. Gdbm.forAll loops over all keys as atoms, Gdbm.forAllBS as bytestrings.

Gdbm.forAllInd

Gdbm.forAllIndBS

{Gdbm.forAllInd +DB +P}

Calls {P KEY VALUE} for every entry in the database. Gdbm.forAllInd loops over all keys as atoms, Gdbm.forAllIndBS as bytestrings.