Db.open

APIRef

import com.sleepycat.db.*;

public void open(String name, String subname, int type, int flags, int mode) throws DbException;

Description

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 int and must be set to one of Db.DB_BTREE, Db.DB_HASH, Db.DB_QUEUE, Db.DB_RECNO or Db.DB_UNKNOWN. If type is Db.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.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.

Db.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.DB_EXCL
Return an error if the database already exists. Underlying filesystem primitives are used to implement this flag. For this reason it is only applicable to the physical database file and cannot be used to test if a subdatabase already exists.

The Db.DB_EXCL flag is only meaningful when specified with the Db.DB_CREATE flag.

Db.DB_NOMMAP
Do not map this database into process memory (see the description of the DbEnv.set_mp_mmapsize method for further information).

Db.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.DB_THREAD
Cause the Db handle returned by Db.open to be free-threaded, that is, useable by multiple threads within a single address space.

If the Db handle is opened within a threaded environment, it is not necessary to specify the Db.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.DB_DBT_MALLOC, Db.DB_DBT_REALLOC or Db.DB_DBT_USERMEM must be specified in Dbts used to retrieve key/data items), regardless of whether Db.DB_THREAD was specified to Db.open.

Threading is always assumed in the Java API, so no special flags are required, and Berkeley DB functions will always behave as if the Db.DB_THREAD flag was specified.

Db.DB_TRUNCATE
Physically truncate the underlying database file, discarding all previous subdatabases or databases. Underlying filesystem primitives are used to implement this flag. For this reason it is only applicable to the physical database file and cannot be used to discard subdatabases.

The Db.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 throws an exception that encapsulates a non-zero error value on failure.

Environment Variables

DB_HOME
If the dbenv argument to db_create was initialized using DbEnv.open 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.

TMPDIR
If the name and dbenv arguments to Db.open are null, the environment variable TMPDIR may be used as a directory in which to create a temporary backing file.

Errors

If a fatal error occurs in Berkeley DB, the Db.open method will fail and throw a DbRunRecoveryException, at which point all subsequent database calls will fail in the same way.

In addition, the Db.open method may fail and throw an exception encapsulating a non-zero error for the following conditions:

Db.DB_OLD_VERSION
The database cannot be opened without being first upgraded.

EEXIST
DB_CREATE and DB_EXCL were specified and the file exists.

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

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

A re_source file was specified with either the Db.DB_THREAD flag or the provided database environment supports transaction processing.

ENOENT
A non-existent re_source file was specified.

In addition, the Db.open method may fail and throw an exception for errors specified for other Berkeley DB and C library or system methods.

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.remove, Db.set_bt_minkey, Db.set_cachesize, Db.set_errcall, Db.set_errpfx, Db.set_flags, Db.set_h_ffactor, Db.set_h_nelem, Db.set_lorder, Db.set_pagesize, Db.set_re_delim, Db.set_re_len, Db.set_re_pad, Db.set_re_source, Db.stat, Db.sync and Db.upgrade.

APIRef

Copyright Sleepycat Software