1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>Db::set_flags()</title> 7 <link rel="stylesheet" href="apiReference.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Berkeley DB C++ API Reference" /> 10 <link rel="up" href="db.html" title="Chapter 2. The Db Handle" /> 11 <link rel="prev" href="dbset_feedback.html" title="Db::set_feedback()" /> 12 <link rel="next" href="dbset_h_compare.html" title="Db::set_h_compare()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Db::set_flags()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="dbset_feedback.html">Prev</a> </td> 22 <th width="60%" align="center">Chapter 2. 23 The Db Handle 24 </th> 25 <td width="20%" align="right"> <a accesskey="n" href="dbset_h_compare.html">Next</a></td> 26 </tr> 27 </table> 28 <hr /> 29 </div> 30 <div class="sect1" lang="en" xml:lang="en"> 31 <div class="titlepage"> 32 <div> 33 <div> 34 <h2 class="title" style="clear: both"><a id="dbset_flags"></a>Db::set_flags()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db_cxx.h> 39 40int 41Db::set_flags(u_int32_t flags); </pre> 42 <p> 43 Configure a database. Calling <code class="methodname">Db::set_flags()</code> is additive; there is 44 no way to clear flags. 45 </p> 46 <p> 47 The <code class="methodname">Db::set_flags()</code> method may not be called after the 48 <a class="xref" href="dbopen.html" title="Db::open()">Db::open()</a> method is called. 49 </p> 50 <p> 51 The <code class="methodname">Db::set_flags()</code> <span> 52 53 <span> 54 method either returns a non-zero error value or throws an 55 exception that encapsulates a non-zero error value on 56 failure, and returns 0 on success. 57 </span> 58 </span> 59 </p> 60 <div class="sect2" lang="en" xml:lang="en"> 61 <div class="titlepage"> 62 <div> 63 <div> 64 <h3 class="title"><a id="id1647064"></a>Parameters</h3> 65 </div> 66 </div> 67 </div> 68 <div class="sect3" lang="en" xml:lang="en"> 69 <div class="titlepage"> 70 <div> 71 <div> 72 <h4 class="title"><a id="id1646915"></a>flags</h4> 73 </div> 74 </div> 75 </div> 76 <p> 77 The <span class="bold"><strong>flags</strong></span> parameter must be set to 0 78 or by bitwise inclusively <span class="bold"><strong>OR</strong></span>'ing 79 together one or more of the following values: 80 81 </p> 82 <p> 83 <span class="bold"><strong>General</strong></span> 84 </p> 85 <p> 86 The following flags may be specified for any Berkeley DB access 87 method: 88 </p> 89 <div class="itemizedlist"> 90 <ul type="disc"> 91 <li> 92 <p><a id="dbset_flags_DB_CHKSUM"></a> 93 <code class="literal">DB_CHKSUM</code> 94 </p> 95 <p> 96 Do checksum verification of pages read into the cache from the backing 97 filestore. Berkeley DB uses the SHA1 Secure Hash Algorithm if 98 encryption is configured and a general hash algorithm if it is not. 99 </p> 100 <p> 101 Calling <code class="methodname">Db::set_flags()</code> with the DB_CHKSUM flag only affects the 102 specified <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> handle (and 103 any other Berkeley DB handles opened within the scope of that handle). 104 </p> 105 <p> 106 If the database already exists when <a class="xref" href="dbopen.html" title="Db::open()">Db::open()</a> 107 is called, the DB_CHKSUM flag will be ignored. 108 </p> 109 </li> 110 <li> 111 <p><a id="dbset_flags_DB_ENCRYPT"></a> 112 <code class="literal">DB_ENCRYPT</code> 113 </p> 114 <p> 115 Encrypt the database using the cryptographic password specified to the 116 <a class="xref" href="envset_encrypt.html" title="DbEnv::set_encrypt()">DbEnv::set_encrypt()</a> or 117 <a class="xref" href="dbset_encrypt.html" title="Db::set_encrypt()">Db::set_encrypt()</a> 118 methods. 119 </p> 120 <p> 121 Calling <code class="methodname">Db::set_flags()</code> with the DB_ENCRYPT flag only affects the 122 specified <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> handle (and 123 any other Berkeley DB handles opened within the scope of that handle). 124 </p> 125 <p> 126 If the database already exists when <a class="xref" href="dbopen.html" title="Db::open()">Db::open()</a> 127 is called, the DB_ENCRYPT flag must be the same as the existing database or an error 128 will be returned. 129 </p> 130 <p> 131 Encrypted databases are not portable between machines of different 132 byte orders, that is, encrypted databases created on big-endian 133 machines cannot be read on little-endian machines, and vice versa. 134 </p> 135 </li> 136 <li> 137 <p><a id="dbset_flags_DB_TXN_NOT_DURABLE"></a> 138 <code class="literal">DB_TXN_NOT_DURABLE</code> 139 </p> 140 <p> 141 If set, Berkeley DB will not write log records for this database. 142 This means that updates of this database exhibit the ACI (atomicity, 143 consistency, and isolation) properties, but not D (durability); that 144 is, database integrity will be maintained, but if the application or 145 system fails, integrity will not persist. The database file must be 146 verified and/or restored from backup after a failure. In order to 147 ensure integrity after application shut down, the database handles 148 must be closed without specifying 149 <a class="link" href="dbclose.html#dbclose_DB_NOSYNC">DB_NOSYNC</a>, or all 150 database changes must be flushed from the database environment cache 151 using either the <a class="xref" href="txncheckpoint.html" title="DbEnv::txn_checkpoint()">DbEnv::txn_checkpoint()</a> 152 or <a class="xref" href="mempsync.html" title="DbEnv::memp_sync()">DbEnv::memp_sync()</a> 153 methods. All database handles for a single physical file must set 154 DB_TXN_NOT_DURABLE, including database handles for different databases 155 in a physical file. 156 </p> 157 <p> 158 Calling <code class="methodname">Db::set_flags()</code> with the DB_TXN_NOT_DURABLE flag only affects 159 the specified <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> handle 160 (and any other Berkeley DB handles opened within the scope of that 161 handle). 162 </p> 163 </li> 164 </ul> 165 </div> 166 <p> 167 <span class="bold"><strong>Btree</strong></span> 168 </p> 169 <p> 170 The following flags may be specified for the Btree access method: 171 </p> 172 <div class="itemizedlist"> 173 <ul type="disc"> 174 <li> 175 <p><a id="dbset_flags_DB_DUP"></a> 176 <code class="literal">DB_DUP</code> 177 </p> 178 <p> 179 Permit duplicate data items in the database; that is, insertion when 180 the key of the key/data pair being inserted already exists in the 181 database will be successful. The ordering of duplicates in the 182 database is determined by the order of insertion, unless the ordering 183 is otherwise specified by use of a cursor operation or a 184 duplicate sort function. 185 </p> 186 <p> 187 The DB_DUPSORT flag is preferred to DB_DUP for performance reasons. 188 The DB_DUP flag should only be used by applications wanting to order 189 duplicate data items manually. 190 </p> 191 <p> 192 Calling <code class="methodname">Db::set_flags()</code> with the DB_DUP flag affects the database, 193 including all threads of control accessing the database. 194 </p> 195 <p> 196 If the database already exists when <a class="xref" href="dbopen.html" title="Db::open()">Db::open()</a> 197 is called, the DB_DUP flag must be the same as the existing database or an error will be 198 returned. 199 </p> 200 <p> 201 It is an error to specify both DB_DUP and DB_RECNUM. 202 </p> 203 </li> 204 <li> 205 <p><a id="dbset_flags_DB_DUPSORT"></a> 206 <code class="literal">DB_DUPSORT</code> 207 </p> 208 <p> 209 Permit duplicate data items in the database; that is, insertion when 210 the key of the key/data pair being inserted already exists in the 211 database will be successful. The ordering of duplicates in the 212 database is determined by the duplicate comparison function. If the 213 application does not specify a comparison function using the 214 <a class="xref" href="dbset_dup_compare.html" title="Db::set_dup_compare()">Db::set_dup_compare()</a> 215 method, a default lexical comparison will be used. It is an error to 216 specify both DB_DUPSORT and DB_RECNUM. 217 </p> 218 <p> 219 Calling <code class="methodname">Db::set_flags()</code> with the DB_DUPSORT flag affects the 220 database, including all threads of control accessing the database. 221 </p> 222 <p> 223 If the database already exists when <a class="xref" href="dbopen.html" title="Db::open()">Db::open()</a> 224 is called, the DB_DUPSORT flag must be the same as the existing database or an error 225 will be returned. 226 </p> 227 </li> 228 <li> 229 <p><a id="dbset_flags_DB_RECNUM"></a> 230 <code class="literal">DB_RECNUM</code> 231 </p> 232 <p> 233 Support retrieval from the Btree using record numbers. For more 234 information, see the 235 <a class="link" href="dbget.html#dbget_DB_SET_RECNO">DB_SET_RECNO</a> 236 flag to the <a class="xref" href="dbget.html" title="Db::get()">Db::get()</a> and 237 <a class="xref" href="dbcget.html" title="Dbc::get()">Dbc::get()</a> methods. 238 </p> 239 <p> 240 Logical record numbers in Btree databases are mutable in the face of 241 record insertion or deletion. See the DB_RENUMBER flag in the Recno 242 access method information for further discussion. 243 </p> 244 <p> 245 Maintaining record counts within a Btree introduces a serious point of 246 contention, namely the page locations where the record counts are 247 stored. In addition, the entire database must be locked during both 248 insertions and deletions, effectively single-threading the database 249 for those operations. Specifying DB_RECNUM can result in serious 250 performance degradation for some applications and data sets. 251 </p> 252 <p> 253 It is an error to specify both DB_DUP and DB_RECNUM. 254 </p> 255 <p> 256 Calling <code class="methodname">Db::set_flags()</code> with the DB_RECNUM flag affects the database, 257 including all threads of control accessing the database. 258 </p> 259 <p> 260 If the database already exists when <a class="xref" href="dbopen.html" title="Db::open()">Db::open()</a> 261 is called, the DB_RECNUM flag must be the same as the existing database or an error 262 will be returned. 263 </p> 264 </li> 265 <li> 266 <p><a id="dbset_flags_DB_REVSPLITOFF"></a> 267 <code class="literal">DB_REVSPLITOFF</code> 268 </p> 269 <p> 270 Turn off reverse splitting in the Btree. As pages are emptied in a 271 database, the Berkeley DB Btree implementation attempts to coalesce 272 empty pages into higher-level pages in order to keep the database as 273 small as possible and minimize search time. This can hurt performance 274 in applications with cyclical data demands; that is, applications 275 where the database grows and shrinks repeatedly. For example, because 276 Berkeley DB does page-level locking, the maximum level of concurrency 277 in a database of two pages is far smaller than that in a database of 278 100 pages, so a database that has shrunk to a minimal size can cause 279 severe deadlocking when a new cycle of data insertion begins. 280 </p> 281 <p> 282 Calling <code class="methodname">Db::set_flags()</code> with the DB_REVSPLITOFF flag only affects the 283 specified <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> handle (and 284 any other Berkeley DB handles opened within the scope of that handle). 285 </p> 286 </li> 287 </ul> 288 </div> 289 <p> 290 <span class="bold"><strong>Hash</strong></span> 291 </p> 292 <p> 293 The following flags may be specified for the Hash access method: 294 </p> 295 <div class="itemizedlist"> 296 <ul type="disc"> 297 <li> 298 <p><a id="dbset_flags_h_DB_DUP"></a> 299 <code class="literal">DB_DUP</code> 300 </p> 301 <p> 302 Permit duplicate data items in the database; that is, insertion when 303 the key of the key/data pair being inserted already exists in the 304 database will be successful. The ordering of duplicates in the 305 database is determined by the order of insertion, unless the ordering 306 is otherwise specified by use of a cursor operation. 307 </p> 308 <p> 309 The DB_DUPSORT flag is preferred to DB_DUP for performance reasons. 310 The DB_DUP flag should only be used by applications wanting to order 311 duplicate data items manually. 312 </p> 313 <p> 314 Calling <code class="methodname">Db::set_flags()</code> with the DB_DUP flag affects the database, 315 including all threads of control accessing the database. 316 </p> 317 <p> 318 If the database already exists when <a class="xref" href="dbopen.html" title="Db::open()">Db::open()</a> 319 is called, the DB_DUP flag must be the same as the existing database or an error will be 320 returned. 321 </p> 322 </li> 323 <li> 324 <p> 325 <code class="literal">DB_DUPSORT</code> 326 </p> 327 <p> 328 Permit duplicate data items in the database; that is, insertion when 329 the key of the key/data pair being inserted already exists in the 330 database will be successful. The ordering of duplicates in the 331 database is determined by the duplicate comparison function. If the 332 application does not specify a comparison function using the 333 <a class="xref" href="dbset_dup_compare.html" title="Db::set_dup_compare()">Db::set_dup_compare()</a> 334 method, a default lexical comparison will be used. 335 </p> 336 <p> 337 Calling <code class="methodname">Db::set_flags()</code> with the DB_DUPSORT flag affects the 338 database, including all threads of control accessing the database. 339 </p> 340 <p> 341 If the database already exists when <a class="xref" href="dbopen.html" title="Db::open()">Db::open()</a> 342 is called, the DB_DUPSORT flag must be the same as the existing database or an error 343 will be returned. 344 </p> 345 </li> 346 </ul> 347 </div> 348 <p> 349 <span class="bold"><strong>Queue</strong></span> 350 </p> 351 <p> 352 The following flags may be specified for the Queue access method: 353 </p> 354 <div class="itemizedlist"> 355 <ul type="disc"> 356 <li> 357 <p> 358 <code class="literal">DB_INORDER</code> 359 </p> 360 <p> 361 The DB_INORDER flag modifies the operation of the 362 <a class="link" href="dbget.html#dbget_DB_CONSUME">DB_CONSUME</a> or 363 <a class="link" href="dbget.html#dbget_DB_CONSUME_WAIT">DB_CONSUME_WAIT</a> 364 flags to <a class="xref" href="dbget.html" title="Db::get()">Db::get()</a> to 365 return key/data pairs in order. That is, they will always return the 366 key/data item from the head of the queue. 367 </p> 368 <p> 369 The default behavior of queue databases is optimized for multiple 370 readers, and does not guarantee that record will be retrieved in the 371 order they are added to the queue. Specifically, if a writing thread 372 adds multiple records to an empty queue, reading threads may skip some 373 of the initial records when the next <a class="xref" href="dbget.html" title="Db::get()">Db::get()</a> 374 call returns. 375 </p> 376 <p> 377 This flag modifies the <a class="xref" href="dbget.html" title="Db::get()">Db::get()</a> 378 call to verify that the record being returned is in fact the head of the queue. This will 379 increase contention and reduce concurrency when there are many reading threads. 380 </p> 381 <p> 382 Calling <code class="methodname">Db::set_flags()</code> with the DB_INORDER flag only affects the 383 specified <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> handle (and 384 any other Berkeley DB handles opened within the scope of that handle). 385 </p> 386 </li> 387 </ul> 388 </div> 389 <p> 390 <span class="bold"><strong>Recno</strong></span> 391 </p> 392 <p> 393 The following flags may be specified for the Recno access method: 394 </p> 395 <div class="itemizedlist"> 396 <ul type="disc"> 397 <li> 398 <p><a id="dbset_flags_DB_RENUMBER"></a> 399 <code class="literal">DB_RENUMBER</code> 400 </p> 401 <p> 402 Specifying the DB_RENUMBER flag causes the logical record numbers to 403 be mutable, and change as records are added to and deleted from the 404 database. 405 </p> 406 <p> 407 Using the <a class="xref" href="dbput.html" title="Db::put()">Db::put()</a> or 408 <a class="xref" href="dbcput.html" title="Dbc::put()">Dbc::put()</a> interfaces 409 to create new records will cause the creation of multiple records if 410 the record number is more than one greater than the largest record 411 currently in the database. For example, creating record 28, when 412 record 25 was previously the last record in the database, will create 413 records 26 and 27 as well as 28. Attempts to retrieve records that 414 were created in this manner will result in an error return of <a href="../../programmer_reference/program_errorret.html#program_errorret.DB_KEYEMPTY" class="olink">DB_KEYEMPTY</a>. 415 </p> 416 <p> 417 If a created record is not at the end of the database, all records 418 following the new record will be automatically renumbered upward by 419 one. For example, the creation of a new record numbered 8 causes 420 records numbered 8 and greater to be renumbered upward by one. If a 421 cursor was positioned to record number 8 or greater before the 422 insertion, it will be shifted upward one logical record, continuing to 423 refer to the same record as it did before. 424 </p> 425 <p> 426 If a deleted record is not at the end of the database, all records 427 following the removed record will be automatically renumbered downward 428 by one. For example, deleting the record numbered 8 causes records 429 numbered 9 and greater to be renumbered downward by one. If a 430 cursor was positioned to record number 9 or greater before the 431 removal, it will be shifted downward one logical record, continuing to 432 refer to the same record as it did before. 433 </p> 434 <p> 435 If a record is deleted, all cursors that were positioned on that record 436 prior to the removal will no longer be positioned on a valid entry. 437 This includes cursors used to delete an item. For example, if 438 a cursor was positioned to record number 8 before the removal of 439 that record, subsequent calls to <a class="xref" href="dbcget.html" title="Dbc::get()">Dbc::get()</a> 440 with flags of DB_CURRENT will result in an error return of 441 <a href="../../programmer_reference/program_errorret.html#program_errorret.DB_KEYEMPTY" class="olink">DB_KEYEMPTY</a> 442 until the cursor is moved to another record. A call to 443 <a class="xref" href="dbcget.html" title="Dbc::get()">Dbc::get()</a> with flags of DB_NEXT 444 will return the new record numbered 8 - which is the record that was 445 numbered 9 prior to the delete (if such a record existed). 446 </p> 447 <p> 448 For these reasons, concurrent access to a Recno database with the 449 DB_RENUMBER flag specified may be largely meaningless, although it is 450 supported. 451 </p> 452 <p> 453 Calling <code class="methodname">Db::set_flags()</code> with the DB_RENUMBER flag affects the 454 database, including all threads of control accessing the database. 455 </p> 456 <p> 457 If the database already exists when <a class="xref" href="dbopen.html" title="Db::open()">Db::open()</a> 458 is called, the DB_RENUMBER flag must be the same as the existing database or an error 459 will be returned. 460 </p> 461 </li> 462 <li> 463 <p><a id="dbset_flags_DB_SNAPSHOT"></a> 464 <code class="literal">DB_SNAPSHOT</code> 465 </p> 466 <p> 467 This flag specifies that any specified <span class="bold"><strong>re_source</strong></span> file be read in its entirety when 468 <a class="xref" href="dbopen.html" title="Db::open()">Db::open()</a> is called. If 469 this flag is not specified, the <span class="bold"><strong>re_source</strong></span> file may be read lazily. 470 </p> 471 <p> 472 See the <a class="xref" href="dbset_re_source.html" title="Db::set_re_source()">Db::set_re_source()</a> 473 method for information on the <span class="bold"><strong>re_source</strong></span> file. 474 </p> 475 <p> 476 Calling <code class="methodname">Db::set_flags()</code> with the DB_SNAPSHOT flag only affects the 477 specified <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> handle (and 478 any other Berkeley DB handles opened within the scope of that handle). 479 </p> 480 </li> 481 </ul> 482 </div> 483 </div> 484 </div> 485 <div class="sect2" lang="en" xml:lang="en"> 486 <div class="titlepage"> 487 <div> 488 <div> 489 <h3 class="title"><a id="id1647918"></a>Errors</h3> 490 </div> 491 </div> 492 </div> 493 <p> 494 The <code class="methodname">Db::set_flags()</code> <span> 495 496 <span> 497 method may fail and throw a <a class="link" href="dbexception.html" title="Chapter 6. The DbException Class">DbException</a> 498 exception, encapsulating one of the following non-zero errors, or return one 499 of the following non-zero errors: 500 </span> 501 </span> 502 </p> 503 <div class="sect3" lang="en" xml:lang="en"> 504 <div class="titlepage"> 505 <div> 506 <div> 507 <h4 class="title"><a id="id1647852"></a>EINVAL</h4> 508 </div> 509 </div> 510 </div> 511 <p> 512 An invalid flag value or parameter was specified. 513 </p> 514 </div> 515 </div> 516 <div class="sect2" lang="en" xml:lang="en"> 517 <div class="titlepage"> 518 <div> 519 <div> 520 <h3 class="title"><a id="id1647416"></a>Class</h3> 521 </div> 522 </div> 523 </div> 524 <p> 525 <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> 526 </p> 527 </div> 528 <div class="sect2" lang="en" xml:lang="en"> 529 <div class="titlepage"> 530 <div> 531 <div> 532 <h3 class="title"><a id="id1647028"></a>See Also</h3> 533 </div> 534 </div> 535 </div> 536 <p> 537 <a class="xref" href="db.html#dblist" title="Database and Related Methods">Database and Related Methods</a> 538 </p> 539 </div> 540 </div> 541 <div class="navfooter"> 542 <hr /> 543 <table width="100%" summary="Navigation footer"> 544 <tr> 545 <td width="40%" align="left"><a accesskey="p" href="dbset_feedback.html">Prev</a> </td> 546 <td width="20%" align="center"> 547 <a accesskey="u" href="db.html">Up</a> 548 </td> 549 <td width="40%" align="right"> <a accesskey="n" href="dbset_h_compare.html">Next</a></td> 550 </tr> 551 <tr> 552 <td width="40%" align="left" valign="top">Db::set_feedback() </td> 553 <td width="20%" align="center"> 554 <a accesskey="h" href="index.html">Home</a> 555 </td> 556 <td width="40%" align="right" valign="top"> Db::set_h_compare()</td> 557 </tr> 558 </table> 559 </div> 560 </body> 561</html> 562