VILLA(3)                    Quick Database Manager                    VILLA(3)



NAME
       Villa - the advanced API of QDBM


SYNOPSIS
       #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);


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.

       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.


SEE ALSO
       qdbm(3), depot(3), curia(3), relic(3), hovel(3), cabin(3), odeum(3),
       ndbm(3), gdbm(3)



Man Page                          2004-04-22                          VILLA(3)
