300 lines
16 KiB
HTML
300 lines
16 KiB
HTML
<!--$Id: db_set_flags.html 63573 2008-05-23 21:43:21Z trent.nelson $-->
|
|
<!--Copyright (c) 1997,2008 Oracle. All rights reserved.-->
|
|
<!--See the file LICENSE for redistribution information.-->
|
|
<html>
|
|
<head>
|
|
<title>Berkeley DB: Db::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>Db::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
|
|
Db::set_flags(u_int32_t flags);
|
|
<p>
|
|
int Db::get_flags(u_int32_t *flagsp);
|
|
</pre></b>
|
|
<hr size=1 noshade>
|
|
<b>Description: Db::set_flags</b>
|
|
<p>Configure a database. Calling Db::set_flags is additive; there
|
|
is no way to clear flags.</p>
|
|
<p>The Db::set_flags method may not be called after the <a href="../api_cxx/db_open.html">Db::open</a> method is called.
|
|
</p>
|
|
<p>The Db::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 to 0 or by bitwise inclusively <b>OR</b>'ing together one
|
|
or more of the following values:
|
|
<b>General</b>
|
|
<p>The following flags may be specified for any Berkeley DB access method:</p>
|
|
<br>
|
|
<a name="2"><!--meow--></a>
|
|
<b><a name="DB_CHKSUM">DB_CHKSUM</a></b><ul compact><li>Do checksum verification of pages read into the cache from the backing
|
|
filestore. Berkeley DB uses the SHA1 Secure Hash Algorithm
|
|
if encryption is configured and a general hash algorithm if it is not.
|
|
<p>Calling Db::set_flags with the DB_CHKSUM flag only affects the
|
|
specified <a href="../api_cxx/db_class.html">Db</a> handle (and any other Berkeley DB handles opened within
|
|
the scope of that handle).</p>
|
|
<p>If the database already exists when <a href="../api_cxx/db_open.html">Db::open</a> is called, the DB_CHKSUM
|
|
flag
|
|
will be ignored.</p>
|
|
If creating additional databases in a file, the checksum behavior specified
|
|
must be consistent with the existing databases in the file or an error will
|
|
be returned.</ul>
|
|
<a name="3"><!--meow--></a>
|
|
<b><a name="DB_ENCRYPT">DB_ENCRYPT</a></b><ul compact><li>Encrypt the database using the cryptographic password specified to the
|
|
<a href="../api_cxx/env_set_encrypt.html">DbEnv::set_encrypt</a> or <a href="../api_cxx/db_set_encrypt.html">Db::set_encrypt</a> methods.
|
|
<p>Calling Db::set_flags with the DB_ENCRYPT flag only affects the
|
|
specified <a href="../api_cxx/db_class.html">Db</a> handle (and any other Berkeley DB handles opened within
|
|
the scope of that handle).</p>
|
|
<p>If the database already exists when <a href="../api_cxx/db_open.html">Db::open</a> is called, the DB_ENCRYPT
|
|
flag
|
|
must be the same as the existing database or an error
|
|
will be returned.
|
|
</p>
|
|
If creating additional databases in a file, the encryption behavior specified
|
|
must be consistent with the existing databases in the file or an error will
|
|
be returned.
|
|
<p>Encrypted databases are not portable between machines of different byte
|
|
orders, that is, encrypted databases created on big-endian machines
|
|
cannot be read on little-endian machines, and vice versa.</p></ul>
|
|
<a name="4"><!--meow--></a>
|
|
<b><a name="DB_TXN_NOT_DURABLE">DB_TXN_NOT_DURABLE</a></b><ul compact><li>If set, Berkeley DB will not write log records for this database. This means
|
|
that updates of this database 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,
|
|
integrity will not persist. The database file must be verified and/or
|
|
restored from backup after a failure. In order to ensure integrity
|
|
after application shut down, the database handles must be closed without
|
|
specifying <a href="../api_cxx/db_close.html#DB_NOSYNC">DB_NOSYNC</a>, or all database changes must be flushed
|
|
from the database environment cache using either the
|
|
<a href="../api_cxx/txn_checkpoint.html">DbEnv::txn_checkpoint</a> or <a href="../api_cxx/memp_sync.html">DbEnv::memp_sync</a> methods. All database handles for
|
|
a single physical file must set DB_TXN_NOT_DURABLE, including
|
|
database handles for different databases in a physical file.
|
|
<p>Calling Db::set_flags with the DB_TXN_NOT_DURABLE flag only affects the
|
|
specified <a href="../api_cxx/db_class.html">Db</a> handle (and any other Berkeley DB handles opened within
|
|
the scope of that handle).</p></ul>
|
|
<br>
|
|
<b>Btree</b>
|
|
<p>The following flags may be specified for the Btree access method:</p>
|
|
<br>
|
|
<a name="5"><!--meow--></a>
|
|
<b><a name="DB_DUP">DB_DUP</a></b><ul compact><li>Permit duplicate data items in the database; that is, insertion when the
|
|
key of the key/data pair being inserted already exists in the database
|
|
will be successful. The ordering of duplicates in the database is
|
|
determined by the order of insertion, unless the ordering is otherwise
|
|
specified by use of a cursor operation.
|
|
<p>The DB_DUPSORT flag is preferred to DB_DUP for
|
|
performance reasons. The DB_DUP flag should only be used by
|
|
applications wanting to order duplicate data items manually.</p>
|
|
<p>Calling Db::set_flags with the DB_DUP flag affects the
|
|
database, including all threads of control accessing the database.</p>
|
|
<p>If the database already exists when <a href="../api_cxx/db_open.html">Db::open</a> is called, the DB_DUP
|
|
flag
|
|
must be the same as the existing database or an error
|
|
will be returned.
|
|
</p>
|
|
<p>It is an error to specify both DB_DUP and DB_RECNUM.</p></ul>
|
|
<a name="6"><!--meow--></a>
|
|
<b><a name="DB_DUPSORT">DB_DUPSORT</a></b><ul compact><li>Permit duplicate data items in the database; that is, insertion when the
|
|
key of the key/data pair being inserted already exists in the database
|
|
will be successful. The ordering of duplicates in the database is
|
|
determined by the duplicate comparison function. If the application
|
|
does not specify a comparison function using the
|
|
<a href="../api_cxx/db_set_dup_compare.html">Db::set_dup_compare</a> method, a default lexical comparison will be used.
|
|
It is an error to specify both DB_DUPSORT and DB_RECNUM.
|
|
<p>Calling Db::set_flags with the DB_DUPSORT flag affects the
|
|
database, including all threads of control accessing the database.</p>
|
|
<p>If the database already exists when <a href="../api_cxx/db_open.html">Db::open</a> is called, the DB_DUPSORT
|
|
flag
|
|
must be the same as the existing database or an error
|
|
will be returned.
|
|
</p></ul>
|
|
<a name="7"><!--meow--></a>
|
|
<b><a name="DB_RECNUM">DB_RECNUM</a></b><ul compact><li>Support retrieval from the Btree using record numbers. For more
|
|
information, see the <a href="../api_cxx/db_get.html#DB_SET_RECNO">DB_SET_RECNO</a> flag to the <a href="../api_cxx/db_get.html">Db::get</a>
|
|
and <a href="../api_cxx/dbc_get.html">Dbc::get</a> methods.
|
|
<p>Logical record numbers in Btree databases are mutable in the face of
|
|
record insertion or deletion. See the DB_RENUMBER flag in the
|
|
Recno access method information for further discussion.</p>
|
|
<p>Maintaining record counts within a Btree introduces a serious point of
|
|
contention, namely the page locations where the record counts are
|
|
stored. In addition, the entire database must be locked during both
|
|
insertions and deletions, effectively single-threading the database for
|
|
those operations. Specifying DB_RECNUM can result in serious
|
|
performance degradation for some applications and data sets.</p>
|
|
<p>It is an error to specify both DB_DUP and DB_RECNUM.</p>
|
|
<p>Calling Db::set_flags with the DB_RECNUM flag affects the
|
|
database, including all threads of control accessing the database.</p>
|
|
<p>If the database already exists when <a href="../api_cxx/db_open.html">Db::open</a> is called, the DB_RECNUM
|
|
flag
|
|
must be the same as the existing database or an error
|
|
will be returned.
|
|
</p></ul>
|
|
<a name="8"><!--meow--></a><a name="9"><!--meow--></a>
|
|
<b><a name="DB_REVSPLITOFF">DB_REVSPLITOFF</a></b><ul compact><li>Turn off reverse splitting in the Btree. As pages are emptied in a
|
|
database, the Berkeley DB Btree implementation attempts to coalesce empty pages
|
|
into higher-level pages in order to keep the database as small as possible
|
|
and minimize search time. This can hurt performance in applications
|
|
with cyclical data demands; that is, applications where the database grows
|
|
and shrinks repeatedly. For example, because Berkeley DB does page-level
|
|
locking, the maximum level of concurrency in a database of two pages is far
|
|
smaller than that in a database of 100 pages, so a database that has
|
|
shrunk to a minimal size can cause severe deadlocking when a new cycle of
|
|
data insertion begins.
|
|
<p>Calling Db::set_flags with the DB_REVSPLITOFF flag only affects the
|
|
specified <a href="../api_cxx/db_class.html">Db</a> handle (and any other Berkeley DB handles opened within
|
|
the scope of that handle).</p></ul>
|
|
<br>
|
|
<b>Hash</b>
|
|
<p>The following flags may be specified for the Hash access method:</p>
|
|
<br>
|
|
<b><a name="DB_DUP">DB_DUP</a></b><ul compact><li>Permit duplicate data items in the database; that is, insertion when the
|
|
key of the key/data pair being inserted already exists in the database
|
|
will be successful. The ordering of duplicates in the database is
|
|
determined by the order of insertion, unless the ordering is otherwise
|
|
specified by use of a cursor operation.
|
|
<p>The DB_DUPSORT flag is preferred to DB_DUP for
|
|
performance reasons. The DB_DUP flag should only be used by
|
|
applications wanting to order duplicate data items manually.</p>
|
|
<p>Calling Db::set_flags with the DB_DUP flag affects the
|
|
database, including all threads of control accessing the database.</p>
|
|
<p>If the database already exists when <a href="../api_cxx/db_open.html">Db::open</a> is called, the DB_DUP
|
|
flag
|
|
must be the same as the existing database or an error
|
|
will be returned.
|
|
</p>
|
|
</ul>
|
|
<b><a name="DB_DUPSORT">DB_DUPSORT</a></b><ul compact><li>Permit duplicate data items in the database; that is, insertion when the
|
|
key of the key/data pair being inserted already exists in the database
|
|
will be successful. The ordering of duplicates in the database is
|
|
determined by the duplicate comparison function. If the application
|
|
does not specify a comparison function using the
|
|
<a href="../api_cxx/db_set_dup_compare.html">Db::set_dup_compare</a> method, a default lexical comparison will be used.
|
|
It is an error to specify both DB_DUPSORT and DB_RECNUM.
|
|
<p>Calling Db::set_flags with the DB_DUPSORT flag affects the
|
|
database, including all threads of control accessing the database.</p>
|
|
<p>If the database already exists when <a href="../api_cxx/db_open.html">Db::open</a> is called, the DB_DUPSORT
|
|
flag
|
|
must be the same as the existing database or an error
|
|
will be returned.
|
|
</p></ul>
|
|
<br>
|
|
<b>Queue</b>
|
|
<p>The following flags may be specified for the Queue access method:</p>
|
|
<br>
|
|
<a name="10"><!--meow--></a>
|
|
<b><a name="DB_INORDER">DB_INORDER</a></b><ul compact><li>The DB_INORDER flag modifies the operation of the
|
|
<a href="../api_cxx/db_get.html#DB_CONSUME">DB_CONSUME</a> or <a href="../api_cxx/db_get.html#DB_CONSUME_WAIT">DB_CONSUME_WAIT</a> flags to <a href="../api_cxx/db_get.html">Db::get</a>
|
|
to return key/data pairs in order. That is, they will always return
|
|
the key/data item from the head of the queue.
|
|
<p>The default behavior of queue databases is optimized for multiple
|
|
readers, and does not guarantee that record will be retrieved in the
|
|
order they are added to the queue. Specifically, if a writing thread
|
|
adds multiple records to an empty queue, reading threads may skip some
|
|
of the initial records when the next <a href="../api_cxx/db_get.html">Db::get</a> call returns.</p>
|
|
<p>This flag modifies the <a href="../api_cxx/db_get.html">Db::get</a> call to verify that the record
|
|
being returned is in fact the head of the queue. This will increase
|
|
contention and reduce concurrency when there are many reading threads.</p>
|
|
<p>Calling Db::set_flags with the DB_INORDER flag only affects the
|
|
specified <a href="../api_cxx/db_class.html">Db</a> handle (and any other Berkeley DB handles opened within
|
|
the scope of that handle).</p></ul>
|
|
<br>
|
|
<b>Recno</b>
|
|
<p>The following flags may be specified for the Recno access method:</p>
|
|
<br>
|
|
<a name="11"><!--meow--></a>
|
|
<b><a name="DB_RENUMBER">DB_RENUMBER</a></b><ul compact><li>Specifying the DB_RENUMBER flag causes the logical record
|
|
numbers to be mutable, and change as records are added to and deleted
|
|
from the database. For example, the deletion of record number 4 causes
|
|
records numbered 5 and greater to be renumbered downward by one. If a
|
|
cursor was positioned to record number 4 before the deletion, it will
|
|
refer to the new record number 4, if any such record exists, after the
|
|
deletion. If a cursor was positioned after record number 4 before the
|
|
deletion, it will be shifted downward one logical record, continuing to
|
|
refer to the same record as it did before.
|
|
<p>Using the <a href="../api_cxx/db_put.html">Db::put</a> or <a href="../api_cxx/dbc_put.html">Dbc::put</a> interfaces to create new
|
|
records will cause the creation of multiple records if the record number
|
|
is more than one greater than the largest record currently in the
|
|
database. For example, creating record 28, when record 25 was previously
|
|
the last record in the database, will create records 26 and 27 as well as
|
|
28. Attempts to retrieve records that were created in this manner will
|
|
result in an error return of <a href="../ref/program/errorret.html#DB_KEYEMPTY">DB_KEYEMPTY</a>.</p>
|
|
<p>If a created record is not at the end of the database, all records
|
|
following the new record will be automatically renumbered upward by one.
|
|
For example, the creation of a new record numbered 8 causes records
|
|
numbered 8 and greater to be renumbered upward by one. If a cursor was
|
|
positioned to record number 8 or greater before the insertion, it will be
|
|
shifted upward one logical record, continuing to refer to the same record
|
|
as it did before.</p>
|
|
<p>For these reasons, concurrent access to a Recno database with the
|
|
DB_RENUMBER flag specified may be largely meaningless, although
|
|
it is supported.</p>
|
|
<p>Calling Db::set_flags with the DB_RENUMBER flag affects the
|
|
database, including all threads of control accessing the database.</p>
|
|
<p>If the database already exists when <a href="../api_cxx/db_open.html">Db::open</a> is called, the DB_RENUMBER
|
|
flag
|
|
must be the same as the existing database or an error
|
|
will be returned.
|
|
</p></ul>
|
|
<a name="12"><!--meow--></a>
|
|
<b><a name="DB_SNAPSHOT">DB_SNAPSHOT</a></b><ul compact><li>This flag specifies that any specified <b>re_source</b> file be read
|
|
in its entirety when <a href="../api_cxx/db_open.html">Db::open</a> is called. If this flag is not
|
|
specified, the <b>re_source</b> file may be read lazily.
|
|
<p>Calling Db::set_flags with the DB_SNAPSHOT flag only affects the
|
|
specified <a href="../api_cxx/db_class.html">Db</a> handle (and any other Berkeley DB handles opened within
|
|
the scope of that handle).</p></ul>
|
|
<br></ul>
|
|
<br>
|
|
<br><b>Errors</b>
|
|
<p>The Db::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: Db::get_flags</b>
|
|
<p>The Db::get_flags method returns the current flags.</p>
|
|
<p>The Db::get_flags method may be called at any time during the life of the
|
|
application.</p>
|
|
<p>The Db::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 Db::get_flags method returns the
|
|
current flags in <b>flagsp</b>.</ul>
|
|
<br>
|
|
<hr size=1 noshade>
|
|
<br><b>Class</b>
|
|
<a href="../api_cxx/db_class.html">Db</a>
|
|
<br><b>See Also</b>
|
|
<a href="../api_cxx/db_list.html">Databases 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>
|