Db::open |
![]() ![]() |
#include <db_cxx.h>int Db::open(const char *name, const char *subname, DBTYPE type, u_int32_t flags, int mode);
The currently supported Berkeley DB file formats (or access methods) are B+tree, 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 by sequentially or logical record number. The Recno format supports fixed- or variable-length records, accessed sequentially or by logical record number, and optionally retrieved from a flat text file.
Storage and retrieval for the Berkeley DB access methods are based on key/data pairs, see Dbt for more information.
The Db::open interface opens the database represented by name for both reading and writing. The argument name is used as the name of a single physical file on disk that will be used to back the database.
Files never intended to be shared or preserved on disk may be created by setting the name parameter to NULL.
The subname argument allows applications to have subdatabases, i.e., multiple databases inside of a single physical file. This is useful when the logical databases are both numerous and reasonably small, in order to avoid creating a large number of underlying files. It is an error to attempt to open a subdatabase in a database file that was not initially created using a subdatabase name. See the Opening a database section of the Reference Guide for more information.
The type argument 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.
The flags and mode arguments specify how files will be opened and/or created if they do not already exist.
The flags value must be set to 0 or by bitwise inclusively OR'ing together one or more of the following values.
The DB_EXCL flag is only meaningful when specified with the DB_CREATE flag.
If the Db handle is opened within a threaded environment, it is not necessary to specify the DB_THREAD flag, the Db handle will always be free-threaded. For this reason, Db handles opened in threaded environments must be treated as if they are free-threaded (e.g., DB_DBT_MALLOC, DB_DBT_REALLOC or DB_DBT_USERMEM must be specified in Dbts used to retrieve key/data items), regardless of whether DB_THREAD was specified to Db::open.
The DB_TRUNCATE flag cannot be transaction protected, and it is an error to specify it in a transaction protected environment.
On UNIX systems, or in IEEE/ANSI Std 1003.1 (POSIX) environments, all files created by the access methods 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)). The group ownership of created files is based on the system and directory defaults, and is not further specified by Berkeley DB. If mode is 0, files are created readable and writeable by both owner and group. On Windows systems, the mode argument is ignored.
Calling Db::open is a reasonably expensive operation, and maintaining a set of open databases will normally be preferable to repeatedly open 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.
In addition, the Db::open method may fail and throw an exception or return a non-zero error for the following conditions:
The DB_THREAD flag was specified and spinlocks are not implemented for this architecture.
A re_source file was specified with either the DB_THREAD flag or the provided database environment supports transaction processing.
In addition, the Db::open method may fail and throw an exception or return a non-zero error for errors specified for other Berkeley DB and C library or system methods.
![]() ![]() |