1<!--Copyright 1999,2008 Oracle. All rights reserved.--> 2<html> 3<head> 4 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 5 <meta name="GENERATOR" content="Mozilla/4.75 [en] (X11; U; Linux 2.2.16-22 i686) [Netscape]"> 6</head> 7<body> 8 9<h2> 10Environment Commands</h2> 11Environments provide a structure for creating a consistent environment 12for processes using one or more of the features of Berkeley DB. Unlike 13some of the database commands, the environment commands are very low level. 14<br> 15<hr WIDTH="100%"> 16<p>The user may create and open a new DB environment by invoking: 17<p><b>> berkdb env</b> 18<br><b> [-cdb] [-cdb_alldb] [-lock] [-log] [-txn [nosync]]</b> 19<br><b> [-create] [-home<i> directory</i>] [-mode <i>mode</i>]</b> 20<br><b> [-data_dir <i>directory</i>] [-log_dir <i>directory</i>] 21[-tmp_dir <i>directory</i>]</b> 22<br><b> [-nommap] [-private] [-recover] [-recover_fatal] 23[-system_mem] [-errfile <i>filename</i>]</b> 24<br><b> [-use_environ] [-use_environ_root] [-verbose 25{<i>which </i>on|off}]</b> 26<br><b> [-region_init]</b> 27<br><b> [-cachesize {<i>gbytes bytes ncaches</i>}]</b> 28<br><b> [-mmapsize<i> size</i>]</b> 29<br><b> [-log_max <i>max</i>]</b> 30<br><b> [-log_buffer <i>size</i>]</b> 31<br><b> [-lock_conflict {<i>nmodes </i>{<i>matrix</i>}}]</b> 32<br><b> [-lock_detect default|oldest|random|youngest]</b> 33<br><b> [-lock_max <i>max</i>]</b> 34<br><b> [-lock_max_locks <i>max</i>]</b> 35<br><b> [-lock_max_lockers <i>max</i>]</b> 36<br><b> [-lock_max_objects <i>max</i>]</b> 37<br><b> [-lock_timeout <i>timeout</i>]</b> 38<br><b> [-overwrite]</b> 39<br><b> [-txn_max <i>max</i>]</b> 40<br><b> [-txn_timeout <i>timeout</i>]</b> 41<br><b> [-client_timeout <i>seconds</i>]</b> 42<br><b> [-server_timeout <i>seconds</i>]</b> 43<br><b> [-server <i>hostname</i>]</b> 44<br><b> [-rep_master] [-rep_client]</b> 45<br><b> [-rep_transport <i>{ machineid sendproc }</i>]</b> 46<br> 47<p>This command opens up an environment. We automatically set 48the DB_THREAD and the DB_INIT_MPOOL flags. The arguments are: 49<ul> 50<li> 51<b>-cdb</b> selects the DB_INIT_CDB flag for Concurrent Data Store</li> 52 53<li> 54<b>-cdb_alldb</b> selects the DB_CDB_ALLDB flag for Concurrent Data Store</li> 55 56<li> 57<b>-lock</b> selects the DB_INIT_LOCK flag for the locking subsystem</li> 58 59<li> 60<b>-log</b> selects the DB_INIT_LOG flag for the logging subsystem</li> 61 62<li> 63<b>-txn</b> selects the DB_INIT_TXN, DB_INIT_LOCK and DB_INIT_LOG flags 64for the transaction subsystem. If <b>nosync</b> is specified, then 65it will also select DB_TXN_NOSYNC to indicate no flushes of log on commits</li> 66 67<li> 68<b>-create </b>selects the DB_CREATE flag to create underlying files</li> 69 70<li> 71<b>-home <i>directory </i></b>selects the home directory of the environment</li> 72 73<li> 74<b>-data_dir <i>directory </i></b>selects the data file directory of the 75environment by calling <a href="../../docs/api_c/env_set_data_dir.html">DBENV->set_data_dir</a>.</li> 76 77<li> 78<b>-log_dir <i>directory </i></b>selects the log file directory of the 79environment by calling <a href="../../docs/api_c/env_set_lg_dir.html">DBENV->set_lg_dir</a>.</li> 80 81<li> 82<b>-tmp_dir <i>directory </i></b>selects the temporary file directory of 83the environment by calling <a href="../../docs/api_c/env_set_tmp_dir.so">DBENV->set_tmp_dir</a>.</li> 84 85<li> 86<b>-mode <i>mode </i></b>sets the permissions of created files to <b><i>mode</i></b></li> 87 88<li> 89<b>-nommap</b> selects the DB_NOMMAP flag to disallow using mmap'ed files</li> 90 91<li> 92<b>-private</b> selects the DB_PRIVATE flag for a private environment</li> 93 94<li> 95<b>-recover</b> selects the DB_RECOVER flag for recovery</li> 96 97<li> 98<b>-recover_fatal</b> selects the DB_RECOVER_FATAL flag for catastrophic 99recovery</li> 100 101<li> 102<b>-system_mem</b> selects the DB_SYSTEM_MEM flag to use system memory</li> 103 104<li> 105<b>-errfile </b>specifies the error file to use for this environment to 106<b><i>filename</i></b> 107by calling <a href="../../docs/api_c/env_set_errfile.html">DBENV->set_errfile</a><b><i>. 108</i></b>If 109the file already exists then we will append to the end of the file</li> 110 111<li> 112<b>-use_environ</b> selects the DB_USE_ENVIRON flag to affect file naming</li> 113 114<li> 115<b>-use_environ_root</b> selects the DB_USE_ENVIRON_ROOT flag to have the 116root environment affect file naming</li> 117 118<li> 119<b>-verbose</b> produces verbose error output for the given which subsystem, 120using the <a href="../../docs/api_c/dbenv_set_verbose.html">DBENV->set_verbose</a> 121method. See the description of <a href="#> <env> verbose which on|off">verbose</a> 122below for valid <b><i>which </i></b>values</li> 123 124<li> 125<b>-region_init </b>specifies that the user wants to page fault the region 126in on startup using the <a href="../../docs/api_c/env_set_region_init.html">DBENV->set_region_init</a> 127method call</li> 128 129<li> 130<b>-cachesize </b>sets the size of the database cache to the size 131specified by <b><i>gbytes </i></b>and <b><i>bytes, </i></b>broken up into 132<b><i>ncaches</i></b> 133number of caches using the <a href="../../docs/api_c/env_set_cachesize.html">DBENV->set_cachesize</a> 134method</li> 135 136<li> 137<b>-mmapsize </b>sets the size of the database page to <b><i>size </i></b>using 138the <a href="../../docs/api_c/env_set_mp_mmapsize.html">DBENV->set_mp_mmapsize</a> 139method</li> 140 141<li> 142<b>-log_max </b>sets the maximum size of the log file to <b><i>max</i></b> 143using the <a href="../../docs/api_c/env_set_lg_max.html">DBENV->set_lg_max</a> 144call</li> 145 146<li> 147<b>-log_regionmax </b>sets the size of the log region to <b><i>max</i></b> 148using the <a href="../../docs/api_c/env_set_lg_regionmax.html">DBENV->set_lg_regionmax</a> 149call</li> 150 151<li> 152<b>-log_buffer </b>sets the size of the log file in bytes to <b><i>size</i></b> 153using the <a href="../../docs/api_c/env_set_lg_bsize.html">DBENV->set_lg_bsize</a> 154call</li> 155 156<li> 157<b>-lock_conflict </b>sets the number of lock modes to <b><i>nmodes</i></b> 158and sets the locking policy for those modes to the <b><i>conflict_matrix</i></b> 159given using the <a href="../../docs/api_c/env_set_lk_conflict.html">DBENV->set_lk_conflict</a> 160method call</li> 161 162<li> 163<b>-lock_detect </b>sets the deadlock detection policy to the given policy 164using the <a href="../../docs/env_set_lk_detect.html">DBENV->set_lk_detect</a> 165method call. The policy choices are:</li> 166 167<ul> 168<li> 169<b>default</b> selects the DB_LOCK_DEFAULT policy for default detection</li> 170 171<li> 172<b>oldest </b>selects DB_LOCK_OLDEST to abort the oldest locker on a deadlock</li> 173 174<li> 175<b>random</b> selects DB_LOCK_RANDOM to abort a random locker on a deadlock</li> 176 177<li> 178<b>youngest</b> selects DB_LOCK_YOUNGEST to abort the youngest locker on 179a deadlock</li> 180</ul> 181 182<li> 183<b>-lock_max_locks </b>sets the maximum number of locks to <b><i>max </i></b>using 184the <a href="../../docs/api_c/env_set_lk_max_locks.html">DBENV->set_lk_max_locks</a> 185method call</li> 186 187<li> 188<b>-lock_max_lockers </b>sets the maximum number of locking entities to 189<b><i>max 190</i></b>using the <a href="../../docs/api_c/env_set_lk_max_lockers.html">DBENV->set_lk_max_lockers</a> 191method call</li> 192 193<li> 194<b>-lock_max_objects </b>sets the maximum number of simultaneously locked 195objects to <b><i>max </i></b>using the <a href="../../docs/api_c/env_set_lk_max_objects.html">DBENV->set_lk_max_objects</a> 196method call</li> 197 198<li> 199<b>-lock_timeout </b>sets the timeout for locks in the environment</li> 200 201<li> 202<b>-overwrite </b>sets DB_OVERWRITE flag</li> 203 204<li> 205<b>-txn_max </b>sets the maximum size of the transaction table to <b><i>max</i></b> 206using the <a href="../../docs/api_c/env_set_txn_max.html">DBENV->set_txn_max</a> 207method call</li> 208 209<li> 210<b>-txn_timeout </b>sets the timeout for transactions in the environment</li> 211 212<li> 213<b>-client_timeout</b> sets the timeout value for the client waiting for 214a reply from the server for RPC operations to <b><i>seconds</i></b>.</li> 215 216<li> 217<b>-server_timeout</b> sets the timeout value for the server to determine 218an idle client is gone to <b><i>seconds</i></b>.</li> 219 220<li> 221<b>-server </b>specifies the <b><i>hostname</i></b> of the server 222to connect to in the <a href="../../docs/api_c/env_set_server.html">DBENV->set_server</a> 223call.</li> 224 225<li> 226<b>-rep_client </b>sets the newly created environment to be a 227replication client, using the <a href="../../docs/api_c/rep_client.html"> 228DBENV->rep_client</a> call.</li> 229 230<li> 231<b>-rep_master </b>sets the newly created environment to be a 232replication master, using the <a href="../../docs/api_c/rep_master.html"> 233DBENV->rep_master</a> call.</li> 234 235<li> 236<b>-rep_transport </b>specifies the replication transport function, 237using the 238<a href="../../docs/api_c/rep_transport.html">DBENV->rep_set_transport</a> 239call. This site's machine ID is set to <b><i>machineid</i></b> and 240the send function, a Tcl proc, is set to <b><i>sendproc</i></b>.</li> 241 242</ul> 243 244This command will invoke the <a href="../../docs/api_c/env_create.html">db_env_create</a> 245function. After it successfully gets a handle to an environment, 246we bind it to a new Tcl command of the form <b><i>envX</i></b>, where X 247is an integer starting at 0 (e.g. <b>env0, env1, </b>etc). 248We use the <i>Tcl_CreateObjCommand()</i> to create the top level environment 249command function. It is through this handle that the user can access 250all the commands described in the <a href="#Environment Commands">Environment 251Commands</a> section. Internally, the handle we get back from DB 252will be stored as the <i>ClientData</i> portion of the new command set 253so that all future environment calls will have that handle readily available. 254Then we call the <a href="../../docs/api_c/env_open.html">DBENV->open</a> 255method call and possibly some number of setup calls as described above. 256<p> 257<hr WIDTH="100%"> 258<br><a NAME="> <env> verbose which on|off"></a><b>> <env> verbose <i>which</i> 259on|off</b> 260<p>This command controls the use of debugging output for the environment. 261This command directly translates to a call to the <a href="../../docs/api_c/dbenv_set_verbose.html">DBENV->set_verbose</a> 262method call. It returns either a 0 (for success), a DB error message 263or it throws a Tcl error with a system message. The user specifies 264<b><i>which</i></b> 265subsystem to control, and indicates whether debug messages should be turned 266<b>on</b> 267or <b>off</b> for that subsystem. The value of <b><i>which</i></b> 268must be one of the following: 269<ul> 270<li> 271<b>deadlock </b>- Chooses the deadlocking code by using the DB_VERB_DEADLOCK 272value</li> 273 274<li> 275<b>recovery </b>- Chooses the recovery code by using the DB_VERB_RECOVERY 276value</li> 277 278<li> 279<b>wait </b>- Chooses the waitsfor code by using the DB_VERB_WAITSFOR value</li> 280</ul> 281 282<hr WIDTH="100%"> 283<p><a NAME="> <env> close"></a><b>> <env> close</b> 284<p>This command closes an environment and deletes the handle. This 285command directly translates to a call to the <a href="../../docs/api_c/env_close.html">DBENV->close</a> 286method call. It returns either a 0 (for success), a DB error message 287or it throws a Tcl error with a system message. 288<p>Additionally, since the handle is no longer valid, we will call <i>Tcl_DeleteCommand() 289</i>so 290that further uses of the handle will be dealt with properly by Tcl itself. 291<p>Also, the close command will automatically abort any <a href="txn.html">transactions</a> 292and close any <a href="mpool.html">mpool</a> memory files. As such 293we must maintain a list of open transaction and mpool handles so that we 294can call <i>Tcl_DeleteCommand</i> on those as well. 295<p> 296<hr WIDTH="100%"> 297 298<b>> berkdb envremove<br> 299[-data_dir <i>directory</i>]<br> 300[-force]<br> 301[-home <i>directory</i>]<br> 302[-log_dir <i>directory</i>]<br> 303[-overwrite]<br> 304[-tmp_dir <i>directory</i>]<br> 305[-use_environ]<br> 306[-use_environ_root]</b> 307 308<p>This command removes the environment if it is not in use and deletes 309the handle. This command directly translates to a call to the <a href="../../docs/api_c/env_remove.html">DBENV->remove</a> 310method call. It returns either a 0 (for success), a DB error message 311or it throws a Tcl error with a system message. The arguments are: 312<ul> 313<li> 314<b>-force</b> selects the DB_FORCE flag to remove even if other processes 315have the environment open</li> 316 317<li> 318<b>-home <i>directory</i> </b>specifies the home directory of the environment</li> 319 320<li> 321<b>-data_dir <i>directory </i></b>selects the data file directory of the 322environment by calling <a href="../../docs/api_c/env_set_data_dir.html">DBENV->set_data_dir</a>.</li> 323 324<li> 325<b>-log_dir <i>directory </i></b>selects the log file directory of the 326environment by calling <a href="../../docs/api_c/env_set_lg_dir.html">DBENV->set_lg_dir</a>.</li> 327 328<li> 329<b>-overwrite </b>sets DB_OVERWRITE flag</li> 330 331<li> 332<b>-tmp_dir <i>directory </i></b>selects the temporary file directory of 333the environment by calling <a href="../../docs/api_c/env_set_tmp_dir.so">DBENV->set_tmp_dir</a>.</li> 334 335<li> 336<b>-use_environ </b>selects the DB_USE_ENVIRON flag to affect file naming</li> 337 338<li> 339<b>-use_environ_root</b> selects the DB_USE_ENVIRON_ROOT flag to affect 340file naming</li> 341</ul> 342 343</body> 344</html> 345