<!DOCTYPE File PUBLIC "-//Liam Quin//DTD C API Documentation v1.1//EN" "doc.dtd"><File>
<Entry dir="liblqtext">
<Function File="../../src/liblqtext/smalldb.c">
<Name>LQT_OpenKeyValueDatabase</Name>
<Class>Database/Dynamic Hashing, Database/Files
<Purpose>
<P>Opens an ndbm-style database of the given name, creating it if
the current database modes allow it.
The function keeps a cache of open databases, so that if there
is already an open database of the given name, its handle is
simply returned.</P>
<P>Opening a Key Value Database involves several file system
accesses and using malloc to obtain memory, so it's much better
to use the cached values.
It is even better still to keep frequently used Key Value
Databases open, for example in a static variable, and to close
them only when the database is closed.</P>
<Returns>
A handle (usually a DBM * pointer) to the named Key Value Database.
<Errors>
If the underlying ndbm-style database couldn't be opened, a fatal
error is produced (E_FATAL|E_SYS) indicating the problem.
One possible cause of this is that $HOME/LQTEXTDIR isn't a directory,
or doesn't exist, and $LQTEXTDIR isn't set to point to a suitable
alternate directory.
Another possible problem is that a previous run of lqaddfile
failed, and left the Key Value Databases locked for writing; the
best thing to do in this case is to run the lqclean program and
start again.
<SeeAlso>
LQT_CloseKeyValueDatabase
LQT_OpenDatabase
LQT_AddActionOnClose
LQT_SyncDatabase
</Function>
<Decl>
API DBM *
LQT_OpenKeyValueDatabase(db, FilePrefix)
    t_LQTEXT_Database *db;
    char *FilePrefix;
</Decl>
</Entry>
