## Environment Commands

Environments provide a structure for creating a consistent environment for processes using one or more of the features of Berkeley DB. Unlike some of the database commands, the environment commands are very low level.

The user may create and open a new DB environment by invoking:

> berkdb env
[-cdb] [-cdb_alldb] [-lock] [-log] [-txn [nosync]]
[-create] [-home directory] [-mode mode]
[-data_dir directory] [-log_dir directory] [-tmp_dir directory]
[-nommap] [-private] [-recover] [-recover_fatal] [-system_mem] [-errfile filename]
[-use_environ] [-use_environ_root] [-verbose {which on|off}]
[-region_init]
[-cachesize {gbytes bytes ncaches}]
[-mmapsize size]
[-log_max max]
[-log_buffer size]
[-lock_conflict {nmodes {matrix}}]
[-lock_detect default|oldest|random|youngest]
[-lock_max max]
[-lock_max_locks max]
[-lock_max_lockers max]
[-lock_max_objects max]
[-txn_max max]
[-client_timeout seconds]
[-server_timeout seconds]
[-server hostname]

This command opens up an environment. We automatically set the DB_THREAD and the DB_INIT_MPOOL flags. The arguments are:

- -cdb selects the DB_INIT_CDB flag for Concurrent Data Store
- -cdb_alldb selects the DB_CDB_ALLDB flag for Concurrent Data Store
- -lock selects the DB_INIT_LOCK flag for the locking subsystem
- -log selects the DB_INIT_LOG flag for the logging subsystem
- -txn selects the DB_INIT_TXN, DB_INIT_LOCK and DB_INIT_LOG flags for the transaction subsystem. If nosync is specified, then it will also select DB_TXN_NOSYNC to indicate no flushes of log on commits
- -create selects the DB_CREATE flag to create underlying files
- -home directory selects the home directory of the environment
- -data_dir directory selects the data file directory of the environment by calling DBENV->set_data_dir.
- -log_dir directory selects the log file directory of the environment by calling DBENV->set_lg_dir.
- -tmp_dir directory selects the temporary file directory of the environment by calling DBENV->set_tmp_dir.
- -mode mode sets the permissions of created files to mode
- -nommap selects the DB_NOMMAP flag to disallow using mmap'ed files
- -private selects the DB_PRIVATE flag for a private environment
- -recover selects the DB_RECOVER flag for recovery
- -recover_fatal selects the DB_RECOVER_FATAL flag for catastrophic recovery
- -system_mem selects the DB_SYSTEM_MEM flag to use system memory
- -errfile specifies the error file to use for this environment to filename by calling DBENV->set_errfile. If the file already exists then we will append to the end of the file
- -use_environ selects the DB_USE_ENVIRON flag to affect file naming
- -use_environ_root selects the DB_USE_ENVIRON_ROOT flag to have the root environment affect file naming
- -verbose produces verbose error output for the given which subsystem, using the DBENV->set_verbose method. See the description of verbose below for valid which values
- -region_init specifies that the user wants to page fault the region in on startup using the DBENV->set_region_init method call
- -cachesize sets the size of the database cache to the size specified by gbytes and bytes, broken up into ncaches number of caches using the DBENV->set_cachesize method
- -mmapsize sets the size of the database page to size using the DBENV->set_mp_mmapsize method
- -log_max sets the maximum size of the log file to max using the DBENV->set_lg_max call
- -log_buffer sets the size of the log file in bytes to size using the DBENV->set_lg_bsize call
- -lock_conflict sets the number of lock modes to nmodes and sets the locking policy for those modes to the conflict_matrix given using the DBENV->set_lk_conflict method call
- -lock_detect sets the deadlock detection policy to the given policy using the DBENV->set_lk_detect method call. The policy choices are:

- default selects the DB_LOCK_DEFAULT policy for default detection
- oldest selects DB_LOCK_OLDEST to abort the oldest locker on a deadlock
- random selects DB_LOCK_RANDOM to abort a random locker on a deadlock
- youngest selects DB_LOCK_YOUNGEST to abort the youngest locker on a deadlock

- -lock_max sets the maximum size of the lock table to max using the DBENV->set_lk_max method call
- -lock_max_locks sets the maximum number of locks to max using the DBENV->set_lk_max_locks method call
- -lock_max_lockers sets the maximum number of locking entities to max using the DBENV->set_lk_max_lockers method call
- -lock_max_objects sets the maximum number of simultaneously locked objects to max using the DBENV->set_lk_max_objects method call
- -txn_max sets the maximum size of the transaction table to max using the DBENV->set_txn_max method call
- -client_timeout sets the timeout value for the client waiting for a reply from the server for RPC operations to seconds.
- -server_timeout sets the timeout value for the server to determine an idle client is gone to seconds.
- -server specifies the hostname of the server to connect to in the DBENV->set_server call.

This command will invoke the db_env_create function. After it successfully gets a handle to an environment, we bind it to a new Tcl command of the form envX, where X is an integer starting at 0 (e.g. env0, env1, etc). We use the Tcl_CreateObjCommand() to create the top level environment command function. It is through this handle that the user can access all the commands described in the Environment Commands section. Internally, the handle we get back from DB will be stored as the ClientData portion of the new command set so that all future environment calls will have that handle readily available. Then we call the DBENV->open method call and possibly some number of setup calls as described above.

> <env> verbose which on|off

This command controls the use of debugging output for the environment. This command directly translates to a call to the DBENV->set_verbose method call. It returns either a 0 (for success), a DB error message or it throws a Tcl error with a system message. The user specifies which subsystem to control, and indicates whether debug messages should be turned on or off for that subsystem. The value of which must be one of the following:

- chkpt - Chooses the checkpointing code by using the DB_VERB_CHKPOINT value
- deadlock - Chooses the deadlocking code by using the DB_VERB_DEADLOCK value
- recovery - Chooses the recovery code by using the DB_VERB_RECOVERY value
- wait - Chooses the waitsfor code by using the DB_VERB_WAITSFOR value

> <env> close

This command closes an environment and deletes the handle. This command directly translates to a call to the DBENV->close method call. It returns either a 0 (for success), a DB error message or it throws a Tcl error with a system message.

Additionally, since the handle is no longer valid, we will call Tcl_DeleteCommand() so that further uses of the handle will be dealt with properly by Tcl itself.

Also, the close command will automatically abort any transactions and close any mpool memory files. As such we must maintain a list of open transaction and mpool handles so that we can call Tcl_DeleteCommand on those as well.

> berkdb envremove [-data_dir directory] [-force] [-home directory] -log_dir directory] [-tmp_dir directory] [-use_environ] [-use_environ_root]

This command removes the environment if it is not in use and deletes the handle. This command directly translates to a call to the DBENV->remove method call. It returns either a 0 (for success), a DB error message or it throws a Tcl error with a system message. The arguments are:

- -force selects the DB_FORCE flag to remove even if other processes have the environment open
- -home directory specifies the home directory of the environment
- -data_dir directory selects the data file directory of the environment by calling DBENV->set_data_dir.
- -log_dir directory selects the log file directory of the environment by calling DBENV->set_lg_dir.
- -tmp_dir directory selects the temporary file directory of the environment by calling DBENV->set_tmp_dir.
- -use_environ selects the DB_USE_ENVIRON flag to affect file naming
- -use_environ_root selects the DB_USE_ENVIRON_ROOT flag to affect file naming