Berkeley DB: Db::open
Description: Berkeley DB: An embedded database programmatic toolkit.
Keywords: embedded,database,programmatic,toolkit,b+tree,btr ee,hash,hashing,transaction,transactions,locking,logging,access method,access me thods,java,C,C++

# Db::open

`

###

    #include <db_cxx.h>

    static int
    Db::open(const char *fname, DBTYPE type, u_int32_t flags,
    	int mode, DbEnv *dbenv, DbInfo *dbinfo, Db **dbpp);

# Description

The Db::open function opens the database represented by file for both reading and writing. Files never intended to be shared or preserved on disk may be created by setting the file parameter to NULL.

Note, while most of the access methods use file as the name of an underlying file on disk, this is not guaranteed. Also, calling Db::open is a reasonably expensive operation. (This is based on a model where the DBMS keeps a set of files open for a long time rather than opening and closing them on each query.)

The type argument is of type DBTYPE and must be set to one of DB_BTREE, DB_HASH, DB_RECNO or DB_UNKNOWN. If type is DB_UNKNOWN, the database must already exist and Db::open will then determine if it is of type DB_BTREE, DB_HASH or DB_RECNO.

The Btree access method is a sorted, balanced tree structure storing associated key/data pairs. Searches, insertions, and deletions in the btree will all complete in O (lg base N) where base is the average number of keys per page. Often, inserting ordered data into btrees results in pages that are half-full. This implementation has been modified to make ordered (or inverse ordered) insertion the best case, resulting in nearly perfect page space utilization.

Space freed by deleting key/data pairs from the database is never reclaimed from the filesystem, although it is reused where possible. This means that the btree storage structure is grow-only. If sufficiently many keys are deleted from a tree that shrinking the underlying database file is desirable, this can be accomplished by creating a new tree from a scan of the existing one.

The Hash access method is an extensible, dynamic hashing scheme.

The Recno access method provides support for fixed and variable length records, optionally backed by a flat text (byte stream) file. Both fixed and variable length records are accessed by their logical record number.

It is valid to create a record whose record number is more than one greater than the last record currently in the database. For example, the creation of record number 8, when records 6 and 7 do not yet exist, is not an error. However, any attempt to retrieve such records (e.g., records 6 and 7) will return DB_KEYEMPTY.

Deleting a record will not, by default, renumber records following the deleted record (see the DB_RENUMBER flag for more information). Any attempt to retrieve deleted records will return DB_KEYEMPTY.

The flags and mode arguments specify how files will be opened and/or created if they do not already exist. The flags value is specified by logically OR'ing together one or more of the following values:

DB_CREATE
  Create any underlying files, as necessary. If the files do not already exist and the DB_CREATE flag is not specified, the call will fail.

DB_NOMMAP
  Do not map this file (see DbMpool::open 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_THREAD
  Cause the m4_reg(Db) handle returned by Db::open to be useable by multiple threads within a single address space, i.e., to be free-threaded.

DB_TRUNCATE
  Logically truncate the database if it exists, i.e., behave as if the database were just created, discarding any previous contents.

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.

When sharing a database environment with other processes, it is necessary to provide the access methods with database environment information. See DbEnv for a description of the dbenv argument.

Additionally, there is access method specific information that may be specified when calling Db::open. See DbInfo for a description of the db_info argument.

The Db::open method copies a pointer to a Db object into the memory location referenced by dbpp. The methods of this object allow you to perform various database actions. The methods are described in the following manual pages: Db::close, Db::cursor, Db::del, Db::fd, Db::get, Db::get_type, Db::put and Db::sync.

# Environment Variables

DB_HOME
  If the dbenv argument to Db::open was initialized using DbEnv::appinit the environment variable DB_HOME may be used as the path of the database home for the interpretation of the dir. Specifically, Db::open is affected by the configuration string value of DB_DATA_DIR.

# Errors

If a fatal error occurs in Berkeley DB, the Db::open method may fail and either return DB_RUNRECOVERY or throw an exception encapsulating DB_RUNRECOVERY, at which point all subsequent database calls will also fail in the same way. 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.

The Db::open method may fail and throw an exception for any of the errors specified for the following Berkeley DB and C library functions: Db::cursor, Db::sync, DBcursor->c_close(3), DBmemp->pgin(3), DBmemp->pgout(3), __account_page(3), abort(3), close(3), dbenv->db_paniccall(3), dbp->h_hash(3), fcntl(3), fflush(3), fprintf(3), free(3), fstat(3), fsync(3), func(3), getenv(3), getpid(3), getuid(3), isdigit(3), DbLockTab::get, DbLockTab::id, DbLock::put, DbLockTab::vec, DbLog::compare, DbLog::flush, DbLog::put, DbLog::db_register, DbLog::db_unregister, lseek(3), malloc(3), memcmp(3), memcpy(3), memmove(3), DbMpool::close, DbMpoolFile::close, DbMpoolFile::get, DbMpoolFile::open, DbMpoolFile::put, DbMpoolFile::set, DbMpoolFile::sync, DbMpool::open, DbMpool::db_register, memset(3), mmap(3), munmap(3), open(3), pread(3), pstat_getdynamic(3), pwrite(3), read(3), realloc(3), sigfillset(3), sigprocmask(3), stat(3), strerror(3), strlen(3), sysconf(3), time(3), unlink(3), vfprintf(3), vsnprintf(3), and write(3).

In addition, the Db::open method may fail and throw an exception or return errno for the following conditions:

EAGAIN
  A lock was unavailable.

EINVAL
  An invalid flag value or parameter was specified (e.g., unknown database type, page size, hash function, recno pad byte, byte order) or a flag value or parameter that is incompatible with the current file specification.

  The DB_THREAD flag was specified and spinlocks are not implemented for this architecture.

  There is a mismatch between the version number of file and the software.

  A re_source file was specified with either the DB_THREAD flag or a non-NULL tx_info field in the DB_ENV argument to Db::open.

ENOENT
  A non-existent re_source file was specified.

# Class

Db

# See Also

Db::close, Db::cursor, Db::del, Db::fd, Db::get, Db::get_byteswapped, Db::get_type, Db::join, Db::open, Db::put, Db::stat and Db::sync.`