env.html 13.5 KB
Newer Older
unknown's avatar
unknown committed
1 2 3 4 5 6 7 8 9 10 11
<!--Copyright 1999-2002 by Sleepycat Software, Inc.-->
<!--All rights reserved.-->
<html>
<head>
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   <meta name="GENERATOR" content="Mozilla/4.75 [en] (X11; U; Linux 2.2.16-22 i686) [Netscape]">
</head>
<body>

<h2>
Environment Commands</h2>
unknown's avatar
unknown committed
12 13 14
Environments provide a structure for creating a consistent environment
for processes using one or more of the features of Berkeley DB.&nbsp; Unlike
some of the database commands, the environment commands are very low level.
unknown's avatar
unknown committed
15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48
<br>
<hr WIDTH="100%">
<p>The user may create and open a new DB environment&nbsp; by invoking:
<p><b>> berkdb env</b>
<br><b>&nbsp;&nbsp;&nbsp; [-cdb] [-cdb_alldb] [-lock] [-log] [-txn [nosync]]</b>
<br><b>&nbsp;&nbsp;&nbsp; [-create] [-home<i> directory</i>] [-mode <i>mode</i>]</b>
<br><b>&nbsp;&nbsp;&nbsp; [-data_dir <i>directory</i>] [-log_dir <i>directory</i>]
[-tmp_dir <i>directory</i>]</b>
<br><b>&nbsp;&nbsp;&nbsp; [-nommap] [-private] [-recover] [-recover_fatal]
[-system_mem] [-errfile <i>filename</i>]</b>
<br><b>&nbsp;&nbsp;&nbsp; [-use_environ] [-use_environ_root] [-verbose
{<i>which </i>on|off}]</b>
<br><b>&nbsp;&nbsp;&nbsp; [-region_init]</b>
<br><b>&nbsp;&nbsp;&nbsp; [-cachesize {<i>gbytes bytes ncaches</i>}]</b>
<br><b>&nbsp;&nbsp;&nbsp; [-mmapsize<i> size</i>]</b>
<br><b>&nbsp;&nbsp;&nbsp; [-log_max <i>max</i>]</b>
<br><b>&nbsp;&nbsp;&nbsp; [-log_buffer <i>size</i>]</b>
<br><b>&nbsp;&nbsp;&nbsp; [-lock_conflict {<i>nmodes </i>{<i>matrix</i>}}]</b>
<br><b>&nbsp;&nbsp;&nbsp; [-lock_detect default|oldest|random|youngest]</b>
<br><b>&nbsp;&nbsp;&nbsp; [-lock_max <i>max</i>]</b>
<br><b>&nbsp;&nbsp;&nbsp; [-lock_max_locks <i>max</i>]</b>
<br><b>&nbsp;&nbsp;&nbsp; [-lock_max_lockers <i>max</i>]</b>
<br><b>&nbsp;&nbsp;&nbsp; [-lock_max_objects <i>max</i>]</b>
<br><b>&nbsp;&nbsp;&nbsp; [-lock_timeout <i>timeout</i>]</b>
<br><b>&nbsp;&nbsp;&nbsp; [-overwrite]</b>
<br><b>&nbsp;&nbsp;&nbsp; [-txn_max <i>max</i>]</b>
<br><b>&nbsp;&nbsp;&nbsp; [-txn_timeout <i>timeout</i>]</b>
<br><b>&nbsp;&nbsp;&nbsp; [-client_timeout <i>seconds</i>]</b>
<br><b>&nbsp;&nbsp;&nbsp; [-server_timeout <i>seconds</i>]</b>
<br><b>&nbsp;&nbsp;&nbsp; [-server <i>hostname</i>]</b>
<br><b>&nbsp;&nbsp;&nbsp; [-rep_master] [-rep_client]</b>
<br><b>&nbsp;&nbsp;&nbsp; [-rep_transport <i>{ machineid sendproc }</i>]</b>
<br>&nbsp;
<p>This command opens up an environment.&nbsp;&nbsp; We automatically set
unknown's avatar
unknown committed
49
the DB_THREAD and the DB_INIT_MPOOL flags.&nbsp; The arguments are:
unknown's avatar
unknown committed
50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250
<ul>
<li>
<b>-cdb</b> selects the DB_INIT_CDB flag for Concurrent Data Store</li>

<li>
<b>-cdb_alldb</b> selects the DB_CDB_ALLDB flag for Concurrent Data Store</li>

<li>
<b>-lock</b> selects the DB_INIT_LOCK flag for the locking subsystem</li>

<li>
<b>-log</b> selects the DB_INIT_LOG flag for the logging subsystem</li>

<li>
<b>-txn</b> selects the DB_INIT_TXN, DB_INIT_LOCK and DB_INIT_LOG flags
for the transaction subsystem.&nbsp; If <b>nosync</b> is specified, then
it will also select DB_TXN_NOSYNC to indicate no flushes of log on commits</li>

<li>
<b>-create </b>selects the DB_CREATE flag to create underlying files</li>

<li>
<b>-home <i>directory </i></b>selects the home directory of the environment</li>

<li>
<b>-data_dir <i>directory </i></b>selects the data file directory of the
environment by calling <a href="../../docs/api_c/env_set_data_dir.html">DBENV->set_data_dir</a>.</li>

<li>
<b>-log_dir <i>directory </i></b>selects the log file directory of the
environment&nbsp; by calling <a href="../../docs/api_c/env_set_lg_dir.html">DBENV->set_lg_dir</a>.</li>

<li>
<b>-tmp_dir <i>directory </i></b>selects the temporary file directory of
the environment&nbsp; by calling <a href="../../docs/api_c/env_set_tmp_dir.so">DBENV->set_tmp_dir</a>.</li>

<li>
<b>-mode <i>mode </i></b>sets the permissions of created files to <b><i>mode</i></b></li>

<li>
<b>-nommap</b> selects the DB_NOMMAP flag to disallow using mmap'ed files</li>

<li>
<b>-private</b> selects the DB_PRIVATE flag for a private environment</li>

<li>
<b>-recover</b> selects the DB_RECOVER flag for recovery</li>

<li>
<b>-recover_fatal</b> selects the DB_RECOVER_FATAL flag for catastrophic
recovery</li>

<li>
<b>-system_mem</b> selects the DB_SYSTEM_MEM flag to use system memory</li>

<li>
<b>-errfile </b>specifies the error file to use for this environment to
<b><i>filename</i></b>
by calling <a href="../../docs/api_c/env_set_errfile.html">DBENV->set_errfile</a><b><i>.
</i></b>If
the file already exists then we will append to the end of the file</li>

<li>
<b>-use_environ</b> selects the DB_USE_ENVIRON flag to affect file naming</li>

<li>
<b>-use_environ_root</b> selects the DB_USE_ENVIRON_ROOT flag to have the
root environment affect file naming</li>

<li>
<b>-verbose</b> produces verbose error output for the given which subsystem,
using the <a href="../../docs/api_c/dbenv_set_verbose.html">DBENV->set_verbose</a>
method.&nbsp;&nbsp; See the description of <a href="#> <env> verbose which on|off">verbose</a>
below for valid <b><i>which </i></b>values</li>

<li>
<b>-region_init </b>specifies that the user wants to page fault the region
in on startup using the <a href="../../docs/api_c/env_set_region_init.html">DBENV->set_region_init</a>
method call</li>

<li>
<b>-cachesize </b>sets the size of the database cache to the size&nbsp;
specified by <b><i>gbytes </i></b>and <b><i>bytes, </i></b>broken up into
<b><i>ncaches</i></b>
number of caches using the <a href="../../docs/api_c/env_set_cachesize.html">DBENV->set_cachesize</a>
method</li>

<li>
<b>-mmapsize </b>sets the size of the database page to <b><i>size </i></b>using
the <a href="../../docs/api_c/env_set_mp_mmapsize.html">DBENV->set_mp_mmapsize</a>
method</li>

<li>
<b>-log_max </b>sets the maximum size of the log file to <b><i>max</i></b>
using the <a href="../../docs/api_c/env_set_lg_max.html">DBENV->set_lg_max</a>
call</li>

<li>
<b>-log_regionmax </b>sets the size of the log region to <b><i>max</i></b>
using the <a href="../../docs/api_c/env_set_lg_regionmax.html">DBENV->set_lg_regionmax</a>
call</li>

<li>
<b>-log_buffer </b>sets the size of the log file in bytes to <b><i>size</i></b>
using the <a href="../../docs/api_c/env_set_lg_bsize.html">DBENV->set_lg_bsize</a>
call</li>

<li>
<b>-lock_conflict </b>sets the number of lock modes to <b><i>nmodes</i></b>
and sets the locking policy for those modes to the <b><i>conflict_matrix</i></b>
given using the <a href="../../docs/api_c/env_set_lk_conflict.html">DBENV->set_lk_conflict</a>
method call</li>

<li>
<b>-lock_detect </b>sets the deadlock detection policy to the given policy
using the <a href="../../docs/env_set_lk_detect.html">DBENV->set_lk_detect</a>
method call.&nbsp; The policy choices are:</li>

<ul>
<li>
<b>default</b> selects the DB_LOCK_DEFAULT policy for default detection</li>

<li>
<b>oldest </b>selects DB_LOCK_OLDEST to abort the oldest locker on a deadlock</li>

<li>
<b>random</b> selects DB_LOCK_RANDOM to abort a random locker on a deadlock</li>

<li>
<b>youngest</b> selects DB_LOCK_YOUNGEST to abort the youngest locker on
a deadlock</li>
</ul>

<li>
<b>-lock_max </b>sets the maximum size of the lock table to <b><i>max </i></b>using
the <a href="../../docs/api_c/env_set_lk_max.html">DBENV->set_lk_max</a>
method call</li>

<li>
<b>-lock_max_locks </b>sets the maximum number of locks to <b><i>max </i></b>using
the <a href="../../docs/api_c/env_set_lk_max_locks.html">DBENV->set_lk_max_locks</a>
method call</li>

<li>
<b>-lock_max_lockers </b>sets the maximum number of locking entities to
<b><i>max
</i></b>using the <a href="../../docs/api_c/env_set_lk_max_lockers.html">DBENV->set_lk_max_lockers</a>
method call</li>

<li>
<b>-lock_max_objects </b>sets the maximum number of simultaneously locked
objects 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>
method call</li>

<li>
<b>-lock_timeout </b>sets the timeout for locks in the environment</li>

<li>
<b>-overwrite </b>sets DB_OVERWRITE flag</li>

<li>
<b>-txn_max </b>sets the maximum size of the transaction table to <b><i>max</i></b>
using the <a href="../../docs/api_c/env_set_txn_max.html">DBENV->set_txn_max</a>
method call</li>

<li>
<b>-txn_timeout </b>sets the timeout for transactions in the environment</li>

<li>
<b>-client_timeout</b> sets the timeout value for the client waiting for
a reply from the server for RPC operations to <b><i>seconds</i></b>.</li>

<li>
<b>-server_timeout</b> sets the timeout value for the server to determine
an idle client is gone to <b><i>seconds</i></b>.</li>

<li>
<b>-server </b>specifies the <b><i>hostname</i></b> of the server
to connect to in the <a href="../../docs/api_c/env_set_server.html">DBENV->set_server</a>
call.</li>

<li>
<b>-rep_client </b>sets the newly created environment to be a
replication client, using the <a href="../../docs/api_c/rep_client.html">
DBENV->rep_client</a> call.</li>

<li>
<b>-rep_master </b>sets the newly created environment to be a
replication master, using the <a href="../../docs/api_c/rep_master.html">
DBENV->rep_master</a> call.</li>

<li>
<b>-rep_transport </b>specifies the replication transport function,
using the
<a href="../../docs/api_c/rep_transport.html">DBENV->set_rep_transport</a>
call.  This site's machine ID is set to <b><i>machineid</i></b> and
the send function, a Tcl proc, is set to <b><i>sendproc</i></b>.</li>

</ul>

This command will invoke the <a href="../../docs/api_c/env_create.html">db_env_create</a>
unknown's avatar
unknown committed
251
function.&nbsp; After it successfully gets a handle to an environment,
unknown's avatar
unknown committed
252 253 254
we bind it to a new Tcl command of the form <b><i>envX</i></b>, where X
is an integer starting at&nbsp; 0 (e.g. <b>env0, env1, </b>etc).&nbsp;
We use the <i>Tcl_CreateObjCommand()</i> to create the top level environment
unknown's avatar
unknown committed
255
command function.&nbsp; It is through this handle that the user can access
unknown's avatar
unknown committed
256 257 258
all the commands described in the <a href="#Environment Commands">Environment
Commands</a> section.&nbsp; Internally, the handle we get back from DB
will be stored as the <i>ClientData</i> portion of the new command set
unknown's avatar
unknown committed
259
so that all future environment calls will have that handle readily available.&nbsp;
unknown's avatar
unknown committed
260
Then we call the <a href="../../docs/api_c/env_open.html">DBENV->open</a>
unknown's avatar
unknown committed
261
method call and possibly some number of setup calls as described above.
unknown's avatar
unknown committed
262 263 264 265 266 267
<p>
<hr WIDTH="100%">
<br><a NAME="> <env> verbose which on|off"></a><b>> &lt;env> verbose <i>which</i>
on|off</b>
<p>This command controls the use of debugging output for the environment.&nbsp;
This command directly translates to a call to the <a href="../../docs/api_c/dbenv_set_verbose.html">DBENV->set_verbose</a>
unknown's avatar
unknown committed
268 269
method call.&nbsp; It returns either a 0 (for success), a DB error message
or it throws a Tcl error with a system message.&nbsp; The user specifies
unknown's avatar
unknown committed
270
<b><i>which</i></b>
unknown's avatar
unknown committed
271
subsystem to control, and indicates whether debug messages should be turned
unknown's avatar
unknown committed
272 273
<b>on</b>
or <b>off</b> for that subsystem.&nbsp; The value of <b><i>which</i></b>
unknown's avatar
unknown committed
274
must be one of the following:
unknown's avatar
unknown committed
275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295
<ul>
<li>
<b>chkpt</b> - Chooses the checkpointing code by using the DB_VERB_CHKPOINT
value</li>

<li>
<b>deadlock </b>- Chooses the deadlocking code by using the DB_VERB_DEADLOCK
value</li>

<li>
<b>recovery </b>- Chooses the recovery code by using the DB_VERB_RECOVERY
value</li>

<li>
<b>wait </b>- Chooses the waitsfor code by using the DB_VERB_WAITSFOR value</li>
</ul>

<hr WIDTH="100%">
<p><a NAME="> <env> close"></a><b>> &lt;env> close</b>
<p>This command closes an environment and deletes the handle.&nbsp; This
command directly translates to a call to the <a href="../../docs/api_c/env_close.html">DBENV->close</a>
unknown's avatar
unknown committed
296 297
method call.&nbsp; It returns either a 0 (for success), a DB error message
or it throws a Tcl error with a system message.
unknown's avatar
unknown committed
298 299
<p>Additionally, since the handle is no longer valid, we will call <i>Tcl_DeleteCommand()
</i>so
unknown's avatar
unknown committed
300
that further uses of the handle will be dealt with properly by Tcl itself.
unknown's avatar
unknown committed
301 302
<p>Also, the close command will automatically abort any <a href="txn.html">transactions</a>
and close any <a href="mpool.html">mpool</a> memory files.&nbsp; As such
unknown's avatar
unknown committed
303
we must maintain a list of open transaction and mpool handles so that we
unknown's avatar
unknown committed
304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319
can call <i>Tcl_DeleteCommand</i> on those as well.
<p>
<hr WIDTH="100%">

<b>> berkdb envremove<br>
[-data_dir <i>directory</i>]<br>
[-force]<br>
[-home <i>directory</i>]<br>
[-log_dir <i>directory</i>]<br>
[-overwrite]<br>
[-tmp_dir <i>directory</i>]<br>
[-use_environ]<br>
[-use_environ_root]</b>

<p>This command removes the environment if it is not in use and deletes
the handle.&nbsp; This command directly translates to a call to the <a href="../../docs/api_c/env_remove.html">DBENV->remove</a>
unknown's avatar
unknown committed
320 321
method call.&nbsp; It returns either a 0 (for success), a DB error message
or it throws a Tcl error with a system message.&nbsp; The arguments are:
unknown's avatar
unknown committed
322 323 324 325 326 327 328
<ul>
<li>
<b>-force</b> selects the DB_FORCE flag to remove even if other processes
have the environment open</li>

<li>
<b>-home <i>directory</i> </b>specifies the home directory of the environment</li>
unknown's avatar
unknown committed
329

unknown's avatar
unknown committed
330 331 332
<li>
<b>-data_dir <i>directory </i></b>selects the data file directory of the
environment by calling <a href="../../docs/api_c/env_set_data_dir.html">DBENV->set_data_dir</a>.</li>
unknown's avatar
unknown committed
333

unknown's avatar
unknown committed
334 335 336
<li>
<b>-log_dir <i>directory </i></b>selects the log file directory of the
environment&nbsp; by calling <a href="../../docs/api_c/env_set_lg_dir.html">DBENV->set_lg_dir</a>.</li>
unknown's avatar
unknown committed
337

unknown's avatar
unknown committed
338 339
<li>
<b>-overwrite </b>sets DB_OVERWRITE flag</li>
unknown's avatar
unknown committed
340

unknown's avatar
unknown committed
341 342 343
<li>
<b>-tmp_dir <i>directory </i></b>selects the temporary file directory of
the environment&nbsp; by calling <a href="../../docs/api_c/env_set_tmp_dir.so">DBENV->set_tmp_dir</a>.</li>
unknown's avatar
unknown committed
344

unknown's avatar
unknown committed
345 346
<li>
<b>-use_environ </b>selects the DB_USE_ENVIRON flag to affect file naming</li>
unknown's avatar
unknown committed
347

unknown's avatar
unknown committed
348 349 350 351
<li>
<b>-use_environ_root</b> selects the DB_USE_ENVIRON_ROOT flag to affect
file naming</li>
</ul>
unknown's avatar
unknown committed
352

unknown's avatar
unknown committed
353 354
</body>
</html>