# qdbm::Villa Class Reference

Inheritance diagram for qdbm::Villa:

List of all members.

## Detailed Description

C++ API of Villa, the basic API of QDBM.

## Public Member Functions

| Villa (const char *name, int omode=Villa::OREADER, VLCFUNC cmp=Villa::cmplex) throw (Villa_error)
| Get the database handle.
virtual | ~Villa () throw ()
| Release the resources.
virtual void | close () throw (Villa_error)
| Close the database handle.
virtual void | put (const char *kbuf, int ksiz, const char *vbuf, int vsiz, int dmode=Villa::DOVER) throw (Villa_error)
| Store a record.
virtual void | out (const char *kbuf, int ksiz) throw (Villa_error)
| Delete a record.
virtual char * | get (const char *kbuf, int ksiz, int *sp=0) throw (Villa_error)
| Retrieve a record.
virtual int | vnum (const char *kbuf, int ksiz) throw (Villa_error)
| Get the number of records corresponding a key.
virtual void | curfirst () throw (Villa_error)
| Move the cursor to the first record.
virtual void | curlast () throw (Villa_error)
| Move the cursor to the last record.
virtual void | curprev () throw (Villa_error)
| Move the cursor to the previous record.
virtual void | curnext () throw (Villa_error)
| Move the cursor to the next record.
virtual void | curjump (const char *kbuf, int ksiz, int jmode=Villa::JFORWARD) throw (Villa_error)
| Move the cursor to positon around a record.
virtual char * | curkey (int *sp=0) throw (Villa_error)
| Get the key of the record where the cursor is.
virtual char * | curval (int *sp=0) throw (Villa_error)
| Get the value of the record where the cursor is.
virtual void | settuning (int lrecmax, int nidxmax, int lcnum, int ncnum) throw (Villa_error)
| Set the tuning parameters for performance.
virtual void | sync () throw (Villa_error)
| Synchronize updating contents with the file and the device.
virtual void | optimize () throw (Villa_error)
| Optimize a database.
virtual char * | name () throw (Villa_error)
| Get the name of the database.
virtual int | fsiz () throw (Villa_error)
| Get the size of the database file.
virtual int | lnum () throw (Villa_error)
| Get the number of the leaf nodes of B+ tree.
virtual int | nnum () throw (Villa_error)
| Get the number of the non-leaf nodes of B+ tree.
virtual int | rnum () throw (Villa_error)
| Get the number of the records stored in a database.
virtual bool | writable () throw (Villa_error)
| Check whether the database handle is a writer or not.
virtual bool | fatalerror () throw (Villa_error)
| Check whether the database has a fatal error or not.
virtual int | inode () throw (Villa_error)
| Get the inode number of the database file.
virtual void | tranbegin () throw (Villa_error)
| Begin the transaction.
virtual void | trancommit () throw (Villa_error)
| Commit the transaction.
virtual void | tranabort () throw (Villa_error)
| Abort the transaction.
virtual void | storerec (const Datum &key, const Datum &val, bool replace=true) throw (Villa_error)
| Store a record.
virtual void | deleterec (const Datum &key) throw (Villa_error)
| Delete a record.
virtual Datum | fetchrec (const Datum &key) throw (Villa_error)
| Fetch a record.
virtual Datum | firstkey () throw (Villa_error)
| Get the first key.
virtual Datum | nextkey () throw (Villa_error)
| Get the next key.
virtual bool | error () throw (Villa_error)
| Check whether a fatal error occured or not.

## Static Public Member Functions

const char * | version () throw ()
| Get the version information.
void | remove (const char *name) throw (Villa_error)
| Remove a database directory.
void | econv (const char *name, bool big) throw (Villa_error)
| Convert a database directory for another platform with different byte order.
int | cmplex (const char *aptr, int asiz, const char *bptr, int bsiz) throw ()
| Compare keys of two records by lexical order.
int | cmpint (const char *aptr, int asiz, const char *bptr, int bsiz) throw ()
| Compare keys of two records as integers.
int | cmpnum (const char *aptr, int asiz, const char *bptr, int bsiz) throw ()
| Compare keys of two records as numbers of big endian.
int | cmpdec (const char *aptr, int asiz, const char *bptr, int bsiz) throw ()
| Compare keys of two records as decimal strings.

## Static Public Attributes

const int | ENOERR
| error code: no error
const int | EFATAL
| error code: with fatal error
const int | EMODE
| error code: invalid mode
const int | EBROKEN
| error code: broken database file
const int | EKEEP
| error code: existing record
const int | ENOITEM
| error code: no item found
const int | EALLOC
| error code: memory allocation error
const int | EMAP
| error code: memory mapping error
const int | EOPEN
| error code: open error
const int | ECLOSE
| error code: close error
const int | ETRUNC
| error code: trunc error
const int | ESYNC
| error code: sync error
const int | ESTAT
| error code: stat error
const int | ESEEK
| error code: seek error
const int | EREAD
| error code: read error
const int | EWRITE
| error code: write error
const int | ELOCK
| error code: lock error
const int | EUNLINK
| error code: unlink error
const int | EMKDIR
| error code: mkdir error
const int | ERMDIR
| error code: rmdir error
const int | EMISC
| error code: miscellaneous error
const int | OREADER
| open mode: open as a reader
const int | OWRITER
| open mode: open as a writer
const int | OCREAT
| open mode: writer creating
const int | OTRUNC
| open mode: writer truncating
const int | ONOLCK
| open mode: open without locking
const int | DOVER
| write mode: overwrite the existing value
const int | DKEEP
| write mode: keep the existing value
const int | DDUP
| write mode: concatenate values
const int | JFORWARD
| jump mode: step forward
const int | JBACKWARD
| jump mode: step backward

## Constructor & Destructor Documentation

qdbm::Villa::Villa | ( | const char * | name,
|  | int | omode = Villa::OREADER,
|  | VLCFUNC | cmp = Villa::cmplex
| ) | throw (Villa_error)

Get the database handle.

Parameters:

  name | the name of a database file.

  omode

  the connection mode: `Villa::OWRITER' as a writer, `Villa::OREADER' as a reader. If the mode is `Villa::OWRITER', the following may be added by bitwise or: `Villa::OCREAT', which means it creates a new database if not exist, `Villa::OTRUNC', which means it creates a new database regardless if one exists. Both of `Villa::OREADER' and `Villa::OWRITER' can be added to by bitwise or: `Villa::ONOLCK', which means it opens a database file without file locking.

  cmp

  the comparing function: `Villa::cmplex' comparing keys in lexical order, `Villa::cmpint' comparing keys as objects of `int' in native byte order, `Villa::cmpnum' comparing keys as numbers of big endian, `Villa::cmpdec' comparing keys as decimal strings. Any function compatible with them can be assigned to the comparing function. The comparing function should be kept same in the life of a database.

Exceptions:

  Villa_error | if an error occures.

Note:
  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. If `Villa::ONOLCK' is used, the application is responsible for exclusion control.

virtual qdbm::Villa::~Villa | ( |  | ) | throw ()`[virtual]`

Release the resources.

Note:
  If the database handle is not closed yet, it is closed.

## Member Function Documentation

virtual void qdbm::Villa::close | ( |  | ) | throw (Villa_error)`[virtual]`

Close the database handle.

Exceptions:

  Villa_error | if an error occures.

Note:
  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.

Implements qdbm::ADBM.

int qdbm::Villa::cmpdec | ( | const char * | aptr,
|  | int | asiz,
|  | const char * | bptr,
|  | int | bsiz
| ) | throw ()`[static]`

Compare keys of two records as decimal strings.

Parameters:

  aptr | the pointer to the region of one key.
  asiz | the size of the region of one key.
  bptr | the pointer to the region of the other key.
  bsiz | the size of the region of the other key.

Returns:
  positive if the former is big, negative if the latter is big, 0 if both are equivalent.

int qdbm::Villa::cmpint | ( | const char * | aptr,
|  | int | asiz,
|  | const char * | bptr,
|  | int | bsiz
| ) | throw ()`[static]`

Compare keys of two records as integers.

Parameters:

  aptr | the pointer to the region of one key.
  asiz | the size of the region of one key.
  bptr | the pointer to the region of the other key.
  bsiz | the size of the region of the other key.

Returns:
  positive if the former is big, negative if the latter is big, 0 if both are equivalent.

int qdbm::Villa::cmplex | ( | const char * | aptr,
|  | int | asiz,
|  | const char * | bptr,
|  | int | bsiz
| ) | throw ()`[static]`

Compare keys of two records by lexical order.

Parameters:

  aptr | the pointer to the region of one key.
  asiz | the size of the region of one key.
  bptr | the pointer to the region of the other key.
  bsiz | the size of the region of the other key.

Returns:
  positive if the former is big, negative if the latter is big, 0 if both are equivalent.

int qdbm::Villa::cmpnum | ( | const char * | aptr,
|  | int | asiz,
|  | const char * | bptr,
|  | int | bsiz
| ) | throw ()`[static]`

Compare keys of two records as numbers of big endian.

Parameters:

  aptr | the pointer to the region of one key.
  asiz | the size of the region of one key.
  bptr | the pointer to the region of the other key.
  bsiz | the size of the region of the other key.

Returns:
  positive if the former is big, negative if the latter is big, 0 if both are equivalent.

virtual void qdbm::Villa::curfirst | ( |  | ) | throw (Villa_error)`[virtual]`

Move the cursor to the first record.

Exceptions:

  Villa_error | if an error occures or there is no record in the database.

virtual void qdbm::Villa::curjump | ( | const char * | kbuf,
|  | int | ksiz,
|  | int | jmode = Villa::JFORWARD
| ) | throw (Villa_error)`[virtual]`

Move the cursor to positon around a record.

Parameters:

  kbuf | the pointer to the region of a key.
  ksiz | the size of the region of the key. If it is negative, the size is assigned with `std::strlen(kbuf)'.

  jmode

  detail adjustment: `Villa::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, `Villa::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.

Exceptions:

  Villa_error | if an error occures or there is no record corresponding the condition.

virtual char* qdbm::Villa::curkey | ( | int * | sp = 0 | ) | throw (Villa_error)`[virtual]`

Get the key of the record where the cursor is.

Parameters:

  sp | the pointer to a variable to which the size of the region of the return value is assigned. If it is 0, it is not used.

Returns:
  the pointer to the region of the key of the corresponding record.

Exceptions:

  Villa_error | if an error occures or no record corresponds to the cursor.

Note:
  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 `std::malloc' call, it should be released with the `std::free' call if it is no longer in use.

virtual void qdbm::Villa::curlast | ( |  | ) | throw (Villa_error)`[virtual]`

Move the cursor to the last record.

Exceptions:

  Villa_error | if an error occures or there is no record in the database.

virtual void qdbm::Villa::curnext | ( |  | ) | throw (Villa_error)`[virtual]`

Move the cursor to the next record.

Exceptions:

  Villa_error | if an error occures or there is no next record.

virtual void qdbm::Villa::curprev | ( |  | ) | throw (Villa_error)`[virtual]`

Move the cursor to the previous record.

Exceptions:

  Villa_error | if an error occures or there is no previous record.

virtual char* qdbm::Villa::curval | ( | int * | sp = 0 | ) | throw (Villa_error)`[virtual]`

Get the value of the record where the cursor is.

Parameters:

  sp | the pointer to a variable to which the size of the region of the return value is assigned. If it is 0, it is not used.

Returns:
  the pointer to the region of the value of the corresponding record.

Exceptions:

  Villa_error | if an error occures or no record corresponds to the cursor.

Note:
  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 `std::malloc' call, it should be released with the `std::free' call if it is no longer in use.

virtual void qdbm::Villa::deleterec | ( | const Datum & | key | ) | throw (Villa_error)`[virtual]`

Delete a record.

Parameters:

  key | reference to a key object.

Exceptions:

  Villa_error | if an error occures or no record corresponds.

Implements qdbm::ADBM.

void qdbm::Villa::econv | ( | const char * | name,
|  | bool | big
| ) | throw (Villa_error)`[static]`

Convert a database directory for another platform with different byte order.

Parameters:

  name | the name of a database directory.
  big | whether the result is for big endian or not.

Exceptions:

  Villa_error | if an error occures.

virtual bool qdbm::Villa::error | ( |  | ) | throw (Villa_error)`[virtual]`

Check whether a fatal error occured or not.

Returns:
  true if the database has a fatal error, false if not.

Exceptions:

  Villa_error | if an error occures.

Implements qdbm::ADBM.

virtual bool qdbm::Villa::fatalerror | ( |  | ) | throw (Villa_error)`[virtual]`

Check whether the database has a fatal error or not.

Returns:
  true if the database has a fatal error, false if not.

Exceptions:

  Villa_error | if an error occures.

virtual Datum qdbm::Villa::fetchrec | ( | const Datum & | key | ) | throw (Villa_error)`[virtual]`

Fetch a record.

Parameters:

  key | reference to a key object.

Returns:
  a temporary instance of the value of the corresponding record.

Exceptions:

  Villa_error | if an error occures or no record corresponds.

Implements qdbm::ADBM.

virtual Datum qdbm::Villa::firstkey | ( |  | ) | throw (Villa_error)`[virtual]`

Get the first key.

Returns:
  a temporary instance of the key of the first record.

Exceptions:

  Villa_error | if an error occures or no record corresponds.

Implements qdbm::ADBM.

virtual int qdbm::Villa::fsiz | ( |  | ) | throw (Villa_error)`[virtual]`

Get the size of the database file.

Returns:
  the size of the database file.

Exceptions:

  Villa_error | if an error occures.

Note:
  Because of the I/O buffer, the return value may be less than the real size.

virtual char* qdbm::Villa::get | ( | const char * | kbuf,
|  | int | ksiz,
|  | int * | sp = 0
| ) | throw (Villa_error)`[virtual]`

Retrieve a record.

Parameters:

  kbuf | the pointer to the region of a key.
  ksiz | the size of the region of the key. If it is negative, the size is assigned with `std::strlen(kbuf)'.
  sp | the pointer to a variable to which the size of the region of the return value is assigned. If it is 0, it is not used.

Returns:
  the pointer to the region of the value of the corresponding record.

Exceptions:

  Villa_error | if an error occures or no record corresponds.

Note:
  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 `std::malloc' call, it should be released with the `std::free' call if it is no longer in use.

virtual int qdbm::Villa::inode | ( |  | ) | throw (Villa_error)`[virtual]`

Get the inode number of the database file.

Returns:
  the inode number of the database file.

Exceptions:

  Villa_error | if an error occures.

virtual int qdbm::Villa::lnum | ( |  | ) | throw (Villa_error)`[virtual]`

Get the number of the leaf nodes of B+ tree.

Returns:
  the number of the leaf nodes.

Exceptions:

  Villa_error | if an error occures.

virtual char* qdbm::Villa::name | ( |  | ) | throw (Villa_error)`[virtual]`

Get the name of the database.

Returns:
  the pointer to the region of the name of the database.

Exceptions:

  Villa_error | if an error occures.

Note:
  Because the region of the return value is allocated with the `std::malloc' call, it should be released with the `std::free' call if it is no longer in use.

virtual Datum qdbm::Villa::nextkey | ( |  | ) | throw (Villa_error)`[virtual]`

Get the next key.

Returns:
  a temporary instance of the key of the next record.

Exceptions:

  Villa_error | if an error occures or no record corresponds.

Implements qdbm::ADBM.

virtual int qdbm::Villa::nnum | ( |  | ) | throw (Villa_error)`[virtual]`

Get the number of the non-leaf nodes of B+ tree.

Returns:
  the number of the non-leaf nodes.

Exceptions:

  Villa_error | if an error occures.

virtual void qdbm::Villa::optimize | ( |  | ) | throw (Villa_error)`[virtual]`

Optimize a database.

Exceptions:

  Villa_error | if an error occures.

Note:
  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 shuold not be used while the transaction is activated.

virtual void qdbm::Villa::out | ( | const char * | kbuf,
|  | int | ksiz
| ) | throw (Villa_error)`[virtual]`

Delete a record.

Parameters:

  kbuf | the pointer to the region of a key.
  ksiz | the size of the region of the key. If it is negative, the size is assigned with `std::strlen(kbuf)'.

Exceptions:

  Villa_error | if an error occures or no record corresponds.

Note:
  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.

virtual void qdbm::Villa::put | ( | const char * | kbuf,
|  | int | ksiz,
|  | const char * | vbuf,
|  | int | vsiz,
|  | int | dmode = Villa::DOVER
| ) | throw (Villa_error)`[virtual]`

Store a record.

Parameters:

  kbuf | the pointer to the region of a key.
  ksiz | the size of the region of the key. If it is negative, the size is assigned with `std::strlen(kbuf)'.
  vbuf | the pointer to the region of a value.
  vsiz | the size of the region of the value. If it is negative, the size is assigned with `std::strlen(vbuf)'.
  dmode | behavior when the key overlaps, by the following values: `Villa::DOVER', which means the specified value overwrites the existing one, `Villa::DKEEP', which means the existing value is kept, `Villa::DDUP', which means duplication of keys is allowed.

Exceptions:

  Villa_error | if an error occures or replace is cancelled.

Note:
  A duplicated record is stored at the tail of the records of the same key. The cursor becomes unavailable due to updating database.

void qdbm::Villa::remove | ( | const char * | name | ) | throw (Villa_error)`[static]`

Remove a database directory.

Parameters:

  name | the name of a database directory.

Exceptions:

  Villa_error | if an error occures.

virtual int qdbm::Villa::rnum | ( |  | ) | throw (Villa_error)`[virtual]`

Get the number of the records stored in a database.

Returns:
  the number of the records stored in the database.

Exceptions:

  Villa_error | if an error occures.

virtual void qdbm::Villa::settuning | ( | int | lrecmax,
|  | int | nidxmax,
|  | int | lcnum,
|  | int | ncnum
| ) | throw (Villa_error)`[virtual]`

Set the tuning parameters for performance.

Parameters:

  lrecmax | 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 | 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 | the max number of caching leaf nodes. If it is not more than 0, the default value is specified.
  ncnum | the max number of caching non-leaf nodes. If it is not more than 0, the default value is specified.

Exceptions:

  Villa_error | if an error occures.

Note:
  The default setting is equivalent to `settuning(49, 192, 1024, 512)'. Because tuning paremeters are not saved in a database, you should specify them every opening a database.

virtual void qdbm::Villa::storerec | ( | const Datum & | key,
|  | const Datum & | val,
|  | bool | replace = true
| ) | throw (Villa_error)`[virtual]`

Store a record.

Parameters:

  key | reference to a key object.
  val | reference to a value object.
  replace | whether the existing value is to be overwritten or not.

Exceptions:

  Villa_error | if an error occures or replace is cancelled.

Implements qdbm::ADBM.

virtual void qdbm::Villa::sync | ( |  | ) | throw (Villa_error)`[virtual]`

Synchronize updating contents with the file and the device.

Exceptions:

  Villa_error | if an error occures.

Note:
  This function is useful when another process uses the connected database file. This function shuold not be used while the transaction is activated.

virtual void qdbm::Villa::tranabort | ( |  | ) | throw (Villa_error)`[virtual]`

Abort the transaction.

Exceptions:

  Villa_error | if an error occures.

Note:
  Updating a database in the transaction is discarded when it is aborted. The state of the database is rollbacked to before transaction. Any other thread except for the one which began the transaction should not call this function.

virtual void qdbm::Villa::tranbegin | ( |  | ) | throw (Villa_error)`[virtual]`

Begin the transaction.

Exceptions:

  Villa_error | if an error occures.

Note:
  If a thread is already in the transaction, the other threads block until the prius is out of the transaction. Only one transaction can be activated with a database handle at the same time.

virtual void qdbm::Villa::trancommit | ( |  | ) | throw (Villa_error)`[virtual]`

Commit the transaction.

Exceptions:

  Villa_error | if an error occures.

Note:
  Updating a database in the transaction is fixed when it is committed successfully. Any other thread except for the one which began the transaction should not call this function.

const char* qdbm::Villa::version | ( |  | ) | throw ()`[static]`

Get the version information.

Returns:
  the string of the version information.

virtual int qdbm::Villa::vnum | ( | const char * | kbuf,
|  | int | ksiz
| ) | throw (Villa_error)`[virtual]`

Get the number of records corresponding a key.

Parameters:

  kbuf | the pointer to the region of a key.
  ksiz | the size of the region of the key. If it is negative, the size is assigned with `std::strlen(kbuf)'.

Returns:
  the number of corresponding records. If no record corresponds, 0 is returned.

Exceptions:

  Villa_error | if an error occures.

virtual bool qdbm::Villa::writable | ( |  | ) | throw (Villa_error)`[virtual]`

Check whether the database handle is a writer or not.

Returns:
  true if the handle is a writer, false if not.

Exceptions:

  Villa_error | if an error occures.

The documentation for this class was generated from the following file:

- xvilla.h