/I)Berkeley DB: DbEnv.appinit[P

DbEnv.appinit





import com.sleepycat.db.*;

9public DbEnv(String homeDir, String db_config, int flags) throws DbException;public DbEnv();@public void appinit(String homeDir, String db_config, int flags) throws DbException;





Description



JThe DbEnv.appinit method provides a simple way to initialize and configureKthe Berkeley DB environment. It is not necessary that it be called, but itHprovides a structure for creating a consistent environment for processes1using one or more of the features of Berkeley DB.

BThe db_home and db_config arguments to DbEnv.appinitQare described in Berkeley DB File Naming.

GThe flags argument specifies the subsystems that are initializedLand how the environment affects Berkeley DB file naming, among other things.ZThe flags value is specified by logically OR'ing together one or more of thefollowing values:

U

Db.DB_CREATE
Cause subsystems to create any underlying files, as necessary.

Db.DB_INIT_CDB
Initialize locking for the Berkeley DB Concurrent Access Methods product. In this mode, Berkeley DB providesAmultiple reader/single writer access. No other locking should bespecified (e.g., do not set Db.DB_INIT_LOCK). Access method calls~are largely unchanged when using the Db.DB_INIT_CDB flag, althougheany cursors through which update operations (e.g., Dbc.put,–Dbc.del) will be made, must have the Db.DB_RMW value set inDthe flags parameter to the cursor call that creates the cursor. SeeKDb.cursor for more information.<

Db.DB_INIT_LOCK
Initialize the lock subsystem; see6DbLock.JThis subsystem should be used when multiple processes or threads are goingOto be reading and writing a Berkeley DB database, so that they do not interfereIwith each other. If all threads are accessing the database(s) read-only,Ithen locking is unnecessary. When the DB_INIT_LOCK flag is specified, it@is usually necessary to run the deadlock detector, as well. See–db_deadlock and DbLockTab.detect for more information.:

Db.DB_INIT_LOG
Initialize the log subsystem; see4DbLog.GThis subsystem is used when recovery from application or system failureis necessary.]>

Db.DB_INIT_MPOOL
Initialize the mpool subsystem; see8DbMpool.OThis subsystem is used whenever the application is using the Berkeley DB accessmethods for any purpose.]B

Db.DB_INIT_TXN
Initialize the transaction subsystem; see4DbTxn.IThis subsystem is used when atomicity of multiple operations and recoveryBare important. The DB_INIT_TXN flag implies the DB_INIT_LOG flag.?

Db.DB_MPOOL_PRIVATE
Create a private memory pool; see8DbMpool./Ignored unless DB_INIT_MPOOL is also specified.T

Db.DB_NOMMAP
Do not memory map database files within this environment; see8DbMpool./Ignored unless DB_INIT_MPOOL is also specified.a

Db.DB_RECOVER
Run normal recovery on this environment before opening it for normal use.JIf this flag is set, the DB_CREATE flag must also be set since the regionswill be removed and recreated.

@The DbEnv.appinit function returns successfully if DB_RECOVER isBspecified and no log files exist, so it is necessary to ensure all8necessary log files are present before running recovery.“For further information, consult db_archive and db_recover.a

Db.DB_RECOVER_FATAL
Run catastrophic recovery on this environment before opening it forEnormal use. If this flag is set, the DB_CREATE flag must also be set0since the regions will be removed and recreated.

CThe DbEnv.appinit function returns successfully if DB_RECOVER_FATALEis specified and no log files exist, so it is necessary to ensure allEnecessary log files are present before running recovery. For further‡information, consult db_archive and db_recover.i

Db.DB_THREAD
Ensure that handles returned by the Berkeley DB subsystems are useable by multiple9threads within a single process, i.e., that the system isfree-threaded.

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

Db.DB_TXN_NOSYNC
On transaction commit, do not synchronously flush the log; see4DbTxn.-Ignored unless DB_INIT_TXN is also specified.k

Db.DB_USE_ENVIRON
The Berkeley DB process' environment may be permitted to specify information toNbe used when naming files; see Berkeley DBIFile Naming. As permitting users to specify which files are used canFcreate security problems, environment information will be used in file<naming for all users only if the DB_USE_ENVIRON flag is set.m

Db.DB_USE_ENVIRON_ROOT
The Berkeley DB process' environment may be permitted to specify informationQto be used when naming files; see Berkeley DBIFile Naming. As permitting users to specify which files are used canAcreate security problems, if the DB_USE_ENVIRON_ROOT flag is set,Henvironment information will be used for file naming only for users withFa user-ID matching that of the superuser (specifically, users for whom8the getuid(2) system call returns the user-ID 0).


)The Berkeley DB environment is configuredEbased on the dbenv argument. It is expected that applicationsjwill use a single DbEnv object as the argument to all of thetsubsystems in the Berkeley DB package. The fields of the DbEnv object*used by DbEnv.appinit are described below.nAny of the DbEnv fields that are not explicitly set will defaultto appropriate values.

pThe following fields in the DbEnv object may be initialized, using9the appropriate set method, before calling DbEnv.appinit:

r

DbPaniccall db_paniccall;
Errors can occur in the Berkeley DB library where the only solution is to shutNdown the application and run recovery. (For example, if Berkeley DB is unableGto write log records to disk because there is insufficient disk space.)oIIn these cases, the value DB_RUNRECOVERY is returned by the function. ItmHis often simpler, however, to simply shut down the application when suchGerrors occur instead of attempting to gracefully return error values upr the stack.

t<If db_paniccall is not null and such an error occurs,Jdb_paniccall.paniccall() will be called. This method takes two arguments.jThe dbenv argument is the current environment's DbEnvEobject, and the errval argument is the system errno value thatn%was returned when the error occurred.ni

DbErrcall db_errcall;
When an error occurs in the Berkeley DB library, an errno value isiAreturned by the method. In some cases, however, the errno Gvalue may be insufficient to completely describe the cause of the error 0especially during initial application debugging.

tDIf db_errcall is not null, db_errcall.errcall() may be calledIwith additional error information. This method takes two arguments. ThedDprefix argument is the current environment's db_errpfxBfield. The buffer argument is a string with the additional information.

fFThis error logging facility does not slow performance or significantlyDincrease application size, and may be run during normal operation aswell as during debugging. 

java.io.OutputStream error_stream;
The error_stream field behaves similarly to the db_errcalldfieldsallowing errors to be Hredirected to a C++ error stream. It is unwise to use both error_stream1with nonzero values of either errcall or errfile.ci

String db_errpfx;
A prefix to prepend to error messages. Because Berkeley DB does not copy thedHmemory referenced by the db_errpfx field, applications may modify%the error message prefix at any time. r`

int db_verbose;
Include informational and debugging messages as well as error messages6in the db_errcall and db_errfile output.
e

n6Each of the open functions that DbEnv.appinit may callŗ(DbLockTab.open, DbLog.open, DbMpool.open andiDbTxnMgr.open), is called as follows, where the DB_CREATErflag is optional:DE

;

GThis call will cause each subsystem to construct pathnames as describedoRin Berkeley DB File Naming. The subsystemChas permission to read and write underlying files as necessary, andeHoptionally to create files. (All created files will be created readableIand writeable by the owner and the group. The group ownership of creatednGfiles is based on the system and directory defaults, and is not furtherispecified by Berkeley DB.)

/FIn addition, the dbenv argument is passed to the open functionsDof any subsystems initialized by DbEnv.appinit. For this reason theifields of the DbEnv object relevant to the subsystems beingmBinitialized must themselves be initialized before DbEnv.appinit isHcalled. See the appropriate subsystem documentation for a list of thesefields and their uses.

eFThe return value from each of these calls is placed in the appropriateHfield of the DbEnv object:

w
DbLockTab lk_info;
The return value of the DbLockTab.open call.<k
DbLog lg_info;
The return value of the DbLog.open call.eq
DbMpool mp_info;
The return value of the DbMpool.open call.jt
DbTxnMgr tx_info;
The return value of the DbTxnMgr.open call.
y

dJIn general, these fields are not directly used by applications; subsystemsxof Berkeley DB that use these fields simply reference them using the DbEnvobject passed to the subsystem.i

n For example,Man application using the Berkeley DB hash access method functions to access at¨database will first call Db.open passing it the DbEnvgBargument initialized by a call to DbEnv.appinit. Then, all future@calls to the hash access method functions for that database willCautomatically use the underlying shared memory buffer pool that waseispecified by the mp_info field of that DbEnv object.L

uDThe single exception to this rule is the tx_info field, whichlapplications must explicitly specify to the DbTxnMgr.begin,–DbTxnMgr.checkpoint and DbTxnMgr.close methods.

fThe error_model field of DbEnv allows the user toNconfigure the way errors are treated in Berkeley DB, and may be changed at anyDtime, including after the call to DbEnv.appinit. The error model isUfurther described in DbException.h

nThe db_prefix field of DbEnv allows the user to configureIthe error message prefix, and may be changed at any time, including afterathe call to DbEnv.appinit.

fMOtherwise, once the Berkeley DB environment has been initialized by a call tor,DbEnv.appinit, no fields should be modified.

g

Architecture Notes

vIDue to the constraints of the PA-RISC memory architecture, HP-UX does notdDallow a process to map a file into its address space multiple times.JFor this reason, each Berkeley DB environment may be opened only once by a?process on HP-UX, i.e., calls to DbEnv.appinit will fail if therNspecified Berkeley DB environment has been opened and not subsequently closed.

GOn Windows/95, files that are opened by multiple processes do not shareaLdata correctly. To cause Berkeley DB to use the paging file to share memorywamong processes, use the DB_REGION_NAME flag of theoudb_value_set function. Obviously, you do not need to do this if 7only a single process will be accessing database files.t

bThe DbEnv.appinit_Hmethod throws an exception that encapsulates an errno on failure.

g

Errors

iUIf a fatal error occurs in Berkeley DB, the DbEnv.appinit method may fail and throw ai}DbRunRecoveryException, at which point all subsequent databaseb%calls will also fail in the same way.a

The DbEnv.appinit &method may fail and throw an exceptionKfor any of the errors specified for the following Berkeley DB and C libraryD functions:4Db.close, abort(3),< ctime(3),>DbEnv.appexit,dbenv->tx_recover(3),a fclose(3), fcntl(3),d fflush(3), fgets(3),l fopen(3),d fprintf(3),pfree(3), getenv(3), getpid(3), getuid(3), isspace(3),=@DbLockTab.open,DDbLockTab.unlink,>DbLog.compare,6DbLog.get,8DbLog.open,<DbLog.unlink, malloc(3), memcpy(3),<DbMpool.open,@DbMpool.unlink, memset(3), realloc(3), stat(3), strcat(3), strchr(3), strcmp(3), strcpy(3), strlen(3),time(3),JDbTxnMgr.checkpoint,>DbTxnMgr.open,BDbTxnMgr.unlink, vfprintf(3),andc vsnprintf(3).e

<In addition, the DbEnv.appinit&method may fail and throw an exceptionencapsulating errnofor the following conditions:u

B

EINVAL
An invalid flag value or parameter was specified.

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

d?The DB_HOME or TMPDIR environment variables were set but empty.i

CAn incorrectly formatted NAME VALUE entry or line was found.t

l

o

`

ENOSPC
HP-UX only: a previously created Berkeley DB environment for this process stillexists.o
s

o

Class

3DbEnvn

m

See Also

/DbEnv.appinit,>DbEnv.appexit,>DbEnv.version,dbenv_get_data_dir,ndbenv_get_errcall,dbenv_get_error_model,dbenv_get_error_stream,edbenv_get_errpfx,idbenv_get_flags,dbenv_get_home,tFDbEnv.get_lg_info,dbenv_get_lg_max,hdbenv_get_lk_conflicts,ldbenv_get_lk_detect,FDbEnv.get_lk_info,dbenv_get_lk_modes,vdbenv_get_log_dir,dbenv_get_lorder,aFDbEnv.get_mp_info,dbenv_get_mp_mmapsize,dbenv_get_mp_size,dbenv_get_tmp_dir,FDbEnv.get_tx_info,dbenv_get_tx_max,adbenv_get_tx_recoverandedbenv_get_verbose.
bno˙˙ational and debugging messages as well as error messages6in the db_errcall and db_errfile output.e

n6Each of the open functions that DbEnv.appinit may callŗ(DbLockTab.open, DbLog.open, DbMpool.open andiDbTxnMgr.open), is called as follows, where the DB_CREATErflag is