# Dbc

           #include <db_cxx.h>

           int
           Dbc::close(void);

           int
           Dbc::del(u_int32_t flags);

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

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

## DESCRIPTION

           The  DB  library  is  a  family of classes that provides a
           modular programming interface to transactions and  record-
           oriented  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
           package, 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,
           cursors  are  only  valid  within  the context of a single
           transaction, the one specified during the Db::cursor  call
           described   in  Db(3).   All  cursor  operations  will  be
           executed 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 transactions, 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
           presence  of  locking, applications should discard cursors
           as soon as they are done with them.  Calling the Db::close
           method  (see  Db(3))  discards  any  cursors opened in the
           context of a particular Db object returned by the Db::open
           call.
           The methods of the Dbc are defined as follows:

           int Dbc::close();
                A  method  that  discards  the  cursor.   No  further
                references to the Dbc object should be made.

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

           int Dbc::del(u_int32_t 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, u_int32_t 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
                created 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
                section 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
                     values, the  first  data  item  in  the  set  of
                     duplicates is returned.

                     If  the  database  is empty, the Dbc::get method
                     will return DB_NOTFOUND.

                DB_LAST
                     The cursor is set to reference the last key/data
                     pair of the database, and that pair is returned.
                     In the presence of  duplicate  key  values,  the
                     last  data  item  in  the  set  of duplicates is
                     returned.

                     If the database is empty,  the  Dbc::get  method
                     will return DB_NOTFOUND.

                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
                     value of 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
                     values, the value of 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
                     The DB_SET_RANGE flag is identical to the DB_SET
                     flag, except that the key is returned as well as
                     the data item, and, in the  case  of  the  btree
                     access method, the returned key/data pair is the
                     smallest  key  greater  than  or  equal  to  the
                     specified  key  (as determined by the comparison
                     function), permitting partial  key  matches  and
                     range searches.

                DB_SET_RECNO
                     Move  the cursor to the specific numbered record
                     of  the  database,  and  return  the  associated
                     key/data  pair.  The data field of the specified
                     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
                DbException(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, u_int32_t 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
                     methods, insert the data element as a  duplicate
                     element  of  the  key  referenced by the cursor.
                     The new element appears  immediately  after  the
                     current  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
                     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_BEFORE
                     In  the  case  of  the  btree  and  hash  access
                     methods, insert the data element as a  duplicate
                     element  of  the  key  referenced by the cursor.
                     The new element appears immediately  before  the
                     current  cursor  position.   It  is  an error to
                     specify 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
                     automatically 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
                     referenced 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
                     methods, 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
                DbException(3)  or  returns  the  value  of  errno on
                failure and 0 on success.

                If Dbc::put fails for any reason, the  state  of  the
                cursor  will  be unchanged.  If Dbc::put succeeds and
                an item is inserted into the database, the cursor  is
                always  positioned  to  reference  the newly inserted
                item.

## CURSOR STABILITY

           In the absence of locking, no guarantees  are  made  about
           the   stability  of  cursors  in  different  processes  or
           threads.  However, the  btree  and  recno  access  methods
           guarantee  that cursor operations, interspersed with other
           cursor or non-cursor operations  in  the  same  thread  of
           control  (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
           cursor.

           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
           conditions:

           [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
           following DB and library functions: Db::del(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), memcpy(3), memmove(3),
           memset(3), realloc(3), and strerror(3).

           In  addition,  the  Dbc::del  method  may fail and throw a
           DbException(3)  or  return   errno   for   the   following
           conditions:

           [EAGAIN]
                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
           following 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
           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
                method   described   in   Db(3)   and   neither   the
                DB_DBT_MALLOC 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
           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), 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
           conditions:

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

           [EAGAIN]
                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.

## SEE ALSO

           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_internal(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)