31.5.4 The Predicates

db_open_env(+EnvName, -EnvRef)

db_open_env(+EnvName, +CacheSize, -EnvRef)

Opens an environment with the name EnvName. A directory with this name is created for the environment if necessary. EnvName is not subject to absolute_file_name/3 conversion.

By using db_open_env/3 one can specify the size of the cache: CacheSize is the (integer) size of the cache in kilobytes. The size of the cache cannot be less than 20 kilobytes. db_open_env/2 will create a cache of the system's default size.

The size of the cache is determined when the environment is created and cannot be changed by future openings.

A process cannot open the same environment more than once.

db_close_env(+EnvRef)

Closes an environment. All databases opened in the environment will be closed as well.

db_current_env(?EnvName, ?EnvRef)

Unifies the arguments with the open environments. This predicate can be used for enumerating all currently open environments through backtracking.

db_open(+DBName, +Mode, ?SpecList, -DBRef)

db_open(+DBName, +Mode, ?SpecList, +Options, -DBRef)

Opens a database with the name DBName. The database physically consists of a directory with the same name, containing the files that make up the database. If the directory does not exist, it is created. In that case Mode must be update and the db-spec SpecList must be ground. If an existing database is opened and Mode is read or update, SpecList is unified with the db-spec given when the database was created. If the unification fails an error is raised. DBRef is unified with a reference to the opened database. DBName is not subject to absolute_file_name/3 conversion.

If Mode is enumerate then the indexing specification is not read, and SpecList is left unbound.

Options provides a way to specify an environment in which to open the database, or a cache size. Options should be a list of terms of the following form:

environment(EnvRef)

The database will be opened in this environment.

cache_size(CacheSize)

This is the (integer) size of the cache in kilobytes. The size of the cache cannot be less than 20 kilobytes. If CacheSize is given as the atom default, a default cache size will be used. If CacheSize is given as the atom off or the atom none, all modified records will be flushed to disk after each operation.

To avoid inconsistency, if multiple processes open the same database, then all of them should do that with Mode set to read or enumerate. (This is not enforced by the system.)

db_close(+DBRef)

Closes the database referenced by DBRef. Any iterators opened in the database will be deallocated.

db_current(?DBName, ?Mode, ?SpecList, ?EnvRef, ?DBRef)

Unifies the arguments with the open databases. This predicate can be used to enumerate all currently open databases through backtracking. If the database was opened without an environment, then EnvRef will be unified with the atom none.

db_store(+DBRef, +Term, -TermRef)

Stores Term in the database DBRef. TermRef is unified with a corresponding term reference. The functor of Term must match the functor of a spec in the db-spec associated with DBRef.

db_fetch(+DBRef, ?Term, ?TermRef)

Unifies Term with a term from the database DBRef. At the same time, TermRef is unified with a corresponding term reference. Backtracking over the predicate unifies with all terms matching Term.

If TermRef is not instantiated then both the functor and the instantiatedness of Term must match a spec in the db-spec associated with DBRef.

If TermRef is instantiated, the referenced term is read and unified with Term.

If you simply want to find all matching terms, it is more efficient to use db_findall/5 or db_enumerate/3.

db_findall(+DBRef, +Template, +Term, :Goal, ?Bag)

Unifies Bag with the list of instances of Template in all proofs of Goal found when Term is unified with a matching term from the database DBRef. Both the functor and the instantiatedness of Term must match a spec in the db-spec associated with DBRef. Conceptually, this predicate is equivalent to findall(Template, (db_fetch(DBRef, Term, _), Goal), Bag).

db_erase(+DBRef, +TermRef)

db_erase(+DBRef, +TermRef, +Term)

Deletes the term from the database DBRef that is referenced by TermRef.

In the case of db_erase/2 the term associated with TermRef has to be looked up. db_erase/3 assumes that the term Term is identical with the term associated with TermRef (modulo variable renaming). If this is not the case, the behavior is undefined.

db_enumerate(+DBRef, ?Term, ?TermRef)

Unifies Term with a term from the database DBRef. At the same time, TermRef is unified with a corresponding term reference. Backtracking over the predicate unifies with all terms matching Term.

Implemented by linear search—the db-spec associated with DBRef is ignored. It is not useful to call this predicate with TermRef instantiated.

db_sync(+DBRef)

Flushes any cached information from the database referenced by DBRef to stable storage.

db_compress(+DBRef, +DBName)

db_compress(+DBRef, +DBName, +SpecList)

Copies the database given by DBRef to a new database named by DBName. The new database will be a compressed version of the first one in the sense that it will not have “holes” resulting from deletion of terms. Deleted term references will also be reused, which implies that references that refer to terms in the old database will be invalid in the new one.

db_compress/2 looks for a database with the db-spec of the original one. db_compress/3 stores the terms found in the original database with the indexing specification SpecList. db_compress/2 cannot be used if the database DBRef was opened in mode enumerate.

If the database DBName already exists then the terms of DBRef will be appended to it. Of course DBName must have an indexing specification, which enables the terms in DBRef to be inserted into it.

In the case of db_compress/3 if the database DBName does not exist, then SpecList must be a valid indexing specification.

db_make_iterator(+DBRef, -Iterator)

db_make_iterator(+DBRef, +Term, -Iterator)

Creates a new iterator and unifies it with Iterator. Iterators created with db_make_iterator/2 iterate through the whole database. Iterators created with db_make_iterator/3 iterate through the terms that would be found by db_fetch(DBRef, Term, _).

Every iterator created by db_make_iterator/[2,3] must be destroyed with db_iterator_done/1.

db_iterator_next(+Iterator, ?Term, ?TermRef)

Iterator advances to the next term, Term and TermRef is unified with the term and its reference pointed to by Iterator. If there is no next term, the predicate fails.

db_iterator_done(+Iterator)

Deallocates Iterator, which must not be in use anymore.

db_current_iterator(?DBRef, ?Term, ?Iterator)

Unifies the the variables with the respective properties of the living iterators. This predicate can be used to enumerate all currently alive iterators through backtracking. If Iterator was made with db_make_iterator/2 then Term will be left unbound.

db_export(+DBName, +ExportFile)

db_export(+DBName, +Options, +ExportFile)

Exports the database with the name DBName to the text file ExportFile. ExportFile can be imported by db_import/[2,3].

Options should be an options list of the form acceptable by db_open/[4,5].

In SICStus 3.12.0 bdb:export/[2,3] is available instead of db_export/[2,3].

db_import(+DBName, +ImportFile)

db_import(+DBName, +Options, +ImportFile)

Imports the text file ImportFile into the database with the name DBName.

If ImportFile is imported into an existing database, the SpecList found in the ImportFile will be unified with the SpecList in the database.

Options should be an options list of the form acceptable by db_open/[4,5].

In SICStus 3.12.0 bdb:import/[2,3] is available instead of db_import/[2,3].