1
<!--$Id: db_set_flags.so,v 10.32 2001/05/05 01:49:12 bostic Exp $-->
2
<!--Copyright 1997-2001 by Sleepycat Software, Inc.-->
3
<!--All rights reserved.-->
6
<title>Berkeley DB: Db.set_flags</title>
7
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
8
<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
11
<a name="2"><!--meow--></a>
12
<table width="100%"><tr valign=top>
17
<a href="../api_java/java_index.html"><img src="../images/api.gif" alt="API"></a><a href="../reftoc.html"><img src="../images/ref.gif" alt="Ref"></a>
22
import com.sleepycat.db.*;
24
public void set_flags(int flags)
28
<p>Calling Db.set_flags is additive; there is no way to clear flags.
29
<p>The <b>flags</b> value must be set to 0 or by bitwise inclusively <b>OR</b>'ing together one or
30
more of the following values:
32
<p>The following flags may be specified for the Btree access method:
34
<a name="3"><!--meow--></a>
35
<p><dt><a name="Db.DB_DUP">Db.DB_DUP</a><dd>Permit duplicate data items in the tree; that is, insertion when the
36
key of the key/data pair being inserted already exists in the tree will
37
be successful. The ordering of duplicates in the tree is determined by
38
the order of insertion, unless the ordering is otherwise specified by
39
use of a cursor operation. It is an error to specify both
40
Db.DB_DUP and Db.DB_RECNUM.
41
<a name="4"><!--meow--></a>
42
<p><dt><a name="Db.DB_DUPSORT">Db.DB_DUPSORT</a><dd>Permit duplicate data items in the tree; that is, insertion when the
43
key of the key/data pair being inserted already exists in the tree will
44
be successful. The ordering of duplicates in the tree is determined by
45
the duplicate comparison function.
46
A default lexical comparison will be used.
47
It is an error to specify both Db.DB_DUPSORT and Db.DB_RECNUM.
48
<a name="5"><!--meow--></a>
49
<p><dt><a name="Db.DB_RECNUM">Db.DB_RECNUM</a><dd>Support retrieval from the Btree using record numbers. For more
50
information, see the DB_GET_RECNO flag to the <a href="../api_java/db_get.html">Db.get</a> and
51
<a href="../api_java/dbc_get.html">Dbc.get</a> methods.
52
<p>Logical record numbers in Btree databases are mutable in the face of
53
record insertion or deletion. See the DB_RENUMBER flag in the Recno
54
access method information for further discussion.
55
<p>Maintaining record counts within a Btree introduces a serious point of
56
contention, namely the page locations where the record counts are stored.
57
In addition, the entire tree must be locked during both insertions and
58
deletions, effectively single-threading the tree for those operations.
59
Specifying DB_RECNUM can result in serious performance degradation for
60
some applications and data sets.
61
<p>It is an error to specify both DB_DUP and DB_RECNUM.
62
<a name="6"><!--meow--></a><a name="7"><!--meow--></a>
63
<p><dt><a name="Db.DB_REVSPLITOFF">Db.DB_REVSPLITOFF</a><dd>Turn off reverse splitting in the Btree. As pages are emptied in a
64
database, the Berkeley DB Btree implementation attempts to coalesce empty pages
65
into higher-level pages in order to keep the tree as small as possible
66
and minimize tree search time. This can hurt performance in applications
67
with cyclical data demands; that is, applications where the database grows
68
and shrinks repeatedly. For example, because Berkeley DB does page-level
69
locking, the maximum level of concurrency in a database of two pages is far
70
smaller than that in a database of 100 pages, so a database that has
71
shrunk to a minimal size can cause severe deadlocking when a new cycle of
72
data insertion begins.
75
<p>The following flags may be specified for the Hash access method:
77
<p><dt><a name="Db.DB_DUP">Db.DB_DUP</a><dd>Permit duplicate data items in the tree; that is, insertion when the
78
key of the key/data pair being inserted already exists in the tree will
79
be successful. The ordering of duplicates in the tree is determined by
80
the order of insertion, unless the ordering is otherwise specified by
81
use of a cursor operation. It is an error to specify both
82
Db.DB_DUP and Db.DB_RECNUM.
83
<p><dt><a name="Db.DB_DUPSORT">Db.DB_DUPSORT</a><dd>Permit duplicate data items in the tree; that is, insertion when the
84
key of the key/data pair being inserted already exists in the tree will
85
be successful. The ordering of duplicates in the tree is determined by
86
the duplicate comparison function.
87
A default lexical comparison will be used.
88
It is an error to specify both Db.DB_DUPSORT and Db.DB_RECNUM.
91
<p>There are no additional flags that may be specified for the Queue access
94
<p>The following flags may be specified for the Recno access method:
96
<a name="8"><!--meow--></a>
97
<p><dt><a name="Db.DB_RENUMBER">Db.DB_RENUMBER</a><dd>Specifying the DB_RENUMBER flag causes the logical record numbers to be
98
mutable, and change as records are added to and deleted from the database.
99
For example, the deletion of record number 4 causes records numbered 5
100
and greater to be renumbered downward by one. If a cursor was positioned
101
to record number 4 before the deletion, it will refer to the new record
102
number 4, if any such record exists, after the deletion. If a cursor was
103
positioned after record number 4 before the deletion, it will be shifted
104
downward one logical record, continuing to refer to the same record as it
106
<p>Using the <a href="../api_java/db_put.html">Db.put</a> or <a href="../api_java/dbc_put.html">Dbc.put</a> interfaces to create new
107
records will cause the creation of multiple records if the record number
108
is more than one greater than the largest record currently in the
109
database. For example, creating record 28, when record 25 was previously
110
the last record in the database, will create records 26 and 27 as well as
111
28. Attempts to retrieve records that were created in this manner will
112
result in an error return of <a href="../ref/program/errorret.html#DB_KEYEMPTY">Db.DB_KEYEMPTY</a>.
113
<p>If a created record is not at the end of the database, all records
114
following the new record will be automatically renumbered upward by one.
115
For example, the creation of a new record numbered 8 causes records
116
numbered 8 and greater to be renumbered upward by one. If a cursor was
117
positioned to record number 8 or greater before the insertion, it will be
118
shifted upward one logical record, continuing to refer to the same record
120
<p>For these reasons, concurrent access to a Recno database with the
121
Db.DB_RENUMBER flag specified may be largely meaningless, although
123
<a name="9"><!--meow--></a>
124
<p><dt><a name="Db.DB_SNAPSHOT">Db.DB_SNAPSHOT</a><dd>This flag specifies that any specified <b>re_source</b> file be read in
125
its entirety when <a href="../api_java/db_open.html">Db.open</a> is called. If this flag is not
126
specified, the <b>re_source</b> file may be read lazily.
128
<p>The Db.set_flags interface may be used only to configure Berkeley DB before
129
the <a href="../api_java/db_open.html">Db.open</a> interface is called.
130
<p>The Db.set_flags method throws an exception that encapsulates a non-zero error value on
133
<p>The Db.set_flags method may fail and throw an exception encapsulating a non-zero error for the following conditions:
135
<p><dt>EINVAL<dd>An invalid flag value or parameter was specified.
137
<p>The <a href="../api_java/db_set_bt_compare.html">Db.set_bt_compare</a> method may fail and throw an exception for errors specified for other Berkeley DB and C library or system methods.
138
If a catastrophic error has occurred, the <a href="../api_java/db_set_bt_compare.html">Db.set_bt_compare</a> method may fail and throw
139
a <a href="../api_java/runrec_class.html">DbRunRecoveryException</a>, in which case all subsequent Berkeley DB calls
140
will fail in the same way.
142
<a href="../api_java/db_class.html">Db</a>
144
<a href="../api_java/db_associate.html">Db.associate</a>,
145
<a href="../api_java/db_close.html">Db.close</a>,
146
<a href="../api_java/db_cursor.html">Db.cursor</a>,
147
<a href="../api_java/db_del.html">Db.del</a>,
148
<a href="../api_java/db_fd.html">Db.fd</a>,
149
<a href="../api_java/db_get.html">Db.get</a>,
150
<a href="../api_java/db_get.html">Db.pget</a>,
151
<a href="../api_java/db_get_byteswapped.html">Db.get_byteswapped</a>,
152
<a href="../api_java/db_get_type.html">Db.get_type</a>,
153
<a href="../api_java/db_join.html">Db.join</a>,
154
<a href="../api_java/db_key_range.html">Db.key_range</a>,
155
<a href="../api_java/db_open.html">Db.open</a>,
156
<a href="../api_java/db_put.html">Db.put</a>,
157
<a href="../api_java/db_remove.html">Db.remove</a>,
158
<a href="../api_java/db_rename.html">Db.rename</a>,
159
<a href="../api_java/db_set_append_recno.html">Db.set_append_recno</a>,
160
<a href="../api_java/db_set_bt_minkey.html">Db.set_bt_minkey</a>,
161
<a href="../api_java/db_set_cachesize.html">Db.set_cachesize</a>,
162
<a href="../api_java/db_set_errcall.html">Db.set_errcall</a>,
163
<a href="../api_java/db_set_errpfx.html">Db.set_errpfx</a>,
164
<a href="../api_java/db_set_feedback.html">Db.set_feedback</a>,
165
<a href="../api_java/db_set_flags.html">Db.set_flags</a>,
166
<a href="../api_java/db_set_h_ffactor.html">Db.set_h_ffactor</a>,
167
<a href="../api_java/db_set_h_nelem.html">Db.set_h_nelem</a>,
168
<a href="../api_java/db_set_lorder.html">Db.set_lorder</a>,
169
<a href="../api_java/db_set_pagesize.html">Db.set_pagesize</a>,
170
<a href="../api_java/db_set_q_extentsize.html">Db.set_q_extentsize</a>,
171
<a href="../api_java/db_set_re_delim.html">Db.set_re_delim</a>,
172
<a href="../api_java/db_set_re_len.html">Db.set_re_len</a>,
173
<a href="../api_java/db_set_re_pad.html">Db.set_re_pad</a>,
174
<a href="../api_java/db_set_re_source.html">Db.set_re_source</a>,
175
<a href="../api_java/db_stat.html">Db.stat</a>,
176
<a href="../api_java/db_sync.html">Db.sync</a>,
177
<a href="../api_java/db_truncate.html">Db.truncate</a>,
178
<a href="../api_java/db_upgrade.html">Db.upgrade</a>,
180
<a href="../api_java/db_verify.html">Db.verify</a>.
182
<table width="100%"><tr><td><br></td><td align=right>
183
<a href="../api_java/java_index.html"><img src="../images/api.gif" alt="API"></a><a href="../reftoc.html"><img src="../images/ref.gif" alt="Ref"></a>
185
<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
added
removed
db/docs/api_java/db_set_flags.html
