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