Villa - the advanced API of QDBM
#include <depot.h>
#include <cabin.h>
#include <villa.h>
#include <stdlib.h>
typedef int(*VLCFUNC)(const char *aptr, int asiz, const char
*bptr, int bsiz);
VILLA *vlopen(const char *name, int omode, VLCFUNC
cmp);
int vlclose(VILLA *villa);
int vlput(VILLA *villa, const char *kbuf, int ksiz, const char
*vbuf, int vsiz, int dmode);
int vlout(VILLA *villa, const char *kbuf, int ksiz);
char *vlget(VILLA *villa, const char *kbuf, int ksiz, int
*sp);
int vlvsiz(VILLA *villa, const char *kbuf, int ksiz);
int vlvnum(VILLA *villa, const char *kbuf, int ksiz);
int vlputlist(VILLA *villa, const char *kbuf, int ksiz, const
CBLIST *vals);
int vloutlist(VILLA *villa, const char *kbuf, int
ksiz);
CBLIST *vlgetlist(VILLA *villa, const char *kbuf, int
ksiz);
char *vlgetcat(VILLA *villa, const char *kbuf, int ksiz, int
*sp);
int vlcurfirst(VILLA *villa);
int vlcurlast(VILLA *villa);
int vlcurprev(VILLA *villa);
int vlcurnext(VILLA *villa);
int vlcurjump(VILLA *villa, const char *kbuf, int ksiz, int
jmode);
char *vlcurkey(VILLA *villa, int *sp);
char *vlcurval(VILLA *villa, int *sp);
int vlcurput(VILLA *villa, const char *vbuf, int vsiz, int
cpmode);
int vlcurout(VILLA *villa);
void vlsettuning(VILLA *villa, int lrecmax, int nidxmax, int
lcnum, int ncnum);
int vlsetfbpsiz(VILLA *villa, int size);
int vlsync(VILLA *villa);
int vloptimize(VILLA *villa);
char *vlname(VILLA *villa);
int vlfsiz(VILLA *villa);
int vllnum(VILLA *villa);
int vlnnum(VILLA *villa);
int vlrnum(VILLA *villa);
int vlwritable(VILLA *villa);
int vlfatalerror(VILLA *villa);
int vlinode(VILLA *villa);
time_t vlmtime(VILLA *villa);
int vltranbegin(VILLA *villa);
int vltrancommit(VILLA *villa);
int vltranabort(VILLA *villa);
int vlremove(const char *name);
int vlrepair(const char *name, VLCFUNC cmp);
int vlexportdb(VILLA *villa, const char *name);
int vlimportdb(VILLA *villa, const char *name);
Villa is the advanced API of QDBM. It provides routines for
managing a database file of B+ tree. Each record is stored being sorted in
order defined by a user. As for hash databases, retrieving method is
provided only as complete accord. However, with Villa, it is possible to
retrieve records specified by range. Cursor is used in order to access each
record in order. It is possible to store records duplicating keys in a
database. Moreover, according to the transaction mechanism, you can commit
or abort operations of a database in a lump.
Villa is implemented, based on Depot and Cabin. A database file of
Villa is actual one of Depot. Although processing speed of retrieving and
storing is slower than Depot, the size of a database is smaller.
In order to use Villa, you should include `depot.h', `cabin.h',
`villa.h' and `stdlib.h' in the source files. Usually, the following
description will be near the beginning of a source file.
#include <depot.h>
#include <cabin.h>
#include <villa.h>
#include <stdlib.h>
A pointer to `VILLA' is used as a database handle. It is like that
some file I/O routines of `stdio.h' use a pointer to `FILE'. A database
handle is opened with the function `vlopen' and closed with `vlclose'. You
should not refer directly to any member of the handle. If a fatal error
occurs in a database, any access method via the handle except `vlclose' will
not work and return error status. Although a process is allowed to use
multiple database handles at the same time, handles of the same database
file should not be used. Before the cursor is used, it should be initialized
by one of `vlcurfirst', `vlcurlast' or `vlcurjump'. Also after storing or
deleting a record with functions except for `vlcurput' and `vlcurout', the
cursor should be initialized.
Villa also assign the external variable `dpecode' with the error
code. The function `dperrmsg' is used in order to get the message of the
error code.
You can define a comparing function to specify the order of
records. The function should be the following type.
- typedef
int(*VLCFUNC)(const char *aptr, int asiz, const char *bptr, int
bsiz);
- `aptr' specifies the pointer to the region of one key. `asiz' specifies
the size of the region of one key. `bptr' specifies the pointer to the
region of the other key. `bsiz' specifies the size of the region of the
other key. The return value is positive if the former is big, negative if
the latter is big, 0 if both are equivalent.
The function `vlopen' is used in order to get a database
handle.
- VILLA *vlopen(const char
*name, int omode, VLCFUNC cmp);
- `name' specifies the name of a database file. `omode' specifies the
connection mode: `VL_OWRITER' as a writer, `VL_OREADER' as a reader. If
the mode is `VL_OWRITER', the following may be added by bitwise or:
`VL_OCREAT', which means it creates a new database if not exist,
`VL_OTRUNC', which means it creates a new database regardless if one
exists, `VL_OZCOMP', which means leaves in the database are compressed,
`VL_OYCOMP', which means leaves in the database are compressed with LZO,
`VL_OXCOMP', which means leaves in the database are compressed with BZIP2.
Both of `VL_OREADER' and `VL_OWRITER' can be added to by bitwise or:
`VL_ONOLCK', which means it opens a database file without file locking, or
`VL_OLCKNB', which means locking is performed without blocking. `cmp'
specifies the comparing function: `VL_CMPLEX' comparing keys in lexical
order, `VL_CMPINT' comparing keys as objects of `int' in native byte
order, `VL_CMPNUM' comparing keys as numbers of big endian, `VL_CMPDEC'
comparing keys as decimal strings. Any function based on the declaration
of the type `VLCFUNC' can be assigned to the comparing function. The
comparing function should be kept same in the life of a database. The
return value is the database handle or `NULL' if it is not successful.
While connecting as a writer, an exclusive lock is invoked to the database
file. While connecting as a reader, a shared lock is invoked to the
database file. The thread blocks until the lock is achieved. `VL_OZCOMP',
`VL_OYCOMP', and `VL_OXCOMP' are available only if QDBM was built each
with ZLIB, LZO, and BZIP2 enabled. If `VL_ONOLCK' is used, the application
is responsible for exclusion control.
The function `vlclose' is used in order to close a database
handle.
- int vlclose(VILLA
*villa);
- `villa' specifies a database handle. If successful, the return value is
true, else, it is false. Because the region of a closed handle is
released, it becomes impossible to use the handle. Updating a database is
assured to be written when the handle is closed. If a writer opens a
database but does not close it appropriately, the database will be broken.
If the transaction is activated and not committed, it is aborted.
The function `vlput' is used in order to store a record.
- int vlput(VILLA *villa,
const char *kbuf, int ksiz, const char *vbuf, int vsiz, int
dmode);
- `villa' specifies a database handle connected as a writer. `kbuf'
specifies the pointer to the region of a key. `ksiz' specifies the size of
the region of the key. If it is negative, the size is assigned with
`strlen(kbuf)'. `vbuf' specifies the pointer to the region of a value.
`vsiz' specifies the size of the region of the value. If it is negative,
the size is assigned with `strlen(vbuf)'. `dmode' specifies behavior when
the key overlaps, by the following values: `VL_DOVER', which means the
specified value overwrites the existing one, `VL_DKEEP', which means the
existing value is kept, `VL_DCAT', which means the specified value is
concatenated at the end of the existing value, `VL_DDUP', which means
duplication of keys is allowed and the specified value is added as the
last one, `VL_DDUPR', which means duplication of keys is allowed and the
specified value is added as the first one. If successful, the return value
is true, else, it is false. The cursor becomes unavailable due to updating
database.
The function `vlout' is used in order to delete a record.
- int vlout(VILLA *villa,
const char *kbuf, int ksiz);
- `villa' specifies a database handle connected as a writer. `kbuf'
specifies the pointer to the region of a key. `ksiz' specifies the size of
the region of the key. If it is negative, the size is assigned with
`strlen(kbuf)'. If successful, the return value is true, else, it is
false. False is returned when no record corresponds to the specified key.
When the key of duplicated records is specified, the first record of the
same key is deleted. The cursor becomes unavailable due to updating
database.
The function `vlget' is used in order to retrieve a record.
- char *vlget(VILLA *villa,
const char *kbuf, int ksiz, int *sp);
- `villa' specifies a database handle. `kbuf' specifies the pointer to the
region of a key. `ksiz' specifies the size of the region of the key. If it
is negative, the size is assigned with `strlen(kbuf)'. `sp' specifies the
pointer to a variable to which the size of the region of the return value
is assigned. If it is `NULL', it is not used. If successful, the return
value is the pointer to the region of the value of the corresponding
record, else, it is `NULL'. `NULL' is returned when no record corresponds
to the specified key. When the key of duplicated records is specified, the
value of the first record of the same key is selected. Because an
additional zero code is appended at the end of the region of the return
value, the return value can be treated as a character string. Because the
region of the return value is allocated with the `malloc' call, it should
be released with the `free' call if it is no longer in use.
The function `vlvsiz' is used in order to get the size of the
value of a record.
- int vlvsiz(VILLA *villa,
const char *kbuf, int ksiz);
- `villa' specifies a database handle. `kbuf' specifies the pointer to the
region of a key. `ksiz' specifies the size of the region of the key. If it
is negative, the size is assigned with `strlen(kbuf)'. If successful, the
return value is the size of the value of the corresponding record, else,
it is -1. If multiple records correspond, the size of the first is
returned.
The function `vlvnum' is used in order to get the number of
records corresponding a key.
- int vlvnum(VILLA *villa,
const char *kbuf, int ksiz);
- `villa' specifies a database handle. `kbuf' specifies the pointer to the
region of a key. `ksiz' specifies the size of the region of the key. If it
is negative, the size is assigned with `strlen(kbuf)'. The return value is
the number of corresponding records. If no record corresponds, 0 is
returned.
The function `vlputlist' is used in order to store plural records
corresponding a key.
- int vlputlist(VILLA
*villa, const char *kbuf, int ksiz, const CBLIST *vals);
- `villa' specifies a database handle connected as a writer. `kbuf'
specifies the pointer to the region of a key. `ksiz' specifies the size of
the region of the key. If it is negative, the size is assigned with
`strlen(kbuf)'. `vals' specifies a list handle of values. The list should
not be empty. If successful, the return value is true, else, it is false.
The cursor becomes unavailable due to updating database.
The function `vloutlist' is used in order to delete all records
corresponding a key.
- int vloutlist(VILLA
*villa, const char *kbuf, int ksiz);
- `villa' specifies a database handle connected as a writer. `kbuf'
specifies the pointer to the region of a key. `ksiz' specifies the size of
the region of the key. If it is negative, the size is assigned with
`strlen(kbuf)'. If successful, the return value is true, else, it is
false. False is returned when no record corresponds to the specified key.
The cursor becomes unavailable due to updating database.
The function `vlgetlist' is used in order to retrieve values of
all records corresponding a key.
- CBLIST *vlgetlist(VILLA
*villa, const char *kbuf, int ksiz);
- `villa' specifies a database handle. `kbuf' specifies the pointer to the
region of a key. `ksiz' specifies the size of the region of the key. If it
is negative, the size is assigned with `strlen(kbuf)'. If successful, the
return value is a list handle of the values of the corresponding records,
else, it is `NULL'. `NULL' is returned when no record corresponds to the
specified key. Because the handle of the return value is opened with the
function `cblistopen', it should be closed with the function `cblistclose'
if it is no longer in use.
The function `vlgetcat' is used in order to retrieve concatenated
values of all records corresponding a key.
- char *vlgetcat(VILLA
*villa, const char *kbuf, int ksiz, int *sp);
- `villa' specifies a database handle. `kbuf' specifies the pointer to the
region of a key. `ksiz' specifies the size of the region of the key. If it
is negative, the size is assigned with `strlen(kbuf)'. `sp' specifies the
pointer to a variable to which the size of the region of the return value
is assigned. If it is `NULL', it is not used. If successful, the return
value is the pointer to the region of the concatenated values of the
corresponding record, else, it is `NULL'. `NULL' is returned when no
record corresponds to the specified key. Because an additional zero code
is appended at the end of the region of the return value, the return value
can be treated as a character string. Because the region of the return
value is allocated with the `malloc' call, it should be released with the
`free' call if it is no longer in use.
The function `vlcurfirst' is used in order to move the cursor to
the first record.
- int vlcurfirst(VILLA
*villa);
- `villa' specifies a database handle. If successful, the return value is
true, else, it is false. False is returned if there is no record in the
database.
The function `vlcurlast' is used in order to move the cursor to
the last record.
- int vlcurlast(VILLA
*villa);
- `villa' specifies a database handle. If successful, the return value is
true, else, it is false. False is returned if there is no record in the
database.
The function `vlcurprev' is used in order to move the cursor to
the previous record.
- int vlcurprev(VILLA
*villa);
- `villa' specifies a database handle. If successful, the return value is
true, else, it is false. False is returned if there is no previous
record.
The function `vlcurnext' is used in order to move the cursor to
the next record.
- int vlcurnext(VILLA
*villa);
- `villa' specifies a database handle. If successful, the return value is
true, else, it is false. False is returned if there is no next
record.
The function `vlcurjump' is used in order to move the cursor to a
position around a record.
- int vlcurjump(VILLA
*villa, const char *kbuf, int ksiz, int jmode);
- `villa' specifies a database handle. `kbuf' specifies the pointer to the
region of a key. `ksiz' specifies the size of the region of the key. If it
is negative, the size is assigned with `strlen(kbuf)'. `jmode' specifies
detail adjustment: `VL_JFORWARD', which means that the cursor is set to
the first record of the same key and that the cursor is set to the next
substitute if completely matching record does not exist, `VL_JBACKWARD',
which means that the cursor is set to the last record of the same key and
that the cursor is set to the previous substitute if completely matching
record does not exist. If successful, the return value is true, else, it
is false. False is returned if there is no record corresponding the
condition.
The function `vlcurkey' is used in order to get the key of the
record where the cursor is.
- char *vlcurkey(VILLA
*villa, int *sp);
- `villa' specifies a database handle. `sp' specifies the pointer to a
variable to which the size of the region of the return value is assigned.
If it is `NULL', it is not used. If successful, the return value is the
pointer to the region of the key of the corresponding record, else, it is
`NULL'. `NULL' is returned when no record corresponds to the cursor.
Because an additional zero code is appended at the end of the region of
the return value, the return value can be treated as a character string.
Because the region of the return value is allocated with the `malloc'
call, it should be released with the `free' call if it is no longer in
use.
The function `vlcurval' is used in order to get the value of the
record where the cursor is.
- char *vlcurval(VILLA
*villa, int *sp);
- `villa' specifies a database handle. `sp' specifies the pointer to a
variable to which the size of the region of the return value assigned. If
it is `NULL', it is not used. If successful, the return value is the
pointer to the region of the value of the corresponding record, else, it
is `NULL'. `NULL' is returned when no record corresponds to the cursor.
Because an additional zero code is appended at the end of the region of
the return value, the return value can be treated as a character string.
Because the region of the return value is allocated with the `malloc'
call, it should be released with the `free' call if it is no longer in
use.
The function `vlcurput' is used in order to insert a record around
the cursor.
- int vlcurput(VILLA
*villa, const char *vbuf, int vsiz, int cpmode);
- `villa' specifies a database handle connected as a writer. `vbuf'
specifies the pointer to the region of a value. `vsiz' specifies the size
of the region of the value. If it is negative, the size is assigned with
`strlen(vbuf)'. `cpmode' specifies detail adjustment: `VL_CPCURRENT',
which means that the value of the current record is overwritten,
`VL_CPBEFORE', which means that a new record is inserted before the
current record, `VL_CPAFTER', which means that a new record is inserted
after the current record. If successful, the return value is true, else,
it is false. False is returned when no record corresponds to the cursor.
After insertion, the cursor is moved to the inserted record.
The function `vlcurout' is used in order to delete the record
where the cursor is.
- int vlcurout(VILLA
*villa);
- `villa' specifies a database handle connected as a writer. If successful,
the return value is true, else, it is false. False is returned when no
record corresponds to the cursor. After deletion, the cursor is moved to
the next record if possible.
The function `vlsettuning' is used in order to set the tuning
parameters for performance.
- void vlsettuning(VILLA
*villa, int lrecmax, int nidxmax, int lcnum, int ncnum);
- `villa' specifies a database handle. `lrecmax' specifies the max number of
records in a leaf node of B+ tree. If it is not more than 0, the default
value is specified. `nidxmax' specifies the max number of indexes in a
non-leaf node of B+ tree. If it is not more than 0, the default value is
specified. `lcnum' specifies the max number of caching leaf nodes. If it
is not more than 0, the default value is specified. `ncnum' specifies the
max number of caching non-leaf nodes. If it is not more than 0, the
default value is specified. The default setting is equivalent to
`vlsettuning(49, 192, 1024, 512)'. Because tuning parameters are not saved
in a database, you should specify them every opening a database.
The function `vlsetfbpsiz' is used in order to set the size of the
free block pool of a database handle.
- int vlsetfbpsiz(VILLA
*villa, int size);
- `villa' specifies a database handle connected as a writer. `size'
specifies the size of the free block pool of a database. If successful,
the return value is true, else, it is false. The default size of the free
block pool is 256. If the size is greater, the space efficiency of
overwriting values is improved with the time efficiency sacrificed.
The function `vlsync' is used in order to synchronize updating
contents with the file and the device.
- int vlsync(VILLA
*villa);
- `villa' specifies a database handle connected as a writer. If successful,
the return value is true, else, it is false. This function is useful when
another process uses the connected database file. This function should not
be used while the transaction is activated.
The function `vloptimize' is used in order to optimize a
database.
- int vloptimize(VILLA
*villa);
- `villa' specifies a database handle connected as a writer. If successful,
the return value is true, else, it is false. In an alternating succession
of deleting and storing with overwrite or concatenate, dispensable regions
accumulate. This function is useful to do away with them. This function
should not be used while the transaction is activated.
The function `vlname' is used in order to get the name of a
database.
- char *vlname(VILLA
*villa);
- `villa' specifies a database handle. If successful, the return value is
the pointer to the region of the name of the database, else, it is `NULL'.
Because the region of the return value is allocated with the `malloc'
call, it should be released with the `free' call if it is no longer in
use.
The function `vlfsiz' is used in order to get the size of a
database file.
- int vlfsiz(VILLA
*villa);
- `villa' specifies a database handle. If successful, the return value is
the size of the database file, else, it is -1. Because of the I/O buffer,
the return value may be less than the hard size.
The function `vllnum' is used in order to get the number of the
leaf nodes of B+ tree.
- int vllnum(VILLA
*villa);
- `villa' specifies a database handle. If successful, the return value is
the number of the leaf nodes, else, it is -1.
The function `vlnnum' is used in order to get the number of the
non-leaf nodes of B+ tree.
- int vlnnum(VILLA
*villa);
- `villa' specifies a database handle. If successful, the return value is
the number of the non-leaf nodes, else, it is -1.
The function `vlrnum' is used in order to get the number of the
records stored in a database.
- int vlrnum(VILLA
*villa);
- `villa' specifies a database handle. If successful, the return value is
the number of the records stored in the database, else, it is -1.
The function `vlwritable' is used in order to check whether a
database handle is a writer or not.
- int vlwritable(VILLA
*villa);
- `villa' specifies a database handle. The return value is true if the
handle is a writer, false if not.
The function `vlfatalerror' is used in order to check whether a
database has a fatal error or not.
- int vlfatalerror(VILLA
*villa);
- `villa' specifies a database handle. The return value is true if the
database has a fatal error, false if not.
The function `vlinode' is used in order to get the inode number of
a database file.
- int vlinode(VILLA
*villa);
- `villa' specifies a database handle. The return value is the inode number
of the database file.
The function `vlmtime' is used in order to get the last modified
time of a database.
- time_t vlmtime(VILLA
*villa);
- `villa' specifies a database handle. The return value is the last modified
time of the database.
The function `vltranbegin' is used in order to begin the
transaction.
- int vltranbegin(VILLA
*villa);
- `villa' specifies a database handle connected as a writer. If successful,
the return value is true, else, it is false. Because this function does
not perform mutual exclusion control in multi-thread, the application is
responsible for it. Only one transaction can be activated with a database
handle at the same time.
The function `vltrancommit' is used in order to commit the
transaction.
- int vltrancommit(VILLA
*villa);
- `villa' specifies a database handle connected as a writer. If successful,
the return value is true, else, it is false. Updating a database in the
transaction is fixed when it is committed successfully.
The function `vltranabort' is used in order to abort the
transaction.
- int vltranabort(VILLA
*villa);
- `villa' specifies a database handle connected as a writer. If successful,
the return value is true, else, it is false. Updating a database in the
transaction is discarded when it is aborted. The state of the database is
rollbacked to before transaction.
The function `vlremove' is used in order to remove a database
file.
- int vlremove(const char
*name);
- `name' specifies the name of a database file. If successful, the return
value is true, else, it is false.
The function `vlrepair' is used in order to repair a broken
database file.
- int vlrepair(const char
*name, VLCFUNC cmp);
- `name' specifies the name of a database file. `cmp' specifies the
comparing function of the database file. If successful, the return value
is true, else, it is false. There is no guarantee that all records in a
repaired database file correspond to the original or expected state.
The function `vlexportdb' is used in order to dump all records as
endian independent data.
- int vlexportdb(VILLA
*villa, const char *name);
- `villa' specifies a database handle. `name' specifies the name of an
output file. If successful, the return value is true, else, it is
false.
The function `vlimportdb' is used in order to load all records
from endian independent data.
- int vlimportdb(VILLA
*villa, const char *name);
- `villa' specifies a database handle connected as a writer. The database of
the handle must be empty. `name' specifies the name of an input file. If
successful, the return value is true, else, it is false.
If QDBM was built with POSIX thread enabled, the global variable
`dpecode' is treated as thread specific data, and functions of Villa are
reentrant. In that case, they are thread-safe as long as a handle is not
accessed by threads at the same time, on the assumption that `errno',
`malloc', and so on are thread-safe.
Vista is the extended API of Villa. To compensate for the defect
that Villa can not handle a file whose size is more than 2GB, Vista does not
use Depot but Curia for handling its internal database. While Vista provides
data structure and operations of B+ tree as with Villa, its database is
realized as a directory.
In order to use Vista, you should include `vista.h' instead of
`villa.h'. Because Vista is implemented by overriding symbols of Villa, it
can be used as with Villa. That is, Signatures of Villa and Vista is all the
same. However, as its adverse effect, modules using Vista can not use Depot
nor Villa.