2
<!--Copyright 1997-2002 by Sleepycat Software, Inc.-->
3
<!--All rights reserved.-->
4
<!--See the file LICENSE for redistribution information.-->
7
<title>Berkeley DB: Db::set_flags</title>
8
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
9
<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
12
<a name="2"><!--meow--></a>
13
<table width="100%"><tr valign=top>
15
<h1>Db::set_flags</h1>
18
<a href="../api_cxx/c_index.html"><img src="../images/api.gif" alt="API"></a><a href="../reftoc.html"><img src="../images/ref.gif" alt="Ref"></a>
23
#include <db_cxx.h>
26
Db::set_flags(u_int32_t flags);
29
<p>Calling Db::set_flags is additive; there is no way to clear flags.
30
<p>The <b>flags</b> value must be set to 0 or by bitwise inclusively <b>OR</b>'ing together one or
31
more of the following values:
33
<p>The following flags may be specified for any Berkeley DB access method:
35
<a name="3"><!--meow--></a>
36
<p><dt><a name="DB_CHKSUM_SHA1">DB_CHKSUM_SHA1</a><dd>Do checksum verification of pages read into the cache from the backing
37
filestore, using the SHA1 Secure Hash Algorithm.
38
<p>Calling Db::set_flags with the DB_CHKSUM_SHA1 flag only affects the
39
specified <a href="../api_cxx/db_class.html">Db</a> handle (and any other Berkeley DB handles opened within
40
the scope of that handle).
41
<p>If the database already exists when <a href="../api_cxx/db_open.html">Db::open</a> is called, the DB_CHKSUM_SHA1
44
If creating additional databases in a file, the checksum behavior specified
45
must be consistent with the existing databases in the file or an error will
47
<a name="4"><!--meow--></a>
48
<p><dt><a name="DB_ENCRYPT">DB_ENCRYPT</a><dd>Encrypt the database using the cryptographic password specified to the
49
<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.
50
<p>Calling Db::set_flags with the DB_ENCRYPT flag only affects the
51
specified <a href="../api_cxx/db_class.html">Db</a> handle (and any other Berkeley DB handles opened within
52
the scope of that handle).
53
<p>If the database already exists when <a href="../api_cxx/db_open.html">Db::open</a> is called, the DB_ENCRYPT
55
must be the same as the existing database or an error
57
If creating additional databases in a file, the encryption behavior specified
58
must be consistent with the existing databases in the file or an error will
62
<p>The following flags may be specified for the Btree access method:
64
<a name="5"><!--meow--></a>
65
<p><dt><a name="DB_DUP">DB_DUP</a><dd>Permit duplicate data items in the tree; that is, insertion when the
66
key of the key/data pair being inserted already exists in the tree will
67
be successful. The ordering of duplicates in the tree is determined by
68
the order of insertion, unless the ordering is otherwise specified by
69
use of a cursor operation. It is an error to specify both DB_DUP
71
<p>Calling Db::set_flags with the DB_DUP flag affects the
72
database, including all threads of control accessing the database.
73
<p>If the database already exists when <a href="../api_cxx/db_open.html">Db::open</a> is called, the DB_DUP
75
must be the same as the existing database or an error
77
<a name="6"><!--meow--></a>
78
<p><dt><a name="DB_DUPSORT">DB_DUPSORT</a><dd>Permit duplicate data items in the tree; that is, insertion when the
79
key of the key/data pair being inserted already exists in the tree will
80
be successful. The ordering of duplicates in the tree is determined by
81
the duplicate comparison function.
82
If the application does not specify a comparison function using the
83
<a href="../api_cxx/db_set_dup_compare.html">Db::set_dup_compare</a> method, a default lexical comparison will be
85
It is an error to specify both DB_DUPSORT and DB_RECNUM.
86
<p>Calling Db::set_flags with the DB_DUPSORT flag affects the
87
database, including all threads of control accessing the database.
88
<p>If the database already exists when <a href="../api_cxx/db_open.html">Db::open</a> is called, the DB_DUPSORT
90
must be the same as the existing database or an error
92
<a name="7"><!--meow--></a>
93
<p><dt><a name="DB_RECNUM">DB_RECNUM</a><dd>Support retrieval from the Btree using record numbers. For more
94
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>
95
and <a href="../api_cxx/dbc_get.html">Dbc::get</a> methods.
96
<p>Logical record numbers in Btree databases are mutable in the face of
97
record insertion or deletion. See the DB_RENUMBER flag in the
98
Recno access method information for further discussion.
99
<p>Maintaining record counts within a Btree introduces a serious point of
100
contention, namely the page locations where the record counts are
101
stored. In addition, the entire tree must be locked during both
102
insertions and deletions, effectively single-threading the tree for
103
those operations. Specifying DB_RECNUM can result in serious
104
performance degradation for some applications and data sets.
105
<p>It is an error to specify both DB_DUP and DB_RECNUM.
106
<p>Calling Db::set_flags with the DB_RECNUM flag affects the
107
database, including all threads of control accessing the database.
108
<p>If the database already exists when <a href="../api_cxx/db_open.html">Db::open</a> is called, the DB_RECNUM
110
must be the same as the existing database or an error
112
<a name="8"><!--meow--></a><a name="9"><!--meow--></a>
113
<p><dt><a name="DB_REVSPLITOFF">DB_REVSPLITOFF</a><dd>Turn off reverse splitting in the Btree. As pages are emptied in a
114
database, the Berkeley DB Btree implementation attempts to coalesce empty pages
115
into higher-level pages in order to keep the tree as small as possible
116
and minimize tree search time. This can hurt performance in applications
117
with cyclical data demands; that is, applications where the database grows
118
and shrinks repeatedly. For example, because Berkeley DB does page-level
119
locking, the maximum level of concurrency in a database of two pages is far
120
smaller than that in a database of 100 pages, so a database that has
121
shrunk to a minimal size can cause severe deadlocking when a new cycle of
122
data insertion begins.
123
<p>Calling Db::set_flags with the DB_REVSPLITOFF flag only affects the
124
specified <a href="../api_cxx/db_class.html">Db</a> handle (and any other Berkeley DB handles opened within
125
the scope of that handle).
128
<p>The following flags may be specified for the Hash access method:
130
<p><dt><a name="DB_DUP">DB_DUP</a><dd>Permit duplicate data items in the tree; that is, insertion when the
131
key of the key/data pair being inserted already exists in the tree will
132
be successful. The ordering of duplicates in the tree is determined by
133
the order of insertion, unless the ordering is otherwise specified by
134
use of a cursor operation. It is an error to specify both DB_DUP
136
<p>Calling Db::set_flags with the DB_DUP flag affects the
137
database, including all threads of control accessing the database.
138
<p>If the database already exists when <a href="../api_cxx/db_open.html">Db::open</a> is called, the DB_DUP
140
must be the same as the existing database or an error
142
<p><dt><a name="DB_DUPSORT">DB_DUPSORT</a><dd>Permit duplicate data items in the tree; that is, insertion when the
143
key of the key/data pair being inserted already exists in the tree will
144
be successful. The ordering of duplicates in the tree is determined by
145
the duplicate comparison function.
146
If the application does not specify a comparison function using the
147
<a href="../api_cxx/db_set_dup_compare.html">Db::set_dup_compare</a> method, a default lexical comparison will be
149
It is an error to specify both DB_DUPSORT and DB_RECNUM.
150
<p>Calling Db::set_flags with the DB_DUPSORT flag affects the
151
database, including all threads of control accessing the database.
152
<p>If the database already exists when <a href="../api_cxx/db_open.html">Db::open</a> is called, the DB_DUPSORT
154
must be the same as the existing database or an error
158
<p>There are no additional flags that may be specified for the Queue access
161
<p>The following flags may be specified for the Recno access method:
163
<a name="10"><!--meow--></a>
164
<p><dt><a name="DB_RENUMBER">DB_RENUMBER</a><dd>Specifying the DB_RENUMBER flag causes the logical record
165
numbers to be mutable, and change as records are added to and deleted
166
from the database. For example, the deletion of record number 4 causes
167
records numbered 5 and greater to be renumbered downward by one. If a
168
cursor was positioned to record number 4 before the deletion, it will
169
refer to the new record number 4, if any such record exists, after the
170
deletion. If a cursor was positioned after record number 4 before the
171
deletion, it will be shifted downward one logical record, continuing to
172
refer to the same record as it did before.
173
<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
174
records will cause the creation of multiple records if the record number
175
is more than one greater than the largest record currently in the
176
database. For example, creating record 28, when record 25 was previously
177
the last record in the database, will create records 26 and 27 as well as
178
28. Attempts to retrieve records that were created in this manner will
179
result in an error return of <a href="../ref/program/errorret.html#DB_KEYEMPTY">DB_KEYEMPTY</a>.
180
<p>If a created record is not at the end of the database, all records
181
following the new record will be automatically renumbered upward by one.
182
For example, the creation of a new record numbered 8 causes records
183
numbered 8 and greater to be renumbered upward by one. If a cursor was
184
positioned to record number 8 or greater before the insertion, it will be
185
shifted upward one logical record, continuing to refer to the same record
187
<p>For these reasons, concurrent access to a Recno database with the
188
DB_RENUMBER flag specified may be largely meaningless, although
190
<p>Calling Db::set_flags with the DB_RENUMBER flag affects the
191
database, including all threads of control accessing the database.
192
<p>If the database already exists when <a href="../api_cxx/db_open.html">Db::open</a> is called, the DB_RENUMBER
194
must be the same as the existing database or an error
196
<a name="11"><!--meow--></a>
197
<p><dt><a name="DB_SNAPSHOT">DB_SNAPSHOT</a><dd>This flag specifies that any specified <b>re_source</b> file be read
198
in its entirety when <a href="../api_cxx/db_open.html">Db::open</a> is called. If this flag is not
199
specified, the <b>re_source</b> file may be read lazily.
200
<p>Calling Db::set_flags with the DB_SNAPSHOT flag only affects the
201
specified <a href="../api_cxx/db_class.html">Db</a> handle (and any other Berkeley DB handles opened within
202
the scope of that handle).
204
<p>The Db::set_flags interface may not be called after the <a href="../api_cxx/db_open.html">Db::open</a>
206
<p>The Db::set_flags method either returns a non-zero error value or throws an exception that
207
encapsulates a non-zero error value on failure, and returns 0 on success.
209
<p>The Db::set_flags method may fail and throw an exception or return a non-zero error for the following conditions:
211
<p><dt>EINVAL<dd>An invalid flag value or parameter was specified.
213
<p>The <a href="../api_cxx/db_set_bt_compare.html">Db::set_bt_compare</a> method may fail and throw an exception or return a non-zero error for errors specified for other Berkeley DB and C library or system methods.
214
If a catastrophic error has occurred, the <a href="../api_cxx/db_set_bt_compare.html">Db::set_bt_compare</a> method may fail and
215
either return <a href="../ref/program/errorret.html#DB_RUNRECOVERY">DB_RUNRECOVERY</a> or throw a
216
<a href="../api_cxx/runrec_class.html">DbRunRecoveryException</a>,
217
in which case all subsequent Berkeley DB calls will fail in the same way.
219
<a href="../api_cxx/db_class.html">Db</a>
221
<a href="../api_cxx/db_list.html">Databases and Related Methods</a>
223
<table width="100%"><tr><td><br></td><td align=right>
224
<a href="../api_cxx/c_index.html"><img src="../images/api.gif" alt="API"></a><a href="../reftoc.html"><img src="../images/ref.gif" alt="Ref"></a>
226
<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
added
removed
libdb/docs/api_cxx/db_set_flags.html
