1<!--$Id: db_set_flags.so,v 10.68 2004/09/28 15:04:19 bostic Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 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,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<table width="100%"><tr valign=top> 12<td> 13<b>Db::set_flags</b> 14</td> 15<td align=right> 16<a href="/api_cxx/api_core.html"><img src="/images/api.gif" alt="API"></a> 17<a href="/ref/toc.html"><img src="/images/ref.gif" alt="Ref"></a></td> 18</tr></table> 19<hr size=1 noshade> 20<tt> 21<b><pre> 22#include <db_cxx.h> 23<p> 24int 25Db::set_flags(u_int32_t flags); 26<p> 27int Db::get_flags(u_int32_t *flagsp); 28</pre></b> 29<hr size=1 noshade> 30<b>Description: Db::set_flags</b> 31<p>Configure a database. Calling Db::set_flags is additive; there 32is no way to clear flags.</p> 33<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. 34</p> 35<p>The Db::set_flags method 36either returns a non-zero error value 37or throws an exception that encapsulates a non-zero error value on 38failure, and returns 0 on success. 39</p> 40<b>Parameters</b> <br> 41 <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 42or more of the following values: 43<b>General</b> 44<p>The following flags may be specified for any Berkeley DB access method:</p> 45<br> 46<a name="2"><!--meow--></a> 47<b><a name="DB_CHKSUM">DB_CHKSUM</a></b><ul compact><li>Do checksum verification of pages read into the cache from the backing 48filestore. Berkeley DB uses the SHA1 Secure Hash Algorithm 49if encryption is configured and a general hash algorithm if it is not. 50<p>Calling Db::set_flags with the DB_CHKSUM flag only affects the 51specified <a href="/api_cxx/db_class.html">Db</a> handle (and any other Berkeley DB handles opened within 52the scope of that handle).</p> 53<p>If the database already exists when <a href="/api_cxx/db_open.html">Db::open</a> is called, the DB_CHKSUM 54flag 55will be ignored.</p> 56If creating additional databases in a file, the checksum behavior specified 57must be consistent with the existing databases in the file or an error will 58be returned.</ul> 59<a name="3"><!--meow--></a> 60<b><a name="DB_ENCRYPT">DB_ENCRYPT</a></b><ul compact><li>Encrypt the database using the cryptographic password specified to the 61<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. 62<p>Calling Db::set_flags with the DB_ENCRYPT flag only affects the 63specified <a href="/api_cxx/db_class.html">Db</a> handle (and any other Berkeley DB handles opened within 64the scope of that handle).</p> 65<p>If the database already exists when <a href="/api_cxx/db_open.html">Db::open</a> is called, the DB_ENCRYPT 66flag 67must be the same as the existing database or an error 68will be returned. 69</p> 70If creating additional databases in a file, the encryption behavior specified 71must be consistent with the existing databases in the file or an error will 72be returned. 73<p>Encrypted databases are not portable between machines of different byte 74orders, that is, encrypted databases created on big-endian machines 75cannot be read on little-endian machines, and vice versa.</p></ul> 76<a name="4"><!--meow--></a> 77<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 78that updates of this database exhibit the ACI (atomicity, consistency, 79and isolation) properties, but not D (durability); that is, database 80integrity will be maintained, but if the application or system fails, 81integrity will not persist. The database file must be verified and/or 82restored from backup after a failure. In order to ensure integrity 83after application shut down, the database handles must be closed without 84specifying <a href="/api_cxx/db_close.html#DB_NOSYNC">DB_NOSYNC</a>, or all database changes must be flushed 85from the database environment cache using either the 86<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 87a single physical file must set DB_TXN_NOT_DURABLE, including 88database handles for different databases in a physical file. 89<p>Calling Db::set_flags with the DB_TXN_NOT_DURABLE flag only affects the 90specified <a href="/api_cxx/db_class.html">Db</a> handle (and any other Berkeley DB handles opened within 91the scope of that handle).</p></ul> 92<br> 93<b>Btree</b> 94<p>The following flags may be specified for the Btree access method:</p> 95<br> 96<a name="5"><!--meow--></a> 97<b><a name="DB_DUP">DB_DUP</a></b><ul compact><li>Permit duplicate data items in the database; that is, insertion when the 98key of the key/data pair being inserted already exists in the database 99will be successful. The ordering of duplicates in the database is 100determined by the order of insertion, unless the ordering is otherwise 101specified by use of a cursor operation. 102<p>The DB_DUPSORT flag is preferred to DB_DUP for 103performance reasons. The DB_DUP flag should only be used by 104applications wanting to order duplicate data items manually.</p> 105<p>Calling Db::set_flags with the DB_DUP flag affects the 106database, including all threads of control accessing the database.</p> 107<p>If the database already exists when <a href="/api_cxx/db_open.html">Db::open</a> is called, the DB_DUP 108flag 109must be the same as the existing database or an error 110will be returned. 111</p> 112<p>It is an error to specify both DB_DUP and DB_RECNUM.</p></ul> 113<a name="6"><!--meow--></a> 114<b><a name="DB_DUPSORT">DB_DUPSORT</a></b><ul compact><li>Permit duplicate data items in the database; that is, insertion when the 115key of the key/data pair being inserted already exists in the database 116will be successful. The ordering of duplicates in the database is 117determined by the duplicate comparison function. If the application 118does not specify a comparison function using the 119<a href="/api_cxx/db_set_dup_compare.html">Db::set_dup_compare</a> method, a default lexical comparison will be used. 120It is an error to specify both DB_DUPSORT and DB_RECNUM. 121<p>Calling Db::set_flags with the DB_DUPSORT flag affects the 122database, including all threads of control accessing the database.</p> 123<p>If the database already exists when <a href="/api_cxx/db_open.html">Db::open</a> is called, the DB_DUPSORT 124flag 125must be the same as the existing database or an error 126will be returned. 127</p></ul> 128<a name="7"><!--meow--></a> 129<b><a name="DB_RECNUM">DB_RECNUM</a></b><ul compact><li>Support retrieval from the Btree using record numbers. For more 130information, 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> 131and <a href="/api_cxx/dbc_get.html">Dbc::get</a> methods. 132<p>Logical record numbers in Btree databases are mutable in the face of 133record insertion or deletion. See the DB_RENUMBER flag in the 134Recno access method information for further discussion.</p> 135<p>Maintaining record counts within a Btree introduces a serious point of 136contention, namely the page locations where the record counts are 137stored. In addition, the entire database must be locked during both 138insertions and deletions, effectively single-threading the database for 139those operations. Specifying DB_RECNUM can result in serious 140performance degradation for some applications and data sets.</p> 141<p>It is an error to specify both DB_DUP and DB_RECNUM.</p> 142<p>Calling Db::set_flags with the DB_RECNUM flag affects the 143database, including all threads of control accessing the database.</p> 144<p>If the database already exists when <a href="/api_cxx/db_open.html">Db::open</a> is called, the DB_RECNUM 145flag 146must be the same as the existing database or an error 147will be returned. 148</p></ul> 149<a name="8"><!--meow--></a><a name="9"><!--meow--></a> 150<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 151database, the Berkeley DB Btree implementation attempts to coalesce empty pages 152into higher-level pages in order to keep the database as small as possible 153and minimize search time. This can hurt performance in applications 154with cyclical data demands; that is, applications where the database grows 155and shrinks repeatedly. For example, because Berkeley DB does page-level 156locking, the maximum level of concurrency in a database of two pages is far 157smaller than that in a database of 100 pages, so a database that has 158shrunk to a minimal size can cause severe deadlocking when a new cycle of 159data insertion begins. 160<p>Calling Db::set_flags with the DB_REVSPLITOFF flag only affects the 161specified <a href="/api_cxx/db_class.html">Db</a> handle (and any other Berkeley DB handles opened within 162the scope of that handle).</p></ul> 163<br> 164<b>Hash</b> 165<p>The following flags may be specified for the Hash access method:</p> 166<br> 167<b><a name="DB_DUP">DB_DUP</a></b><ul compact><li>Permit duplicate data items in the database; that is, insertion when the 168key of the key/data pair being inserted already exists in the database 169will be successful. The ordering of duplicates in the database is 170determined by the order of insertion, unless the ordering is otherwise 171specified by use of a cursor operation. 172<p>The DB_DUPSORT flag is preferred to DB_DUP for 173performance reasons. The DB_DUP flag should only be used by 174applications wanting to order duplicate data items manually.</p> 175<p>Calling Db::set_flags with the DB_DUP flag affects the 176database, including all threads of control accessing the database.</p> 177<p>If the database already exists when <a href="/api_cxx/db_open.html">Db::open</a> is called, the DB_DUP 178flag 179must be the same as the existing database or an error 180will be returned. 181</p> 182</ul> 183<b><a name="DB_DUPSORT">DB_DUPSORT</a></b><ul compact><li>Permit duplicate data items in the database; that is, insertion when the 184key of the key/data pair being inserted already exists in the database 185will be successful. The ordering of duplicates in the database is 186determined by the duplicate comparison function. If the application 187does not specify a comparison function using the 188<a href="/api_cxx/db_set_dup_compare.html">Db::set_dup_compare</a> method, a default lexical comparison will be used. 189It is an error to specify both DB_DUPSORT and DB_RECNUM. 190<p>Calling Db::set_flags with the DB_DUPSORT flag affects the 191database, including all threads of control accessing the database.</p> 192<p>If the database already exists when <a href="/api_cxx/db_open.html">Db::open</a> is called, the DB_DUPSORT 193flag 194must be the same as the existing database or an error 195will be returned. 196</p></ul> 197<br> 198<b>Queue</b> 199<p>The following flags may be specified for the Queue access method:</p> 200<br> 201<a name="10"><!--meow--></a> 202<b><a name="DB_INORDER">DB_INORDER</a></b><ul compact><li>The DB_INORDER flag modifies the operation of the 203<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> 204to return key/data pairs in order. That is, they will always return 205the key/data item from the head of the queue. 206<p>The default behavior of queue databases is optimized for multiple 207readers, and does not guarantee that record will be retrieved in the 208order they are added to the queue. Specifically, if a writing thread 209adds multiple records to an empty queue, reading threads may skip some 210of the initial records when the next <a href="/api_cxx/db_get.html">Db::get</a> call returns.</p> 211<p>This flag modifies the <a href="/api_cxx/db_get.html">Db::get</a> call to verify that the record 212being returned is in fact the head of the queue. This will increase 213contention and reduce concurrency when there are many reading threads.</p> 214<p>Calling Db::set_flags with the DB_INORDER flag only affects the 215specified <a href="/api_cxx/db_class.html">Db</a> handle (and any other Berkeley DB handles opened within 216the scope of that handle).</p></ul> 217<br> 218<b>Recno</b> 219<p>The following flags may be specified for the Recno access method:</p> 220<br> 221<a name="11"><!--meow--></a> 222<b><a name="DB_RENUMBER">DB_RENUMBER</a></b><ul compact><li>Specifying the DB_RENUMBER flag causes the logical record 223numbers to be mutable, and change as records are added to and deleted 224from the database. For example, the deletion of record number 4 causes 225records numbered 5 and greater to be renumbered downward by one. If a 226cursor was positioned to record number 4 before the deletion, it will 227refer to the new record number 4, if any such record exists, after the 228deletion. If a cursor was positioned after record number 4 before the 229deletion, it will be shifted downward one logical record, continuing to 230refer to the same record as it did before. 231<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 232records will cause the creation of multiple records if the record number 233is more than one greater than the largest record currently in the 234database. For example, creating record 28, when record 25 was previously 235the last record in the database, will create records 26 and 27 as well as 23628. Attempts to retrieve records that were created in this manner will 237result in an error return of <a href="/ref/program/errorret.html#DB_KEYEMPTY">DB_KEYEMPTY</a>.</p> 238<p>If a created record is not at the end of the database, all records 239following the new record will be automatically renumbered upward by one. 240For example, the creation of a new record numbered 8 causes records 241numbered 8 and greater to be renumbered upward by one. If a cursor was 242positioned to record number 8 or greater before the insertion, it will be 243shifted upward one logical record, continuing to refer to the same record 244as it did before.</p> 245<p>For these reasons, concurrent access to a Recno database with the 246DB_RENUMBER flag specified may be largely meaningless, although 247it is supported.</p> 248<p>Calling Db::set_flags with the DB_RENUMBER flag affects the 249database, including all threads of control accessing the database.</p> 250<p>If the database already exists when <a href="/api_cxx/db_open.html">Db::open</a> is called, the DB_RENUMBER 251flag 252must be the same as the existing database or an error 253will be returned. 254</p></ul> 255<a name="12"><!--meow--></a> 256<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 257in its entirety when <a href="/api_cxx/db_open.html">Db::open</a> is called. If this flag is not 258specified, the <b>re_source</b> file may be read lazily. 259<p>Calling Db::set_flags with the DB_SNAPSHOT flag only affects the 260specified <a href="/api_cxx/db_class.html">Db</a> handle (and any other Berkeley DB handles opened within 261the scope of that handle).</p></ul> 262<br></ul> 263<br> 264<br><b>Errors</b> 265<p>The Db::set_flags method 266may fail and throw 267<a href="/api_cxx/except_class.html">DbException</a>, 268encapsulating one of the following non-zero errors, or return one of 269the following non-zero errors:</p> 270<br> 271<b>EINVAL</b><ul compact><li>An 272invalid flag value or parameter was specified.</ul> 273<br> 274<hr size=1 noshade> 275<b>Description: Db::get_flags</b> 276<p>The Db::get_flags method returns the current flags.</p> 277<p>The Db::get_flags method may be called at any time during the life of the 278application.</p> 279<p>The Db::get_flags method 280either returns a non-zero error value 281or throws an exception that encapsulates a non-zero error value on 282failure, and returns 0 on success. 283</p> 284<b>Parameters</b> <br> 285 <b>flagsp</b><ul compact><li>The Db::get_flags method returns the 286current flags in <b>flagsp</b>.</ul> 287<br> 288<hr size=1 noshade> 289<br><b>Class</b> 290<a href="/api_cxx/db_class.html">Db</a> 291<br><b>See Also</b> 292<a href="/api_cxx/db_list.html">Databases and Related Methods</a> 293</tt> 294<table width="100%"><tr><td><br></td><td align=right> 295<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> 296</td></tr></table> 297<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 298</body> 299</html> 300