#include <db_cxx.h>

int
Db::open(DbTxn *txnid, const char *file,
    const char *database, DBTYPE type, u_int32_t flags, int mode);

int
Db::get_dbname(const char **filenamep, const char **dbnamep);

int
Db::get_multiple()

int
Db::get_open_flags(u_int32_t *flagsp);

int
Db::get_transactional()

The Db::open method opens the database represented by the file and database parameters for both reading and writing.

The currently supported Berkeley DB file formats (or access methods) are Btree, Hash, 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.

• 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 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.

  In-memory databases never intended to be preserved on disk may be created by setting the file parameter to NULL. If the database parameter is also 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.

• 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.

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 flags parameter must be set to 0 or by bitwise inclusively OR'ing together one or more of the following values:
  DB_AUTO_COMMIT
  • 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.
  DB_CREATE
  • Create the database. If the database does not already exist and the DB_CREATE flag is not specified, the Db::open will fail.
  DB_EXCL
  • Return an error if the database already exists. The DB_EXCL flag is only meaningful when specified with the DB_CREATE flag.
  DB_MULTIVERSION
  • 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.
  DB_NOMMAP
  • Do not map this database into process memory (see the DbEnv::set_mp_mmapsize method for further information).
  DB_RDONLY
  • 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.
  DB_READ_UNCOMMITTED
  • 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.
  DB_THREAD
  • Cause the Db handle returned by Db::open to be free-threaded; that is, concurrently usable by multiple threads in the address space.
  DB_TRUNCATE
  • 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 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 type parameter is of type DBTYPE, and must be set to one of DB_BTREE, DB_HASH, 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.

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::set_data_dir method, or by setting the "set_data_dir" string in the environment's DB_CONFIG file.

• 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 file or directory does not exist.

The Db::open method may fail and throw DbException, encapsulating one of the following non-zero errors, or return one of the following non-zero errors:

• The database cannot be opened without being first upgraded.

• DB_CREATE and DB_EXCL were specified and the database exists.

• 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; or if an invalid flag value or parameter was specified.

• A nonexistent re_source file was specified.

• The database handle has been invalidated because a replication election unrolled a committed transaction.

• The operation was blocked by client/master synchronization.

If a transactional database environment operation was selected to resolve a deadlock, the Db::open method will fail and either return DB_LOCK_DEADLOCK or throw a DbDeadlockException exception.

If a Berkeley DB Concurrent Data Store database environment configured for lock timeouts was unable to grant a lock in the allowed time, the Db::open method will fail and either return DB_LOCK_NOTGRANTED or throw a DbLockNotGrantedException exception.

The Db::get_dbname method returns the current filename and database name.

• The filenamep parameter references memory into which a pointer to the current filename is copied.

• The dbnamep parameter references memory into which a pointer to the current database name is copied.

The Db::get_dbname method may be called at any time during the life of the application.

The Db::get_dbname 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.

The Db::get_multiple method returns non-zero if the Db handle references a physical file supporting multiple databases.

In this case, the Db handle is a handle on a database whose key values are the names of the databases stored in the physical file and whose data values are opaque objects. No keys or data values may be modified or stored using the database handle.

The Db::get_multiple method may not be called before the Db::open method is called.

The Db::get_open_flags method returns the current open method flags.

The Db::get_open_flags method may not be called before the Db::open method is called.

The Db::get_open_flags 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.

• The Db::get_open_flags method returns the current open method flags in flagsp.

The Db::get_transactional method returns non-zero if the Db handle has been opened in a transactional mode.

The Db::get_transactional method may be called at any time during the life of the application.