# qdbm::Curia Class Reference

Inheritance diagram for qdbm::Curia:

List of all members.

## Detailed Description

C++ API of Curia, the extended API of QDBM.

## Public Member Functions

| Curia (const char *name, int omode=Curia::OREADER, int bnum=-1, int dnum=-1) throw (Curia_error)
| Get the database handle.
virtual | ~Curia () throw ()
| Release the resources.
virtual void | close () throw (Curia_error)
| Close the database handle.
virtual void | put (const char *kbuf, int ksiz, const char *vbuf, int vsiz, int dmode=Curia::DOVER) throw (Curia_error)
| Store a record.
virtual void | out (const char *kbuf, int ksiz) throw (Curia_error)
| Delete a record.
virtual char * | get (const char *kbuf, int ksiz, int start=0, int max=-1, int *sp=0) throw (Curia_error)
| Retrieve a record.
virtual int | vsiz (const char *kbuf, int ksiz) throw (Curia_error)
| Get the size of the value of a record.
virtual void | iterinit () throw (Curia_error)
| Initialize the iterator of the database handle.
virtual char * | iternext (int *sp=0) throw (Curia_error)
| Get the next key of the iterator.
virtual void | setalign (int align) throw (Curia_error)
| Set alignment of the database handle.
virtual void | sync () throw (Curia_error)
| Synchronize updating contents with the files and the devices.
virtual void | optimize (int bnum=-1) throw (Curia_error)
| Optimize the database.
virtual char * | name () throw (Curia_error)
| Get the name of the database.
virtual int | fsiz () throw (Curia_error)
| Get the total size of database files.
virtual int | bnum () throw (Curia_error)
| Get the total number of the elements of each bucket array.
virtual int | busenum () throw (Curia_error)
| Get the total number of the used elements of each bucket array.
virtual int | rnum () throw (Curia_error)
| Get the number of the records stored in the database.
virtual bool | writable () throw (Curia_error)
| Check whether the database handle is a writer or not.
virtual bool | fatalerror () throw (Curia_error)
| Check whether the database has a fatal error or not.
virtual int | inode () throw (Curia_error)
| Get the inode number of the database directory.
virtual void | putlob (const char *kbuf, int ksiz, const char *vbuf, int vsiz, int dmode=Curia::DOVER) throw (Curia_error)
| Store a large object.
virtual void | outlob (const char *kbuf, int ksiz) throw (Curia_error)
| Delete a large object.
virtual char * | getlob (const char *kbuf, int ksiz, int start=0, int max=-1, int *sp=0) throw (Curia_error)
| Retrieve a large object.
virtual int | vsizlob (const char *kbuf, int ksiz) throw (Curia_error)
| Get the size of the value of a large object.
virtual int | rnumlob () throw (Curia_error)
| Get the number of the large objects stored in the database.
virtual void | storerec (const Datum &key, const Datum &val, bool replace=true) throw (Curia_error)
| Store a record.
virtual void | deleterec (const Datum &key) throw (Curia_error)
| Delete a record.
virtual Datum | fetchrec (const Datum &key) throw (Curia_error)
| Fetch a record.
virtual Datum | firstkey () throw (Curia_error)
| Get the first key.
virtual Datum | nextkey () throw (Curia_error)
| Get the next key.
virtual bool | error () throw (Curia_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 (Curia_error)
| Remove a database directory.
void | econv (const char *name, bool big) throw (Curia_error)
| Convert a database directory for another platform with different byte order.

## 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 | DCAT
| write mode: concatenate values

## Constructor & Destructor Documentation

qdbm::Curia::Curia | ( | const char * | name,
|  | int | omode = Curia::OREADER,
|  | int | bnum = -1,
|  | int | dnum = -1
| ) | throw (Curia_error)

Get the database handle.

Parameters:

  name | the name of a database directory.

  omode

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

  bnum | the number of elements of each bucket array. If it is not more than 0, the default value is specified. The size of each bucket array is determined on creating, and can not be changed except for by optimization of the database. Suggested size of each bucket array is about from 0.5 to 4 times of the number of all records to store.
  dnum | the number of division of the database. If it is not more than 0, the default value is specified. The number of division can not be changed from the initial value. The max number of division is 512.

Note:
  While connecting as a writer, an exclusive lock is invoked to the database directory. While connecting as a reader, a shared lock is invoked to the database directory. The thread blocks until the lock is achieved. If `Curia::ONOLCK' is used, the application is responsible for exclusion control.

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

Release the resources.

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

## Member Function Documentation

virtual int qdbm::Curia::bnum | ( |  | ) | throw (Curia_error)`[virtual]`

Get the total number of the elements of each bucket array.

Returns:
  the total number of the elements of each bucket array.

Exceptions:

  Curia_error | if an error occures.

virtual int qdbm::Curia::busenum | ( |  | ) | throw (Curia_error)`[virtual]`

Get the total number of the used elements of each bucket array.

Returns:
  the total number of the used elements of each bucket array.

Exceptions:

  Curia_error | if an error occures.

Note:
  This function is inefficient because it accesses all elements of each bucket array.

virtual void qdbm::Curia::close | ( |  | ) | throw (Curia_error)`[virtual]`

Close the database handle.

Exceptions:

  Curia_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.

Implements qdbm::ADBM.

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

Delete a record.

Parameters:

  key | reference to a key object.

Exceptions:

  Curia_error | if an error occures or no record corresponds.

Implements qdbm::ADBM.

void qdbm::Curia::econv | ( | const char * | name,
|  | bool | big
| ) | throw (Curia_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:

  Curia_error | if an error occures.

virtual bool qdbm::Curia::error | ( |  | ) | throw (Curia_error)`[virtual]`

Check whether a fatal error occured or not.

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

Exceptions:

  Curia_error | if an error occures.

Implements qdbm::ADBM.

virtual bool qdbm::Curia::fatalerror | ( |  | ) | throw (Curia_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:

  Curia_error | if an error occures.

virtual Datum qdbm::Curia::fetchrec | ( | const Datum & | key | ) | throw (Curia_error)`[virtual]`

Fetch a record.

Parameters:

  key | reference to a key object.

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

Exceptions:

  Curia_error | if an error occures or no record corresponds.

Implements qdbm::ADBM.

virtual Datum qdbm::Curia::firstkey | ( |  | ) | throw (Curia_error)`[virtual]`

Get the first key.

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

Exceptions:

  Curia_error | if an error occures or no record corresponds.

Implements qdbm::ADBM.

virtual int qdbm::Curia::fsiz | ( |  | ) | throw (Curia_error)`[virtual]`

Get the total size of database files.

Returns:
  the total size of the database files.

Exceptions:

  Curia_error | if an error occures.

virtual char* qdbm::Curia::get | ( | const char * | kbuf,
|  | int | ksiz,
|  | int | start = 0,
|  | int | max = -1,
|  | int * | sp = 0
| ) | throw (Curia_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)'.
  start | the offset address of the beginning of the region of the value to be read.
  max | the max size to read with. If it is negative, the size is unlimited.
  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:

  Curia_error | if an error occures, no record corresponds, or the size of the value of the corresponding record is less than `start'.

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 char* qdbm::Curia::getlob | ( | const char * | kbuf,
|  | int | ksiz,
|  | int | start = 0,
|  | int | max = -1,
|  | int * | sp = 0
| ) | throw (Curia_error)`[virtual]`

Retrieve a large object.

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)'.
  start | the offset address of the beginning of the region of the value to be read.
  max | the max size to be read. If it is negative, the size to read is unlimited.
  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 large object.

Exceptions:

  Curia_error | if an error occures, no record corresponds, or the size of the value of the corresponding record is less than `start'.

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 int qdbm::Curia::inode | ( |  | ) | throw (Curia_error)`[virtual]`

Get the inode number of the database directory.

Returns:
  the inode number of the database directory.

Exceptions:

  Curia_error | if an error occures.

virtual void qdbm::Curia::iterinit | ( |  | ) | throw (Curia_error)`[virtual]`

Initialize the iterator of the database handle.

Exceptions:

  Curia_error | if an error occures.

Note:
  The iterator is used in order to access the key of every record stored in a database.

virtual char* qdbm::Curia::iternext | ( | int * | sp = 0 | ) | throw (Curia_error)`[virtual]`

Get the next key of the iterator.

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 next key.

Exceptions:

  Curia_error | if an error occures or no record is to be get out of the iterator.

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.

  It is possible to access every record by iteration of calling this function. However, it is not assured if updating the database is occurred while the iteration. Besides, the order of this traversal access method is arbitrary, so it is not assured that the order of storing matches the one of the traversal access.

virtual char* qdbm::Curia::name | ( |  | ) | throw (Curia_error)`[virtual]`

Get the name of the database.

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

Exceptions:

  Curia_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::Curia::nextkey | ( |  | ) | throw (Curia_error)`[virtual]`

Get the next key.

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

Exceptions:

  Curia_error | if an error occures or no record corresponds.

Implements qdbm::ADBM.

virtual void qdbm::Curia::optimize | ( | int | bnum = -1 | ) | throw (Curia_error)`[virtual]`

Optimize the database.

Parameters:

  bnum | the number of the elements of each bucket array. If it is not more than 0, the default value is specified.

Exceptions:

  Curia_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.

virtual void qdbm::Curia::out | ( | const char * | kbuf,
|  | int | ksiz
| ) | throw (Curia_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:

  Curia_error | if an error occures or no record corresponds.

virtual void qdbm::Curia::outlob | ( | const char * | kbuf,
|  | int | ksiz
| ) | throw (Curia_error)`[virtual]`

Delete a large object.

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:

  Curia_error | if an error occures or no large object corresponds.

virtual void qdbm::Curia::put | ( | const char * | kbuf,
|  | int | ksiz,
|  | const char * | vbuf,
|  | int | vsiz,
|  | int | dmode = Curia::DOVER
| ) | throw (Curia_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: `Curia::DOVER', which means the specified value overwrites the existing one, `Curia::DKEEP', which means the existing value is kept, `Curia::DCAT', which means the specified value is concatenated at the end of the existing value.

Exceptions:

  Curia_error | if an error occures or replace is cancelled.

virtual void qdbm::Curia::putlob | ( | const char * | kbuf,
|  | int | ksiz,
|  | const char * | vbuf,
|  | int | vsiz,
|  | int | dmode = Curia::DOVER
| ) | throw (Curia_error)`[virtual]`

Store a large object.

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: `Curia::DOVER', which means the specified value overwrites the existing one, `Curia::DKEEP', which means the existing value is kept, `Curia::DCAT', which means the specified value is concatenated at the end of the existing value.

Exceptions:

  Curia_error | if an error occures or replace is cancelled.

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

Remove a database directory.

Parameters:

  name | the name of a database directory.

Exceptions:

  Curia_error | if an error occures.

virtual int qdbm::Curia::rnum | ( |  | ) | throw (Curia_error)`[virtual]`

Get the number of the records stored in the database.

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

Exceptions:

  Curia_error | if an error occures.

virtual int qdbm::Curia::rnumlob | ( |  | ) | throw (Curia_error)`[virtual]`

Get the number of the large objects stored in the database.

Returns:
  the number of the large objects stored in the database.

Exceptions:

  Curia_error | if an error occures.

virtual void qdbm::Curia::setalign | ( | int | align | ) | throw (Curia_error)`[virtual]`

Set alignment of the database handle.

Parameters:

  align | the basic size of alignment.

Exceptions:

  Curia_error | if an error occures.

Note:
  If alignment is set to a database, the efficiency of overwriting values are improved. The size of alignment is suggested to be average size of the values of the records to be stored. If alignment is positive, padding whose size is multiple number of the alignment is placed. If alignment is negative, as `vsiz' is the size of a value, the size of padding is calculated with `(vsiz / pow(2, abs(align) - 1))'. Because alignment setting is not saved in a database, you should specify alignment every opening a database.

virtual void qdbm::Curia::storerec | ( | const Datum & | key,
|  | const Datum & | val,
|  | bool | replace = true
| ) | throw (Curia_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:

  Curia_error | if an error occures or replace is cancelled.

Implements qdbm::ADBM.

virtual void qdbm::Curia::sync | ( |  | ) | throw (Curia_error)`[virtual]`

Synchronize updating contents with the files and the devices.

Note:
  Curia_error if an error occures. This function is useful when another process uses the connected database directory.

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

Get the version information.

Returns:
  the string of the version information.

virtual int qdbm::Curia::vsiz | ( | const char * | kbuf,
|  | int | ksiz
| ) | throw (Curia_error)`[virtual]`

Get the size of the value of 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)'.

Returns:
  the size of the value of the corresponding record.

Exceptions:

  Curia_error | if an error occures or no record corresponds.

Note:
  Because this function does not read the entity of a record, it is faster than `get'.

virtual int qdbm::Curia::vsizlob | ( | const char * | kbuf,
|  | int | ksiz
| ) | throw (Curia_error)`[virtual]`

Get the size of the value of a large object.

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 size of the value of the corresponding large object.

Exceptions:

  Curia_error | if an error occures or no large object corresponds.

Note:
  Because this function does not read the entity of a large object, it is faster than `getlob'.

virtual bool qdbm::Curia::writable | ( |  | ) | throw (Curia_error)`[virtual]`

Check whether the database handle is a writer or not.

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

Exceptions:

  Curia_error | if an error occures.

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

- xcuria.h