qdbm::Villa Class Reference

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

Inheritance diagram for qdbm::Villa:
qdbm::ADBM

List of all members.

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 bool put (const char *kbuf, int ksiz, const char *vbuf, int vsiz, int dmode=Villa::DOVER) throw (Villa_error)
 Store a record.
virtual bool 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 vsiz (const char *kbuf, int ksiz) throw (Villa_error)
 Get the size of the value of a record.
virtual int vnum (const char *kbuf, int ksiz) throw (Villa_error)
 Get the number of records corresponding a key.
virtual bool curfirst () throw (Villa_error)
 Move the cursor to the first record.
virtual bool curlast () throw (Villa_error)
 Move the cursor to the last record.
virtual bool curprev () throw (Villa_error)
 Move the cursor to the previous record.
virtual bool curnext () throw (Villa_error)
 Move the cursor to the next record.
virtual bool curjump (const char *kbuf, int ksiz, int jmode=Villa::JFORWARD) throw (Villa_error)
 Move the cursor to a position 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 bool curput (const char *vbuf, int vsiz, int cpmode=Villa::CPCURRENT) throw (Villa_error)
 Insert a record around the cursor.
virtual bool curout () throw (Villa_error)
 Delete 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 time_t mtime () throw (Villa_error)
 Get the last modified time of the database.
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

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

Public Attributes

bool silent
 whether to repress frequent exceptions

Static Public Attributes

static const int ENOERR
 error code: no error
static const int EFATAL
 error code: with fatal error
static const int EMODE
 error code: invalid mode
static const int EBROKEN
 error code: broken database file
static const int EKEEP
 error code: existing record
static const int ENOITEM
 error code: no item found
static const int EALLOC
 error code: memory allocation error
static const int EMAP
 error code: memory mapping error
static const int EOPEN
 error code: open error
static const int ECLOSE
 error code: close error
static const int ETRUNC
 error code: trunc error
static const int ESYNC
 error code: sync error
static const int ESTAT
 error code: stat error
static const int ESEEK
 error code: seek error
static const int EREAD
 error code: read error
static const int EWRITE
 error code: write error
static const int ELOCK
 error code: lock error
static const int EUNLINK
 error code: unlink error
static const int EMKDIR
 error code: mkdir error
static const int ERMDIR
 error code: rmdir error
static const int EMISC
 error code: miscellaneous error
static const int OREADER
 open mode: open as a reader
static const int OWRITER
 open mode: open as a writer
static const int OCREAT
 open mode: writer creating
static const int OTRUNC
 open mode: writer truncating
static const int ONOLCK
 open mode: open without locking
static const int OLCKNB
 open mode: lock without blocking
static const int OZCOMP
 open mode: compress leaves with ZLIB
static const int OYCOMP
 open mode: compress leaves with LZO
static const int OXCOMP
 open mode: compress leaves with BZIP2
static const int DOVER
 write mode: overwrite the existing value
static const int DKEEP
 write mode: keep the existing value
static const int DCAT
 write mode: concatenate values
static const int DDUP
 write mode: allow duplication of keys
static const int DDUPR
 write mode: allow duplication with reverse order
static const int JFORWARD
 jump mode: step forward
static const int JBACKWARD
 jump mode: step backward
static const int CPCURRENT
 insertion mode: overwrite the current record
static const int CPBEFORE
 insertion mode: insert before the current record
static const int CPAFTER
 insertion mode: insert after the current record

Detailed Description

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

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: `VillaOWRITER' as a writer, `VillaOREADER' as a reader. If the mode is `VillaOWRITER', the following may be added by bitwise or: `VillaOCREAT', which means it creates a new database if not exist, `VillaOTRUNC', which means it creates a new database regardless if one exists, `VillaOZCOMP', which means leaves in the database are compressed with ZLIB, `VillaOYCOMP', which means leaves in the database are compressed with LZO, `VillaOXCOMP', which means leaves in the database are compressed with BZIP2. Both of `VillaOREADER' and `VillaOWRITER' can be added to by bitwise or: `VillaONOLCK', which means it opens a database file without file locking, or `VillaOLCKNB', which means locking is performed without blocking.
cmp the comparing function: `Villacmplex' comparing keys in lexical order, `Villacmpint' comparing keys as objects of `int' in native byte order, `Villacmpnum' comparing keys as numbers of big endian, `Villacmpdec' 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 occurs.
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. `VillaOZCOMP', `VillaOYCOMP', and `VillaOXCOMP' are available only if QDBM was built each with ZLIB, LZO, and BZIP2 enabled. If `VillaONOLCK' 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 occurs.
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.

static 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.
static 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.
static 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.
static 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 bool qdbm::Villa::curfirst (  )  throw (Villa_error) [virtual]

Move the cursor to the first record.

Returns:
always true. However, if the silent flag is true and no record corresponds, false is returned instead of exception.
Exceptions:
Villa_error if an error occurs or there is no record in the database.
virtual bool qdbm::Villa::curjump ( const char *  kbuf,
int  ksiz,
int  jmode = Villa::JFORWARD 
) throw (Villa_error) [virtual]

Move the cursor to a position 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 `stdstrlen(kbuf)'.
jmode detail adjustment: `VillaJFORWARD', 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, `VillaJBACKWARD', 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.
Returns:
always true. However, if the silent flag is true and no record corresponds, false is returned instead of exception.
Exceptions:
Villa_error if an error occurs 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. If the silent flag is true and no record corresponds, 0 is returned instead of exception.
Exceptions:
Villa_error if an error occurs 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 `stdmalloc' call, it should be released with the `stdfree' call if it is no longer in use.
virtual bool qdbm::Villa::curlast (  )  throw (Villa_error) [virtual]

Move the cursor to the last record.

Returns:
always true. However, if the silent flag is true and no record corresponds, false is returned instead of exception.
Exceptions:
Villa_error if an error occurs or there is no record in the database.
virtual bool qdbm::Villa::curnext (  )  throw (Villa_error) [virtual]

Move the cursor to the next record.

Returns:
always true. However, if the silent flag is true and no record corresponds, false is returned instead of exception.
Exceptions:
Villa_error if an error occurs or there is no next record.
virtual bool qdbm::Villa::curout (  )  throw (Villa_error) [virtual]

Delete the record where the cursor is.

Returns:
always true. However, if the silent flag is true and no record corresponds to the cursor, false is returned instead of exception.
Exceptions:
Villa_error if an error occurs or no record corresponds to the cursor.
Note:
After deletion, the cursor is moved to the next record if possible.
virtual bool qdbm::Villa::curprev (  )  throw (Villa_error) [virtual]

Move the cursor to the previous record.

Returns:
always true. However, if the silent flag is true and no record corresponds, false is returned instead of exception.
Exceptions:
Villa_error if an error occurs or there is no previous record.
virtual bool qdbm::Villa::curput ( const char *  vbuf,
int  vsiz,
int  cpmode = Villa::CPCURRENT 
) throw (Villa_error) [virtual]

Insert a record around the cursor.

Parameters:
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 assi