Db



NAME

       Db - database access class


SYNOPSIS

       #include <db_cxx.h>

       static int
       Db::open(const char *fname, DBTYPE type,
            int flags, int mode, DbEnv *dbenv, DbInfo *dbinfo, Db **dbpp);

       DBTYPE
       Db::get_type(void) const;

       int
       Db::close(int flags);

       int
       Db::cursor(DbTxn *txnid, Dbc **cursorp);

       int
       Db::del(Dbt *key, DbTxn *txnid);

       int
       Db::fd(int *fdp);

       int
       Db::get(DbTxn *txnid, Dbt *key, Dbt *data, int flags);

       int
       Db::put(DbTxn *txnid, Dbt *key, Dbt *data, int flags);

       int
       Db::stat(void *sp, void *(*db_malloc)(size_t), int flags);

       int
       Db::sync(int flags);


DESCRIPTION

       The DB library is a family of classes that provides a mod-
       ular programming interface to transactions and record-ori-
       ented  file  access.   The  library  includes  support for
       transactions, locking, logging and file page  caching,  as
       well  as  various  indexed  access  methods.   Many of the
       classes (e.g., the file page  caching  class)  are  useful
       independent of the other DB classes, although some classes
       are explicitly based on other classes (e.g.,  transactions
       and  logging).   For a general description of the DB pack-
       age, see db_intro(3).

       This manual page describes the Db class, which is the cen-
       ter of access activity.

       The currently supported file formats are btree, hashed and
       recno.  The btree format is a representation of a  sorted,
       shared  or preserved on disk may be created by setting the
       file parameter to NULL.

       The Db::open method copies a pointer to a  Db  object  (as
       typedef'd in the <db_cxx.h> include file), into the memory
       location referenced by dbpp.  The methods of  this  object
       allow   you   to  perform  various  database  actions,  as
       described below.  The Db::open method  throws  a  DbExcep-
       tion(3)  or returns the value of errno on failure and 0 on
       success.

       Note, while most of the access methods  use  file  as  the
       name  of  an  underlying file on disk, this is not guaran-
       teed.  Also, calling Db::open is  a  reasonably  expensive
       operation.  (This is based on a model where the DBMS keeps
       a set of files open for a long time  rather  than  opening
       and closing them on each query.)

       The  type  argument  is  of type DBTYPE (as defined in the
       <db_cxx.h> include  file)  and  must  be  set  to  one  of
       DB_BTREE,  DB_HASH,  DB_RECNO  or  DB_UNKNOWN.  If type is
       DB_UNKNOWN, the database must already exist  and  Db::open
       will  then determine if it is of type DB_BTREE, DB_HASH or
       DB_RECNO.

       The flags and mode arguments specify  how  files  will  be
       opened  and/or created when they don't already exist.  The
       flags value is specified by or'ing together one or more of
       the following values:

       DB_CREATE
            Create  any  underlying  files, as necessary.  If the
            files do not already exist and the DB_CREATE flag  is
            not specified, the call will fail.

       DB_NOMMAP
            Do  not  map  this  file  (see DbMpool(3) for further
            information).

       DB_RDONLY
            Open the database for reading only.  Any  attempt  to
            write the database using the access methods will fail
            regardless of the actual permissions of any  underly-
            ing files.

       DB_THREAD
            Cause  the  Db handle returned by the Db::open method
            to be useable by multiple  threads  within  a  single
            address space, i.e., to be ``free-threaded''.

       DB_TRUNCATE
            ``Truncate''  the database if it exists, i.e., behave
            as if the database were just created, discarding  any
            previous contents.

       The  Db  object  returned by Db::open describes a database
       type, and includes a set of functions to  perform  various
       actions,  as  described  below.  The methods for Db are as
       follows:

       DBTYPE Db::get_type(void);
            The type of the underlying access  method  (and  file
            format).    Returns   one  of  DB_BTREE,  DB_HASH  or
            DB_RECNO.  This value may be used  to  determine  the
            type  of  the  database  after a return from Db::open
            with the type argument set to DB_UNKNOWN.

       int Db::close(int flags);
            A method to flush any  cached  information  to  disk,
            close  any  open cursors (see Dbc(3)), free any allo-
            cated resources,  and  close  any  underlying  files.
            Since key/data pairs are cached in memory, failing to
            sync the file with  the  close  or  sync  method  may
            result in inconsistent or lost information.

            The flags parameter must be set to 0 or the following
            value:

            DB_NOSYNC
                 Do not flush cached information to disk.

            The DB_NOSYNC flag is a dangerous option.  It  should
            only be set if the application is doing logging (with
            or without transactions)  so  that  the  database  is
            recoverable  after  a system or application crash, or
            if the database  is  always  generated  from  scratch
            after any system or application crash.

            It  is  important  to understand that flushing cached
            information to disk  only  minimizes  the  window  of
            opportunity  for  corrupted data.  While unlikely, it
            is possible for database corruption to  happen  if  a
            system or application crash occurs while writing data
            to the database.  To ensure that database  corruption
            never  occurs, applications must either: use transac-
            tions and logging with automatic recovery,  use  log-
            ging  and  application-specific  recovery,  or edit a
            copy of the  database,  and,  once  all  applications
            using  the  database  have successfully called close,
            replace the original database with the updated  copy.

            When multiple threads are using the Db handle concur-
            rently, only a single thread may call the  Db  handle
            close method.

            The  close  method throws a DbException(3) or returns
            the value of errno on failure and 0 on success.

       int Db::cursor(DbTxn *txnid, Dbc **cursorp);
            the txnid parameter specifies the transaction context
            in which the cursor may be used.  See Dbc(3) for more
            information.

            The  cursor method throws a DbException(3) or returns
            the value of errno on failure and 0 on success.

       int Db::del(DbTxn *txnid, Dbt *key, int flags);
            A method to remove key/data pairs from the  database.
            The  key/data  pair associated with the specified key
            is discarded from the database.  In the  presence  of
            duplicate key values, all records associated with the
            designated key will be discarded.

            If the file is being accessed under transaction  pro-
            tection,  the  txnid  parameter  is  a transaction ID
            returned from txn_begin, otherwise, NULL.


            The flags parameter is currently unused, and must  be
            set to 0.

            The del method throws a DbException(3) or returns the
            value of errno on failure, 0 on success, and  DB_NOT-
            FOUND if the specified key did not exist in the file.

       int Db::fd(int *fdp);
            A method that copies a file descriptor representative
            of the underlying database into the memory referenced
            by fdp.  A file descriptor referencing the same  file
            will  be returned to all processes that call Db::open
            with the same file argument.   This  file  descriptor
            may be safely used as an argument to the fcntl(2) and
            flock(2) locking functions.  The file  descriptor  is
            not necessarily associated with any of the underlying
            files used by the access method.

            The fd method only supports a coarse-grained form  of
            locking.   Applications  should  use the lock manager
            where possible.

            The fd method throws a DbException(3) or returns  the
            value of errno on failure and 0 on success.

       int Db::get(DbTxn *txnid, Dbt *key, Dbt *data, int flags);
            A method that is an  interface  for  keyed  retrieval
            from  the  database.   The  address and length of the
            data associated with the specified key  are  returned
            in the object referenced by data.

            In  the  presence  of  duplicate key values, get will
            return the first data item for  the  designated  key.
            Duplicates  are  sorted  by insert order except where
            this order has been overwritten by cursor operations.
                 database.  Upon return, both the  key  and  data
                 items  will  have  been  filled in, not just the
                 data item as is done for all other uses  of  the
                 get method.

                 For DB_GET_RECNO to be specified, the underlying
                 database must be of type btree, and it must have
                 been   created  with  the  DB_RECNUM  flag  (see
                 Db::open(3)).  In this case, the data  field  of
                 the  key  must be a pointer to a memory location
                 of type db_recno_t, as described in Dbt(3).

            If the database is a recno database and the requested
            key  exists,  but was never explicitly created by the
            application or was  later  deleted,  the  get  method
            returns DB_KEYEMPTY.  Otherwise, if the requested key
            isn't in the database, the get method returns DB_NOT-
            FOUND.   Otherwise,  the get method throws a DbExcep-
            tion(3) or returns the value of errno on failure  and
            0 on success.

       int Db::put(DbTxn *txnid, Dbt *key, Dbt *data, int flags);
            A method to store key/data pairs in the database.  If
            the database supports duplicates, the put method adds
            the new data value at the end of the duplicate set.

            If the file is being accessed under transaction  pro-
            tection,  the  txnid  parameter  is  a transaction ID
            returned from txn_begin, otherwise, NULL.

            The flags value is specified by or'ing  together  one
            or more of the following values:

            DB_APPEND
                 Append  the  key/data  pair  to  the  end of the
                 database.  For DB_APPEND to  be  specified,  the
                 underlying  database must be of type recno.  The
                 record  number  allocated  to  the   record   is
                 returned in the specified key.

            DB_NOOVERWRITE
                 Enter the new key/data pair only if the key does
                 not already appear in the database.

            The default behavior of the put method  is  to  enter
            the  new  key/data  pair,  replacing  any  previously
            existing key if duplicates are disallowed, or to  add
            a duplicate entry if duplicates are allowed.  Even if
            the designated database allows duplicates, a call  to
            put with the DB_NOOVERWRITE flag set will fail if the
            key already exists in the database.

            The put method throws a DbException(3) or returns the
            value   of  errno  on  failure,  0  on  success,  and
            sion of Db and cached data.

            The  sync  method  throws a DbException(3) or returns
            the value of errno on failure and 0 on success.

       int Db::stat(void *sp,
                 void *(*db_malloc)(size_t), int flags);
            A method to create a statistical structure and copy a
            pointer  to  it into user-specified memory locations.
            Specifically, if sp is non-NULL,  a  pointer  to  the
            statistics  for the database are copied into the mem-
            ory location it references.

            Statistical structures are created in allocated  mem-
            ory.  If db_malloc is non-NULL, it is called to allo-
            cate the memory, otherwise, the library function mal-
            loc(3)  is  used.   The function db_malloc must match
            the calling conventions of the malloc(3) library rou-
            tine.   Regardless,  the  caller  is  responsible for
            deallocating the returned memory.  To deallocate  the
            returned  memory,  free each returned memory pointer;
            pointers inside the memory do not need to be individ-
            ually freed.

            In  the  presence  of  multiple  threads or processes
            accessing an active database, the  returned  informa-
            tion may be out-of-date.

            This  method  may  access  all  of  the  pages in the
            database, and therefore may incur  a  severe  perfor-
            mance  penalty  and  have obvious negative effects on
            the underlying buffer pool.


            The flags parameter must be set to 0 or the following
            value:


            DB_RECORDCOUNT
                 In  the  case of a btree or recno database, fill
                 in the bt_nrecs field, but do  not  collect  any
                 other  information.   This flag makes it reason-
                 able for applications to request a record  count
                 from  a database without incurring a performance
                 penalty.

            The stat method throws a  DbException(3)  or  returns
            the value of errno on failure and 0 on success.

            In  the  case  of  a  btree  or  recno  database, the
            statistics  are  stored  in  a  structure   of   type
            DB_BTREE_STAT (typedef'd in <db_cxx.h>).  The follow-
            ing fields will be filled in:

                 The  re_len  value  specified to Db::open(3), if
                 any.
            u_int32_t bt_re_pad;
                 The re_pad value specified  to  Db::open(3),  if
                 any.
            u_int32_t bt_pagesize;
                 Underlying tree page size.
            u_int32_t bt_levels;
                 Number of levels in the tree.
            u_int32_t bt_nrecs;
                 Number  of  data  items in the tree (since there
                 may be multiple data items per key, this  number
                 may not be the same as the number of keys).
            u_int32_t bt_int_pg;
                 Number of tree internal pages.
            u_int32_t bt_leaf_pg;
                 Number of tree leaf pages.
            u_int32_t bt_dup_pg;
                 Number of tree duplicate pages.
            u_int32_t bt_over_pg;
                 Number of tree overflow pages.
            u_int32_t bt_free;
                 Number of pages on the free list.
            u_int32_t bt_freed;
                 Number of pages made available for reuse because
                 they were emptied.
            u_int32_t bt_int_pgfree;
                 Number of bytes free in tree internal pages.
            u_int32_t bt_leaf_pgfree;
                 Number of bytes free in tree leaf pages.
            u_int32_t bt_dup_pgfree;
                 Number of bytes free in tree duplicate pages.
            u_int32_t bt_over_pgfree;
                 Number of bytes free in tree overflow pages.
            u_int32_t bt_pfxsaved;
                 Number of bytes saved by prefix compression.
            u_int32_t bt_split;
                 Total number of tree page splits (includes  fast
                 and root splits).
            u_int32_t bt_rootsplit;
                 Number of root page splits.
            u_int32_t bt_fastsplit;
                 Number  of  fast  splits.   When sorted keys are
                 added to the database, the Db btree  implementa-
                 tion  will  split  left or right to increase the
                 page-fill factor.  This number is a  measure  of
                 how  often it was possible to make such a split.
            u_int32_t bt_added;
                 Number of keys added.
            u_int32_t bt_deleted;
                 Number of keys deleted.
            u_int32_t bt_get;
                 Number of keys  retrieved.   (Note,  this  value
                 will  not  reflect  any  keys retrieved when the
                 the description of bt_cache_hit; this number  is
                 a measure of how often the lookup failed.


ENVIRONMENT VARIABLES

       The  following  environment variables affect the execution
       of Db::open:

       DB_HOME
            If the dbenv argument  to  Db::open  was  initialized
            using  db_appinit,  the  environment variable DB_HOME
            may be used as the path of the database home for  the
            interpretation  of  the  dir argument to Db::open, as
            described in db_appinit(3).   Specifically,  Db::open
            is  affected  by  the  configuration  string value of
            DB_DATA_DIR.


EXAMPLES

       Applications that create short-lived  databases  that  are
       discarded  or  recreated  when  the  system  fails and are
       unconcerned with concurrent access and loss of data due to
       catastrophic  failure,  may wish to use the Db::open func-
       tionality without other parts of  the  Db  library.   Such
       applications  will  only  be  concerned with the Db access
       methods.  The Db access methods will use the  memory  pool
       subsystem,  but the application is unlikely to be aware of
       this.  See the file examples_cxx/AccessExample.cpp in  the

       Db  source distribution for a C++ language code example of
       how such an application might use the Db library.


ERRORS

       Methods marked as returning errno will, by default,  throw
       an exception that encapsulates the error information.  The
       default error behavior can be changed, see DbException(3).

       The Db::open method may fail and throw a DbException(3) or
       return errno for any of the errors specified for the  fol-
       lowing DB and library functions: Db::sync(3),
       DbLock::get(3), DbLock::put(3), DbLockTab::id(3),
       DbLockTab::vec(3), DbLog::db_register(3), DbLog::put(3),
       DbMpool::close(3), DbMpool::db_register(3),
       DbMpool::open(3), DbMpoolFile::close(3),
       DbMpoolFile::get(3), DbMpoolFile::open(3),
       DbMpoolFile::put(3), DbMpoolFile::set(3),
       DbMpoolFile::sync(3), calloc(3), close(2), fcntl(2),
       fflush(3), malloc(3), memcpy(3), memmove(3), memset(3),
       mmap(2), munmap(2), open(2), read(2), realloc(3),
       sigfillset(3), sigprocmask(2), stat(2), strcpy(3),
       strdup(3), strerror(3), strlen(3), time(3), and unlink(2).

       In  addition,  the  Db::open  method  may fail and throw a
       DbException(3) or return errno for  the  following  condi-
       tions:


            There is a mismatch between  the  version  number  of
            file and the software.

            A  re_source  file  was  specified  with  either  the
            DB_THREAD flag or a non-NULL  tx_info  field  in  the
            DbEnv argument to Db::open.

       [ENOENT]
            A non-existent re_source file was specified.

       [EPERM]
            Database  corruption  was  detected.   All subsequent
            database calls (other  than  Db::close)  will  return
            EPERM.

       The  Db::close  method may fail and throw a DbException(3)
       or return errno for any of the errors  specified  for  the
       following DB and library functions: Db::sync(3),
       DbLock::get(3), DbLock::put(3), DbLockTab::vec(3),
       DbLog::db_register(3), DbLog::put(3), DbMpool::close(3),
       DbMpoolFile::close(3), DbMpoolFile::get(3),
       DbMpoolFile::put(3), DbMpoolFile::set(3),
       DbMpoolFile::sync(3), calloc(3), close(2), fflush(3),
       malloc(3), memcpy(3), memmove(3), memset(3), munmap(2),
       realloc(3), and strerror(3).

       The Db::cursor method may fail and throw a  DbException(3)
       or  return  errno  for any of the errors specified for the
       following DB and library functions: calloc(3).

       In addition, the Db::cursor method may fail  and  throw  a
       DbException(3)  or  return  errno for the following condi-
       tions:

       [EINVAL]
            An invalid flag value or parameter was specified.

       [EPERM]
            Database corruption  was  detected.   All  subsequent
            database  calls  (other  than  Db::close) will return
            EPERM.

       The Db::del method may fail and throw a DbException(3)  or
       return  errno for any of the errors specified for the fol-
       lowing DB and library functions: DbLock::get(3),
       DbLock::put(3), DbLockTab::id(3), DbLockTab::vec(3),
       DbLog::put(3), DbMpoolFile::get(3), DbMpoolFile::put(3),
       DbMpoolFile::set(3), calloc(3), fcntl(2), fflush(3),
       malloc(3), memcmp(3), memcpy(3), memmove(3), memset(3),
       realloc(3), and strerror(3).

       In addition, the Db::del method may fail and throw a DbEx-
       ception(3) or return errno for the following conditions:
       In addition, the Db::fd method may fail and throw a  DbEx-
       ception(3) or return errno for the following conditions:


       [ENOENT]
            The   Db::fd  method  was  called  for  an  in-memory
            database, or no underlying file has yet been created.

       [EPERM]
            Database  corruption  was  detected.   All subsequent
            database calls (other  than  Db::close)  will  return
            EPERM.

       The  Db::get method may fail and throw a DbException(3) or
       return errno for any of the errors specified for the  fol-
       lowing DB and library functions: DbLock::get(3),
       DbLock::put(3), DbLockTab::id(3), DbLockTab::vec(3),
       DbLog::put(3), DbMpoolFile::get(3), DbMpoolFile::put(3),
       DbMpoolFile::set(3), Dbc::get(3), calloc(3), fcntl(2),
       fflush(3), malloc(3), memcmp(3), memcpy(3), memmove(3),
       memset(3), realloc(3), and strerror(3).

       In addition, the Db::get method may fail and throw a DbEx-
       ception(3) or return errno for the following conditions:

       [EAGAIN]
            A lock was unavailable.

       [EINVAL]
            An invalid flag value or parameter was specified.

            The  DB_THREAD  flag was specified to the Db::open(3)
            method and neither the DB_DBT_MALLOC or  DB_DBT_USER-
            MEM flags were set in the Dbt.

            A record number of 0 was specified.

       [EPERM]
            Database  corruption  was  detected.   All subsequent
            database calls (other  than  Db::close)  will  return
            EPERM.

       The  Db::put method may fail and throw a DbException(3) or
       return errno for any of the errors specified for the  fol-
       lowing DB and library functions: DbLock::get(3),
       DbLock::put(3), DbLockTab::id(3), DbLockTab::vec(3),
       DbLog::put(3), DbMpoolFile::get(3), DbMpoolFile::put(3),
       DbMpoolFile::set(3), calloc(3), fcntl(2), fflush(3),
       malloc(3), memcmp(3), memcpy(3), memmove(3), memset(3),
       realloc(3), and strerror(3).

       In addition, the Db::put method may fail and throw a DbEx-
       ception(3) or return errno for the following conditions:

            An attempt was made to add a record to a fixed-length
            database that was too large to fit.

            An attempt was made to do a partial put.

       [EPERM]
            Database corruption  was  detected.   All  subsequent
            database  calls  (other  than  Db::close) will return
            EPERM.

       [ENOSPC]
            A btree exceeded the maximum btree depth (255).

       The Db::stat method may fail and throw a DbException(3) or
       return  errno for any of the errors specified for the fol-
       lowing DB and library functions: DbLock::get(3),
       DbLock::put(3), DbLockTab::id(3), DbLockTab::vec(3),
       DbMpoolFile::get(3), DbMpoolFile::put(3), calloc(3),
       fcntl(2),  fflush(3), malloc(3), memcpy(3), and memset(3).

       The Db::sync method may fail and throw a DbException(3) or
       return  errno for any of the errors specified for the fol-
       lowing DB and library functions: Db::get(3), Db::sync(3),
       DbLock::get(3), DbLock::put(3), DbLockTab::id(3),
       DbLockTab::vec(3), DbLog::put(3), DbMpoolFile::get(3),
       DbMpoolFile::put(3), DbMpoolFile::set(3),
       DbMpoolFile::sync(3), calloc(3), close(2), fcntl(2),
       fflush(3), malloc(3), memcpy(3), memmove(3), memset(3),
       munmap(2), open(2), realloc(3), strerror(3), unlink(2),
       and write(2).

       In  addition,  the  Db::sync  method  may fail and throw a
       DbException(3) or return errno for  the  following  condi-
       tions:

       [EINVAL]
            An invalid flag value or parameter was specified.

       [EPERM]
            Database  corruption  was  detected.   All subsequent
            database calls (other  than  Db::close)  will  return
            EPERM.


SEE ALSO

       The  Ubiquitous  B-tree,  Douglas Comer, ACM Comput. Surv.
       11, 2 (June 1979), 121-138.
       Prefix B-trees, Bayer and Unterauer, ACM  Transactions  on
       Database Systems, Vol. 2, 1 (March 1977), 11-26.

       The  Art  of  Computer  Programming  Vol.  3:  Sorting and
       Searching, D.E. Knuth, 1968, pp 471-480.

       Dynamic Hash Tables, Per-Ake Larson, Communications of the
       ACM, April 1988.
       DbLock(3), DbLocktab(3), DbLog(3), DbLsn(3), DbMpool(3),
       DbMpoolFile(3), Dbt(3), DbTxn(3), DbTxnMgr(3)