## 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.