<!DOCTYPE File PUBLIC "-//Liam Quin//DTD C API Documentation v1.1//EN" "doc.dtd"><File>
<Entry dir="liblqtext">
<Function File="../../src/liblqtext/close.c">
<Name>LQT_AddActionOnClose</Name>
<Class>Database/Database
<Purpose>
<P>The given Action function will be called whenever LQT_CloseDatabase
or LQT_SyncDatabase is called.</P>
<P>The string Description is used in trace and debugging messages, and
also in error messages; it should be a human-readable description of
the action that the function is performing, or it could be
an ASCII string containing the name of the function.  The Description
string is not copied; a pointer to it is retained.  Therefore, it is
an error to free it after calling LQT_AddActionOnClose.</P>
<P>The given Flags argument may be any combination of
LQT_ON_SYNC and LQT_ON_CLOSE using bitwise or.
If the LQT_ON_SYNC flag is given, the given Action is called by
LQT_SyncDatabase; if LQT_ON_CLOSE is given, the given Action is
called by LQT_CloseDatabase.
It is unusual to have an action for the Sync case and not for the
Close case, but it is not forbidden.</P>
<P>You can register any number of functions in this way.
The most recently registered function is called first, and so on.</P>
<P>LQT_OpenDatabase uses this function to register the following
functions, in order, so that LQT_FlushBlockCache is called last:
<LIST><LI>LQT_FlushBlockCache (Write out cached low-level
data blocks);</LI>
<LI>LQT_WriteCurrentMaxWID (Write out largest allocated WID);</LI>
<LI>LQTpFlushWIDCache (Write out cached WID index blocks);</LI>
<LI>LQTp_FlushLastBlockCache (Write out cached lastblock data);</LI>
<LI>LQT_SyncAndCloseAllKeyValueDatabases (Flush and close all open
Dynamic Hashing (ndbm) key-value databases)</LI></LIST>
<P>You can see these called by running a client with the Debug
trace flag set (e.g. lqwordlist -t Debug).</P>
<Notes>
<P>The list of functions registered may change between revisions of
lq-text, and is given here for illustrative purposes.</P>
<SeeAlso>
LQT_OpenDatabase
LQT_CloseDatabase
LQT_OpenKeyValueDatabase
</Function>
<Decl>
API void
LQT_AddActionOnClose(db, Description, Action, Flags)
    t_LQTEXT_Database *db;
    char *Description;
    int (* Action)(
#ifdef HAVE_PROTO
	t_LQTEXT_Database *
# endif
    );
    unsigned int Flags;
</Decl>
</Entry>
