#include <db_cxx.h>
int
Db::open(DbTxn *txnid, const char *file,
const char *database, DBTYPE type, u_int32_t flags, int mode);
The Db::open() method opens the database represented by the
file and database.
The currently supported Berkeley DB file formats (or access methods) are Btree, Hash, Heap, Queue, and Recno. The Btree format is a representation of a sorted, balanced tree structure. The Hash format is an extensible, dynamic hashing scheme. The Queue format supports fast access to fixed-length records accessed sequentially or by logical record number. The Recno format supports fixed- or variable-length records, accessed sequentially or by logical record number, and optionally backed by a flat text file.
Storage and retrieval for the Berkeley DB access methods are based on key/data pairs; see Dbt for more information.
Calling Db::open() is a relatively expensive operation, and
maintaining a set of open databases will normally be preferable to
repeatedly opening and closing the database for each new query.
The Db::open()
method either returns a non-zero error value or throws an
exception that encapsulates a non-zero error value on
failure, and returns 0 on success.
If Db::open() fails, the
Db::close()
method must be
called to discard the Db
handle.
If the operation is part of an application-specified transaction, the txnid parameter is a transaction handle returned from DbEnv::txn_begin() ; if the operation is part of a Berkeley DB Concurrent Data Store group, the txnid parameter is a handle returned from DbEnv::cdsgroup_begin() ; otherwise NULL. If no transaction handle is specified, but the DB_AUTO_COMMIT flag is specified, the operation will be implicitly transaction protected. Note that transactionally protected operations on a Db handle requires the Db handle itself be transactionally protected during its open. Also note that the transaction must be committed before the handle is closed; see Berkeley DB handles for more information.
The file parameter is used as the name of an underlying file that will be used to back the database; see File naming for more information.
In-memory databases never intended to be preserved on disk may be created by setting the file parameter to NULL. Whether other threads of control can access this database is driven entirely by whether the database parameter is set to NULL.
When using a Unicode build on Windows (the default), the file argument will be interpreted as a UTF-8 string, which is equivalent to ASCII for Latin characters.
The database parameter is optional, and allows applications to have multiple databases in a single file. Although no database parameter needs to be specified, it is an error to attempt to open a second database in a file that was not initially created using a database name. Further, the database parameter is not supported by the Queue or Heap format. Finally, when opening multiple databases in the same physical file, it is important to consider locking and memory cache issues; see Opening multiple databases in a single file for more information.
If both the database and file parameters are NULL, the database is strictly temporary and cannot be opened by any other thread of control. Thus the database can only be accessed by sharing the single database handle that created it, in circumstances where doing so is safe.
If the database parameter is not set to NULL, the database can be opened by other threads of control and will be replicated to client sites in any replication group, regardless of whether the file parameter is set to NULL.
The type parameter is of
type DBTYPE, and must be set to one of
DB_BTREE, DB_HASH,
DB_HEAP, DB_QUEUE,
DB_RECNO, or DB_UNKNOWN.
If type is DB_UNKNOWN, the
database must already exist and
Db::open() will automatically
determine its type. The
Db::get_type()
method
may be used to determine the underlying type of databases opened using
DB_UNKNOWN.
It is an error to specify the incorrect type for a database that already exists.
The flags parameter must be set to zero or by bitwise inclusively OR'ing together one or more of the following values:
Enclose the Db::open()
call within a transaction. If the call succeeds,
the open operation will be recoverable and all
subsequent database modification operations based
on this handle will be transactionally protected.
If the call fails, no database will have been
created.
Create the database. If the database does not
already exist and the DB_CREATE
flag is not specified, the
Db::open() will fail.
Return an error if the database already exists. The
DB_EXCL flag is only meaningful
when specified with the DB_CREATE.
flag.
Open the database with support for
multiversion concurrency control.
This will cause updates to the database to follow a
copy-on-write protocol, which is required to
support snapshot isolation. The
DB_MULTIVERSION flag requires
that the database be transactionally protected
during its open and is not supported by the queue
format.
Do not map this database into process memory (see the DbEnv::set_mp_mmapsize() method for further information).
Open the database for reading only. Any attempt to modify items in the database will fail, regardless of the actual permissions of any underlying files.
Support transactional read operations with degree 1 isolation. Read operations on the database may request the return of modified but not yet committed data. This flag must be specified on all Db handles used to perform dirty reads or database updates, otherwise requests for dirty reads may not be honored and the read may block.
Open the database with slice support. If the set_slice_count DB_CONFIG parameter is not set, this flag is ignored. In addition, slice support must be configured for the database at compile time, or this flag is ignored.
If this flag is specified, then the
file parameter
must not be NULL and the database
parameter must be NULL. Also, the
type parameter
must be either DB_BTREE or
DB_HASH, or
DB_UNKNOWN when opening an
existing database.
This flag is optional when opening an existing database.
This flag can not be used if the supporting environment
was opened with the DB_INIT_REP and
DB_FAILCHK flags. Also, distributed
transactions can not be used with sliced databases.
Cause the Db
handle returned by
Db::open() to be
free-threaded; that is,
concurrently usable by multiple threads in the
address space. You should use this flag only in
the absence of an encompassing environment.
When opening the database within an encompassing environment, the database inherits the state of this flag from the environment. That is, if the encompassing environment is threaded, then the database will also be threaded. Note that it is an error to specify this flag to the database open if the encompassing environment is not threaded.
Note that this flag is incompatible with the Db::set_lk_exclusive() method.
Be aware that enabling this flag will serialize calls to DB when using the handle across threads. If concurrent scaling is important to your application we recommend opening separate handles for each thread (and not specifying this flag), rather than sharing handles between threads.
Physically truncate the underlying file, discarding all previous databases it might have held. Underlying filesystem primitives are used to implement this flag. For this reason, it is applicable only to the file and cannot be used to discard databases within a file.
The DB_TRUNCATE flag cannot be lock or
transaction-protected, and it is an error to specify it in a
locking or transaction-protected environment.
On Windows systems, the mode parameter is ignored.
On UNIX systems or in IEEE/ANSI Std 1003.1 (POSIX) environments, files created by the database open are created with mode mode (as described in chmod(2)) and modified by the process' umask value at the time of creation (see umask(2)). Created files are owned by the process owner; the group ownership of created files is based on the system and directory defaults, and is not further specified by Berkeley DB. System shared memory segments created by the database open are created with mode mode, unmodified by the process' umask value. If mode is 0, the database open will use a default mode of readable and writable by both owner and group.
If the database was opened within a database environment, the environment variable DB_HOME may be used as the path of the database environment home.
Db::open() is affected by any
database directory specified using the
DbEnv::add_data_dir()
method, or by setting the "add_data_dir" string in the
environment's DB_CONFIG file.
TMPDIR
If the file and
dbenv parameters to
Db::open() are
NULL, the environment variable
TMPDIR may be used as
a directory in which to create temporary backing files
The Db::open()
method may fail and throw a DbException
exception, encapsulating one of the following non-zero errors, or return one
of the following non-zero errors:
A transactional database environment operation was selected to resolve a deadlock.
DbDeadlockException is thrown if
your Berkeley DB API is configured to throw exceptions.
Otherwise, DB_LOCK_DEADLOCK is returned.
A Berkeley DB Concurrent Data Store database environment configured for lock timeouts was unable to grant a lock in the allowed time.
You attempted to open a database handle that is configured for no waiting exclusive locking, but the exclusive lock could not be immediately obtained. See Db::set_lk_exclusive() for more information.
DbLockNotGrantedException is thrown if
your Berkeley DB API is configured to throw exceptions.
Otherwise, DB_LOCK_NOTGRANTED is returned.
Checksum mismatch detected on a database metadata page. Either the database is corrupted or the file is not a Berkeley DB database file.
If an unknown database type, page size, hash function, pad
byte, byte order, or a flag value or parameter that is
incompatible with the specified database was specified; the
DB_THREAD
flag was specified and fast mutexes are not available for
this architecture; the
DB_THREAD
flag was specified to Db::open(),
but was not specified to the
DbEnv::open() call for the
environment in which the
Db handle was created; a
backing flat text file was specified with either the
DB_THREAD
flag or the provided database environment supports
transaction processing; a Heap database is in use and
Db::set_heapsize()
was used to set a heap size that is different from the value
used to create the database or an invalid heap region size was
set using
Db::set_heap_regionsize()
;
or if an invalid flag value or parameter was specified.
When a client synchronizes with the master, it is possible for committed
transactions to be rolled back. This invalidates all the database and cursor
handles opened in the replication environment. Once this occurs, an attempt to use
such a handle will
throw a DbRepHandleDeadException (if
your application is configured to throw exceptions), or
return DB_REP_HANDLE_DEAD.
The application will need to discard the handle and open a new one in order to
continue processing.
The operation was blocked by client/master synchronization.
DbDeadlockException is thrown if
your Berkeley DB API is configured to throw exceptions.
Otherwise, DB_REP_LOCKOUT is returned.