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)