Main Page   Namespace List   Class Hierarchy   Compound List   Compound Members  

qdbm::Depot Class Reference

Inheritance diagram for qdbm::Depot:

Inheritance graph
List of all members.

Detailed Description

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


Public Member Functions

 Depot (const char *name, int omode=Depot::OREADER, int bnum=-1) throw (Depot_error)
 Get the database handle.

virtual ~Depot () throw ()
 Release the resources.

virtual void close () throw (Depot_error)
 Close the database handle.

virtual void put (const char *kbuf, int ksiz, const char *vbuf, int vsiz, int dmode=Depot::DOVER) throw (Depot_error)
 Store a record.

virtual void out (const char *kbuf, int ksiz) throw (Depot_error)
 Delete a record.

virtual char * get (const char *kbuf, int ksiz, int start=0, int max=-1, int *sp=0) throw (Depot_error)
 Retrieve a record.

virtual int vsiz (const char *kbuf, int ksiz) throw (Depot_error)
 Get the size of the value of a record.

virtual void iterinit () throw (Depot_error)
 Initialize the iterator of the database handle.

virtual char * iternext (int *sp=0) throw (Depot_error)
 Get the next key of the iterator.

virtual void setalign (int align) throw (Depot_error)
 Set alignment of the database handle.

virtual void sync () throw (Depot_error)
 Synchronize contents of updating the database with the file and the device.

virtual void optimize (int bnum=-1) throw (Depot_error)
 Optimize the database.

virtual char * name () throw (Depot_error)
 Get the name of the database.

virtual int fsiz () throw (Depot_error)
 Get the size of the database file.

virtual int bnum () throw (Depot_error)
 Get the number of the elements of the bucket array.

virtual int busenum () throw (Depot_error)
 Get the number of the used elements of the bucket array.

virtual int rnum () throw (Depot_error)
 Get the number of the records stored in the database.

virtual bool writable () throw (Depot_error)
 Check whether the database handle is a writer or not.

virtual bool fatalerror () throw (Depot_error)
 Check whether the database has a fatal error or not.

virtual int inode () throw (Depot_error)
 Get the inode number of the database file.

virtual int fdesc () throw (Depot_error)
 Get the file descriptor of the database file.

virtual void storerec (const Datum &key, const Datum &val, bool replace=true) throw (Depot_error)
 Store a record.

virtual void deleterec (const Datum &key) throw (Depot_error)
 Delete a record.

virtual Datumfetchrec (const Datum &key) throw (Depot_error)
 Fetch a record.

virtual Datumfirstkey () throw (Depot_error)
 Get the first key.

virtual Datumnextkey () throw (Depot_error)
 Get the next key.

virtual bool error () throw (Depot_error)
 Check whether an fatal error occured or not.

virtual void clearerror () throw (Depot_error)
 No effect.


Static Public Member Functions

const char * version () throw ()
 Get the version information.

void remove (const char *name) throw (Depot_error)
 Remove a database file.


Static Public Attributes

const int ENOERR = DP_ENOERR
 error code: no error

const int EFATAL = DP_EFATAL
 error code: with fatal error

const int EMODE = DP_EMODE
 error code: invalid mode

const int EBROKEN = DP_EBROKEN
 error code: broken database file

const int EKEEP = DP_EKEEP
 error code: existing record

const int ENOITEM = DP_ENOITEM
 error code: no item found

const int EALLOC = DP_EALLOC
 error code: memory allocation error

const int EMAP = DP_EMAP
 error code: memory mapping error

const int EOPEN = DP_EOPEN
 error code: open error

const int ECLOSE = DP_ECLOSE
 error code: close error

const int ETRUNC = DP_ETRUNC
 error code: trunc error

const int ESYNC = DP_ESYNC
 error code: sync error

const int ESTAT = DP_ESTAT
 error code: stat error

const int ESEEK = DP_ESEEK
 error code: seek error

const int EREAD = DP_EREAD
 error code: read error

const int EWRITE = DP_EWRITE
 error code: write error

const int ELOCK = DP_ELOCK
 error code: lock error

const int EUNLINK = DP_EUNLINK
 error code: unlink error

const int EMKDIR = DP_EMKDIR
 error code: mkdir error

const int ERMDIR = DP_ERMDIR
 error code: rmdir error

const int EMISC = DP_EMISC
 error code: miscellaneous error

const int OREADER = DP_OREADER
 open mode: open as a reader

const int OWRITER = DP_OWRITER
 open mode: open as a writer

const int OCREAT = DP_OCREAT
 open mode: writer creating

const int OTRUNC = DP_OTRUNC
 open mode: writer truncating

const int DOVER = DP_DOVER
 write mode: overwrite the existing value

const int DKEEP = DP_DKEEP
 write mode: keep the existing value

const int DCAT = DP_DCAT
 write mode: concatenate values


Constructor & Destructor Documentation

qdbm::Depot::Depot const char *    name,
int    omode = Depot::OREADER,
int    bnum = -1
throw (Depot_error)
 

Get the database handle.

Parameters:
name the name of a database file.
omode the connection mode: `Depot::OWRITER' as a writer, `Depot::OREADER' as a reader. If the mode is `Depot::OWRITER', the following may be added by bitwise or: `Depot::OCREAT', which means it creates a new database if not exist, `Depot::OTRUNC', which means it creates a new database regardless if one exists.
bnum the number of elements of the bucket array. If it is not more than 0, the default value is specified. The size of a bucket array is determined on creating, and can not be changed except for by optimization of the database. Suggested size of a bucket array is about from 0.5 to 4 times of the number of all records to store.
Exceptions:
Depot_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.

virtual qdbm::Depot::~Depot   throw () [virtual]
 

Release the resources.

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


Member Function Documentation

virtual int qdbm::Depot::bnum   throw (Depot_error) [virtual]
 

Get the number of the elements of the bucket array.

Returns:
the number of the elements of the bucket array.
Exceptions:
Depot_error if an error occures.

virtual int qdbm::Depot::busenum   throw (Depot_error) [virtual]
 

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

Returns:
the number of the used elements of the bucket array.
Exceptions:
Depot_error if an error occures.
Note:
This function is inefficient because it accesses all elements of the bucket array.

virtual void qdbm::Depot::clearerror   throw (Depot_error) [virtual]
 

No effect.

Exceptions:
Depot_error if an error occures.

Implements qdbm::ADBM.

virtual void qdbm::Depot::close   throw (Depot_error) [virtual]
 

Close the database handle.

Exceptions:
Depot_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::Depot::deleterec const Datum   key throw (Depot_error) [virtual]
 

Delete a record.

Parameters:
key reference to a key object.
Exceptions:
Depot_error if an error occures or no record corresponds.

Implements qdbm::ADBM.

virtual bool qdbm::Depot::error   throw (Depot_error) [virtual]
 

Check whether an fatal error occured or not.

Returns:
true if the database has a fatal error, false if not.
Exceptions:
Depot_error if an error occures.

Implements qdbm::ADBM.

virtual bool qdbm::Depot::fatalerror   throw (Depot_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:
Depot_error if an error occures.

virtual int qdbm::Depot::fdesc   throw (Depot_error) [virtual]
 

Get the file descriptor of the database file.

Returns:
the file descriptor of the database file.
Exceptions:
Depot_error if an error occures.
Note:
Handling the file descriptor of a database file directly is not suggested.

virtual Datum* qdbm::Depot::fetchrec const Datum   key throw (Depot_error) [virtual]
 

Fetch a record.

Parameters:
key reference to a key object.
Returns:
the pointer to an instance of the value of the corresponding record.
Exceptions:
Depot_error if an error occures or no record corresponds.
Note:
The instance pointed to by the return value is to be destloyed by the caller.

Implements qdbm::ADBM.

virtual Datum* qdbm::Depot::firstkey   throw (Depot_error) [virtual]
 

Get the first key.

Returns:
the pointer to an instance of the value of the first record.
Exceptions:
Depot_error if an error occures or no record corresponds.
Note:
The instance pointed to by the return value is to be destloyed by the caller.

Implements qdbm::ADBM.

virtual int qdbm::Depot::fsiz   throw (Depot_error) [virtual]
 

Get the size of the database file.

Returns:
the size of the database file.
Exceptions:
Depot_error if an error occures.

virtual char* qdbm::Depot::get const char *    kbuf,
int    ksiz,
int    start = 0,
int    max = -1,
int *    sp = 0
throw (Depot_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 a pointer to the variable to which the size of the region of the return value assigned. If it is 0, it is not used.
Returns:
the pointer to the region of the value of the corresponding record.
Exceptions:
Depot_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::Depot::inode   throw (Depot_error) [virtual]
 

Get the inode number of the database file.

Returns:
the inode number of the database file.
Exceptions:
Depot_error if an error occures.

virtual void qdbm::Depot::iterinit   throw (Depot_error) [virtual]
 

Initialize the iterator of the database handle.

Exceptions:
Depot_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::Depot::iternext int *    sp = 0 throw (Depot_error) [virtual]
 

Get the next key of the iterator.

Parameters:
sp a pointer to the variable to which the size of the region of the return value assigned. If it is 0, it is not used.
Returns:
the pointer to the region of the next key.
Exceptions:
Depot_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::Depot::name   throw (Depot_error) [virtual]
 

Get the name of the database.

Returns:
the pointer to the region of the name of the database.
Exceptions:
Depot_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::Depot::nextkey   throw (Depot_error) [virtual]
 

Get the next key.

Returns:
the pointer to an instance of the value of the first record.
Exceptions:
Depot_error if an error occures or no record corresponds.
Note:
The instance pointed to by the return value is to be destloyed by the caller.

Implements qdbm::ADBM.

virtual void qdbm::Depot::optimize int    bnum = -1 throw (Depot_error) [virtual]
 

Optimize the database.

Parameters:
bnum the number of the elements of the bucket array. If it is not more than 0, the default value is specified.
Exceptions:
Depot_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::Depot::out const char *    kbuf,
int    ksiz
throw (Depot_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:
Depot_error if an error occures or no record corresponds.

virtual void qdbm::Depot::put const char *    kbuf,
int    ksiz,
const char *    vbuf,
int    vsiz,
int    dmode = Depot::DOVER
throw (Depot_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: `Depot::DOVER', which means the specified value overwrites the existing one, `Depot::DKEEP', which means the existing value is kept, `Depot::DCAT', which means the specified value is concatenated at the end of the existing value.
Exceptions:
Depot_error if an error occures or replace is cancelled.

void qdbm::Depot::remove const char *    name throw (Depot_error) [static]
 

Remove a database file.

Parameters:
name the name of a database file.
Exceptions:
Depot_error if an error occures.

virtual int qdbm::Depot::rnum   throw (Depot_error) [virtual]
 

Get the number of the records stored in the database.

Returns:
the number of the records stored in the database.
Exceptions:
Depot_error if an error occures.

virtual void qdbm::Depot::setalign int    align throw (Depot_error) [virtual]
 

Set alignment of the database handle.

Parameters:
align the basic size of alignment.
Exceptions:
Depot_error if an error occures.
Note:
If alignment is set to a database, the efficiency of overwriting values are improved. The basic size of alignment is suggested to be average size of the values of the records to be stored. When a record is storing, the size of the region reserved for its value is determined as multiple of the alignment size. The alignment size is determined as multiple of the basic size of alignment. Because alignment setting is not saved in a database, you should specify alignment every opening a database.

virtual void qdbm::Depot::storerec const Datum   key,
const Datum   val,
bool    replace = true
throw (Depot_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:
Depot_error if an error occures or replace is cancelled.

Implements qdbm::ADBM.

virtual void qdbm::Depot::sync   throw (Depot_error) [virtual]
 

Synchronize contents of updating the database with the file and the device.

Exceptions:
Depot_error if an error occures.
Note:
This function is useful when another process uses the connected database file.

const char* qdbm::Depot::version   throw () [static]
 

Get the version information.

Returns:
the string of the version information.

virtual int qdbm::Depot::vsiz const char *    kbuf,
int    ksiz
throw (Depot_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:
Depot_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 bool qdbm::Depot::writable   throw (Depot_error) [virtual]
 

Check whether the database handle is a writer or not.

Returns:
true if the handle is a writer, false if not.
Exceptions:
Depot_error if an error occures.


The documentation for this class was generated from the following file:
Generated on Thu Apr 10 03:35:39 2003 for QDBM for C++ by doxygen1.3-rc3