dbm-open

Function

Package: dbi.ndbm

ToC

DocOverview

CGDoc

RelNotes

Index

PermutedIndex

Allegro CL version 7.0
This page is new in 7.0.

dbm-open

Arguments: filename &key if-exists if-does-not-exist default-return external-format mode store-null-terminators

dbm-open opens or creates an ndbm database. filename specifies the base filename for the database (notes on this below).

The keyword arguments are:

if-exists: the value may be :append (the default), :overwrite, or :supersede. :append and :overwrite are synonymous and indicate that an existing database should be opened. :supersede means that any existing database should be erased and a fresh database should be created.
if-does-not-exist: the value may be :error (the default) or :create. :error means that an error will be generated if the database does not exist. :create means that a fresh database will be created if one does not exist.
default-return: this argument specifies the default data type to return from dbm-fetch. Internally, NDBM databases simply work with byte arrays. However, it is often convenient to work with strings. If default-return is :string (the default), then database data will be converted to strings before being returned from dbm-fetch (unless the return type is specified in the call to dbm-fetch). If default-return is :usb8, then dbm-fetch will return usb8 vectors (that is, (unsigned-byte 8) vectors) unless the return type is specified in the call to dbm-fetch.
external-format: this argument specifies the default external format to use when storing/retrieving strings from the database. If not supplied, then (locale-external-format *locale*) will be used. (See locale-external-format and *locale*.)
mode: this argument is defined by the open(2) system call documentation on each system. No value need be specified, as the default value is generally suitable.
store-null-terminators: if this argument is true (the default), then when strings are used as keys or data, their null terminating bytes are included in the data stored in the database.

This function returns an ndbm object.

Note about the filename

Your operating system's implementation of NDBM may augment the supplied filename and open/create additional files to support the database. For example, many implementations take the base filename and make two files: filename.dir and file.pag. Always use just the base filename when calling dbm-open.