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]
    [-lock_timeout timeout]
    [-overwrite]
    [-txn_max max]
    [-txn_timeout timeout]
    [-client_timeout seconds]
    [-server_timeout seconds]
    [-server hostname]
    [-rep_master] [-rep_client]
    [-rep_transport { machineid sendproc }]
 

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

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:

> <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]
[-overwrite]
[-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: