Dbc



NAME

       Dbc - database sequential access functions


SYNOPSIS

       #include <db_cxx.h>

       int
       Dbc::close(void);

       int
       Dbc::del(int flags);

       int
       Dbc::get(Dbt *key, Dbt *data, int flags);

       int
       Dbc::put(Dbt *key, Dbt *data, 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  specific  details  of  the
       cursor support for the access methods in Db(3).

       The  Dbc  functions  are  the library interface supporting
       sequential access to the  records  stored  by  the  access
       methods of the Db library.  Cursors are created by calling
       Db::cursor method described  in  Db(3),  which  returns  a
       pointer to a Dbc object.

       Each cursor maintains positioning information within a set
       of key/data pairs.  In the presence of transactions,  cur-
       sors  are only valid within the context of a single trans-
       action, the  one  specified  during  the  Db::cursor  call
       described  in  Db(3).   All cursor operations will be exe-
       cuted in the context of that transaction.  Before aborting
       or  committing a transaction, all cursors used within that
       transaction must be closed.  In the presence  of  transac-
       tions,  the  application  must call DbTxn::abort if any of
       the cursor operations returns that a deadlock (EAGAIN)  or
       system failure occurred.

       When  locking  is enabled, page locks are retained between
       consecutive cursor calls.  For this reason, in  the  pres-
       ence  of  locking,  applications should discard cursors as
            returns  the  value of errno on failure and 0 on suc-
            cess.

       int Dbc::del(int flags);
            A method that deletes  the  key/data  pair  currently
            referenced by the cursor.

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

            The cursor position is unchanged after a  delete  and
            subsequent  calls  to  cursor functions expecting the
            cursor to reference an existing key will fail.

            The  Dbc::del  method  throws  a  DbException(3)   or
            returns  the value of errno on failure, 0 on success,
            and DB_KEYEMPTY  if  the  element  has  already  been
            deleted.

       int Dbc::get(Dbt *key, Dbt *data, int flags);
            A  method  that  retrieves  key/data  pairs  from the
            database.  The address and  length  of  the  key  are
            returned  in the object referenced by key (except for
            the case of the DB_SET flag where the key  object  is
            unchanged),  and  the  address and length of the data
            are returned in the object referenced by data.

            Modifications to the  database  during  a  sequential
            scan  will  be  reflected  in  the scan, i.e. records
            inserted behind a cursor will not be  returned  while
            records  inserted  in  front  of  a  cursor  will  be
            returned.

            In recno databases, missing  entries  (i.e.,  entries
            that  were never explicitly created or that were cre-
            ated and then deleted),  will  be  skipped  during  a
            sequential scan.

            If  multiple  threads  or processes insert items into
            the same database file  without  using  locking,  the
            results are undefined.  For more detail, see the sec-
            tion below on cursor stability.

            The parameter flags must be set to exactly one of the
            following values:

            DB_FIRST
                 The   cursor  is  set  to  reference  the  first
                 key/data pair of the database, and that pair  is
                 returned.  In the presence of duplicate key val-
                 ues, the first data item in the  set  of  dupli-
                 cates is returned.

                 If  the  database  is empty, the Dbc::get method

            DB_NEXT
                 If the cursor is not yet initialized, DB_NEXT is
                 identical to DB_FIRST.

                 Otherwise, move the cursor to the next  key/data
                 pair of the database, and that pair is returned.
                 In the presence of duplicate key values, the key
                 may not change.

                 If  the  cursor is already on the last record in
                 the database, the Dbc::get  method  will  return
                 DB_NOTFOUND.

            DB_PREV
                 If the cursor is not yet initialized, DB_PREV is
                 identical to DB_LAST.

                 Otherwise,  move  the  cursor  to  the  previous
                 key/data  pair of the database, and that pair is
                 returned.  In the presence of duplicate key val-
                 ues, the key may not change.

                 If  the cursor is already on the first record in
                 the database, the Dbc::get  method  will  return
                 DB_NOTFOUND.

            DB_CURRENT
                 Return the key/data pair currently referenced by
                 the cursor.

                 If the cursor key/data pair  has  been  deleted,
                 the Dbc::get method will return DB_KEYEMPTY.

                 If  the  cursor  is  not  yet  initialized,  the
                 Dbc::get method will return EINVAL.

            DB_SET
                 Move the cursor to the specified  key/data  pair
                 of the database, and return the datum associated
                 with the given key.

                 In  the  presence  of  duplicate   key   values,
                 Dbc::get will return the first data item for the
                 given key.

                 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 Dbc::get method returns DB_KEYEMPTY.

                 If  no  matching  keys  are  found, the Dbc::get
                 method will return DB_NOTFOUND.

            DB_SET_RANGE
                 key  must be a pointer to a memory location from
                 which a db_recno_t may be read, as described  in
                 Dbt(3).   This  memory  location will be read to
                 determine the record to be retrieved.

                 For DB_SET_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 in Db(3)).

            DB_GET_RECNO
                 Return  the  record  number  associated with the
                 cursor.  The record number will be  returned  in
                 the  data  Dbt  as described in Dbt(3).  The key
                 parameter is ignored.

                 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 in Db(3)).

            Otherwise,  the  Dbc::get  method  throws  a DbExcep-
            tion(3) or returns the value of errno on failure  and
            0 on success.

            If  Dbc::get  fails  for any reason, the state of the
            cursor will be unchanged.

       int Dbc::put(Dbt *key, Dbt *data, int flags);
            A  method  that  stores  key/data  pairs   into   the
            database.

            The flags parameter must be set to exactly one of the
            following values:

            DB_AFTER
                 In the case of the btree and hash  access  meth-
                 ods, insert the data element as a duplicate ele-
                 ment of the key referenced by the  cursor.   The
                 new  element  appears immediately after the cur-
                 rent cursor position.  It is an error to specify
                 DB_AFTER   if   the  underlying  btree  or  hash
                 database was not created with the  DB_DUP  flag.
                 The key parameter is ignored.

                 In the case of the recno access method, it is an
                 error to  specify  DB_AFTER  if  the  underlying
                 recno   database   was   not  created  with  the
                 DB_RENUMBER flag.  If the DB_RENUMBER  flag  was
                 specified,  a  new  key  is created, all records
                 after the inserted item are automatically renum-
                 bered, and the key of the new record is returned
                 in the object referenced by the  parameter  key.
                 The  initial  value  of  the  key  parameter  is
                 DB_BEFORE   if  the  underlying  btree  or  hash
                 database was not created with the  DB_DUP  flag.
                 The key parameter is ignored.

                 In the case of the recno access method, it is an
                 error to specify  DB_BEFORE  if  the  underlying
                 recno   database   was   not  created  with  the
                 DB_RENUMBER flag.  If the DB_RENUMBER  flag  was
                 specified,  a  new  key  is created, the current
                 record and all records after  it  are  automati-
                 cally  renumbered, and the key of the new record
                 is returned in  the  object  referenced  by  the
                 parameter  key.   The  initial  value of the key
                 parameter is ignored.  See Db::open in Db(3) for
                 more information.

                 If  the  cursor  is  not  yet  initialized,  the
                 Dbc::put method will return EINVAL.

            DB_CURRENT
                 Overwrite the data of the key/data  pair  refer-
                 enced  by  the  cursor  with  the specified data
                 item.

                 The key parameter is ignored.

                 If  the  cursor  is  not  yet  initialized,  the
                 Dbc::put method will return EINVAL.

            DB_KEYFIRST
                 In  the  case of the btree and hash access meth-
                 ods, insert the specified key/data pair into the
                 database.   If  the  key  already  exists in the
                 database, the inserted data item is added as the
                 first of the data items for that key.

                 The DB_KEYFIRST flag may not be specified to the
                 recno access method.

            DB_KEYLAST
                 Insert the  specified  key/data  pair  into  the
                 database.   If  the  key  already  exists in the
                 database, the inserted data item is added as the
                 last of the data items for that key.

                 The  DB_KEYLAST flag may not be specified to the
                 recno access method.

            If the cursor record has been deleted,  the  Dbc::put
            method will return DB_KEYEMPTY.

            Otherwise,  the  Dbc::put  method  throws  a DbExcep-
            tion(3) or returns the value of errno on failure  and
            0 on success.

       cursor or non-cursor operations in the same thread of con-
       trol  (i.e.,  thread  or  single-threaded  process),  will
       always  return  keys  in  order  and will return each non-
       deleted key/data pair  exactly  once.   Because  the  hash
       access  method uses a dynamic hashing algorithm, it cannot
       guarantee any form of stability in the presence of inserts
       and deletes unless locking is performed.

       If  locking was specified when the Db file was opened, but
       transactions are not in effect, the access methods provide
       repeatable  reads  with respect to the cursor.  That is, a
       DB_CURRENT call on the cursor is guaranteed to return  the
       same  record  as was returned on the last call to the cur-
       sor.

       In the presence of transactions, the access  method  calls
       between  DbTxnMgr::begin and DbTxn::abort or DbTxn::commit
       provide degree 3 consistency.  For all access  methods,  a
       cursor  scan  of the database performed within the context
       of a transaction is guaranteed  to  return  each  key/data
       pair  once  and  only  once, except in the following case.
       If, while performing a cursor scan using the  hash  access
       method,  the transaction performing the scan inserts a new
       pair into the database,  it  is  possible  that  duplicate
       key/data pairs will be returned.


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 Dbc::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: 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), memcpy(3), memmove(3), memset(3), realloc(3),
       and strerror(3).

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

       [EAGAIN]
            A lock was unavailable.

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

       The Dbc::del method may fail and throw a DbException(3) or
       return errno for any of the errors specified for the  fol-
            A lock was unavailable.

       [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 Dbc::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: Db::get(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), calloc(3),
       fcntl(2), fflush(3), malloc(3), memcmp(3), memcpy(3),
       memmove(3), memset(3), realloc(3), and strerror(3).

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

       [EAGAIN]
            A lock was unavailable.

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

            The  DB_THREAD  flag  was  specified  to the Db::open
            method described in Db(3) and neither the DB_DBT_MAL-
            LOC or DB_DBT_USERMEM flags were set in the Dbt.

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

       The Dbc::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 Dbc::put method  may  fail  and  throw  a
       DbException(3)  or  return  errno for the following condi-
       tions:

       [EACCES]
            An attempt was made to modify a read-only database.

       db_archive(1), db_checkpoint(1), db_deadlock(1), db_dump(1),
       db_load(1), db_recover(1), db_stat(1), db_intro(3), db_jump(3),
       db_thread(3), Db(3), Dbc(3), DbEnv(3), DbException(3), DbInfo(3),
       DbLock(3), DbLocktab(3), DbLog(3), DbLsn(3), DbMpool(3),
       DbMpoolFile(3), Dbt(3), DbTxn(3), DbTxnMgr(3)