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.
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.
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_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_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_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_sync(+DBRef)Flushes any cached information from the database referenced by DBRef to stable storage.
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 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].