NAME
Villa - the advanced API of QDBMSYNOPSIS
#include <depot.h>DESCRIPTION
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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- int vlwritable(VILLA *villa);
- `villa' specifies a database handle. The return value is true if the handle is a writer, false if 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.
- int vlinode(VILLA *villa);
- `villa' specifies a database handle. The return value is the inode number of the database file.
- time_t vlmtime(VILLA *villa);
- `villa' specifies a database handle. The return value is the last modified time of the database.
- 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.
- 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.
- 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.
- int vlremove(const char *name);
- `name' specifies the name of a database file. If successful, the return value is true, else, it is false.
- 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.
- 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.
- 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.
SEE ALSO
qdbm(3), depot(3), curia(3), relic(3), hovel(3), cabin(3), odeum(3), ndbm(3), gdbm(3)| 2004-04-22 | Man Page |