*I#Berkeley DB: Db.open[P

Db.open





import com.sleepycat.db.*;

-public static Db open(String fname, int type,0int flags, int mode, DbEnv dbenv, DbInfo dbinfo) throws DbException;





Description



6The Db.open function opens the database represented by)file for both reading and writing.HFiles never intended to be shared or preserved on disk may be created by#setting the file parameter to null.

HNote, while most of the access methods use file as the name of an0underlying file on disk, this is not guaranteed.:Also, calling Db.open is a reasonably expensive operation.H(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.)

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

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

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

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

FThe Recno access method provides support for fixed and variable length=records, optionally backed by a flat text (byte stream) file.DBoth fixed and variable length records are accessed by their logicalrecord number.

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

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

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

^

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

Db.DB_NOMMAP
Do not map this file (see DbMpool.open for further information).:

Db.DB_RDONLY
Open the database for reading only.GAny attempt to modify items in the database will fail regardless of the+actual permissions of any underlying files.T

Db.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 befree-threaded.MNote, threading is assumed in the Java API, so no special flags are required,Tand Berkeley DB functions will always behave as if the DB_THREAD flag was specified.Z

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


WAll files created by the access methods are created with mode mode (as describedHin chmod(2)) and modified by the process' umask value at the time$of creation (see umask(2)))).IThe group ownership of created files is based on the system and directory6defaults, and is not further specified by Berkeley DB.

IWhen sharing a database environment with other processes, it is necessaryDto provide the access methods with database environment information.gSee DbEnv for a description of the dbenv argument.

EAdditionally, there is access method specific information that may bespecified when calling Db.open.kSee DbInfo for a description of the db_info argument.

The Db.open method?returns a Db object.IThe methods of this object allow you to perform various database actions.8The methods are described in the following manual pages:4Db.close,6Db.cursor,0Db.del,.Db.fd,0Db.get,:Db.get_type,/Db.putand2Db.sync.

Environment Variables





DB_HOME
=If the dbenv argument to Db.open was initialized usingiDbEnv.appinit the environment variable DB_HOME mayBbe used as the path of the database home for the interpretation of9the dir. Specifically, Db.open is affected by the*configuration string value of DB_DATA_DIR.




Errors

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

The Db.open&method may fail and throw an exceptionKfor any of the errors specified for the following Berkeley DB and C library functions:6Db.cursor,2Db.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,8DbLock.put,>DbLockTab.vec,>DbLog.compare,:DbLog.flush,6DbLog.put,FDbLog.db_register,JDbLog.db_unregister, lseek(3), malloc(3), memcmp(3), memcpy(3), memmove(3),>DbMpool.close,FDbMpoolFile.close,BDbMpoolFile.get,DDbMpoolFile.open,BDbMpoolFile.put,BDbMpoolFile.set,DDbMpoolFile.sync,<DbMpool.open,JDbMpool.db_register, memset(3),mmap(3), munmap(3),open(3), pread(3),apstat_getdynamic(3), pwrite(3),read(3), realloc(3),sigfillset(3),sigprocmask(3),sstat(3), strerror(3), strlen(3), sysconf(3),gtime(3), unlink(3), vfprintf(3), vsnprintf(3),vandn write(3).

wIn addition, the Db.open&method may fail and throw an exceptionencapsulating errnofor the following conditions:b

(

EAGAIN
A lock was unavailable.
r

e

Y

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

bFThe DB_THREAD flag was specified and spinlocks are not implemented forthis architecture.

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

eIA 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.D

ENOENT
A non-existent re_source file was specified.
_

.

Class

-Dbc

s

See Also

k4Db.close,6Db.cursor,0Db.del,.Db.fd,0Db.get,HDb.get_byteswapped,:Db.get_type,2Db.join,Db.open,0Db.put,1Db.stattandt2Db.sync.
r e˙˙that shrinking theBunderlying database file is desirable, this can be accomplished by4creating a new tree from a scan of the existing one.

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

FThe Recno access method provides sup