330 lines
20 KiB
HTML
330 lines
20 KiB
HTML
<!--$Id-->
|
|
<!--Copyright (c) 1997,2008 Oracle. All rights reserved.-->
|
|
<!--See the file LICENSE for redistribution information.-->
|
|
<html>
|
|
<head>
|
|
<title>Berkeley DB: DbEnv::set_flags</title>
|
|
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
|
|
<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++">
|
|
</head>
|
|
<body bgcolor=white>
|
|
<table width="100%"><tr valign=top>
|
|
<td>
|
|
<b>DbEnv::set_flags</b>
|
|
</td>
|
|
<td align=right>
|
|
<a href="../api_cxx/api_core.html"><img src="../images/api.gif" alt="API"></a>
|
|
<a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a></td>
|
|
</tr></table>
|
|
<hr size=1 noshade>
|
|
<tt>
|
|
<b><pre>
|
|
#include <db_cxx.h>
|
|
<p>
|
|
int
|
|
DbEnv::set_flags(u_int32_t flags, int onoff);
|
|
<p>
|
|
int
|
|
DbEnv::get_flags(u_int32_t *flagsp)
|
|
</pre></b>
|
|
<hr size=1 noshade>
|
|
<b>Description: DbEnv::set_flags</b>
|
|
<p>Configure a database environment.</p>
|
|
<p>The database environment's flag values may also be configured using the
|
|
environment's <a href="../ref/env/db_config.html#DB_CONFIG">DB_CONFIG</a> 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 <a href="../ref/env/db_config.html#DB_CONFIG">DB_CONFIG</a> file is read when the database environment
|
|
is opened, it will silently overrule configuration done before that
|
|
time.</p>
|
|
<p>The DbEnv::set_flags method
|
|
either returns a non-zero error value
|
|
or throws an exception that encapsulates a non-zero error value on
|
|
failure, and returns 0 on success.
|
|
</p>
|
|
<b>Parameters</b> <br>
|
|
<b>flags</b><ul compact><li>The <b>flags</b> parameter must be set by bitwise inclusively <b>OR</b>'ing together one or more
|
|
of the following values:
|
|
<br>
|
|
<b><a name="DB_AUTO_COMMIT">DB_AUTO_COMMIT</a></b><ul compact><li>If set, <a href="../api_cxx/db_class.html">Db</a> handle operations for which no explicit transaction
|
|
handle was specified, and which modify databases in the database
|
|
environment, will be automatically enclosed within a transaction.
|
|
<p>Calling DbEnv::set_flags with the <a href="../api_cxx/env_set_flags.html#DB_AUTO_COMMIT">DB_AUTO_COMMIT</a> flag only affects
|
|
the specified <a href="../api_cxx/env_class.html">DbEnv</a> handle (and any other Berkeley DB handles opened
|
|
within the scope of that handle).
|
|
For consistent behavior across the environment, all <a href="../api_cxx/env_class.html">DbEnv</a>
|
|
handles opened in the environment must either set the <a href="../api_cxx/env_set_flags.html#DB_AUTO_COMMIT">DB_AUTO_COMMIT</a> flag
|
|
or the flag should be specified in the <a href="../ref/env/db_config.html#DB_CONFIG">DB_CONFIG</a> configuration
|
|
file.</p>
|
|
<p>The <a href="../api_cxx/env_set_flags.html#DB_AUTO_COMMIT">DB_AUTO_COMMIT</a> flag may be used to configure Berkeley DB at any time during
|
|
the life of the application.</p></ul>
|
|
<a name="2"><!--meow--></a>
|
|
<b><a name="DB_CDB_ALLDB">DB_CDB_ALLDB</a></b><ul compact><li>If set, Berkeley DB Concurrent Data Store applications will perform locking on an environment-wide
|
|
basis rather than on a per-database basis.
|
|
<p>Calling DbEnv::set_flags with the DB_CDB_ALLDB flag only affects
|
|
the specified <a href="../api_cxx/env_class.html">DbEnv</a> handle (and any other Berkeley DB handles opened
|
|
within the scope of that handle).
|
|
For consistent behavior across the environment, all <a href="../api_cxx/env_class.html">DbEnv</a>
|
|
handles opened in the environment must either set the DB_CDB_ALLDB flag
|
|
or the flag should be specified in the <a href="../ref/env/db_config.html#DB_CONFIG">DB_CONFIG</a> configuration
|
|
file.</p>
|
|
<p>The DB_CDB_ALLDB flag may be used to configure Berkeley DB only before the
|
|
<a href="../api_cxx/env_open.html">DbEnv::open</a> method is called.</p></ul>
|
|
<a name="3"><!--meow--></a>
|
|
<b><a name="DB_DIRECT_DB">DB_DIRECT_DB</a></b><ul compact><li>Turn off system buffering of Berkeley DB database files to avoid double caching.
|
|
<p>Calling DbEnv::set_flags with the DB_DIRECT_DB flag only affects
|
|
the specified <a href="../api_cxx/env_class.html">DbEnv</a> handle (and any other Berkeley DB handles opened
|
|
within the scope of that handle).
|
|
For consistent behavior across the environment, all <a href="../api_cxx/env_class.html">DbEnv</a>
|
|
handles opened in the environment must either set the DB_DIRECT_DB flag
|
|
or the flag should be specified in the <a href="../ref/env/db_config.html#DB_CONFIG">DB_CONFIG</a> configuration
|
|
file.</p>
|
|
<p>The DB_DIRECT_DB flag may be used to configure Berkeley DB at any time during
|
|
the life of the application.</p></ul>
|
|
<a name="4"><!--meow--></a>
|
|
<b><a name="DB_DSYNC_DB">DB_DSYNC_DB</a></b><ul compact><li>Configure Berkeley DB to flush database writes to the backing disk before
|
|
returning from the write system call, rather than flushing database
|
|
writes explicitly in a separate system call, as necessary. This is only
|
|
available on some systems (for example, systems supporting the
|
|
IEEE/ANSI Std 1003.1 (POSIX) standard O_DSYNC flag, or systems supporting the Windows
|
|
FILE_FLAG_WRITE_THROUGH flag). This flag may result in inaccurate file
|
|
modification times and other file-level information for Berkeley DB database
|
|
files. This flag will almost certainly result in a performance decrease
|
|
on most systems. This flag is only applicable to certain filesysystem
|
|
(for example, the Veritas VxFS filesystem), where the filesystem's
|
|
support for trickling writes back to stable storage behaves badly (or
|
|
more likely, has been misconfigured).
|
|
<p>Calling DbEnv::set_flags with the DB_DSYNC_DB flag only affects
|
|
the specified <a href="../api_cxx/env_class.html">DbEnv</a> handle (and any other Berkeley DB handles opened
|
|
within the scope of that handle).
|
|
For consistent behavior across the environment, all <a href="../api_cxx/env_class.html">DbEnv</a>
|
|
handles opened in the environment must either set the DB_DSYNC_DB flag
|
|
or the flag should be specified in the <a href="../ref/env/db_config.html#DB_CONFIG">DB_CONFIG</a> configuration
|
|
file.</p>
|
|
<p>The DB_DSYNC_DB flag may be used to configure Berkeley DB at any time during
|
|
the life of the application.</p></ul>
|
|
<b><a name="DB_MULTIVERSION">DB_MULTIVERSION</a></b><ul compact><li>If set, all databases in the environment will be opened as if
|
|
DB_MULTIVERSION is passed to <a href="../api_cxx/db_open.html">Db::open</a>. This flag will
|
|
be ignored for queue databases for which DB_MULTIVERSION is not
|
|
supported.
|
|
<p>Calling DbEnv::set_flags with the DB_MULTIVERSION flag only affects
|
|
the specified <a href="../api_cxx/env_class.html">DbEnv</a> handle (and any other Berkeley DB handles opened
|
|
within the scope of that handle).
|
|
For consistent behavior across the environment, all <a href="../api_cxx/env_class.html">DbEnv</a>
|
|
handles opened in the environment must either set the DB_MULTIVERSION flag
|
|
or the flag should be specified in the <a href="../ref/env/db_config.html#DB_CONFIG">DB_CONFIG</a> configuration
|
|
file.</p>
|
|
<p>The DB_MULTIVERSION flag may be used to configure Berkeley DB at any time during
|
|
the life of the application.</p></ul>
|
|
<a name="5"><!--meow--></a>
|
|
<b><a name="DB_NOLOCKING">DB_NOLOCKING</a></b><ul compact><li>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.
|
|
<p>Calling DbEnv::set_flags with the DB_NOLOCKING flag only affects
|
|
the specified <a href="../api_cxx/env_class.html">DbEnv</a> handle (and any other Berkeley DB handles opened
|
|
within the scope of that handle).
|
|
</p>
|
|
<p>The DB_NOLOCKING flag may be used to configure Berkeley DB at any time during
|
|
the life of the application.</p></ul>
|
|
<a name="6"><!--meow--></a>
|
|
<b><a name="DB_NOMMAP">DB_NOMMAP</a></b><ul compact><li>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 <a href="../api_cxx/env_set_mp_mmapsize.html">DbEnv::set_mp_mmapsize</a> method for further
|
|
information).
|
|
<p>Calling DbEnv::set_flags with the DB_NOMMAP flag only affects
|
|
the specified <a href="../api_cxx/env_class.html">DbEnv</a> handle (and any other Berkeley DB handles opened
|
|
within the scope of that handle).
|
|
For consistent behavior across the environment, all <a href="../api_cxx/env_class.html">DbEnv</a>
|
|
handles opened in the environment must either set the DB_NOMMAP flag
|
|
or the flag should be specified in the <a href="../ref/env/db_config.html#DB_CONFIG">DB_CONFIG</a> configuration
|
|
file.</p>
|
|
<p>The DB_NOMMAP flag may be used to configure Berkeley DB at any time during
|
|
the life of the application.</p></ul>
|
|
<a name="7"><!--meow--></a>
|
|
<b><a name="DB_NOPANIC">DB_NOPANIC</a></b><ul compact><li>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 <a href="../ref/program/errorret.html#DB_RUNRECOVERY">DB_RUNRECOVERY</a>.) This
|
|
functionality should never be used for purposes other than debugging.
|
|
<p>Calling DbEnv::set_flags with the DB_NOPANIC flag only affects
|
|
the specified <a href="../api_cxx/env_class.html">DbEnv</a> handle (and any other Berkeley DB handles opened
|
|
within the scope of that handle).
|
|
</p>
|
|
<p>The DB_NOPANIC flag may be used to configure Berkeley DB at any time during
|
|
the life of the application.</p></ul>
|
|
<b><a name="DB_OVERWRITE">DB_OVERWRITE</a></b><ul compact><li>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.
|
|
<p>Calling DbEnv::set_flags with the DB_OVERWRITE flag only affects
|
|
the specified <a href="../api_cxx/env_class.html">DbEnv</a> handle (and any other Berkeley DB handles opened
|
|
within the scope of that handle).
|
|
</p>
|
|
<p>The DB_OVERWRITE flag may be used to configure Berkeley DB at any time during
|
|
the life of the application.</p></ul>
|
|
<a name="8"><!--meow--></a>
|
|
<b><a name="DB_PANIC_ENVIRONMENT">DB_PANIC_ENVIRONMENT</a></b><ul compact><li>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 <a href="../ref/program/errorret.html#DB_RUNRECOVERY">DB_RUNRECOVERY</a>.) This flag may
|
|
not be specified using the environment's <a href="../ref/env/db_config.html#DB_CONFIG">DB_CONFIG</a> file.
|
|
<p>Calling DbEnv::set_flags with the DB_PANIC_ENVIRONMENT flag affects the
|
|
database environment, including all threads of control accessing the
|
|
database environment.</p>
|
|
<p>The DB_PANIC_ENVIRONMENT flag may be used to configure Berkeley DB only after the
|
|
<a href="../api_cxx/env_open.html">DbEnv::open</a> method is called.</p></ul>
|
|
<a name="9"><!--meow--></a>
|
|
<b><a name="DB_REGION_INIT">DB_REGION_INIT</a></b><ul compact><li>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.
|
|
<p>Calling DbEnv::set_flags with the DB_REGION_INIT flag only affects
|
|
the specified <a href="../api_cxx/env_class.html">DbEnv</a> handle (and any other Berkeley DB handles opened
|
|
within the scope of that handle).
|
|
For consistent behavior across the environment, all <a href="../api_cxx/env_class.html">DbEnv</a>
|
|
handles opened in the environment must either set the DB_REGION_INIT flag
|
|
or the flag should be specified in the <a href="../ref/env/db_config.html#DB_CONFIG">DB_CONFIG</a> configuration
|
|
file.</p>
|
|
<p>The DB_REGION_INIT flag may be used to configure Berkeley DB at any time during
|
|
the life of the application.</p></ul>
|
|
<b><a name="DB_TIME_NOTGRANTED">DB_TIME_NOTGRANTED</a></b><ul compact><li>If set, database calls timing out based on lock or transaction timeout
|
|
values will
|
|
throw a <a href="../api_cxx/lockng_class.html">DbLockNotGrantedException</a> exception instead of
|
|
<a href="../api_cxx/deadlock_class.html">DbDeadlockException</a>.
|
|
This allows applications to distinguish between operations which have
|
|
deadlocked and operations which have exceeded their time limits.
|
|
<p>Calling DbEnv::set_flags with the DB_TIME_NOTGRANTED flag only affects
|
|
the specified <a href="../api_cxx/env_class.html">DbEnv</a> handle (and any other Berkeley DB handles opened
|
|
within the scope of that handle).
|
|
For consistent behavior across the environment, all <a href="../api_cxx/env_class.html">DbEnv</a>
|
|
handles opened in the environment must either set the DB_TIME_NOTGRANTED flag
|
|
or the flag should be specified in the <a href="../ref/env/db_config.html#DB_CONFIG">DB_CONFIG</a> configuration
|
|
file.</p>
|
|
<p>The DB_TIME_NOTGRANTED flag may be used to configure Berkeley DB at any time during
|
|
the life of the application.</p></ul>
|
|
<a name="10"><!--meow--></a>
|
|
<b><a name="DB_TXN_NOSYNC">DB_TXN_NOSYNC</a></b><ul compact><li>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.
|
|
<p>Calling DbEnv::set_flags with the DB_TXN_NOSYNC flag only affects
|
|
the specified <a href="../api_cxx/env_class.html">DbEnv</a> handle (and any other Berkeley DB handles opened
|
|
within the scope of that handle).
|
|
For consistent behavior across the environment, all <a href="../api_cxx/env_class.html">DbEnv</a>
|
|
handles opened in the environment must either set the DB_TXN_NOSYNC flag
|
|
or the flag should be specified in the <a href="../ref/env/db_config.html#DB_CONFIG">DB_CONFIG</a> configuration
|
|
file.</p> <p>The DB_TXN_NOSYNC flag may be used to configure Berkeley DB at any time during
|
|
the life of the application.</p></ul>
|
|
<b><a name="DB_TXN_NOWAIT">DB_TXN_NOWAIT</a></b><ul compact><li>If set and a lock is unavailable for any Berkeley DB operation performed in
|
|
the context of a transaction, cause the operation to
|
|
either return <a href="../ref/program/errorret.html#DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a> or throw a
|
|
<a href="../api_cxx/deadlock_class.html">DbDeadlockException</a> exception (or return
|
|
<a href="../ref/program/errorret.html#DB_LOCK_NOTGRANTED">DB_LOCK_NOTGRANTED</a> or throw a <a href="../api_cxx/lockng_class.html">DbLockNotGrantedException</a>
|
|
exception if configured using the DB_TIME_NOTGRANTED flag).
|
|
<p>Calling DbEnv::set_flags with the DB_TXN_NOWAIT flag only affects
|
|
the specified <a href="../api_cxx/env_class.html">DbEnv</a> handle (and any other Berkeley DB handles opened
|
|
within the scope of that handle).
|
|
For consistent behavior across the environment, all <a href="../api_cxx/env_class.html">DbEnv</a>
|
|
handles opened in the environment must either set the DB_TXN_NOWAIT flag
|
|
or the flag should be specified in the <a href="../ref/env/db_config.html#DB_CONFIG">DB_CONFIG</a> configuration
|
|
file.</p>
|
|
<p>The DB_TXN_NOWAIT flag may be used to configure Berkeley DB at any time during
|
|
the life of the application.</p></ul>
|
|
<b><a name="DB_TXN_SNAPSHOT">DB_TXN_SNAPSHOT</a></b><ul compact><li>If set, all transactions in the environment will be started as if
|
|
DB_TXN_SNAPSHOT were passed to <a href="../api_cxx/txn_begin.html">DbEnv::txn_begin</a>, and all
|
|
non-transactional cursors will be opened as if DB_TXN_SNAPSHOT
|
|
were passed to <a href="../api_cxx/db_cursor.html">Db::cursor</a>.
|
|
<p>Calling DbEnv::set_flags with the DB_TXN_SNAPSHOT flag only affects
|
|
the specified <a href="../api_cxx/env_class.html">DbEnv</a> handle (and any other Berkeley DB handles opened
|
|
within the scope of that handle).
|
|
For consistent behavior across the environment, all <a href="../api_cxx/env_class.html">DbEnv</a>
|
|
handles opened in the environment must either set the DB_TXN_SNAPSHOT flag
|
|
or the flag should be specified in the <a href="../ref/env/db_config.html#DB_CONFIG">DB_CONFIG</a> configuration
|
|
file.</p>
|
|
<p>The DB_TXN_SNAPSHOT flag may be used to configure Berkeley DB at any time during
|
|
the life of the application.</p></ul>
|
|
<a name="11"><!--meow--></a>
|
|
<b><a name="DB_TXN_WRITE_NOSYNC">DB_TXN_WRITE_NOSYNC</a></b><ul compact><li>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.
|
|
<p>Calling DbEnv::set_flags with the DB_TXN_WRITE_NOSYNC flag only affects
|
|
the specified <a href="../api_cxx/env_class.html">DbEnv</a> handle (and any other Berkeley DB handles opened
|
|
within the scope of that handle).
|
|
For consistent behavior across the environment, all <a href="../api_cxx/env_class.html">DbEnv</a>
|
|
handles opened in the environment must either set the DB_TXN_WRITE_NOSYNC flag
|
|
or the flag should be specified in the <a href="../ref/env/db_config.html#DB_CONFIG">DB_CONFIG</a> configuration
|
|
file.</p>
|
|
<p>The DB_TXN_WRITE_NOSYNC flag may be used to configure Berkeley DB at any time during
|
|
the life of the application.</p></ul>
|
|
<a name="12"><!--meow--></a>
|
|
<b><a name="DB_YIELDCPU">DB_YIELDCPU</a></b><ul compact><li>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.
|
|
<p>Calling DbEnv::set_flags with the DB_YIELDCPU flag only affects
|
|
the specified <a href="../api_cxx/env_class.html">DbEnv</a> handle (and any other Berkeley DB handles opened
|
|
within the scope of that handle).
|
|
For consistent behavior across the environment, all <a href="../api_cxx/env_class.html">DbEnv</a>
|
|
handles opened in the environment must either set the DB_YIELDCPU flag
|
|
or the flag should be specified in the <a href="../ref/env/db_config.html#DB_CONFIG">DB_CONFIG</a> configuration
|
|
file.</p>
|
|
<p>The DB_YIELDCPU flag may be used to configure Berkeley DB at any time during
|
|
the life of the application.</p></ul>
|
|
<br></ul>
|
|
<b>onoff</b><ul compact><li>If the <b>onoff</b> parameter is zero, the specified flags are cleared;
|
|
otherwise they are set.</ul>
|
|
<br>
|
|
<br><b>Errors</b>
|
|
<p>The DbEnv::set_flags method
|
|
may fail and throw
|
|
<a href="../api_cxx/except_class.html">DbException</a>,
|
|
encapsulating one of the following non-zero errors, or return one of
|
|
the following non-zero errors:</p>
|
|
<br>
|
|
<b>EINVAL</b><ul compact><li>An
|
|
invalid flag value or parameter was specified.</ul>
|
|
<br>
|
|
<hr size=1 noshade>
|
|
<b>Description: DbEnv::get_flags</b>
|
|
<p>The DbEnv::get_flags method returns the configuration flags.</p>
|
|
<p>The DbEnv::get_flags method may be called at any time during the life of the
|
|
application.</p>
|
|
<p>The DbEnv::get_flags method
|
|
either returns a non-zero error value
|
|
or throws an exception that encapsulates a non-zero error value on
|
|
failure, and returns 0 on success.
|
|
</p>
|
|
<b>Parameters</b> <br>
|
|
<b>flagsp</b><ul compact><li>The DbEnv::get_flags method returns the
|
|
configuration flags in <b>flagsp</b>.</ul>
|
|
<br>
|
|
<hr size=1 noshade>
|
|
<br><b>Class</b>
|
|
<a href="../api_cxx/env_class.html">DbEnv</a>
|
|
<br><b>See Also</b>
|
|
<a href="../api_cxx/env_list.html">Database Environments and Related Methods</a>
|
|
</tt>
|
|
<table width="100%"><tr><td><br></td><td align=right>
|
|
<a href="../api_cxx/api_core.html"><img src="../images/api.gif" alt="API"></a><a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a>
|
|
</td></tr></table>
|
|
<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font>
|
|
</body>
|
|
</html>
|