com.sleepycat.db
Class DbEnv

java.lang.Object
  |
  +--com.sleepycat.db.DbEnv

public class DbEnv

extends Object

The DbEnv object is the handle for a Berkeley DB environment -- a collection including support for some or all of caching, locking, logging and transaction subsystems, as well as databases and log files. Methods off the DbEnv handle are used to configure the environment as well as to operate on subsystems and databases in the environment.

DbEnv handles are free-threaded if the Db.DB_THREAD flag is specified to the DbEnv.open method when the environment is opened. The DbEnv handle should not be closed while any other handle remains open that is using it as a reference (for example, Db or DbTxn). Once either the DbEnv.close or DbEnv.remove methods are called, the handle may not be accessed again, regardless of the method's return.

Nested Class Summary

static class

DbEnv.RepProcessMessage

Constructor Summary

DbEnv(int flags)
The constructor creates the DbEnv object.

Method Summary

void	close(int flags) The DbEnv.close method closes the Berkeley DB environment, freeing any allocated resources and closing any underlying subsystems.
void	dbremove(DbTxn txnid, String file, String database, int flags) Deprecated. As of Berkeley DB 4.2, replaced by dbRemove(DbTxn,String,String,int)
void	dbRemove(DbTxn txnid, String file, String database, int flags) The DbEnv.dbRemove method removes the database specified by the file and database parameters.
void	dbrename(DbTxn txnid, String file, String database, String newname, int flags) Deprecated. As of Berkeley DB 4.2, replaced by dbRename(DbTxn,String,String,String,int)
void	dbRename(DbTxn txnid, String file, String database, String newname, int flags) The DbEnv.dbRename method renames the database specified by the file and database parameters to newname.
void	err(int error, String message) The DbEnv.err, DbEnv.errx, Db.err and Db.errx methods provide error-messaging functionality for applications written using the Berkeley DB library.
void	errx(String message) The DbEnv.errx and Db.errx methods perform identically to the DbEnv.err and Db.err methods, except that they do not append the final separator characters and standard error string to the error message.
int	get_cachesize_ncache() Deprecated. As of Berkeley DB 4.2, replaced by getCacheSizeNcache()
long	get_cachesize() Deprecated. As of Berkeley DB 4.2, replaced by getCacheSize()
String[]	get_data_dirs() Deprecated. As of Berkeley DB 4.2, replaced by getDataDirs()
int	get_encrypt_flags() Deprecated. As of Berkeley DB 4.2, replaced by getEncryptFlags()
String	get_errpfx() Deprecated. As of Berkeley DB 4.2, replaced by getErrorPrefix()
int	get_flags() Deprecated. As of Berkeley DB 4.2, replaced by getFlags()
String	get_home() Deprecated. As of Berkeley DB 4.2, replaced by getDbEnvHome()
int	get_lg_bsize() Deprecated. As of Berkeley DB 4.2, replaced by getLogBufferSize()
String	get_lg_dir() Deprecated. As of Berkeley DB 4.2, replaced by getLogDir()
int	get_lg_max() Deprecated. As of Berkeley DB 4.2, replaced by getLogMax()
int	get_lg_regionmax() Deprecated. As of Berkeley DB 4.2, replaced by getLogRegionMax()
byte[][]	get_lk_conflicts() Deprecated. As of Berkeley DB 4.2, replaced by getLockConflicts()
int	get_lk_detect() Deprecated. As of Berkeley DB 4.2, replaced by getLockDetect()
int	get_lk_max_lockers() Deprecated. As of Berkeley DB 4.2, replaced by getLockMaxLockers()
int	get_lk_max_locks() Deprecated. As of Berkeley DB 4.2, replaced by getLockMaxLocks()
int	get_lk_max_objects() Deprecated. As of Berkeley DB 4.2, replaced by getLockMaxObjects()
long	get_mp_mmapsize() Deprecated. As of Berkeley DB 4.2, replaced by getMemoryPoolMapSize()
int	get_open_flags() Deprecated. As of Berkeley DB 4.2, replaced by getOpenFlags()
long	get_rep_limit() Deprecated. As of Berkeley DB 4.2, replaced by getReplicationLimit()
long	get_shm_key() Deprecated. As of Berkeley DB 4.2, replaced by getSegmentId()
int	get_tas_spins() Deprecated. As of Berkeley DB 4.2, replaced by getTestAndSetSpins()
long	get_timeout(int flag) Deprecated. As of Berkeley DB 4.2, replaced by getTimeout(int)
String	get_tmp_dir() Deprecated. As of Berkeley DB 4.2, replaced by getTmpDir()
int	get_tx_max() Deprecated. As of Berkeley DB 4.2, replaced by getTxnMax()
long	get_tx_timestamp() Deprecated. As of Berkeley DB 4.2, replaced by getTxnTimestamp()
boolean	get_verbose(int which) Deprecated. As of Berkeley DB 4.2, replaced by getVerbose(int)
static int	get_version_major() Deprecated. As of Berkeley DB 4.2, replaced by getVersionMajor()
static int	get_version_minor() Deprecated. As of Berkeley DB 4.2, replaced by getVersionMinor()
static int	get_version_patch() Deprecated. As of Berkeley DB 4.2, replaced by getVersionPatch()
static String	get_version_string() Deprecated. As of Berkeley DB 4.2, replaced by getVersionString()
long	getCacheSize() The DbEnv.getCacheSize method returns the size of the cache.
int	getCacheSizeNcache() The DbEnv.getCacheSizeNcache method returns the number of caches.
String[]	getDataDirs() The DbEnv.getDataDirs method returns the array of directories.
String	getDbEnvHome() The DbEnv.getDbEnvHome method returns the database environment home directory.
int	getEncryptFlags() The DbEnv.getEncryptFlags method returns the encryption flags.
String	getErrorPrefix() The DbEnv.getErrorPrefix method returns the error prefix.
int	getFlags() The DbEnv.getFlags method returns the configuration flags.
byte[][]	getLockConflicts() The DbEnv.getLockConflicts method returns the conflicts array.
int	getLockDetect() The DbEnv.getLockDetect method returns the deadlock detector configuration.
int	getLockMaxLockers() The DbEnv.getLockMaxLockers method returns the maximum number of lockers.
int	getLockMaxLocks() The DbEnv.setLockMaxLocks method returns the maximum number of locks.
int	getLockMaxObjects() The DbEnv.getLockMaxObjects method returns the maximum number of locked objects.
int	getLogBufferSize() The DbEnv.getLogBufferSize method returns the size of the log buffer, in bytes.
String	getLogDir() The DbEnv.getLogDir method returns the log directory.
int	getLogMax() The DbEnv.getLogMax method returns the maximum log file size.
int	getLogRegionMax() The DbEnv.getLogRegionMax method returns the size of the underlying logging subsystem region.
long	getMemoryPoolMapSize() The DbEnv.getMemoryPoolMapSize method returns the maximum file map size.
int	getOpenFlags() The DbEnv.getOpenFlags method returns the open method flags.
long	getReplicationLimit() The DbEnv.getReplicationLimit method returns the transmit limit in bytes.
long	getSegmentId() The DbEnv.getSegmentId method returns the base segment ID.
int	getTestAndSetSpins() The DbEnv.getTestAndSetSpins method returns the test-and-set spin count.
long	getTimeout(int flag) The DbEnv.getTimeout method returns a timeout value, in microseconds.
String	getTmpDir() The DbEnv.getTmpDir method returns the database environment temporary file directory.
int	getTxnMax() The DbEnv.getTxnMax method returns the number of active transactions.
long	getTxnTimestamp() The DbEnv.getTxnTimestamp method returns the recovery timestamp.
boolean	getVerbose(int which) The DbEnv.getVerbose method returns whether the specified which parameter is currently set or not.
static int	getVersionMajor() The DbEnv.getVersionMajor method returns the release major number.
static int	getVersionMinor() The DbEnv.getVersionMinor method returns the release minor number.
static int	getVersionPatch() The DbEnv.getVersionPatch method returns the release patch number.
static String	getVersionString() The DbEnv.getVersionString method returns the release verbose version information, suitable for display.
int	lock_detect(int flags, int atype) Deprecated. As of Berkeley DB 4.2, replaced by lockDetect(int,int)
DbLock	lock_get(int locker, int flags, Dbt object, int lock_mode) Deprecated. As of Berkeley DB 4.2, replaced by lockGet(int,int,Dbt,int)
void	lock_id_free(int id) Deprecated. As of Berkeley DB 4.2, replaced by lockIdFree(int)
int	lock_id() Deprecated. As of Berkeley DB 4.2, replaced by lockId()
void	lock_put(DbLock lock) Deprecated. As of Berkeley DB 4.2, replaced by lockPut(DbLock)
DbLockStat	lock_stat(int flags) Deprecated. As of Berkeley DB 4.2, replaced by lockStat(int)
void	lock_vec(int locker, int flags, DbLockRequest[] list, int offset, int count) Deprecated. As of Berkeley DB 4.2, replaced by lockVector(int,int,DbLockRequest[],int,int)
int	lockDetect(int flags, int atype) The DbEnv.lockDetect method runs one iteration of the deadlock detector.
DbLock	lockGet(int locker, int flags, Dbt object, int lock_mode) The DbEnv.lockGet method acquires a lock from the lock table, returning information about it in a DbLock object.
int	lockId() The DbEnv.lockId method returns a locker ID, which is guaranteed to be unique in the specified lock table.
void	lockIdFree(int id) The DbEnv.lockIdFree method frees a locker ID allocated by the DbEnv.lockId method.
void	lockPut(DbLock lock) The DbEnv.lockPut method releases lock.
DbLockStat	lockStat(int flags) The DbEnv.lockStat method returns the locking subsystem statistics.
void	lockVector(int locker, int flags, DbLockRequest[] list, int offset, int count) The DbEnv.lockVector method atomically obtains and releases one or more locks from the lock table.
String[]	log_archive(int flags) Deprecated. As of Berkeley DB 4.2, replaced by logArchive(int)
static int	log_compare(DbLsn lsn0, DbLsn lsn1) Deprecated. As of Berkeley DB 4.2, replaced by logCompare(DbLsn,DbLsn)
DbLogc	log_cursor(int flags) Deprecated. As of Berkeley DB 4.2, replaced by logCursor(int)
String	log_file(DbLsn lsn) Deprecated. As of Berkeley DB 4.2, replaced by logFile(DbLsn)
void	log_flush(DbLsn lsn) Deprecated. As of Berkeley DB 4.2, replaced by logFlush(DbLsn)
void	log_put(DbLsn lsn, Dbt data, int flags) Deprecated. As of Berkeley DB 4.2, replaced by logPut(DbLsn,Dbt,int)
DbLogStat	log_stat(int flags) Deprecated. As of Berkeley DB 4.2, replaced by logStat(int)
String[]	logArchive(int flags) The DbEnv.logArchive method returns an array of log or database filenames.
static int	logCompare(DbLsn lsn0, DbLsn lsn1) The DbEnv.logCompare method allows the caller to compare two DbLsn objects, returning 0 if they are equal, 1 if lsn0 is greater than lsn1, and -1 if lsn0 is less than lsn1.
DbLogc	logCursor(int flags) The DbEnv.logCursor method returns a created log cursor.
String	logFile(DbLsn lsn) The DbEnv.logFile method maps DbLsn objects to filenames, returning the name of the file containing the record named by lsn.
void	logFlush(DbLsn lsn) The DbEnv.logFlush method writes log records to disk.
void	logPut(DbLsn lsn, Dbt data, int flags) The DbEnv.logPut method appends records to the log.
DbLogStat	logStat(int flags) The DbEnv.logStat method returns the logging subsystem statistics.
DbMpoolFStat[]	memoryPoolFileStat(int flags) The DbEnv.memoryPoolFileStat method creates an array of DbMpoolFStat objects containing statistics for individual files in the cache.
DbMpoolStat	memoryPoolStat(int flags) The DbEnv.memoryPoolStat method returns the memory pool (that is, the buffer cache) subsystem statistics.
int	memoryPoolTrickle(int percent) The DbEnv.memoryPoolTrickle method ensures that a specified percent of the pages in the shared memory pool are clean, by writing dirty pages to their backing files.
DbMpoolFStat[]	memp_fstat(int flags) Deprecated. As of Berkeley DB 4.2, replaced by memoryPoolFileStat(int)
DbMpoolStat	memp_stat(int flags) Deprecated. As of Berkeley DB 4.2, replaced by memoryPoolStat(int)
int	memp_trickle(int percent) Deprecated. As of Berkeley DB 4.2, replaced by memoryPoolTrickle(int)
void	open(String db_home, int flags, int mode) The DbEnv.open method opens a Berkeley DB environment.
void	remove(String db_home, int flags) The DbEnv.remove method destroys a Berkeley DB environment if it is not currently in use.
int	rep_elect(int nsites, int priority, int timeout) Deprecated. As of Berkeley DB 4.2, replaced by replicationElect(int,int,int)
int	rep_process_message(Dbt control, Dbt rec, DbEnv.RepProcessMessage envid, DbLsn ret_lsn) Deprecated. As of Berkeley DB 4.2, replaced by replicationProcessMessage(Dbt,Dbt,DbEnv.RepProcessMessage,DbLsn)
void	rep_start(Dbt cdata, int flags) Deprecated. As of Berkeley DB 4.2, replaced by replicationStart(Dbt,int)
DbRepStat	rep_stat(int flags) Deprecated. As of Berkeley DB 4.2, replaced by replicationStat(int)
int	replicationElect(int nsites, int priority, int timeout) The DbEnv.replicationElect method holds an election for the master of a replication group.
int	replicationProcessMessage(Dbt control, Dbt rec, DbEnv.RepProcessMessage envid, DbLsn ret_lsn) The DbEnv.replicationProcessMessage method processes an incoming replication message sent by a member of the replication group to the local database environment.
void	replicationStart(Dbt cdata, int flags) The DbEnv.replicationStart method configures the database environment as a client or master in a group of replicated database environments.
DbRepStat	replicationStat(int flags) The DbEnv.replicationStat method returns the replication subsystem statistics.
void	set_app_dispatch(DbAppDispatch tx_recover) Deprecated. As of Berkeley DB 4.2, replaced by setAppDispatch(DbAppDispatch)
void	set_cachesize(int gbytes, int bytes, int ncache) Deprecated. Replaced in Berkeley DB 4.2 by setCacheSize(long,int)
void	set_cachesize(long bytes, int ncache) Deprecated. As of Berkeley DB 4.2, replaced by setCacheSize(long,int)
void	set_data_dir(String dir) Deprecated. As of Berkeley DB 4.2, replaced by setDataDir(String)
void	set_encrypt(String passwd, int flags) Deprecated. As of Berkeley DB 4.2, replaced by setEncrypted(String,int)
void	set_errcall(DbErrcall db_errcall_fcn) Deprecated. Replaced in Berkeley DB 4.2 by setErrorHandler(DbErrorHandler)
void	set_error_stream(OutputStream stream) Deprecated. As of Berkeley DB 4.2, replaced by setErrorStream(java.io.OutputStream)
void	set_errpfx(String errpfx) Deprecated. As of Berkeley DB 4.2, replaced by setErrorPrefix(String)
void	set_feedback(DbEnvFeedback feedback) Deprecated. Replaced in Berkeley DB 4.2 by setFeedbackHandler(DbEnvFeedbackHandler)
void	set_flags(int flags, boolean onoff) Deprecated. As of Berkeley DB 4.2, replaced by setFlags(int,boolean)
void	set_lg_bsize(int lg_bsize) Deprecated. As of Berkeley DB 4.2, replaced by setLogBufferSize(int)
void	set_lg_dir(String dir) Deprecated. As of Berkeley DB 4.2, replaced by setLogDir(String)
void	set_lg_max(int lg_max) Deprecated. As of Berkeley DB 4.2, replaced by setLogMax(int)
void	set_lg_regionmax(int lg_regionmax) Deprecated. As of Berkeley DB 4.2, replaced by setLogRegionMax(int)
void	set_lk_conflicts(byte[][] conflicts) Deprecated. As of Berkeley DB 4.2, replaced by setLockConflicts(byte[][])
void	set_lk_detect(int detect) Deprecated. As of Berkeley DB 4.2, replaced by setLockDetect(int)
void	set_lk_max_lockers(int max) Deprecated. As of Berkeley DB 4.2, replaced by setLockMaxLockers(int)
void	set_lk_max_locks(int max) Deprecated. As of Berkeley DB 4.2, replaced by setLockMaxLocks(int)
void	set_lk_max_objects(int max) Deprecated. As of Berkeley DB 4.2, replaced by setLockMaxObjects(int)
void	set_mp_mmapsize(long mp_mmapsize) Deprecated. As of Berkeley DB 4.2, replaced by setMemoryPoolMapSize(long)
void	set_rep_limit(int gbytes, int bytes) Deprecated. Replaced in Berkeley DB 4.2 by setReplicationLimit(long)
void	set_rep_limit(long bytes) Deprecated. As of Berkeley DB 4.2, replaced by setReplicationLimit(long)
void	set_rep_transport(int envid, DbRepTransport send) Deprecated. As of Berkeley DB 4.2, replaced by setReplicationTransport(int,DbRepTransport)
void	set_rpc_server(DbClient client, String host, long cl_timeout, long sv_timeout, int flags) Deprecated. As of Berkeley DB 4.2, replaced by setRpcServer(DbClient,String,long,long,int)
void	set_shm_key(long shm_key) Deprecated. As of Berkeley DB 4.2, replaced by setSegmentId(long)
void	set_tas_spins(int tas_spins) Deprecated. As of Berkeley DB 4.2, replaced by setTestAndSetSpins(int)
void	set_timeout(long timeout, int flags) Deprecated. As of Berkeley DB 4.2, replaced by setTimeout(long,int)
void	set_tmp_dir(String dir) Deprecated. As of Berkeley DB 4.2, replaced by setTmpDir(String)
void	set_tx_max(int max) Deprecated. As of Berkeley DB 4.2, replaced by setTxnMax(int)
void	set_tx_timestamp(Date timestamp) Deprecated. As of Berkeley DB 4.2, replaced by setTxnTimestamp(java.util.Date)
void	set_verbose(int which, boolean onoff) Deprecated. As of Berkeley DB 4.2, replaced by setVerbose(int,boolean)
void	setAppDispatch(DbAppDispatch tx_recover)
void	setCacheSize(long bytes, int ncache) Set the size of the shared memory buffer pool -- that is, the cache.
void	setDataDir(String dir) Set the path of a directory to be used as the location of the access method database files.
void	setEncrypted(String passwd, int flags) Set the password used by the Berkeley DB library to perform encryption and decryption.
void	setErrorHandler(DbErrorHandler db_errcall_fcn) When an error occurs in the Berkeley DB library, an exception is thrown.
void	setErrorPrefix(String errpfx) Set the prefix string that appears before error messages issued by Berkeley DB.
void	setErrorStream(OutputStream stream) When an error occurs in the Berkeley DB library, an exception is thrown.
void	setFeedbackHandler(DbEnvFeedbackHandler db_feedback_fcn)
void	setFlags(int flags, boolean onoff) Configure a database environment.
void	setLockConflicts(byte[][] conflicts) Set the locking conflicts matrix.
void	setLockDetect(int detect) Set if the deadlock detector is to be run whenever a lock conflict occurs, and specify what lock request(s) should be rejected.
void	setLockMaxLockers(int max) Set the maximum number of locking entities supported by the Berkeley DB environment.
void	setLockMaxLocks(int max) Set the maximum number of locks supported by the Berkeley DB environment.
void	setLockMaxObjects(int max) Set the maximum number of locked objects supported by the Berkeley DB environment.
void	setLogBufferSize(int lg_bsize) Set the size of the in-memory log buffer, in bytes.
void	setLogDir(String dir) The path of a directory to be used as the location of logging files.
void	setLogMax(int lg_max) Set the maximum size of a single file in the log, in bytes.
void	setLogRegionMax(int lg_regionmax) Set the size of the underlying logging area of the Berkeley DB environment, in bytes.
void	setMemoryPoolMapSize(long mp_mmapsize) Files that are opened read-only in the pool (and that satisfy a few other criteria) are, by default, mapped into the process address space instead of being copied into the local cache.
void	setPanicHandler(DbPanicHandler db_panic_fcn)
void	setReplicationLimit(long bytes) The DbEnv.setReplicationLimit method imposes a byte-count limit on the amount of data that will be transmitted from a site in a single call to DbEnv.replicationProcessMessage method.
void	setReplicationTransport(int envid, DbRepTransport send)
void	setRpcServer(DbClient client, String host, long cl_timeout, long sv_timeout, int flags) Establishes a connection for this dbenv to a RPC server.
void	setSegmentId(long shm_key) Specify a base segment ID for Berkeley DB environment shared memory regions created in system memory on VxWorks or systems supporting X/Open-style shared memory interfaces; for example, UNIX systems supporting shmget(2) and related System V IPC interfaces.
void	setTestAndSetSpins(int tas_spins) Specify that test-and-set mutexes should spin tas_spins times without blocking.
void	setTimeout(long timeout, int flags) The DbEnv.setTimeout method sets timeout values for locks or transactions in the database environment.
void	setTmpDir(String dir) Specify the path of a directory to be used as the location of temporary files.
void	setTxnMax(int max) Configure the Berkeley DB database environment to support at least max active transactions.
void	setTxnTimestamp(Date timestamp) Recover to the time specified by timestamp rather than to the most current possible date.
void	setVerbose(int which, boolean onoff) The DbEnv.setVerbose method turns specific additional informational and debugging messages in the Berkeley DB message output on and off.
static String	strerror(int error) The DbEnv.strerror method returns an error message string corresponding to the error number error parameter.
DbTxn	txn_begin(DbTxn parent, int flags) Deprecated. As of Berkeley DB 4.2, replaced by txnBegin(DbTxn,int)
void	txn_checkpoint(int kbyte, int min, int flags) Deprecated. As of Berkeley DB 4.2, replaced by txnCheckpoint(int,int,int)
DbPreplist[]	txn_recover(int count, int flags) Deprecated. As of Berkeley DB 4.2, replaced by txnRecover(int,int)
DbTxnStat	txn_stat(int flags) Deprecated. As of Berkeley DB 4.2, replaced by txnStat(int)
DbTxn	txnBegin(DbTxn parent, int flags) The DbEnv.txnBegin method creates a new transaction in the environment and returns a DbTxn that uniquely identifies it.
void	txnCheckpoint(int kbyte, int min, int flags) The DbEnv.txnCheckpoint method flushes the underlying memory pool, writes a checkpoint record to the log, and then flushes the log.
DbPreplist[]	txnRecover(int count, int flags) The DbEnv.txnRecover method returns a list of prepared but not yet resolved transactions.
DbTxnStat	txnStat(int flags) The DbEnv.txnStat method returns the transaction subsystem statistics.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DbEnv

public DbEnv(int flags)
      throws DbException

The constructor creates the DbEnv object. The constructor allocates memory internally; calling the DbEnv.close or DbEnv.remove methods will free that memory.

Parameters:

flags - The following flags value may be specified:

• Db.DB_RPCCLIENT

  Create a client environment to connect to a server.

  The Db.DB_RPCCLIENT flag indicates to the system that this environment is remote on a server. The use of this flag causes the environment methods to use functions that call a server instead of local functions. Prior to making any environment or database method calls, the application must call the DbEnv.setRpcServer function to establish the connection to the server.

Throws:

DbException - Signals that an exception of some sort has occurred.

Method Detail

close

public void close(int flags)
           throws DbException

The DbEnv.close method closes the Berkeley DB environment, freeing any allocated resources and closing any underlying subsystems.

The DbEnv handle should not be closed while any other handle that refers to it is not yet closed; for example, database environment handles must not be closed while database handles remain open, or transactions in the environment have not yet been committed or aborted. Specifically, this includes Db, Dbc, DbTxn, DbLogc and DbMpoolFile handles.

Where the environment was initialized with the Db.DB_INIT_LOCK flag, calling DbEnv.close does not release any locks still held by the closing process, providing functionality for long-lived locks.

Where the environment was initialized with the Db.DB_INIT_TXN flag, calling DbEnv.close aborts any unresolved transactions. Applications should not depend on this behavior for transactions involving Berkeley DB databases; all such transactions should be explicitly resolved. The problem with depending on this semantic is that aborting an unresolved transaction involving database operations requires a database handle. Because the database handles should have been closed before calling DbEnv.close, it will not be possible to abort the transaction, and recovery will have to be run on the Berkeley DB environment before further operations are done.

Where log cursors were created using the DbEnv.logCursor method, calling DbEnv.close does not imply closing those cursors.

In multithreaded applications, only a single thread may call DbEnv.close.

After DbEnv.close has been called, regardless of its return, the Berkeley DB environment handle may not be accessed again.

Parameters:

flags - currently unused, and must be set to 0.

Throws:

DbException - Signals that an exception of some sort has occurred.

lock_vec

public void lock_vec(int locker,
                     int flags,
                     DbLockRequest[] list,
                     int offset,
                     int count)
              throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by lockVector(int,int,DbLockRequest[],int,int)

DbException

lockVector

public void lockVector(int locker,
                       int flags,
                       DbLockRequest[] list,
                       int offset,
                       int count)
                throws DbException

The DbEnv.lockVector method atomically obtains and releases one or more locks from the lock table. The DbEnv.lockVector method is intended to support acquisition or trading of multiple locks under one lock table semaphore, as is needed for lock coupling or in multigranularity locking for lock escalation.

If any of the requested locks cannot be acquired, or any of the locks to be released cannot be released, the operations before the failing operation are guaranteed to have completed successfully, and DbEnv.lockVector throws an exception

Parameters:

flags - must be set to 0 or the following value:

• Db.DB_LOCK_NOWAIT

  If a lock cannot be granted because the requested lock conflicts with an existing lock, throw a DbLockNotGrantedException immediately instead of waiting for the lock to become available. In this case, the index of the request that was not granted can be found by calling DbLockNotGrantedException.get_index.

locker - an unsigned 32-bit integer quantity. It represents the entity requesting or releasing the lock.

list - The list array provided to DbEnv.lockVector is a set of DbLockRequest objects. Only count elements of list starting at offset are considered by DbEnv.lockVector. A DbLockRequest object has at least the following fields:

A DB_LOCKREQ structure has at least the following fields:

The operation to be performed, which must be set to one of the following values:

• Db.DB_LOCK_GET

  Get the lock defined by the values of the mode and obj structure fields, for the specified locker. Upon return from DbEnv.lockVector, if the lock field is non-null, a reference to the acquired lock is stored there. (This reference is invalidated by any call to DbEnv.lockVector or DbEnv.lockPut that releases the lock.)

• Db.DB_LOCK_GET_TIMEOUT

  Identical to Db.DB_LOCK_GET except that the value in the timeout structure field overrides any previously specified timeout value for this lock. A value of 0 turns off any previously specified timeout.

• Db.DB_LOCK_PUT

  The lock to which the lock structure field refers is released. The locker parameter, and mode and obj fields are ignored.

• Db.DB_LOCK_PUT_ALL

  All locks held by the specified locker are released. The lock, mode, and obj structure fields are ignored. Locks acquired in operations performed by the current call to DbEnv.lockVector which appear before the Db.DB_LOCK_PUT_ALL operation are released; those acquired in operations appearing after the Db.DB_LOCK_PUT_ALL operation are not released.

• Db.DB_LOCK_PUT_OBJ

  All locks held on obj are released. The locker parameter and the lock and mode structure fields are ignored. Locks acquired in operations performed by the current call to DbEnv.lockVector that appear before the Db.DB_LOCK_PUT_OBJ operation are released; those acquired in operations appearing after the Db.DB_LOCK_PUT_OBJ operation are not released.

• Db.DB_LOCK_TIMEOUT

  Cause the specified locker to timeout immediately. If the database environment has not configured automatic deadlock detection, the transaction will timeout the next time deadlock detection is performed. As transactions acquire locks on behalf of a single locker ID, timing out the locker ID associated with a transaction will time out the transaction itself.

A lock reference.

The lock mode, used as an index into the environment's lock conflict matrix. When using the default lock conflict matrix, mode must be set to one of the following values:

• Db.DB_LOCK_READ

  read (shared)

• Db.DB_LOCK_WRITE

  write (exclusive)

• Db.DB_LOCK_IWRITE

  intention to write (shared)

• Db.DB_LOCK_IREAD

  intention to read (shared)

• Db.DB_LOCK_IWR

  intention to read and write (shared)

See DbEnv.setLockConflicts and Standard Lock Modes for more information on the lock conflict matrix.

An untyped byte string that specifies the object to be locked or released. Applications using the locking subsystem directly while also doing locking via the Berkeley DB access methods must take care not to inadvertently lock objects that happen to be equal to the unique file IDs used to lock files. See Access method locking conventions for more information.

The lock timeout value.

Throws:

DbException

DbDeadlockException - If a transactional database environment operation was selected to resolve a deadlock, the DbEnv.lockVector method will fail and throw a DbDeadlockException exception.

DbLockNotGrantedException - If a Berkeley DB Concurrent Data Store database environment configured for lock timeouts was unable to grant a lock in the allowed time, the DbEnv.lockVector method will fail and throw a DbLockNotGrantedException exception.

DbLockNotGrantedException - If the Db.DB_LOCK_NOWAIT flag or lock timers were configured and the lock could not be granted before the wait-time expired, the DbEnv.lockVector method will fail and throw a DbLockNotGrantedException exception.

IllegalArgumentException - The DbEnv.lockVector method will fail and throw a IllegalArgumentException exception if an invalid flag value or parameter was specified.

DbMemoryException - If the maximum number of locks has been reached, the DbEnv.lockVector method will fail and throw a DbMemoryException exception.

open

public void open(String db_home,
                 int flags,
                 int mode)
          throws DbException,
                 FileNotFoundException

The DbEnv.open method opens a Berkeley DB environment. It provides a structure for creating a consistent environment for processes using one or more of the features of Berkeley DB.

Parameters:

db_home - the database environment's home directory. For more information on db_home, and filename resolution in general, see Berkeley DB File Naming. The environment variable DB_HOME may be used as the path of the database home, as described in Berkeley DB File Naming.

flags - specifies the subsystems that are initialized and how the application's environment affects Berkeley DB file naming, among other things. The flags parameter must be set to 0 or by bitwise inclusively OR'ing together one or more of the following values:

Because there are a large number of flags that can be specified, they have been grouped together by functionality. The first group of flags indicates which of the Berkeley DB subsystems should be initialized:

• Db.DB_JOINENV

  Join an existing environment. This option allows applications to join an existing environment without knowing which Berkeley DB subsystems the environment supports.

• Db.DB_INIT_CDB

  Initialize locking for the Berkeley DB Concurrent Data Store product. In this mode, Berkeley DB provides multiple reader/single writer access. The only other subsystem that should be specified with the Db.DB_INIT_CDB flag is Db.DB_INIT_MPOOL.

• Db.DB_INIT_LOCK

  Initialize the locking subsystem. This subsystem should be used when multiple processes or threads are going to be reading and writing a Berkeley DB database, so that they do not interfere with each other. If all threads are accessing the database(s) read-only, locking is unnecessary. When the Db.DB_INIT_LOCK flag is specified, it is usually necessary to run a deadlock detector, as well. See db_deadlock and DbEnv.lockDetect for more information.

• Db.DB_INIT_LOG

  Initialize the logging subsystem. This subsystem should be used when recovery from application or system failure is necessary. If the log region is being created and log files are already present, the log files are reviewed; subsequent log writes are appended to the end of the log, rather than overwriting current log entries.

• Db.DB_INIT_MPOOL

  Initialize the shared memory buffer pool subsystem. This subsystem should be used whenever an application is using any Berkeley DB access method.

• Db.DB_INIT_REP

  Initialize the replication subsystem. This subsystem should be used whenever an application plans on using replication. The Db.DB_INIT_REP flag requires the Db.DB_INIT_TXN and Db.DB_INIT_LOCK flags also be configured.

• Db.DB_INIT_TXN

  Initialize the transaction subsystem. This subsystem should be used when recovery and atomicity of multiple operations are important. The Db.DB_INIT_TXN flag implies the Db.DB_INIT_LOG flag.

The second group of flags govern what recovery, if any, is performed when the environment is initialized:

• Db.DB_RECOVER

  Run normal recovery on this environment before opening it for normal use. If this flag is set, the Db.DB_CREATE flag must also be set because the regions will be removed and re-created.

• Db.DB_RECOVER_FATAL

  Run catastrophic recovery on this environment before opening it for normal use. If this flag is set, the Db.DB_CREATE flag must also be set because the regions will be removed and re-created.

A standard part of the recovery process is to remove the existing Berkeley DB environment and create a new one in which to perform recovery. If the thread of control performing recovery does not specify the correct region initialization information (for example, the correct memory pool cache size), the result can be an application running in an environment with incorrect cache and other subsystem sizes. For this reason, the thread of control performing recovery should specify correct configuration information before calling the DbEnv.open method; or it should remove the environment after recovery is completed, leaving creation of the correctly sized environment to a subsequent call to DbEnv.open.

All Berkeley DB recovery processing must be single-threaded; that is, only a single thread of control may perform recovery or access a Berkeley DB environment while recovery is being performed. Because it is not an error to specify Db.DB_RECOVER for an environment for which no recovery is required, it is reasonable programming practice for the thread of control responsible for performing recovery and creating the environment to always specify the Db.DB_CREATE and Db.DB_RECOVER flags during startup.

The DbEnv.open function returns successfully if Db.DB_RECOVER or Db.DB_RECOVER_FATAL is specified and no log files exist, so it is necessary to ensure that all necessary log files are present before running recovery. For further information, consult db_archive and db_recover.

The third group of flags govern file-naming extensions in the environment:

• Db.DB_USE_ENVIRON

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

• Db.DB_USE_ENVIRON_ROOT

  The Berkeley DB process' environment may be permitted to specify information to be used when naming files; see Berkeley DB File Naming. Because permitting users to specify which files are used can create security problems, if the Db.DB_USE_ENVIRON_ROOT flag is set, environment information will be used for file naming only for users with appropriate permissions (for example, users with a user-ID of 0 on UNIX systems).

Finally, there are a few additional unrelated flags:

• Db.DB_CREATE

  Cause Berkeley DB subsystems to create any underlying files, as necessary.

• Db.DB_LOCKDOWN

  Lock shared Berkeley DB environment files and memory-mapped databases into memory.

• Db.DB_PRIVATE

  Specify that the environment will only be accessed by a single process (although that process may be multithreaded). This flag has two effects on the Berkeley DB environment. First, all underlying data structures are allocated from per-process memory instead of from shared memory that is potentially accessible to more than a single process. Second, mutexes are only configured to work between threads.

  This flag should not be specified if more than a single process is accessing the environment because it is likely to cause database corruption and unpredictable behavior. For example, if both a server application and the Berkeley DB utility db_stat are expected to access the environment, the Db.DB_PRIVATE flag should not be specified.

• Db.DB_SYSTEM_MEM

  Allocate memory from system shared memory instead of from memory backed by the filesystem. See Shared Memory Regions for more information.

• Db.DB_THREAD

  Cause the DbEnv handle returned by DbEnv.open to be free-threaded; that is, usable by multiple threads within a single address space.

  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.

mode - On UNIX systems or in IEEE/ANSI Std 1003.1 (POSIX) environments, all files created by Berkeley DB 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)). If mode is 0, Berkeley DB will use a default mode of readable and writable by both owner and group. On Windows systems, the mode parameter is ignored. The group ownership of created files is based on the system and directory defaults, and is not further specified by Berkeley DB.

Throws:

DbException - The DbEnv.open method may fail and throw DbException, encapsulating one of the following non-zero errors:

The shared memory region was locked and (repeatedly) unavailable.

HP-UX only: a previously created Berkeley DB environment for this process still exists.

IllegalArgumentException - The DbEnv.open method will fail and throw a IllegalArgumentException exception if the Db.DB_THREAD flag was specified and fast mutexes are not available for this architecture; The DB_HOME or TMPDIR environment variables were set, but empty; An incorrectly formatted NAME VALUE entry or line was found; or if an invalid flag value or parameter was specified.

FileNotFoundException - If the file or directory does not exist, the DbEnv.open method will fail and throw a FileNotFoundException exception.

remove

public void remove(String db_home,
                   int flags)
            throws DbException,
                   FileNotFoundException

The DbEnv.remove method destroys a Berkeley DB environment if it is not currently in use. The environment regions, including any backing files, are removed. Any log or database files and the environment directory are not removed.

If there are processes that have called DbEnv.open without calling DbEnv.close (that is, there are processes currently using the environment), DbEnv.remove will fail without further action unless the Db.DB_FORCE flag is set, in which case DbEnv.remove will attempt to remove the environment, regardless of any processes still using it.

The result of attempting to forcibly destroy the environment when it is in use is unspecified. Processes using an environment often maintain open file descriptors for shared regions within it. On UNIX systems, the environment removal will usually succeed, and processes that have already joined the region will continue to run in that region without change. However, processes attempting to join the environment will either fail or create new regions. On other systems in which the unlink(2) system call will fail if any process has an open file descriptor for the file (for example Windows/NT), the region removal will fail.

Calling DbEnv.remove should not be necessary for most applications because the Berkeley DB environment is cleaned up as part of normal database recovery procedures. However, applications may want to call DbEnv.remove as part of application shut down to free up system resources. For example, if the Db.DB_SYSTEM_MEM flag was specified to DbEnv.open, it may be useful to call DbEnv.remove in order to release system shared memory segments that have been allocated. Or, on architectures in which mutexes require allocation of underlying system resources, it may be useful to call DbEnv.remove in order to release those resources. Alternatively, if recovery is not required because no database state is maintained across failures, and no system resources need to be released, it is possible to clean up an environment by simply removing all the Berkeley DB files in the database environment's directories.

In multithreaded applications, only a single thread may call DbEnv.remove.

A DbEnv handle that has already been used to open an environment should not be used to call the DbEnv.remove method; a new DbEnv handle should be created for that purpose.

After DbEnv.remove has been called, regardless of its return, the Berkeley DB environment handle may not be accessed again.

Parameters:

db_home - The db_home parameter names the database environment to be removed.

flags - must be set to 0 or by bitwise inclusively OR'ing together one or more of the following values:

• Db.DB_FORCE

  If the Db.DB_FORCE flag is set, the environment is removed, regardless of any processes that may still using it, and no locks are acquired during this process. (Generally, the Db.DB_FORCE flag is specified only when applications were unable to shut down cleanly, and there is a risk that an application may have died holding a Berkeley DB lock.)

• Db.DB_USE_ENVIRON

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

• Db.DB_USE_ENVIRON_ROOT

  The Berkeley DB process' environment may be permitted to specify information to be used when naming files; see Berkeley DB File Naming. Because permitting users to specify which files are used can create security problems, if the Db.DB_USE_ENVIRON_ROOT flag is set, environment information will be used for file naming only for users with appropriate permissions (for example, users with a user-ID of 0 on UNIX systems).

Throws:

DbException - The DbEnv.remove method may fail and throw DbException, encapsulating one of the following non-zero errors:

The shared memory region was in use and the force flag was not set.

FileNotFoundException - If the file or directory does not exist, the DbEnv.remove method will fail and throw a FileNotFoundException exception.

set_cachesize

public void set_cachesize(int gbytes,
                          int bytes,
                          int ncache)
                   throws DbException

Deprecated. Replaced in Berkeley DB 4.2 by setCacheSize(long,int)

DbException

get_errpfx

public String get_errpfx()

Deprecated. As of Berkeley DB 4.2, replaced by getErrorPrefix()

getErrorPrefix

public String getErrorPrefix()

The DbEnv.getErrorPrefix method returns the error prefix.

The DbEnv.getErrorPrefix method may be called at any time during the life of the application.

Returns:

The DbEnv.getErrorPrefix method returns the error prefix.

set_errcall

public void set_errcall(DbErrcall db_errcall_fcn)
                 throws DbException

Deprecated. Replaced in Berkeley DB 4.2 by setErrorHandler(DbErrorHandler)

DbException

set_error_stream

public void set_error_stream(OutputStream stream)

Deprecated. As of Berkeley DB 4.2, replaced by setErrorStream(java.io.OutputStream)

setErrorStream

public void setErrorStream(OutputStream stream)

When an error occurs in the Berkeley DB library, an exception is thrown. In some cases, however, the error information known to the Java layer may be insufficient to completely describe the cause of the error, especially during initial application debugging.

The DbEnv.setErrorStream and Db.setErrorStream methods are used to enhance the mechanism for reporting error messages to the application by setting a OutputStream to be used for displaying additional Berkeley DB error messages. In some cases, when an error occurs, Berkeley DB will output an additional error message to the specified stream.

The error message will consist of the prefix string and a colon (":") (if a prefix string was previously specified using DbEnv.setErrorPrefix), an error string, and a trailing <newline> character.

Alternatively, you can use the DbEnv.setErrorHandler method to capture the additional error information in a way that does not use output streams. You should not mix these approaches.

This error-logging enhancement does not slow performance or significantly increase application size, and may be run during normal operation as well as during application debugging.

Parameters:

stream - the application-specified output stream to be used for additional error information.

set_errpfx

public void set_errpfx(String errpfx)

Deprecated. As of Berkeley DB 4.2, replaced by setErrorPrefix(String)

setErrorPrefix

public void setErrorPrefix(String errpfx)

Set the prefix string that appears before error messages issued by Berkeley DB.

The DbEnv.setErrorPrefix method may be called at any time during the life of the application.

Parameters:

errpfx - the application-specified error prefix for additional error messages.

set_feedback

public void set_feedback(DbEnvFeedback feedback)
                  throws DbException

Deprecated. Replaced in Berkeley DB 4.2 by setFeedbackHandler(DbEnvFeedbackHandler)

DbException

set_rep_limit

public void set_rep_limit(int gbytes,
                          int bytes)
                   throws DbException

Deprecated. Replaced in Berkeley DB 4.2 by setReplicationLimit(long)

DbException

set_tx_timestamp

public void set_tx_timestamp(Date timestamp)
                      throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by setTxnTimestamp(java.util.Date)

DbException

setTxnTimestamp

public void setTxnTimestamp(Date timestamp)
                     throws DbException

Recover to the time specified by timestamp rather than to the most current possible date.

Once a database environment has been upgraded to a new version of Berkeley DB involving a log format change (see Upgrading Berkeley DB installations), it is no longer possible to recover to a specific time before that upgrade.

The DbEnv.setTxnTimestamp method configures operations performed using the specified DbEnv handle, not all operations performed on the underlying database environment.

The DbEnv.setTxnTimestamp method may not be called after the DbEnv.open method is called.

Parameters:

timestamp - references the memory location where the recovery timestamp is located.

Note that only the seconds (not the milliseconds) of the timestamp are used

Throws:

DbException

IllegalArgumentException - The DbEnv.setTxnTimestamp method will fail and throw a IllegalArgumentException exception if it is not possible to recover to the specified time using the log files currently present in the environment; or if an invalid flag value or parameter was specified.

dbremove

public void dbremove(DbTxn txnid,
                     String file,
                     String database,
                     int flags)
              throws DbException,
                     DbDeadlockException,
                     DbLockNotGrantedException,
                     FileNotFoundException

Deprecated. As of Berkeley DB 4.2, replaced by dbRemove(DbTxn,String,String,int)

DbException

DbDeadlockException

DbLockNotGrantedException

FileNotFoundException

dbRemove

public void dbRemove(DbTxn txnid,
                     String file,
                     String database,
                     int flags)
              throws DbException,
                     DbDeadlockException,
                     DbLockNotGrantedException,
                     FileNotFoundException

The DbEnv.dbRemove method removes the database specified by the file and database parameters. If no database is specified, the underlying file represented by file is removed, incidentally removing all of the databases it contained.

Applications should never remove databases with open Db handles, or in the case of removing a file, when any database in the file has an open handle. For example, some architectures do not permit the removal of files with open system handles. On these architectures, attempts to remove databases currently in use by any thread of control in the system will fail.

Environment Variables

The environment variable DB_HOME may be used as the path of the database environment home.

DbEnv.dbRemove is affected by any database directory specified using the DbEnv.setDataDir method, or by setting the "set_data_dir" string in the environment's DB_CONFIG file.

Parameters:

database - the database to be removed.

file - the physical file which contains the database(s) to be removed.

flags - must be set to 0 or the following value:

• Db.DB_AUTO_COMMIT

  Enclose the DbEnv.dbRemove call within a transaction. If the call succeeds, changes made by the operation will be recoverable. If the call fails, the operation will have made no changes.

txnid - If the operation is to be transaction-protected, the txnid parameter is a transaction handle returned from DbEnv.txnBegin; otherwise, null.

Throws:

DbException - The DbEnv.dbRemove method may fail and throw DbException, encapsulating one of the following non-zero errors:

An attempt was made to remove the underlying file and a database in the file was currently open.

DbDeadlockException - If a transactional database environment operation was selected to resolve a deadlock, the DbEnv.dbRemove method will fail and throw a DbDeadlockException exception.

DbLockNotGrantedException - If a Berkeley DB Concurrent Data Store database environment configured for lock timeouts was unable to grant a lock in the allowed time, the DbEnv.dbRemove method will fail and throw a DbLockNotGrantedException exception.

IllegalArgumentException - The DbEnv.dbRemove method will fail and throw a IllegalArgumentException exception if DbEnv.dbRemove called before DbEnv.open was called; or if an invalid flag value or parameter was specified.

FileNotFoundException - If the file or directory does not exist, the DbEnv.dbRemove method will fail and throw a FileNotFoundException exception.

dbrename

public void dbrename(DbTxn txnid,
                     String file,
                     String database,
                     String newname,
                     int flags)
              throws DbException,
                     DbDeadlockException,
                     DbLockNotGrantedException,
                     FileNotFoundException

Deprecated. As of Berkeley DB 4.2, replaced by dbRename(DbTxn,String,String,String,int)

DbException

DbDeadlockException

DbLockNotGrantedException

FileNotFoundException

dbRename

public void dbRename(DbTxn txnid,
                     String file,
                     String database,
                     String newname,
                     int flags)
              throws DbException,
                     DbDeadlockException,
                     DbLockNotGrantedException,
                     FileNotFoundException

The DbEnv.dbRename method renames the database specified by the file and database parameters to newname. If no database is specified, the underlying file represented by file is renamed, incidentally renaming all of the databases it contained.

Applications should not rename databases that are currently in use. If an underlying file is being renamed and logging is currently enabled in the database environment, no database in the file may be open when the DbEnv.dbRename method is called. In particular, some architectures do not permit renaming files with open handles. On these architectures, attempts to rename databases that are currently in use by any thread of control in the system will fail.

Environment Variables

The environment variable DB_HOME may be used as the path of the database environment home.

DbEnv.dbRename is affected by any database directory specified using the DbEnv.setDataDir method, or by setting the "set_data_dir" string in the environment's DB_CONFIG file.

Parameters:

database - the database to be removed.

file - the physical file which contains the database(s) to be removed.

flags - must be set to 0 or the following value:

• Db.DB_AUTO_COMMIT

  Enclose the DbEnv.dbRename call within a transaction. If the call succeeds, changes made by the operation will be recoverable. If the call fails, the operation will have made no changes.

newname - the new name of the database or file.

txnid - If the operation is to be transaction-protected, the txnid parameter is a transaction handle returned from DbEnv.txnBegin; otherwise, null.

Throws:

DbException - The DbEnv.dbRename method may fail and throw DbException, encapsulating one of the following non-zero errors:

An attempt was made to rename the underlying file and a database in the file was currently open.

DbDeadlockException - If a transactional database environment operation was selected to resolve a deadlock, the DbEnv.dbRename method will fail and throw a DbDeadlockException exception.

DbLockNotGrantedException - If a Berkeley DB Concurrent Data Store database environment configured for lock timeouts was unable to grant a lock in the allowed time, the DbEnv.dbRename method will fail and throw a DbLockNotGrantedException exception.

IllegalArgumentException - The DbEnv.dbRename method will fail and throw a IllegalArgumentException exception if DbEnv.dbRename called before DbEnv.open was called; or if an invalid flag value or parameter was specified.

FileNotFoundException - If the file or directory does not exist, the DbEnv.dbRename method will fail and throw a FileNotFoundException exception.

err

public void err(int error,
                String message)

The DbEnv.err, DbEnv.errx, Db.err and Db.errx methods provide error-messaging functionality for applications written using the Berkeley DB library.

The DbEnv.err method constructs an error message consisting of the following elements:

If no error callback function has been set using the DbEnv.setErrorHandler method, any prefix string specified using the DbEnv.setErrorPrefix method, followed by two separating characters: a colon and a <space> character.

Two separating characters: a colon and a <space> character.

The standard system or Berkeley DB library error string associated with the error value, as returned by the DbEnv.strerror method.

This constructed error message is then handled as follows:

If an error callback function has been set (see Db.setErrorHandler and DbEnv.setErrorHandler), that function is called with two parameters: any prefix string specified (see Db.setErrorPrefix and DbEnv.setErrorPrefix) and the error message.

If an OutputStream has been set (see DbEnv.setErrorStream and Db.setErrorStream), the error message is written to that stream.

If none of these output options has been configured, the error message is written to System.err, the standard error output stream.

Parameters:

error - the error value for which the DbEnv.err and Db.err methods will display a explanatory string.

message - an error message to display.

errx

public void errx(String message)

The DbEnv.errx and Db.errx methods perform identically to the DbEnv.err and Db.err methods, except that they do not append the final separator characters and standard error string to the error message.

Parameters:

message - an error message to display.

get_data_dirs

public String[] get_data_dirs()
                       throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by getDataDirs()

DbException

getDataDirs

public String[] getDataDirs()
                     throws DbException

The DbEnv.getDataDirs method returns the array of directories.

The DbEnv.getDataDirs method may be called at any time during the life of the application.

Returns:

The DbEnv.getDataDirs method returns the array of directories.

Throws:

DbException - Signals that an exception of some sort has occurred.

get_encrypt_flags

public int get_encrypt_flags()
                      throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by getEncryptFlags()

DbException

getEncryptFlags

public int getEncryptFlags()
                    throws DbException

The DbEnv.getEncryptFlags method returns the encryption flags.

The DbEnv.getEncryptFlags method may be called at any time during the life of the application.

Returns:

The DbEnv.getEncryptFlags method returns the encryption flags.

Throws:

DbException - Signals that an exception of some sort has occurred.

get_flags

public int get_flags()
              throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by getFlags()

DbException

getFlags

public int getFlags()
             throws DbException

The DbEnv.getFlags method returns the configuration flags.

The DbEnv.getFlags method may be called at any time during the life of the application.

Returns:

The DbEnv.getFlags method returns the configuration flags.

Throws:

DbException - Signals that an exception of some sort has occurred.

get_home

public String get_home()
                throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by getDbEnvHome()

DbException

getDbEnvHome

public String getDbEnvHome()
                    throws DbException

The DbEnv.getDbEnvHome method returns the database environment home directory.

The DbEnv.getDbEnvHome method may be called at any time during the life of the application.

Returns:

The DbEnv.getDbEnvHome method returns the database environment home directory.

Throws:

DbException - Signals that an exception of some sort has occurred.

get_open_flags

public int get_open_flags()
                   throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by getOpenFlags()

DbException

getOpenFlags

public int getOpenFlags()
                 throws DbException

The DbEnv.getOpenFlags method returns the open method flags.

The DbEnv.getOpenFlags method may not be called before the DbEnv.open method has been called.

Returns:

The DbEnv.getOpenFlags method returns the open method flags.

Throws:

DbException - Signals that an exception of some sort has occurred.

get_shm_key

public long get_shm_key()
                 throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by getSegmentId()

DbException

getSegmentId

public long getSegmentId()
                  throws DbException

The DbEnv.getSegmentId method returns the base segment ID.

The DbEnv.getSegmentId method may be called at any time during the life of the application.

Returns:

The DbEnv.getSegmentId method returns the base segment ID.

Throws:

DbException - Signals that an exception of some sort has occurred.

get_tas_spins

public int get_tas_spins()
                  throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by getTestAndSetSpins()

DbException

getTestAndSetSpins

public int getTestAndSetSpins()
                       throws DbException

The DbEnv.getTestAndSetSpins method returns the test-and-set spin count.

The DbEnv.getTestAndSetSpins method may be called at any time during the life of the application.

Returns:

The DbEnv.getTestAndSetSpins method returns the test-and-set spin count.

Throws:

DbException - Signals that an exception of some sort has occurred.

get_tmp_dir

public String get_tmp_dir()
                   throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by getTmpDir()

DbException

getTmpDir

public String getTmpDir()
                 throws DbException

The DbEnv.getTmpDir method returns the database environment temporary file directory.

The DbEnv.getTmpDir method may be called at any time during the life of the application.

Returns:

The DbEnv.getTmpDir method returns the database environment temporary file directory.

Throws:

DbException - Signals that an exception of some sort has occurred.

get_verbose

public boolean get_verbose(int which)
                    throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by getVerbose(int)

DbException

getVerbose

public boolean getVerbose(int which)
                   throws DbException

The DbEnv.getVerbose method returns whether the specified which parameter is currently set or not.

The DbEnv.getVerbose method may be called at any time during the life of the application.

Parameters:

which - the message value for which configuration is being checked.

Returns:

The DbEnv.getVerbose method returns whether the specified which parameter is currently set or not.

Throws:

DbException - Signals that an exception of some sort has occurred.

set_cachesize

public void set_cachesize(long bytes,
                          int ncache)
                   throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by setCacheSize(long,int)

DbException

setCacheSize

public void setCacheSize(long bytes,
                         int ncache)
                  throws DbException

Set the size of the shared memory buffer pool -- that is, the cache. The cache should be the size of the normal working data set of the application, with some small amount of additional memory for unusual situations. (Note: the working set is not the same as the number of pages accessed simultaneously, and is usually much larger.)

The default cache size is 256KB, and may not be specified as less than 20KB. Any cache size less than 500MB is automatically increased by 25% to account for buffer pool overhead; cache sizes larger than 500MB are used as specified. The current maximum size of a single cache is 4GB. (All sizes are in powers-of-two, that is, 256KB is 2^32 not 256,000.) For information on tuning the Berkeley DB cache size, see Selecting a cache size.

It is possible to specify caches to Berkeley DB larger than 4GB and/or large enough they cannot be allocated contiguously on some architectures. For example, some releases of Solaris limit the amount of memory that may be allocated contiguously by a process. If ncache is 0 or 1, the cache will be allocated contiguously in memory. If it is greater than 1, the cache will be broken up into ncache equally sized, separate pieces of memory.

The database environment's cache size may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_cachesize", one or more whitespace characters, and the cache size specified in three parts: the gigabytes of cache, the additional bytes of cache, and the number of caches, also separated by whitespace characters. For example, "set_cachesize 2 524288000 3" would create a 2.5GB logical cache, split between three physical caches. Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.

The DbEnv.setCacheSize method configures a database environment, not only operations performed using the specified DbEnv handle.

The DbEnv.setCacheSize method may not be called after the DbEnv.open method is called. If the database environment already exists when DbEnv.open is called, the information specified to DbEnv.setCacheSize will be ignored.

Parameters:

bytes - The size of the cache in bytes.

ncache - the number of caches to create.

Throws:

DbException

IllegalArgumentException - The DbEnv.setCacheSize method will fail and throw a IllegalArgumentException exception if the specified cache size was impossibly small; the method was called after DbEnv.open was called; or if an invalid flag value or parameter was specified.

set_data_dir

public void set_data_dir(String dir)
                  throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by setDataDir(String)

DbException

setDataDir

public void setDataDir(String dir)
                throws DbException

Set the path of a directory to be used as the location of the access method database files. Paths specified to the Db.open function will be searched relative to this path. Paths set using this method are additive, and specifying more than one will result in each specified directory being searched for database files. If any directories are specified, created database files will always be created in the first path specified.

If no database directories are specified, database files can exist only in the environment home directory. See Berkeley DB File Naming for more information.

For the greatest degree of recoverability from system or application failure, database files and log files should be located on separate physical devices.

The database environment's data directories may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_data_dir", one or more whitespace characters, and the directory name.

The DbEnv.setDataDir method configures operations performed using the specified DbEnv handle, not all operations performed on the underlying database environment.

The DbEnv.setDataDir method may not be called after the DbEnv.open method is called. If the database environment already exists when DbEnv.open is called, the information specified to DbEnv.setDataDir must be consistent with the existing environment or corruption can occur.

Parameters:

dir - a directory to be used as a location for database files.

Throws:

DbException

IllegalArgumentException - The DbEnv.setDataDir method will fail and throw a IllegalArgumentException exception if the method was called after DbEnv.open was called; or if an invalid flag value or parameter was specified.

set_encrypt

public void set_encrypt(String passwd,
                        int flags)
                 throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by setEncrypted(String,int)

DbException

setEncrypted

public void setEncrypted(String passwd,
                         int flags)
                  throws DbException

Set the password used by the Berkeley DB library to perform encryption and decryption.

The DbEnv.setEncrypted method configures a database environment, not only operations performed using the specified DbEnv handle.

The DbEnv.setEncrypted method may not be called after the DbEnv.open method is called. If the database environment already exists when DbEnv.open is called, the information specified to DbEnv.setEncrypted must be consistent with the existing environment or an error will be returned.

Parameters:

flags - must be set to 0 or the following value:

• Db.DB_ENCRYPT_AES

  Use the Rijndael/AES (also known as the Advanced Encryption Standard and Federal Information Processing Standard (FIPS) 197) algorithm for encryption or decryption.

passwd - the password used to perform encryption and decryption.

Throws:

DbException - The DbEnv.setEncrypted method may fail and throw DbException, encapsulating one of the following non-zero errors:

Cryptography is not available in this Berkeley DB release.

IllegalArgumentException - The DbEnv.setEncrypted method will fail and throw a IllegalArgumentException exception if the method was called after DbEnv.open was called; or if an invalid flag value or parameter was specified.

setErrorHandler

public void setErrorHandler(DbErrorHandler db_errcall_fcn)
                     throws DbException

When an error occurs in the Berkeley DB library, an exception is thrown. In some cases, however, the errno value may be insufficient to completely describe the cause of the error, especially during initial application debugging.

The DbEnv.setOnError and Db.setErrorHandler methods are used to enhance the mechanism for reporting error messages to the application. The DbEnv.setOnError and Db.setErrorHandler methods must be called with a single object parameter. The object's class must implement the DbErrorHandler interface.

In some cases, when an error occurs, Berkeley DB will invoke the object's errcall() method with two parameters; the first is the prefix string (as previously set by Db.setErrorPrefix or DbEnv.setErrorPrefix), the second will be an error message string. It is up to this method to display the message in an appropriate manner.

Alternatively, you can use the DbEnv.setErrorStream and Db.setErrorStream methods to display the additional information via an output stream. You should not mix these approaches.

This error-logging enhancement does not slow performance or significantly increase application size, and may be run during normal operation as well as during application debugging.

The DbEnv.setOnError method may be called at any time during the life of the application.

Parameters:

db_errcall_fcn - the application-specified error reporting function. The function takes two parameters:

The errpfx parameter is the prefix string (as previously set by Db.setErrorPrefix or DbEnv.setErrorPrefix).

The msg parameter is the error message string.

Throws:

DbException - Signals that an exception of some sort has occurred.

set_flags

public void set_flags(int flags,
                      boolean onoff)
               throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by setFlags(int,boolean)

DbException

setFlags

public void setFlags(int flags,
                     boolean onoff)
              throws DbException

Configure a database environment.

The database environment's flag values may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_flags", one or more whitespace characters, and the method flag parameter as a string; for example, "set_flags DB_TXN_NOSYNC". Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.

Parameters:

flags - must be set by bitwise inclusively OR'ing together one or more of the following values:

• Db.DB_AUTO_COMMIT

  If set, operations for which no explicit transaction handle was specified, and which modify databases in the database environment, will be automatically enclosed within a transaction. If the call succeeds, changes made by the operation will be recoverable. If the call fails, the operation will have made no changes.

  Calling DbEnv.setFlags with the Db.DB_AUTO_COMMIT flag only affects the specified DbEnv handle (and any other Berkeley DB handles opened within the scope of that handle). For consistent behavior across the environment, all DbEnv handles opened in the environment must either set the Db.DB_AUTO_COMMIT flag or the flag should be specified in the DB_CONFIG configuration file.

  The Db.DB_AUTO_COMMIT flag may be used to configure Berkeley DB at any time during the life of the application.

• Db.DB_CDB_ALLDB

  If set, Berkeley DB Concurrent Data Store applications will perform locking on an environment-wide basis rather than on a per-database basis.

  Calling DbEnv.setFlags with the Db.DB_CDB_ALLDB flag only affects the specified DbEnv handle (and any other Berkeley DB handles opened within the scope of that handle). For consistent behavior across the environment, all DbEnv handles opened in the environment must either set the Db.DB_CDB_ALLDB flag or the flag should be specified in the DB_CONFIG configuration file.

  The Db.DB_CDB_ALLDB flag may be used to configure Berkeley DB only before the DbEnv.open method is called.

• Db.DB_DIRECT_DB

  Turn off system buffering of Berkeley DB database files to avoid double caching.

  Calling DbEnv.setFlags with the Db.DB_DIRECT_DB flag only affects the specified DbEnv handle (and any other Berkeley DB handles opened within the scope of that handle). For consistent behavior across the environment, all DbEnv handles opened in the environment must either set the Db.DB_DIRECT_DB flag or the flag should be specified in the DB_CONFIG configuration file.

  The Db.DB_DIRECT_DB flag may be used to configure Berkeley DB at any time during the life of the application.

• Db.DB_DIRECT_LOG

  Turn off system buffering of Berkeley DB log files to avoid double caching.

  Calling DbEnv.setFlags with the Db.DB_DIRECT_LOG flag only affects the specified DbEnv handle (and any other Berkeley DB handles opened within the scope of that handle). For consistent behavior across the environment, all DbEnv handles opened in the environment must either set the Db.DB_DIRECT_LOG flag or the flag should be specified in the DB_CONFIG configuration file.

  The Db.DB_DIRECT_LOG flag may be used to configure Berkeley DB at any time during the life of the application.

• Db.DB_LOG_AUTOREMOVE

  If set, Berkeley DB will automatically remove log files that are no longer needed. Automatic log file removal is likely to make catastrophic recovery impossible.

  Calling DbEnv.setFlags with the Db.DB_LOG_AUTOREMOVE flag only affects the specified DbEnv handle (and any other Berkeley DB handles opened within the scope of that handle). For consistent behavior across the environment, all DbEnv handles opened in the environment must either set the Db.DB_LOG_AUTOREMOVE flag or the flag should be specified in the DB_CONFIG configuration file.

  The Db.DB_LOG_AUTOREMOVE flag may be used to configure Berkeley DB at any time during the life of the application.

• Db.DB_NOLOCKING

  If set, Berkeley DB will grant all requested mutual exclusion mutexes and database locks without regard for their actual availability. This functionality should never be used for purposes other than debugging.

  Calling DbEnv.setFlags with the Db.DB_NOLOCKING flag only affects the specified DbEnv handle (and any other Berkeley DB handles opened within the scope of that handle).

  The Db.DB_NOLOCKING flag may be used to configure Berkeley DB at any time during the life of the application.

• Db.DB_NOMMAP

  If set, Berkeley DB will copy read-only database files into the local cache instead of potentially mapping them into process memory (see the description of the DbEnv.setMemoryPoolMapSize method for further information).

  Calling DbEnv.setFlags with the Db.DB_NOMMAP flag only affects the specified DbEnv handle (and any other Berkeley DB handles opened within the scope of that handle). For consistent behavior across the environment, all DbEnv handles opened in the environment must either set the Db.DB_NOMMAP flag or the flag should be specified in the DB_CONFIG configuration file.

  The Db.DB_NOMMAP flag may be used to configure Berkeley DB at any time during the life of the application.

• Db.DB_NOPANIC

  If set, Berkeley DB will ignore any panic state in the database environment. (Database environments in a panic state normally refuse all attempts to call Berkeley DB functions, returning Db.DB_RUNRECOVERY.) This functionality should never be used for purposes other than debugging.

  Calling DbEnv.setFlags with the Db.DB_NOPANIC flag only affects the specified DbEnv handle (and any other Berkeley DB handles opened within the scope of that handle).

  The Db.DB_NOPANIC flag may be used to configure Berkeley DB at any time during the life of the application.

• Db.DB_OVERWRITE

  Overwrite files stored in encrypted formats before deleting them. Berkeley DB overwrites files using alternating 0xff, 0x00 and 0xff byte patterns. For file overwriting to be effective, the underlying file must be stored on a fixed-block filesystem. Systems with journaling or logging filesystems will require operating system support and probably modification of the Berkeley DB sources.

  Calling DbEnv.setFlags with the Db.DB_OVERWRITE flag only affects the specified DbEnv handle (and any other Berkeley DB handles opened within the scope of that handle).

  The Db.DB_OVERWRITE flag may be used to configure Berkeley DB at any time during the life of the application.

• Db.DB_PANIC_ENVIRONMENT

  If set, Berkeley DB will set the panic state for the database environment. (Database environments in a panic state normally refuse all attempts to call Berkeley DB functions, returning Db.DB_RUNRECOVERY.) This flag may not be specified using the environment's DB_CONFIG file. This flag may be used to configure Berkeley DB only after the DbEnv.open method is called.

  Calling DbEnv.setFlags with the Db.DB_PANIC_ENVIRONMENT flag affects the database environment, including all threads of control accessing the database environment.

  The Db.DB_PANIC_ENVIRONMENT flag may be used to configure Berkeley DB at any time during the life of the application.

• Db.DB_REGION_INIT

  In some applications, the expense of page-faulting the underlying shared memory regions can affect performance. (For example, if the page-fault occurs while holding a lock, other lock requests can convoy, and overall throughput may decrease.) If set, Berkeley DB will page-fault shared regions into memory when initially creating or joining a Berkeley DB environment. In addition, Berkeley DB will write the shared regions when creating an environment, forcing the underlying virtual memory and filesystems to instantiate both the necessary memory and the necessary disk space. This can also avoid out-of-disk space failures later on.

  Calling DbEnv.setFlags with the Db.DB_REGION_INIT flag only affects the specified DbEnv handle (and any other Berkeley DB handles opened within the scope of that handle). For consistent behavior across the environment, all DbEnv handles opened in the environment must either set the Db.DB_REGION_INIT flag or the flag should be specified in the DB_CONFIG configuration file.

  The Db.DB_REGION_INIT flag may be used to configure Berkeley DB at any time during the life of the application.

• Db.DB_TIME_NOTGRANTED

  If set, database calls timing out based on lock or transaction timeout values will throw a DbLockNotGrantedException exception instead of DbDeadlockException. This allows applications to distinguish between operations which have deadlocked and operations which have exceeded their time limits.

  Calling DbEnv.setFlags with the Db.DB_TIME_NOTGRANTED flag only affects the specified DbEnv handle (and any other Berkeley DB handles opened within the scope of that handle). For consistent behavior across the environment, all DbEnv handles opened in the environment must either set the Db.DB_TIME_NOTGRANTED flag or the flag should be specified in the DB_CONFIG configuration file.

  The Db.DB_TIME_NOTGRANTED flag may be used to configure Berkeley DB at any time during the life of the application.

• Db.DB_TXN_NOSYNC

  If set, Berkeley DB will not write or synchronously flush the log on transaction commit. This means that transactions exhibit the ACI (atomicity, consistency, and isolation) properties, but not D (durability); that is, database integrity will be maintained, but if the application or system fails, it is possible some number of the most recently committed transactions may be undone during recovery. The number of transactions at risk is governed by how many log updates can fit into the log buffer, how often the operating system flushes dirty buffers to disk, and how often the log is checkpointed.

  Calling DbEnv.setFlags with the Db.DB_TXN_NOSYNC flag only affects the specified DbEnv handle (and any other Berkeley DB handles opened within the scope of that handle). For consistent behavior across the environment, all DbEnv handles opened in the environment must either set the Db.DB_TXN_NOSYNC flag or the flag should be specified in the DB_CONFIG configuration file.

  The Db.DB_TXN_NOSYNC flag may be used to configure Berkeley DB at any time during the life of the application.

• Db.DB_TXN_NOT_DURABLE

  If set, Berkeley DB will not write log records. This means that transactions exhibit the ACI (atomicity, consistency, and isolation) properties, but not D (durability); that is, database integrity will be maintained, but if the application or system fails, integrity will not persist. All database files must be verified and/or restored from backup after a failure. In order to ensure integrity after application shut down, all database handles must be closed without specifying Db.DB_NOSYNC, or all database changes must be flushed from the database environment cache using the DbEnv.txnCheckpoint method.

  Calling DbEnv.setFlags with the Db.DB_TXN_NOT_DURABLE flag only affects the specified DbEnv handle (and any other Berkeley DB handles opened within the scope of that handle). For consistent behavior across the environment, all DbEnv handles opened in the environment must either set the Db.DB_TXN_NOT_DURABLE flag or the flag should be specified in the DB_CONFIG configuration file.

  The Db.DB_TXN_NOT_DURABLE flag may be used to configure Berkeley DB at any time during the life of the application.

• Db.DB_TXN_WRITE_NOSYNC

  If set, Berkeley DB will write, but will not synchronously flush, the log on transaction commit. This means that transactions exhibit the ACI (atomicity, consistency, and isolation) properties, but not D (durability); that is, database integrity will be maintained, but if the system fails, it is possible some number of the most recently committed transactions may be undone during recovery. The number of transactions at risk is governed by how often the system flushes dirty buffers to disk and how often the log is checkpointed.

  Calling DbEnv.setFlags with the Db.DB_TXN_WRITE_NOSYNC flag only affects the specified DbEnv handle (and any other Berkeley DB handles opened within the scope of that handle). For consistent behavior across the environment, all DbEnv handles opened in the environment must either set the Db.DB_TXN_WRITE_NOSYNC flag or the flag should be specified in the DB_CONFIG configuration file.

  The Db.DB_TXN_WRITE_NOSYNC flag may be used to configure Berkeley DB at any time during the life of the application.

• Db.DB_YIELDCPU

  If set, Berkeley DB will yield the processor immediately after each page or mutex acquisition. This functionality should never be used for purposes other than stress testing.

  Calling DbEnv.setFlags with the Db.DB_YIELDCPU flag only affects the specified DbEnv handle (and any other Berkeley DB handles opened within the scope of that handle). For consistent behavior across the environment, all DbEnv handles opened in the environment must either set the Db.DB_YIELDCPU flag or the flag should be specified in the DB_CONFIG configuration file.

  The Db.DB_YIELDCPU flag may be used to configure Berkeley DB at any time during the life of the application.

onoff - If the onoff parameter is false, the specified flags are cleared; otherwise they are set.

Throws:

DbException

IllegalArgumentException - The DbEnv.setFlags method will fail and throw a IllegalArgumentException exception if an invalid flag value or parameter was specified.

setFeedbackHandler

public void setFeedbackHandler(DbEnvFeedbackHandler db_feedback_fcn)
                        throws DbException

DbException

set_mp_mmapsize

public void set_mp_mmapsize(long mp_mmapsize)
                     throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by setMemoryPoolMapSize(long)

DbException

setMemoryPoolMapSize

public void setMemoryPoolMapSize(long mp_mmapsize)
                          throws DbException

Files that are opened read-only in the pool (and that satisfy a few other criteria) are, by default, mapped into the process address space instead of being copied into the local cache. This can result in better-than-usual performance because available virtual memory is normally much larger than the local cache, and page faults are faster than page copying on many systems. However, it can cause resource starvation in the presence of limited virtual memory, and it can result in immense process sizes in the presence of large databases.

The DbEnv.getMemoryPoolMapSize method sets the maximum file size, in bytes, for a file to be mapped into the process address space. If no value is specified, it defaults to 10MB.

The database environment's maximum mapped file size may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_mp_mmapsize", one or more whitespace characters, and the size in bytes. Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.

The DbEnv.setMemoryPoolMapSize method configures operations performed using the specified DbEnv handle, not all operations performed on the underlying database environment.

The DbEnv.setMemoryPoolMapSize method may be called at any time during the life of the application.

Parameters:

mp_mmapsize - the maximum file size, in bytes, for a file to be mapped into the process address space.

Throws:

DbException

IllegalArgumentException - The DbEnv.setMemoryPoolMapSize method will fail and throw a IllegalArgumentException exception if the method was called after DbEnv.open was called; or if an invalid flag value or parameter was specified.

setPanicHandler

public void setPanicHandler(DbPanicHandler db_panic_fcn)
                     throws DbException

DbException

set_rpc_server

public void set_rpc_server(DbClient client,
                           String host,
                           long cl_timeout,
                           long sv_timeout,
                           int flags)
                    throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by setRpcServer(DbClient,String,long,long,int)

DbException

setRpcServer

public void setRpcServer(DbClient client,
                         String host,
                         long cl_timeout,
                         long sv_timeout,
                         int flags)
                  throws DbException

Establishes a connection for this dbenv to a RPC server.

The DbEnv.setRpcServer method configures operations performed using the specified DbEnv handle, not all operations performed on the underlying database environment.

The DbEnv.setRpcServer method may not be called after the DbEnv.open method is called.

Parameters:

cl_timeout - specifies the number of seconds the client should wait for results to come back from the server. Once the timeout has expired on any communication with the server, Db.DB_NOSERVER will be returned. If this value is zero, a default timeout is used.

client - reserved for future use. If it is not NULL, an exception is thrown.

host - the host to which the Berkeley DB server will connect and create a channel for communication.

flags - currently unused, and must be set to 0.

sv_timeout - specifies the number of seconds the server should allow a client connection to remain idle before assuming that the client is gone. Once that timeout has been reached, the server releases all resources associated with that client connection. Subsequent attempts by that client to communicate with the server result in Db.DB_NOSERVER_ID, indicating that an invalid identifier has been given to the server. This value can be considered a hint to the server. The server may alter this value based on its own policies or allowed values. If this value is zero, a default timeout is used.

Throws:

DbException

IllegalArgumentException - The DbEnv.setRpcServer method will fail and throw a IllegalArgumentException exception if an invalid flag value or parameter was specified.

set_shm_key

public void set_shm_key(long shm_key)
                 throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by setSegmentId(long)

DbException

setSegmentId

public void setSegmentId(long shm_key)
                  throws DbException

Specify a base segment ID for Berkeley DB environment shared memory regions created in system memory on VxWorks or systems supporting X/Open-style shared memory interfaces; for example, UNIX systems supporting shmget(2) and related System V IPC interfaces.

This base segment ID will be used when Berkeley DB shared memory regions are first created. It will be incremented a small integer value each time a new shared memory region is created; that is, if the base ID is 35, the first shared memory region created will have a segment ID of 35, and the next one will have a segment ID between 36 and 40 or so. A Berkeley DB environment always creates a master shared memory region; an additional shared memory region for each of the subsystems supported by the environment (Locking, Logging, Memory Pool and Transaction); plus an additional shared memory region for each additional memory pool cache that is supported. Already existing regions with the same segment IDs will be removed. See Shared Memory Regions for more information.

The intent behind this method is two-fold: without it, applications have no way to ensure that two Berkeley DB applications don't attempt to use the same segment IDs when creating different Berkeley DB environments. In addition, by using the same segment IDs each time the environment is created, previously created segments will be removed, and the set of segments on the system will not grow without bound.

The database environment's base segment ID may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_shm_key", one or more whitespace characters, and the ID. Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.

The DbEnv.setSegmentId method configures operations performed using the specified DbEnv handle, not all operations performed on the underlying database environment.

The DbEnv.setSegmentId method may not be called after the DbEnv.open method is called. If the database environment already exists when DbEnv.open is called, the information specified to DbEnv.setSegmentId must be consistent with the existing environment or corruption can occur.

Parameters:

shm_key - the base segment ID for the database environment.

Throws:

DbException

IllegalArgumentException - The DbEnv.setSegmentId method will fail and throw a IllegalArgumentException exception if the method was called after DbEnv.open was called; or if an invalid flag value or parameter was specified.

set_tas_spins

public void set_tas_spins(int tas_spins)
                   throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by setTestAndSetSpins(int)

DbException

setTestAndSetSpins

public void setTestAndSetSpins(int tas_spins)
                        throws DbException

Specify that test-and-set mutexes should spin tas_spins times without blocking. The value defaults to 1 on uniprocessor systems and to 50 times the number of processors on multiprocessor systems.

The database environment's test-and-set spin count may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_tas_spins", one or more whitespace characters, and the number of spins. Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.

The DbEnv.setTestAndSetSpins method configures operations performed using the specified DbEnv handle, not all operations performed on the underlying database environment.

The DbEnv.setTestAndSetSpins method may be called at any time during the life of the application.

Parameters:

tas_spins - the number of spins test-and-set mutexes should execute before blocking.

Throws:

DbException

IllegalArgumentException - The DbEnv.setTestAndSetSpins method will fail and throw a IllegalArgumentException exception if an invalid flag value or parameter was specified.

set_timeout

public void set_timeout(long timeout,
                        int flags)
                 throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by setTimeout(long,int)

DbException

setTimeout

public void setTimeout(long timeout,
                       int flags)
                throws DbException

The DbEnv.setTimeout method sets timeout values for locks or transactions in the database environment.

Timeouts are checked whenever a thread of control blocks on a lock or when deadlock detection is performed. (In the case of Db.DB_SET_LOCK_TIMEOUT, the lock is one requested explicitly through the Lock subsystem interfaces. In the case of Db.DB_SET_TXN_TIMEOUT, the lock is one requested on behalf of a transaction. In either case, it may be a lock requested by the database access methods underlying the application.) As timeouts are only checked when the lock request first blocks or when deadlock detection is performed, the accuracy of the timeout depends on how often deadlock detection is performed.

Timeout values specified for the database environment may be overridden on a per-lock or per-transaction basis. See DbEnv.lockVector and DbTxn.setTimeout for more information.

The DbEnv.setTimeout method configures a database environment, not only operations performed using the specified DbEnv handle.

The DbEnv.setTimeout method may be called at any time during the life of the application.

Parameters:

flags - must be set to one of the following values:

• Db.DB_SET_LOCK_TIMEOUT

  Set the timeout value for locks in this database environment.

  The database environment's lock timeout value may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_lock_timeout", one or more whitespace characters, and the lock timeout value. Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.

• Db.DB_SET_TXN_TIMEOUT

  Set the timeout value for transactions in this database environment.

  The database environment's transaction timeout value may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_txn_timeout", one or more whitespace characters, and the transaction timeout value. Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.

timeout - the timeout value. It must be specified as an unsigned 32-bit number of microseconds, limiting the maximum timeout to roughly 71 minutes.

Throws:

DbException

IllegalArgumentException - The DbEnv.setTimeout method will fail and throw a IllegalArgumentException exception if an invalid flag value or parameter was specified.

set_tmp_dir

public void set_tmp_dir(String dir)
                 throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by setTmpDir(String)

DbException

setTmpDir

public void setTmpDir(String dir)
               throws DbException

Specify the path of a directory to be used as the location of temporary files. The files created to back in-memory access method databases will be created relative to this path. These temporary files can be quite large, depending on the size of the database.

If no directories are specified, the following alternatives are checked in the specified order. The first existing directory path is used for all temporary files.

1. The value of the environment variable TMPDIR.
2. The value of the environment variable TEMP.
3. The value of the environment variable TMP.
4. The value of the environment variable TempFolder.
5. The value returned by the GetTempPath interface.
6. The directory /var/tmp.
7. The directory /usr/tmp.
8. The directory /temp.
9. The directory /tmp.
10. The directory C:/temp.
11. The directory C:/tmp.

Note: environment variables are only checked if one of the Db.DB_USE_ENVIRON or Db.DB_USE_ENVIRON_ROOT flags were specified.

Note: the GetTempPath interface is only checked on Win/32 platforms.

The database environment's temporary file directory may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_tmp_dir", one or more whitespace characters, and the directory name. Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.

The DbEnv.setTmpDir method configures operations performed using the specified DbEnv handle, not all operations performed on the underlying database environment.

The DbEnv.setTmpDir method may not be called after the DbEnv.open method is called. If the database environment already exists when DbEnv.open is called, the information specified to DbEnv.setTmpDir must be consistent with the existing environment or corruption can occur.

Parameters:

dir - the directory to be used to store temporary files.

Throws:

DbException

IllegalArgumentException - The DbEnv.setTmpDir method will fail and throw a IllegalArgumentException exception if the method was called after DbEnv.open was called; or if an invalid flag value or parameter was specified.

set_tx_max

public void set_tx_max(int max)
                throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by setTxnMax(int)

DbException

setTxnMax

public void setTxnMax(int max)
               throws DbException

Configure the Berkeley DB database environment to support at least max active transactions. This value bounds the size of the memory allocated for transactions. Child transactions are counted as active until they either commit or abort.

When all of the memory available in the database environment for transactions is in use, calls to DbEnv.txnBegin will fail (until some active transactions complete). If this interface is never called, the database environment is configured to support at least 20 active transactions.

The database environment's number of active transactions may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_tx_max", one or more whitespace characters, and the number of transactions. Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.

The DbEnv.setTxnMax method configures a database environment, not only operations performed using the specified DbEnv handle.

The DbEnv.setTxnMax method may not be called after the DbEnv.open method is called. If the database environment already exists when DbEnv.open is called, the information specified to DbEnv.setTxnMax will be ignored.

Parameters:

max - The max parameter configures the minimum number of simultaneously active transactions supported by Berkeley DB database environment.

Throws:

DbException

IllegalArgumentException - The DbEnv.setTxnMax method will fail and throw a IllegalArgumentException exception if the method was called after DbEnv.open was called; or if an invalid flag value or parameter was specified.

set_app_dispatch

public void set_app_dispatch(DbAppDispatch tx_recover)
                      throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by setAppDispatch(DbAppDispatch)

DbException

setAppDispatch

public void setAppDispatch(DbAppDispatch tx_recover)
                    throws DbException

DbException

set_verbose

public void set_verbose(int which,
                        boolean onoff)
                 throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by setVerbose(int,boolean)

DbException

setVerbose

public void setVerbose(int which,
                       boolean onoff)
                throws DbException

The DbEnv.setVerbose method turns specific additional informational and debugging messages in the Berkeley DB message output on and off. To see the additional messages, verbose messages must also be configured for the application. For more information on verbose messages, see the Db.setErrorStream method.

The database environment's messages may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_verbose", one or more whitespace characters, and the method which parameter as a string; for example, "set_verbose DB_VERB_CHKPOINT". Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.

The DbEnv.setVerbose method configures operations performed using the specified DbEnv handle, not all operations performed on the underlying database environment.

The DbEnv.setVerbose method may be called at any time during the life of the application.

Parameters:

onoff - If the onoff parameter is set to true, the additional messages are output.

which - must be set to one of the following values:

• Db.DB_VERB_CHKPOINT

  Display checkpoint location information when searching the log for checkpoints.

• Db.DB_VERB_DEADLOCK

  Display additional information when doing deadlock detection.

• Db.DB_VERB_RECOVERY

  Display additional information when performing recovery.

• Db.DB_VERB_REPLICATION

  Display additional information when processing replication messages.

  Note, to get complete replication logging when debugging replication applications, you must also configure and build the Berkeley DB library with the --enable-diagnostic configuration option as well as call the DbEnv.setVerbose method.

• Db.DB_VERB_WAITSFOR

  Display the waits-for table when doing deadlock detection.

Throws:

DbException

IllegalArgumentException - The DbEnv.setVerbose method will fail and throw a IllegalArgumentException exception if an invalid flag value or parameter was specified.

get_lk_conflicts

public byte[][] get_lk_conflicts()
                          throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by getLockConflicts()

DbException

getLockConflicts

public byte[][] getLockConflicts()
                          throws DbException

The DbEnv.getLockConflicts method returns the conflicts array.

The DbEnv.getLockConflicts method may be called at any time during the life of the application.

Returns:

The DbEnv.getLockConflicts method returns the conflicts array.

Throws:

DbException - Signals that an exception of some sort has occurred.

get_lk_detect

public int get_lk_detect()
                  throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by getLockDetect()

DbException

getLockDetect

public int getLockDetect()
                  throws DbException

The DbEnv.getLockDetect method returns the deadlock detector configuration.

The DbEnv.getLockDetect method may be called at any time during the life of the application.

Returns:

The DbEnv.getLockDetect method returns the deadlock detector configuration.

Throws:

DbException - Signals that an exception of some sort has occurred.

get_lk_max_locks

public int get_lk_max_locks()
                     throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by getLockMaxLocks()

DbException

getLockMaxLocks

public int getLockMaxLocks()
                    throws DbException

The DbEnv.setLockMaxLocks method returns the maximum number of locks.

The DbEnv.setLockMaxLocks method may be called at any time during the life of the application.

Returns:

The DbEnv.setLockMaxLocks method returns the maximum number of locks.

Throws:

DbException - Signals that an exception of some sort has occurred.

get_lk_max_lockers

public int get_lk_max_lockers()
                       throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by getLockMaxLockers()

DbException

getLockMaxLockers

public int getLockMaxLockers()
                      throws DbException

The DbEnv.getLockMaxLockers method returns the maximum number of lockers.

The DbEnv.getLockMaxLockers method may be called at any time during the life of the application.

Returns:

The DbEnv.getLockMaxLockers method returns the maximum number of lockers.

Throws:

DbException - Signals that an exception of some sort has occurred.

get_lk_max_objects

public int get_lk_max_objects()
                       throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by getLockMaxObjects()

DbException

getLockMaxObjects

public int getLockMaxObjects()
                      throws DbException

The DbEnv.getLockMaxObjects method returns the maximum number of locked objects.

The DbEnv.getLockMaxObjects method may be called at any time during the life of the application.

Returns:

The DbEnv.getLockMaxObjects method returns the maximum number of locked objects.

Throws:

DbException - Signals that an exception of some sort has occurred.

lock_detect

public int lock_detect(int flags,
                       int atype)
                throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by lockDetect(int,int)

DbException

lockDetect

public int lockDetect(int flags,
                      int atype)
               throws DbException

The DbEnv.lockDetect method runs one iteration of the deadlock detector. The deadlock detector traverses the lock table and marks one of the participating lock requesters for rejection in each deadlock it finds.

Parameters:

atype - specifies which lock request(s) to reject. It must be set to one of the following list:

• Db.DB_LOCK_DEFAULT

  Use whatever lock policy was specified when the database environment was created. If no lock policy has yet been specified, set the lock policy to Db.DB_LOCK_RANDOM.

• Db.DB_LOCK_EXPIRE

  Reject lock requests which have timed out. No other deadlock detection is performed.

• Db.DB_LOCK_MAXLOCKS

  Reject the lock request for the locker ID with the greatest number of locks.

• Db.DB_LOCK_MINLOCKS

  Reject the lock request for the locker ID with the fewest number of locks.

• Db.DB_LOCK_MINWRITE

  Reject the lock request for the locker ID with the fewest number of write locks.

• Db.DB_LOCK_OLDEST

  Reject the lock request for the oldest locker ID.

• Db.DB_LOCK_RANDOM

  Reject the lock request for a random locker ID.

• Db.DB_LOCK_YOUNGEST

  Reject the lock request for the youngest locker ID.

flags - currently unused, and must be set to 0.

Returns:

The DbEnv.lockDetect method returns the number of lock requests that were rejected.

Throws:

DbException

IllegalArgumentException - The DbEnv.lockDetect method will fail and throw a IllegalArgumentException exception if an invalid flag value or parameter was specified.

lock_get

public DbLock lock_get(int locker,
                       int flags,
                       Dbt object,
                       int lock_mode)
                throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by lockGet(int,int,Dbt,int)

DbException

lockGet

public DbLock lockGet(int locker,
                      int flags,
                      Dbt object,
                      int lock_mode)
               throws DbException

The DbEnv.lockGet method acquires a lock from the lock table, returning information about it in a DbLock object.

Parameters:

flags - must be set to 0 or the following value:

• Db.DB_LOCK_NOWAIT

  If a lock cannot be granted because the requested lock conflicts with an existing lock, throw a DbLockNotGrantedException immediately instead of waiting for the lock to become available.

lock_mode - used as an index into the environment's lock conflict matrix. When using the default lock conflict matrix, lock_mode must be set to one of the following values: read (shared) write (exclusive) intention to write (shared) intention to read (shared) intention to read and write (shared)

See DbEnv.setLockConflicts and Standard Lock Modes for more information on the lock conflict matrix.

locker - an unsigned 32-bit integer quantity. It represents the entity requesting the lock.

object - an untyped byte string that specifies the object to be locked. Applications using the locking subsystem directly while also doing locking via the Berkeley DB access methods must take care not to inadvertently lock objects that happen to be equal to the unique file IDs used to lock files. See Access method locking conventions for more information.

Returns:

The DbEnv.lockGet method throws an exception that encapsulates a non-zero error value on failure.

Throws:

DbException

DbDeadlockException - If a transactional database environment operation was selected to resolve a deadlock, the DbEnv.lockGet method will fail and throw a DbDeadlockException exception.

DbLockNotGrantedException - If a Berkeley DB Concurrent Data Store database environment configured for lock timeouts was unable to grant a lock in the allowed time, the DbEnv.lockGet method will fail and throw a DbLockNotGrantedException exception.

DbLockNotGrantedException - If the Db.DB_LOCK_NOWAIT flag or lock timers were configured and the lock could not be granted before the wait-time expired, the DbEnv.lockGet method will fail and throw a DbLockNotGrantedException exception.

IllegalArgumentException - The DbEnv.lockGet method will fail and throw a IllegalArgumentException exception if an invalid flag value or parameter was specified.

DbMemoryException - If the maximum number of locks has been reached, the DbEnv.lockGet method will fail and throw a DbMemoryException exception.

lock_id

public int lock_id()
            throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by lockId()

DbException

lockId

public int lockId()
           throws DbException

The DbEnv.lockId method returns a locker ID, which is guaranteed to be unique in the specified lock table.

The DbEnv.lockIdFree method should be called to return the locker ID to the Berkeley DB library when it is no longer needed.

Returns:

The DbEnv.lockId method returns a locker ID which is guaranteed to be unique in the specified lock table.

Throws:

DbException - Signals that an exception of some sort has occurred.

lock_id_free

public void lock_id_free(int id)
                  throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by lockIdFree(int)

DbException

lockIdFree

public void lockIdFree(int id)
                throws DbException

The DbEnv.lockIdFree method frees a locker ID allocated by the DbEnv.lockId method.

Parameters:

id - the locker id to be freed.

Throws:

DbException

IllegalArgumentException - The DbEnv.lockIdFree method will fail and throw a IllegalArgumentException exception if the locker ID is invalid or locks are still held by this locker ID; or if an invalid flag value or parameter was specified.

lock_put

public void lock_put(DbLock lock)
              throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by lockPut(DbLock)

DbException

lockPut

public void lockPut(DbLock lock)
             throws DbException

The DbEnv.lockPut method releases lock.

Parameters:

lock - the lock to be released.

Throws:

DbException

IllegalArgumentException - The DbEnv.lockPut method will fail and throw a IllegalArgumentException exception if an invalid flag value or parameter was specified.

lock_stat

public DbLockStat lock_stat(int flags)
                     throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by lockStat(int)

DbException

lockStat

public DbLockStat lockStat(int flags)
                    throws DbException

The DbEnv.lockStat method returns the locking subsystem statistics.

The DbEnv.lockStat method creates a DbLockStat object encapsulating the locking subsystem statistics. The following data fields are available from the DbLockStat object:

For convenience, the DbLockStat class has a toString method that lists all the data fields.

Parameters:

flags - must be set to 0 or the following value:

• Db.DB_STAT_CLEAR

  Reset statistics after returning their values.

Returns:

The DbEnv.lockStat method throws an exception that encapsulates a non-zero error value on failure.

Throws:

DbException

IllegalArgumentException - The DbEnv.lockStat method will fail and throw a IllegalArgumentException exception if an invalid flag value or parameter was specified.

set_lk_conflicts

public void set_lk_conflicts(byte[][] conflicts)
                      throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by setLockConflicts(byte[][])

DbException

setLockConflicts

public void setLockConflicts(byte[][] conflicts)
                      throws DbException

Set the locking conflicts matrix.

If DbEnv.setLockConflicts is never called, a standard conflicts array is used; see Standard Lock Modes for more information.

The DbEnv.setLockConflicts method configures a database environment, not only operations performed using the specified DbEnv handle.

The DbEnv.setLockConflicts method may not be called after the DbEnv.open method is called. If the database environment already exists when DbEnv.open is called, the information specified to DbEnv.setLockConflicts will be ignored.

Parameters:

conflicts - the new locking conflicts matrix. A non-0 value for the array element indicates that requested_mode and held_mode conflict:

conflicts[requested_mode][held_mode]

The not-granted mode must be represented by 0.

Throws:

DbException

IllegalArgumentException - The DbEnv.setLockConflicts method will fail and throw a IllegalArgumentException exception if the method was called after DbEnv.open was called; or if an invalid flag value or parameter was specified.

DbMemoryException - If the conflicts array could not be copied, the DbEnv.setLockConflicts method will fail and throw a DbMemoryException exception.

set_lk_detect

public void set_lk_detect(int detect)
                   throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by setLockDetect(int)

DbException

setLockDetect

public void setLockDetect(int detect)
                   throws DbException

Set if the deadlock detector is to be run whenever a lock conflict occurs, and specify what lock request(s) should be rejected. As transactions acquire locks on behalf of a single locker ID, rejecting a lock request associated with a transaction normally requires the transaction be aborted.

The database environment's deadlock detector configuration may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_lk_detect", one or more whitespace characters, and the method detect parameter as a string; for example, "set_lk_detect DB_LOCK_OLDEST". Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.

The DbEnv.setLockDetect method configures a database environment, not only operations performed using the specified DbEnv handle.

The DbEnv.setLockDetect method may not be called after the DbEnv.open method is called. If the database environment already exists when DbEnv.open is called, the information specified to DbEnv.setLockDetect must be consistent with the existing environment or an error will be returned.

Parameters:

detect - The detect parameter configures the deadlock detector. The specified value must be one of the following list:

• Db.DB_LOCK_DEFAULT

  Use whatever lock policy was specified when the database environment was created. If no lock policy has yet been specified, set the lock policy to Db.DB_LOCK_RANDOM.

• Db.DB_LOCK_EXPIRE

  Reject lock requests which have timed out. No other deadlock detection is performed.

• Db.DB_LOCK_MAXLOCKS

  Reject the lock request for the locker ID with the greatest number of locks.

• Db.DB_LOCK_MINLOCKS

  Reject the lock request for the locker ID with the fewest number of locks.

• Db.DB_LOCK_MINWRITE

  Reject the lock request for the locker ID with the fewest number of write locks.

• Db.DB_LOCK_OLDEST

  Reject the lock request for the oldest locker ID.

• Db.DB_LOCK_RANDOM

  Reject the lock request for a random locker ID.

• Db.DB_LOCK_YOUNGEST

  Reject the lock request for the youngest locker ID.

Throws:

DbException

IllegalArgumentException - The DbEnv.setLockDetect method will fail and throw a IllegalArgumentException exception if the method was called after DbEnv.open was called; or if an invalid flag value or parameter was specified.

set_lk_max_lockers

public void set_lk_max_lockers(int max)
                        throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by setLockMaxLockers(int)

DbException

setLockMaxLockers

public void setLockMaxLockers(int max)
                       throws DbException

Set the maximum number of locking entities supported by the Berkeley DB environment. This value is used by DbEnv.open to estimate how much space to allocate for various lock-table data structures. The default value is 1000 lockers. For specific information on configuring the size of the lock subsystem, see Configuring locking: sizing the system.

The database environment's maximum number of lockers may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_lk_max_lockers", one or more whitespace characters, and the number of lockers. Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.

The DbEnv.setLockMaxLockers method configures a database environment, not only operations performed using the specified DbEnv handle.

The DbEnv.setLockMaxLockers method may not be called after the DbEnv.open method is called. If the database environment already exists when DbEnv.open is called, the information specified to DbEnv.setLockMaxLockers will be ignored.

Parameters:

max - the maximum number simultaneous locking entities supported by the Berkeley DB environment.

Throws:

DbException

IllegalArgumentException - The DbEnv.setLockMaxLockers method will fail and throw a IllegalArgumentException exception if the method was called after DbEnv.open was called; or if an invalid flag value or parameter was specified.

set_lk_max_locks

public void set_lk_max_locks(int max)
                      throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by setLockMaxLocks(int)

DbException

setLockMaxLocks

public void setLockMaxLocks(int max)
                     throws DbException

Set the maximum number of locks supported by the Berkeley DB environment. This value is used by DbEnv.open to estimate how much space to allocate for various lock-table data structures. The default value is 1000 locks. For specific information on configuring the size of the lock subsystem, see Configuring locking: sizing the system.

The database environment's maximum number of locks may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_lk_max_locks", one or more whitespace characters, and the number of locks. Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.

The DbEnv.setLockMaxLocks method configures a database environment, not only operations performed using the specified DbEnv handle.

The DbEnv.setLockMaxLocks method may not be called after the DbEnv.open method is called. If the database environment already exists when DbEnv.open is called, the information specified to DbEnv.setLockMaxLocks will be ignored.

Parameters:

max - the maximum number of locks supported by the Berkeley DB environment.

Throws:

DbException

IllegalArgumentException - The DbEnv.setLockMaxLocks method will fail and throw a IllegalArgumentException exception if the method was called after DbEnv.open was called; or if an invalid flag value or parameter was specified.

set_lk_max_objects

public void set_lk_max_objects(int max)
                        throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by setLockMaxObjects(int)

DbException

setLockMaxObjects

public void setLockMaxObjects(int max)
                       throws DbException

Set the maximum number of locked objects supported by the Berkeley DB environment. This value is used by DbEnv.open to estimate how much space to allocate for various lock-table data structures. The default value is 1000 objects. For specific information on configuring the size of the lock subsystem, see Configuring locking: sizing the system.

The database environment's maximum number of objects may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_lk_max_objects", one or more whitespace characters, and the number of objects. Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.

The DbEnv.setLockMaxObjects method configures a database environment, not only operations performed using the specified DbEnv handle.

The DbEnv.setLockMaxObjects method may not be called after the DbEnv.open method is called. If the database environment already exists when DbEnv.open is called, the information specified to DbEnv.setLockMaxObjects will be ignored.

Parameters:

max - the maximum number of locked objects supported by the Berkeley DB environment.

Throws:

DbException

IllegalArgumentException - The DbEnv.setLockMaxObjects method will fail and throw a IllegalArgumentException exception if the method was called after DbEnv.open was called; or if an invalid flag value or parameter was specified.

get_lg_bsize

public int get_lg_bsize()
                 throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by getLogBufferSize()

DbException

getLogBufferSize

public int getLogBufferSize()
                     throws DbException

The DbEnv.getLogBufferSize method returns the size of the log buffer, in bytes.

The DbEnv.getLogBufferSize method may be called at any time during the life of the application.

Returns:

The DbEnv.getLogBufferSize method returns the size of the log buffer, in bytes.

Throws:

DbException - Signals that an exception of some sort has occurred.

get_lg_dir

public String get_lg_dir()
                  throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by getLogDir()

DbException

getLogDir

public String getLogDir()
                 throws DbException

The DbEnv.getLogDir method returns the log directory.

The DbEnv.getLogDir method may be called at any time during the life of the application.

Returns:

The DbEnv.getLogDir method returns the log directory.

Throws:

DbException - Signals that an exception of some sort has occurred.

get_lg_max

public int get_lg_max()
               throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by getLogMax()

DbException

getLogMax

public int getLogMax()
              throws DbException

The DbEnv.getLogMax method returns the maximum log file size.

The DbEnv.getLogMax method may be called at any time during the life of the application.

Returns:

The DbEnv.getLogMax method returns the maximum log file size.

Throws:

DbException - Signals that an exception of some sort has occurred.

get_lg_regionmax

public int get_lg_regionmax()
                     throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by getLogRegionMax()

DbException

getLogRegionMax

public int getLogRegionMax()
                    throws DbException

The DbEnv.getLogRegionMax method returns the size of the underlying logging subsystem region.

The DbEnv.getLogRegionMax method may be called at any time during the life of the application.

Returns:

The DbEnv.getLogRegionMax method returns the size of the underlying logging subsystem region.

Throws:

DbException - Signals that an exception of some sort has occurred.

log_archive

public String[] log_archive(int flags)
                     throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by logArchive(int)

DbException

logArchive

public String[] logArchive(int flags)
                    throws DbException

The DbEnv.logArchive method returns an array of log or database filenames.

By default, DbEnv.logArchive returns the names of all of the log files that are no longer in use (for example, that are no longer involved in active transactions), and that may safely be archived for catastrophic recovery and then removed from the system. If there are no filenames to return, DbEnv.logArchive returns null.

Log cursor handles (returned by the DbEnv.logCursor method) may have open file descriptors for log files in the database environment. Also, the Berkeley DB interfaces to the database environment logging subsystem (for example, DbEnv.logPut and DbTxn.abort) may allocate log cursors and have open file descriptors for log files as well. On operating systems where filesystem related system calls (for example, rename and unlink on Windows/NT) can fail if a process has an open file descriptor for the affected file, attempting to move or remove the log files listed by DbEnv.logArchive may fail. All Berkeley DB internal use of log cursors operates on active log files only and furthermore, is short-lived in nature. So, an application seeing such a failure should be restructured to close any open log cursors it may have, and otherwise to retry the operation until it succeeds. (Although the latter is not likely to be necessary; it is hard to imagine a reason to move or rename a log file in which transactions are being logged or aborted.)

See db_archive for more information on database archival procedures.

Parameters:

flags - must be set to 0 or by bitwise inclusively OR'ing together one or more of the following values:

• Db.DB_ARCH_ABS

  All pathnames are returned as absolute pathnames, instead of relative to the database home directory.

• Db.DB_ARCH_DATA

  Return the database files that need to be archived in order to recover the database from catastrophic failure. If any of the database files have not been accessed during the lifetime of the current log files, DbEnv.logArchive will not include them in this list. It is also possible that some of the files referred to by the log have since been deleted from the system.

  The Db.DB_ARCH_DATA and Db.DB_ARCH_LOG flags are mutually exclusive.

• Db.DB_ARCH_LOG

  Return all the log filenames, regardless of whether or not they are in use.

  The Db.DB_ARCH_DATA and Db.DB_ARCH_LOG flags are mutually exclusive.

• Db.DB_ARCH_REMOVE

  Remove log files that are no longer needed; no filenames are returned. Automatic log file removal is likely to make catastrophic recovery impossible.

  The Db.DB_ARCH_REMOVE flag may not be specified with any other flag.

Returns:

The DbEnv.logArchive method throws an exception that encapsulates a non-zero error value on failure.

Throws:

DbException

IllegalArgumentException - The DbEnv.logArchive method will fail and throw a IllegalArgumentException exception if an invalid flag value or parameter was specified.

log_compare

public static int log_compare(DbLsn lsn0,
                              DbLsn lsn1)

Deprecated. As of Berkeley DB 4.2, replaced by logCompare(DbLsn,DbLsn)

logCompare

public static int logCompare(DbLsn lsn0,
                             DbLsn lsn1)

The DbEnv.logCompare method allows the caller to compare two DbLsn objects, returning 0 if they are equal, 1 if lsn0 is greater than lsn1, and -1 if lsn0 is less than lsn1.

Parameters:

lsn0 - one of the DbLsn objects to be compared.

lsn1 - one of the DbLsn objects to be compared.

Returns:

The DbEnv.logCompare method returns 0 if the DbLsn object parameters are equal, 1 if lsn0 is greater than lsn1, and -1 if lsn0 is less than lsn1.

log_cursor

public DbLogc log_cursor(int flags)
                  throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by logCursor(int)

DbException

logCursor

public DbLogc logCursor(int flags)
                 throws DbException

The DbEnv.logCursor method returns a created log cursor.

Parameters:

flags - currently unused, and must be set to 0.

Returns:

The DbEnv.logCursor method throws an exception that encapsulates a non-zero error value on failure.

Throws:

DbException

IllegalArgumentException - The DbEnv.logCursor method will fail and throw a IllegalArgumentException exception if an invalid flag value or parameter was specified.

log_file

public String log_file(DbLsn lsn)
                throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by logFile(DbLsn)

DbException

logFile

public String logFile(DbLsn lsn)
               throws DbException

The DbEnv.logFile method maps DbLsn objects to filenames, returning the name of the file containing the record named by lsn.

This mapping of DbLsn objects to files is needed for database administration. For example, a transaction manager typically records the earliest DbLsn needed for restart, and the database administrator may want to archive log files to tape when they contain only DbLsn entries before the earliest one needed for restart.

Parameters:

lsn - the DbLsn object for which a filename is wanted.

Returns:

The DbEnv.logFile method throws an exception that encapsulates a non-zero error value on failure.

Throws:

DbException

DbMemoryException - If the supplied buffer was too small to hold the log filename, the DbEnv.logFile method will fail and throw a DbMemoryException exception.

log_flush

public void log_flush(DbLsn lsn)
               throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by logFlush(DbLsn)

DbException

logFlush

public void logFlush(DbLsn lsn)
              throws DbException

The DbEnv.logFlush method writes log records to disk.

Parameters:

lsn - All log records with DbLsn values less than or equal to the lsn parameter are written to disk. If lsn is null, all records in the log are flushed.

Throws:

DbException

IllegalArgumentException - The DbEnv.logFlush method will fail and throw a IllegalArgumentException exception if an invalid flag value or parameter was specified.

log_put

public void log_put(DbLsn lsn,
                    Dbt data,
                    int flags)
             throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by logPut(DbLsn,Dbt,int)

DbException

logPut

public void logPut(DbLsn lsn,
                   Dbt data,
                   int flags)
            throws DbException

The DbEnv.logPut method appends records to the log. The DbLsn of the put record is returned in the lsn parameter.

Parameters:

data - the record to write to the log.

The caller is responsible for providing any necessary structure to data. (For example, in a write-ahead logging protocol, the application must understand what part of data is an operation code, what part is redo information, and what part is undo information. In addition, most transaction managers will store in data the DbLsn of the previous log record for the same transaction, to support chaining back through the transaction's log records during undo.)

flags - must be set to 0 or the following value:

• Db.DB_FLUSH

  The log is forced to disk after this record is written, guaranteeing that all records with DbLsn values less than or equal to the one being "put" are on disk before DbEnv.logPut returns.

lsn - references memory into which the DbLsn of the put record is copied.

Throws:

DbException

IllegalArgumentException - The DbEnv.logFlush method will fail and throw a IllegalArgumentException exception if the record to be logged is larger than the maximum log record; or if an invalid flag value or parameter was specified.

log_stat

public DbLogStat log_stat(int flags)
                   throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by logStat(int)

DbException

logStat

public DbLogStat logStat(int flags)
                  throws DbException

The DbEnv.logStat method returns the logging subsystem statistics.

The DbEnv.logStat method creates a DbLogStat object encapsulating the logging subsystem statistics. The following data fields are available from the DbLogStat object:

For convenience, the DbLogStat class has a toString method that lists all the data fields.

Parameters:

flags - must be set to 0 or the following value:

• Db.DB_STAT_CLEAR

  Reset statistics after returning their values.

Returns:

The DbEnv.logStat method throws an exception that encapsulates a non-zero error value on failure.

Throws:

DbException

IllegalArgumentException - The DbEnv.logStat method will fail and throw a IllegalArgumentException exception if an invalid flag value or parameter was specified.

set_lg_bsize

public void set_lg_bsize(int lg_bsize)
                  throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by setLogBufferSize(int)

DbException

setLogBufferSize

public void setLogBufferSize(int lg_bsize)
                      throws DbException

Set the size of the in-memory log buffer, in bytes. By default, or if the value is set to 0, a size of 32K is used. The size of the log file (see DbEnv.setLogMax) must be at least four times the size of the in-memory log buffer.

Log information is stored in-memory until the storage space fills up or transaction commit forces the information to be flushed to stable storage. In the presence of long-running transactions or transactions producing large amounts of data, larger buffer sizes can increase throughput.

The database environment's log buffer size may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_lg_bsize", one or more whitespace characters, and the size in bytes. Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.

The DbEnv.setLogBufferSize method configures a database environment, not only operations performed using the specified DbEnv handle.

The DbEnv.setLogBufferSize method may not be called after the DbEnv.open method is called. If the database environment already exists when DbEnv.open is called, the information specified to DbEnv.setLogBufferSize will be ignored.

Parameters:

lg_bsize - the size of the in-memory log buffer, in bytes.

Throws:

DbException

IllegalArgumentException - The DbEnv.setLogBufferSize method will fail and throw a IllegalArgumentException exception if the method was called after DbEnv.open was called; The size of the log file is less than four times the size of the in-memory log buffer; or if an invalid flag value or parameter was specified.

set_lg_dir

public void set_lg_dir(String dir)
                throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by setLogDir(String)

DbException

setLogDir

public void setLogDir(String dir)
               throws DbException

The path of a directory to be used as the location of logging files. Log files created by the Log Manager subsystem will be created in this directory.

If no logging directory is specified, log files are created in the environment home directory. See Berkeley DB File Naming for more information.

For the greatest degree of recoverability from system or application failure, database files and log files should be located on separate physical devices.

The database environment's logging directory may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_lg_dir", one or more whitespace characters, and the directory name. Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.

The DbEnv.setLogDir method configures operations performed using the specified DbEnv handle, not all operations performed on the underlying database environment.

The DbEnv.setLogDir method may not be called after the DbEnv.open method is called. If the database environment already exists when DbEnv.open is called, the information specified to DbEnv.setLogDir must be consistent with the existing environment or corruption can occur.

Parameters:

dir - the directory used to store the logging files.

Throws:

DbException

IllegalArgumentException - The DbEnv.setLogDir method will fail and throw a IllegalArgumentException exception if the method was called after DbEnv.open was called; or if an invalid flag value or parameter was specified.

set_lg_max

public void set_lg_max(int lg_max)
                throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by setLogMax(int)

DbException

setLogMax

public void setLogMax(int lg_max)
               throws DbException

Set the maximum size of a single file in the log, in bytes. By default, or if the lg_max parameter is set to 0, a size of 10MB is used. Because DbLsn file offsets are unsigned four-byte values, the set value may not be larger than the maximum unsigned four-byte value. The size of the log file must be at least four times the size of the in-memory log buffer (see DbEnv.setLogBufferSize).

See Log File Limits for more information.

The database environment's log file size may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_lg_max", one or more whitespace characters, and the size in bytes. Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.

The DbEnv.setLogMax method configures a database environment, not only operations performed using the specified DbEnv handle.

The DbEnv.setLogMax method may be called at any time during the life of the application.

If no size is specified by the application, the size last specified for the database region will be used, or if no database region previously existed, the default will be used.

Parameters:

lg_max - the size of a single log file, in bytes.

Throws:

DbException

IllegalArgumentException - The DbEnv.setLogMax method will fail and throw a IllegalArgumentException exception if the method was called after DbEnv.open was called; the size of the log file is less than four times the size of the in-memory log buffer; The specified log file size was too large; or if an invalid flag value or parameter was specified.

set_lg_regionmax

public void set_lg_regionmax(int lg_regionmax)
                      throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by setLogRegionMax(int)

DbException

setLogRegionMax

public void setLogRegionMax(int lg_regionmax)
                     throws DbException

Set the size of the underlying logging area of the Berkeley DB environment, in bytes. By default, or if the value is set to 0, the default size is 60KB. The log region is used to store filenames, and so may need to be increased in size if a large number of files will be opened and registered with the specified Berkeley DB environment's log manager.

The database environment's log region size may also be set using the environment's DB_CONFIG file. The syntax of the entry in that file is a single line with the string "set_lg_regionmax", one or more whitespace characters, and the size in bytes. Because the DB_CONFIG file is read when the database environment is opened, it will silently overrule configuration done before that time.

The DbEnv.setLogRegionMax method configures a database environment, not only operations performed using the specified DbEnv handle.

The DbEnv.setLogRegionMax method may not be called after the DbEnv.open method is called. If the database environment already exists when DbEnv.open is called, the information specified to DbEnv.setLogRegionMax will be ignored.

Parameters:

lg_regionmax - the size of the logging area in the Berkeley DB environment, in bytes.

Throws:

DbException

IllegalArgumentException - The DbEnv.setLogRegionMax method will fail and throw a IllegalArgumentException exception if the method was called after DbEnv.open was called; or if an invalid flag value or parameter was specified.

get_cachesize

public long get_cachesize()
                   throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by getCacheSize()

DbException

getCacheSize

public long getCacheSize()
                  throws DbException

The DbEnv.getCacheSize method returns the size of the cache.

The DbEnv.getCacheSize method may be called at any time during the life of the application.

Returns:

The DbEnv.getCacheSize method returns the size of the cache.

Throws:

DbException - Signals that an exception of some sort has occurred.

get_cachesize_ncache

public int get_cachesize_ncache()
                         throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by getCacheSizeNcache()

DbException

getCacheSizeNcache

public int getCacheSizeNcache()
                       throws DbException

The DbEnv.getCacheSizeNcache method returns the number of caches.

The DbEnv.getCacheSizeNcache method may be called at any time during the life of the application.

Returns:

The DbEnv.getCacheSizeNcache method returns the number of caches.

Throws:

DbException - Signals that an exception of some sort has occurred.

get_mp_mmapsize

public long get_mp_mmapsize()
                     throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by getMemoryPoolMapSize()

DbException

getMemoryPoolMapSize

public long getMemoryPoolMapSize()
                          throws DbException

The DbEnv.getMemoryPoolMapSize method returns the maximum file map size.

The DbEnv.getMemoryPoolMapSize method may be called at any time during the life of the application.

Returns:

The DbEnv.getMemoryPoolMapSize method returns the maximum file map size.

Throws:

DbException - Signals that an exception of some sort has occurred.

memp_stat

public DbMpoolStat memp_stat(int flags)
                      throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by memoryPoolStat(int)

DbException

memoryPoolStat

public DbMpoolStat memoryPoolStat(int flags)
                           throws DbException

The DbEnv.memoryPoolStat method returns the memory pool (that is, the buffer cache) subsystem statistics.

The DbEnv.memoryPoolStat method creates a DbMpoolStat object encapsulating memory pool (that is, the buffer cache) statistics. The following data fields are available from the DbMpoolStat object:

For convenience, the DbMpoolStat class has a toString method that lists all the data fields.

Parameters:

flags - must be set to 0 or the following value:

• Db.DB_STAT_CLEAR

  Reset statistics after returning their values.

Returns:

The DbEnv.memoryPoolStat method throws an exception that encapsulates a non-zero error value on failure.

Throws:

DbException - Signals that an exception of some sort has occurred.

memp_fstat

public DbMpoolFStat[] memp_fstat(int flags)
                          throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by memoryPoolFileStat(int)

DbException

memoryPoolFileStat

public DbMpoolFStat[] memoryPoolFileStat(int flags)
                                  throws DbException

The DbEnv.memoryPoolFileStat method creates an array of DbMpoolFStat objects containing statistics for individual files in the cache. Each DbMpoolFStat object contains statistics for an individual DbMpoolFile. The following data fields are available for each DbMpoolFStat object:

For convenience, the DbMpoolFStat class has a toString method that lists all the data fields.

Parameters:

flags - must be set to 0 or the following value:

• Db.DB_STAT_CLEAR

  Reset statistics after returning their values.

Returns:

The DbEnv.memoryPoolFileStat method throws an exception that encapsulates a non-zero error value on failure.

Throws:

DbException

IllegalArgumentException - The DbEnv.memoryPoolStat method will fail and throw a IllegalArgumentException exception if an invalid flag value or parameter was specified.

memp_trickle

public int memp_trickle(int percent)
                 throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by memoryPoolTrickle(int)

DbException

memoryPoolTrickle

public int memoryPoolTrickle(int percent)
                      throws DbException

The DbEnv.memoryPoolTrickle method ensures that a specified percent of the pages in the shared memory pool are clean, by writing dirty pages to their backing files.

The purpose of the DbEnv.memoryPoolTrickle function is to enable a memory pool manager to ensure that a page is always available for reading in new information without having to wait for a write.

Parameters:

percent - the percent of the pages in the cache that should be clean.

Returns:

The DbEnv.memoryPoolTrickle method returns the number of pages that were written to reach the specified percentage.

Throws:

DbException

IllegalArgumentException - The DbEnv.memoryPoolTrickle method will fail and throw a IllegalArgumentException exception if an invalid flag value or parameter was specified.

get_tx_max

public int get_tx_max()
               throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by getTxnMax()

DbException

getTxnMax

public int getTxnMax()
              throws DbException

The DbEnv.getTxnMax method returns the number of active transactions.

The DbEnv.getTxnMax method may be called at any time during the life of the application.

Returns:

The DbEnv.getTxnMax method returns the number of active transactions.

Throws:

DbException - Signals that an exception of some sort has occurred.

get_tx_timestamp

public long get_tx_timestamp()
                      throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by getTxnTimestamp()

DbException

getTxnTimestamp

public long getTxnTimestamp()
                     throws DbException

The DbEnv.getTxnTimestamp method returns the recovery timestamp.

The DbEnv.getTxnTimestamp method may be called at any time during the life of the application.

Returns:

The DbEnv.getTxnTimestamp method returns the recovery timestamp.

Throws:

DbException - Signals that an exception of some sort has occurred.

get_timeout

public long get_timeout(int flag)
                 throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by getTimeout(int)

DbException

getTimeout

public long getTimeout(int flag)
                throws DbException

The DbEnv.getTimeout method returns a timeout value, in microseconds.

The DbEnv.getTimeout method may be called at any time during the life of the application.

Parameters:

flag - must be set to one of the following values:

• Db.DB_SET_LOCK_TIMEOUT

  Return the timeout value for locks in this database environment.

• Db.DB_SET_TXN_TIMEOUT

  Return the timeout value for transactions in this database environment.

Returns:

The DbEnv.getTimeout method returns a timeout value, in microseconds.

Throws:

DbException - Signals that an exception of some sort has occurred.

txn_begin

public DbTxn txn_begin(DbTxn parent,
                       int flags)
                throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by txnBegin(DbTxn,int)

DbException

txnBegin

public DbTxn txnBegin(DbTxn parent,
                      int flags)
               throws DbException

The DbEnv.txnBegin method creates a new transaction in the environment and returns a DbTxn that uniquely identifies it. Calling the DbTxn.abort, DbTxn.commit or DbTxn.discard methods will discard the returned handle.

Note: Transactions may only span threads if they do so serially; that is, each transaction must be active in only a single thread of control at a time. This restriction holds for parents of nested transactions as well; not two children may be concurrently active in more than one thread of control at any one time.

Note: Cursors may not span transactions; that is, each cursor must be opened and closed within a single transaction.

Note: A parent transaction may not issue any Berkeley DB operations -- except for DbEnv.txnBegin, DbTxn.abort and DbTxn.commit -- while it has active child transactions (child transactions that have not yet been committed or aborted).

Parameters:

flags - must be set to 0 or by bitwise inclusively OR'ing together one or more of the following values:

• Db.DB_DIRTY_READ

  All read operations performed by the transaction may read modified but not yet committed data. Silently ignored if the Db.DB_DIRTY_READ flag was not specified when the underlying database was opened.

• Db.DB_TXN_NOSYNC

  Do not synchronously flush the log when this transaction commits or prepares. This means the transaction will exhibit the ACI (atomicity, consistency, and isolation) properties, but not D (durability); that is, database integrity will be maintained but it is possible that this transaction may be undone during recovery.

  This behavior may be set for a Berkeley DB environment using the DbEnv.setFlags method. Any value specified to this method overrides that setting.

• Db.DB_TXN_NOWAIT

  If a lock is unavailable for any Berkeley DB operation performed in the context of this transaction, cause the operation to throw a DbDeadlockException immediately instead of blocking on the lock.

• Db.DB_TXN_SYNC

  Synchronously flush the log when this transaction commits or prepares. This means the transaction will exhibit all of the ACID (atomicity, consistency, isolation, and durability) properties.

  This behavior is the default for Berkeley DB environments unless the Db.DB_TXN_NOSYNC flag was specified to the DbEnv.setFlags method. Any value specified to this method overrides that setting.

parent - If the parent parameter is non-null, the new transaction will be a nested transaction, with the transaction indicated by parent as its parent. Transactions may be nested to any level. In the presence of distributed transactions and two-phase commit, only the parental transaction, that is a transaction without a parent specified, should be passed as an parameter to DbTxn.prepare.

Returns:

The DbEnv.txnBegin method throws an exception that encapsulates a non-zero error value on failure.

Throws:

DbException

DbMemoryException - If the maximum number of concurrent transactions has been reached, the DbEnv.txnBegin method will fail and throw a DbMemoryException exception.

txn_checkpoint

public void txn_checkpoint(int kbyte,
                           int min,
                           int flags)
                    throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by txnCheckpoint(int,int,int)

DbException

txnCheckpoint

public void txnCheckpoint(int kbyte,
                          int min,
                          int flags)
                   throws DbException

The DbEnv.txnCheckpoint method flushes the underlying memory pool, writes a checkpoint record to the log, and then flushes the log.

Parameters:

flags - must be set to 0 or the following value:

• Db.DB_FORCE

  Force a checkpoint record, even if there has been no activity since the last checkpoint.

kbyte - If the kbyte parameter is non-zero, a checkpoint will be done if more than kbyte kilobytes of log data have been written since the last checkpoint.

min - If the min parameter is non-zero, a checkpoint will be done if more than min minutes have passed since the last checkpoint.

Throws:

DbException

IllegalArgumentException - The DbEnv.txnCheckpoint method will fail and throw a IllegalArgumentException exception if an invalid flag value or parameter was specified.

txn_recover

public DbPreplist[] txn_recover(int count,
                                int flags)
                         throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by txnRecover(int,int)

DbException

txnRecover

public DbPreplist[] txnRecover(int count,
                               int flags)
                        throws DbException

The DbEnv.txnRecover method returns a list of prepared but not yet resolved transactions. The DbEnv.txnRecover method should only be called after the environment has been recovered. Because database environment state must be preserved between recovery and the application calling DbEnv.txnRecover, applications must either call DbEnv.txnRecover using the same environment handle used when recovery is done, or the database environment must not be configured using the Db.DB_PRIVATE flag.

The DbEnv.txnRecover method returns a list of transactions that must be resolved by the application (committed, aborted or discarded). The return value is an array of objects of type DbPreplist; the following DbPreplist fields will be filled in:

The application must call DbTxn.abort, DbTxn.commit or DbTxn.discard on each returned DbTxn handle before starting any new operations.

Parameters:

count - specifies the number of maximum size of the array that should be returned.

flags - must be set to one of the following values:

• Db.DB_FIRST

  Begin returning a list of prepared, but not yet resolved transactions.

• Db.DB_NEXT

  Continue returning a list of prepared, but not yet resolved transactions, starting where the last call to DbEnv.txnRecover left off.

Returns:

The DbEnv.txnRecover method throws an exception that encapsulates a non-zero error value on failure.

Throws:

DbException - Signals that an exception of some sort has occurred.

txn_stat

public DbTxnStat txn_stat(int flags)
                   throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by txnStat(int)

DbException

txnStat

public DbTxnStat txnStat(int flags)
                  throws DbException

The DbEnv.txnStat method returns the transaction subsystem statistics.

The DbEnv.txnStat method creates a DbTxnStat object encapsulating the transaction subsystem statistics. The following data fields are available from the DbTxnStat object:

For convenience, the DbTxnStat class has a toString method that lists all the data fields.

Parameters:

flags - must be set to 0 or the following value:

• Db.DB_STAT_CLEAR

  Reset statistics after returning their values.

Returns:

The DbEnv.txnStat method throws an exception that encapsulates a non-zero error value on failure.

Throws:

DbException

IllegalArgumentException - The DbEnv.txnStat method will fail and throw a IllegalArgumentException exception if an invalid flag value or parameter was specified.

get_rep_limit

public long get_rep_limit()
                   throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by getReplicationLimit()

DbException

getReplicationLimit

public long getReplicationLimit()
                         throws DbException

The DbEnv.getReplicationLimit method returns the transmit limit in bytes.

The DbEnv.getReplicationLimit method may be called at any time during the life of the application.

Returns:

The DbEnv.getReplicationLimit method returns the transmit limit in bytes.

Throws:

DbException - Signals that an exception of some sort has occurred.

rep_elect

public int rep_elect(int nsites,
                     int priority,
                     int timeout)
              throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by replicationElect(int,int,int)

DbException

replicationElect

public int replicationElect(int nsites,
                            int priority,
                            int timeout)
                     throws DbException

The DbEnv.replicationElect method holds an election for the master of a replication group.

If the election is successful, the new master's ID may be the ID of the previous master, or the ID of the current environment. The application is responsible for adjusting its usage of the other environments in the replication group, including directing all database updates to the newly selected master, in accordance with the results of this election.

The thread of control that calls the DbEnv.replicationElect method must not be the thread of control that processes incoming messages; processing the incoming messages is necessary to successfully complete an election.

Parameters:

nsites - The nsites parameter indicates the number of environments that the application believes are in the replication group. This number is used by Berkeley DB to avoid having two masters active simultaneously, even in the case of a network partition. During an election, a new master cannot be elected unless more than half of nsites agree on the new master. Thus, in the face of a network partition, the side of the partition with more than half the environments will elect a new master and continue, while the environments communicating with fewer than half the other environments will fail to find a new master.

priority - the priority of this environment. It must be a positive integer, or 0 if this environment is not permitted to become a master (see Replication environment priorities for more information).

timeout - specifies a timeout period for an election. If the election has not completed after timeout microseconds, the election will fail.

Returns:

The DbEnv.replicationElect method returns the newly elected master's ID.

Throws:

DbException - The DbEnv.replicationElect method may fail and throw DbException, encapsulating one of the following non-zero errors:

The replication group was unable to elect a master, or was unable to complete the election in the specified timeout period.

rep_process_message

public int rep_process_message(Dbt control,
                               Dbt rec,
                               DbEnv.RepProcessMessage envid,
                               DbLsn ret_lsn)
                        throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by replicationProcessMessage(Dbt,Dbt,DbEnv.RepProcessMessage,DbLsn)

DbException

replicationProcessMessage

public int replicationProcessMessage(Dbt control,
                                     Dbt rec,
                                     DbEnv.RepProcessMessage envid,
                                     DbLsn ret_lsn)
                              throws DbException

The DbEnv.replicationProcessMessage method processes an incoming replication message sent by a member of the replication group to the local database environment.

For implementation reasons, all incoming replication messages must be processed using the same DbEnv handle. It is not required that a single thread of control process all messages, only that all threads of control processing messages use the same handle.

The DbEnv.replicationProcessMessage method has additional return values:

Parameters:

control - The control parameter should reference a copy of the control parameter specified by Berkeley DB on the sending environment.

envid - The envid parameter should contain the local identifier that corresponds to the environment that sent the message to be processed (see Replication environment IDs for more information).

rec - The rec parameter should reference a copy of the rec parameter specified by Berkeley DB on the sending environment.

ret_lsn - If DbEnv.replicationProcessMessage method returns Db.DB_REP_NOTPERM then the ret_lsn parameter will contain the log sequence number of this permanent log message that could not be written to disk. If DbEnv.replicationProcessMessage method returns Db.DB_REP_ISPERM then the ret_lsn parameter will contain largest log sequence number of the permanent records that are now written to disk as a result of processing this message. In all other cases the value of ret_lsn is undefined.

Returns:

• DB_REP_DUPMASTER

  The DbEnv.replicationProcessMessage method will throw an exception that encapsulates Db.DB_REP_DUPMASTER if the replication group has more than one master.

The application should reconfigure itself as a client by calling the DbEnv.replicationStart method, and then call for an election by calling DbEnv.replicationElect.

• DB_REP_HOLDELECTION

  The DbEnv.replicationProcessMessage method will throw an exception that encapsulates Db.DB_REP_HOLDELECTION if an election is needed.

The application should call for an election by calling DbEnv.replicationElect.

• DB_REP_ISPERM

  The DbEnv.replicationProcessMessage method will return Db.DB_REP_ISPERM if processing this message results in the processing of records that are permanent.

The maximum LSN of the permanent records stored is returned.

• DB_REP_NEWMASTER

  The DbEnv.replicationProcessMessage method will return Db.DB_REP_NEWMASTER if a new master has been elected.

The envid parameter contains the environment ID of the new master. If the recipient of this error return has been made master, it is the application's responsibility to begin acting as the master environment.

• DB_REP_NEWSITE

  The DbEnv.replicationProcessMessage method will return Db.DB_REP_NEWSITE if the system received contact information from a new environment.

The rec parameter contains the opaque data specified in the cdata parameter to the DbEnv.replicationStart. The application should take whatever action is needed to establish a communication channel with this new environment.

• DB_REP_NOTPERM

  The DbEnv.replicationProcessMessage method will return Db.DB_REP_NOTPERM if a message carrying a Db.DB_REP_PERMANENT flag was processed successfully, but was not written to disk.

The LSN of this record is returned. The application should take whatever action is deemed necessary to retain its recoverability characteristics.

• DB_REP_OUTDATED

  The DbEnv.replicationProcessMessage method will throw an exception that encapsulates Db.DB_REP_OUTDATED if the current environment's logs are too far out of date with respect to the master to be automatically synchronized.

The application should copy over a hot backup of the environment, run recovery, and restart the client.

Unless otherwise specified, the DbEnv.replicationProcessMessage method throws an exception that encapsulates a non-zero error value on failure.

Throws:

DbException - Signals that an exception of some sort has occurred.

rep_start

public void rep_start(Dbt cdata,
                      int flags)
               throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by replicationStart(Dbt,int)

DbException

replicationStart

public void replicationStart(Dbt cdata,
                             int flags)
                      throws DbException

The DbEnv.replicationStart method configures the database environment as a client or master in a group of replicated database environments. Replication master environments are the only database environments where replicated databases may be modified. Replication client environments are read-only as long as they are clients. Replication client environments may be upgraded to be replication master environments in the case that the current master fails or there is no master present.

The enclosing database environment must already have been opened by calling the DbEnv.open method and must already have been configured to send replication messages by calling the DbEnv.setReplicationTransport method.

Parameters:

cdata - an opaque data item that is sent over the communication infrastructure when the client or master comes online (see Connecting to a new site for more information). If no such information is useful, cdata should be null.

flags - must be set to one of the following values:

• Db.DB_REP_CLIENT

  Configure the environment as a replication client.

• Db.DB_REP_LOGSONLY

  Configure the environment as a log files-only client.

• Db.DB_REP_MASTER

  Configure the environment as a replication master.

Throws:

DbException

IllegalArgumentException - The DbEnv.replicationStart method will fail and throw a IllegalArgumentException exception if the database environment was not already configured to communicate with a replication group by a call to DbEnv.setReplicationTransport; the database environment was not already opened; or if an invalid flag value or parameter was specified.

rep_stat

public DbRepStat rep_stat(int flags)
                   throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by replicationStat(int)

DbException

replicationStat

public DbRepStat replicationStat(int flags)
                          throws DbException

The DbEnv.replicationStat method returns the replication subsystem statistics.

The DbEnv.replicationStat method creates a DbRepStat object encapsulating the replication subsystem statistics. The following data fields are available from the DbRepStat object:

For convenience, the DbRepStat class has a toString method that lists all the data fields.

Parameters:

flags - must be set to 0 or the following value:

• Db.DB_STAT_CLEAR

  Reset statistics after returning their values.

Returns:

The DbEnv.replicationStat method throws an exception that encapsulates a non-zero error value on failure.

Throws:

DbException

IllegalArgumentException - The DbEnv.replicationStat method will fail and throw a IllegalArgumentException exception if an invalid flag value or parameter was specified.

set_rep_limit

public void set_rep_limit(long bytes)
                   throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by setReplicationLimit(long)

DbException

setReplicationLimit

public void setReplicationLimit(long bytes)
                         throws DbException

The DbEnv.setReplicationLimit method imposes a byte-count limit on the amount of data that will be transmitted from a site in a single call to DbEnv.replicationProcessMessage method.

The DbEnv.setReplicationLimit method configures a database environment, not only operations performed using the specified DbEnv handle.

The DbEnv.setReplicationLimit method may not be called before the DbEnv.open method has been called.

Parameters:

bytes - specifies the maximum number of bytes that will be sent in a single call to DbEnv.replicationProcessMessage method.

Throws:

DbException - Signals that an exception of some sort has occurred.

set_rep_transport

public void set_rep_transport(int envid,
                              DbRepTransport send)
                       throws DbException

Deprecated. As of Berkeley DB 4.2, replaced by setReplicationTransport(int,DbRepTransport)

DbException

setReplicationTransport

public void setReplicationTransport(int envid,
                                    DbRepTransport send)
                             throws DbException

DbException

strerror

public static String strerror(int error)

The DbEnv.strerror method returns an error message string corresponding to the error number error parameter.

This function is a superset of the ANSI C X3.159-1989 (ANSI C) strerror(3) function. If the error number error is greater than or equal to 0, then the string returned by the system function strerror(3) is returned. If the error number is less than 0, an error string appropriate to the corresponding Berkeley DB library error is returned. See Error returns to applications for more information.

Parameters:

error - the error number for which an error message string is wanted.

Returns:

The DbEnv.strerror method returns an error message string corresponding to the error number error parameter.

get_version_major

public static int get_version_major()

Deprecated. As of Berkeley DB 4.2, replaced by getVersionMajor()

getVersionMajor

public static int getVersionMajor()

The DbEnv.getVersionMajor method returns the release major number.

The DbEnv.getVersionMajor method may be called at any time during the life of the application.

Returns:

The DbEnv.getVersionMajor method returns the release major number.

get_version_minor

public static int get_version_minor()

Deprecated. As of Berkeley DB 4.2, replaced by getVersionMinor()

getVersionMinor

public static int getVersionMinor()

The DbEnv.getVersionMinor method returns the release minor number.

The DbEnv.getVersionMinor method may be called at any time during the life of the application.

Returns:

The DbEnv.getVersionMinor method returns the release minor number.

get_version_patch

public static int get_version_patch()

Deprecated. As of Berkeley DB 4.2, replaced by getVersionPatch()

getVersionPatch

public static int getVersionPatch()

The DbEnv.getVersionPatch method returns the release patch number.

The DbEnv.getVersionPatch method may be called at any time during the life of the application.

Returns:

The DbEnv.getVersionPatch method returns the release patch number.

get_version_string

public static String get_version_string()

Deprecated. As of Berkeley DB 4.2, replaced by getVersionString()

getVersionString

public static String getVersionString()

The DbEnv.getVersionString method returns the release verbose version information, suitable for display.

The DbEnv.getVersionString method may be called at any time during the life of the application.

Returns:

The DbEnv.getVersionString method returns the release verbose version information, suitable for display.