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::open()</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="dbkey_range.html" title="Db::key_range()" /> 12 <link rel="next" href="dbput.html" title="Db::put()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Db::open()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="dbkey_range.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="dbput.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="dbopen"></a>Db::open()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db_cxx.h> 39 40int 41Db::open(DbTxn *txnid, const char *file, 42 const char *database, DBTYPE type, u_int32_t flags, int mode); </pre> 43 <p> 44 The <code class="methodname">Db::open()</code> method opens the database represented by the 45 <span class="bold"><strong>file</strong></span> and <span class="bold"><strong>database</strong></span>. 46 </p> 47 <p> 48 The currently supported Berkeley DB file formats (or <span class="emphasis"><em>access 49 methods</em></span>) are Btree, Hash, Queue, and Recno. The Btree 50 format is a representation of a sorted, balanced tree structure. The 51 Hash format is an extensible, dynamic hashing scheme. The Queue 52 format supports fast access to fixed-length records accessed 53 sequentially or by logical record number. The Recno format supports 54 fixed- or variable-length records, accessed sequentially or by logical 55 record number, and optionally backed by a flat text file. 56 </p> 57 <p> 58 Storage and retrieval for the Berkeley DB access methods are based on 59 key/data pairs; see <a class="link" href="dbt.html" title="Chapter 4. The Dbt Handle">Dbt</a> 60 for more information. 61 </p> 62 <p> 63 Calling <code class="methodname">Db::open()</code> is a relatively expensive operation, and 64 maintaining a set of open databases will normally be preferable to 65 repeatedly opening and closing the database for each new query. 66 </p> 67 <p> 68 The <code class="methodname">Db::open()</code> <span> 69 70 <span> 71 method either returns a non-zero error value or throws an 72 exception that encapsulates a non-zero error value on 73 failure, and returns 0 on success. 74 </span> 75 </span> 76 If <code class="methodname">Db::open()</code> fails, the 77 <a class="xref" href="dbclose.html" title="Db::close()">Db::close()</a> method must be 78 called to discard the <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> 79 handle. 80 </p> 81 <div class="sect2" lang="en" xml:lang="en"> 82 <div class="titlepage"> 83 <div> 84 <div> 85 <h3 class="title"><a id="id1639518"></a>Parameters</h3> 86 </div> 87 </div> 88 </div> 89 <div class="sect3" lang="en" xml:lang="en"> 90 <div class="titlepage"> 91 <div> 92 <div> 93 <h4 class="title"><a id="id1639501"></a>database</h4> 94 </div> 95 </div> 96 </div> 97 <p> 98 The <span class="bold"><strong>database</strong></span> parameter is optional, 99 and allows applications to have multiple databases in a single file. 100 Although no <span class="bold"><strong>database</strong></span> parameter needs 101 to be specified, it is an error to attempt to open a second database 102 in a <span class="bold"><strong>file</strong></span> that was not initially 103 created using a <span class="bold"><strong>database</strong></span> name. 104 Further, the <span class="bold"><strong>database</strong></span> parameter is 105 not supported by the Queue format. Finally, when opening multiple 106 databases in the same physical file, it is important to consider 107 locking and memory cache issues; see 108 <a href="../../programmer_reference/am_opensub.html" class="olink">Opening multiple databases in a single file</a> 109 for more information. 110 </p> 111 <p> 112 If both the <span class="bold"><strong>database</strong></span> and 113 <span class="bold"><strong>file</strong></span> parameters are NULL, 114 the database is strictly temporary and cannot be opened 115 by any other thread of control. Thus the database can only be accessed 116 by sharing the single database handle that created it, in 117 circumstances where doing so is safe. 118 </p> 119 <p> 120 If the <span class="bold"><strong>database</strong></span> parameter is not 121 set to NULL, the database can be opened by other threads of control 122 and will be replicated to client sites in any replication group, regardless 123 of whether the <span class="bold"><strong>file</strong></span> parameter is set to 124 NULL. 125 </p> 126 </div> 127 <div class="sect3" lang="en" xml:lang="en"> 128 <div class="titlepage"> 129 <div> 130 <div> 131 <h4 class="title"><a id="id1640053"></a>file</h4> 132 </div> 133 </div> 134 </div> 135 <p> 136 The <span class="bold"><strong>file</strong></span> parameter is used as the 137 name of an underlying file that will be used to back the database; see 138 <a href="../../programmer_reference/env_naming.html" class="olink">File naming</a> for more 139 information. 140 </p> 141 <p> 142 In-memory databases never intended to be preserved on disk may be 143 created by setting the <span class="bold"><strong>file</strong></span> parameter 144 to NULL. Whether other threads of control can access this database is 145 driven entirely by whether the <span class="bold"><strong>database</strong></span> 146 parameter is set to NULL. 147 </p> 148 <p> 149 When using a Unicode build on Windows (the default), the <span class="bold"><strong>file</strong></span> argument will be interpreted as a UTF-8 150 string, which is equivalent to ASCII for Latin characters. 151 </p> 152 </div> 153 <div class="sect3" lang="en" xml:lang="en"> 154 <div class="titlepage"> 155 <div> 156 <div> 157 <h4 class="title"><a id="id1640112"></a>flags</h4> 158 </div> 159 </div> 160 </div> 161 <p> 162 The <span class="bold"><strong>flags</strong></span> parameter must be set to zero or 163 by bitwise inclusively <span class="bold"><strong>OR</strong></span>'ing together one 164 or more of the following values: 165 </p> 166 <div class="itemizedlist"> 167 <ul type="disc"> 168 <li> 169 <p><a id="open_DB_AUTO_COMMIT"></a> 170 <code class="literal">DB_AUTO_COMMIT</code> 171 </p> 172 <p> 173 Enclose the <code class="methodname">Db::open()</code> call within a transaction. If the call 174 succeeds, the open operation will be recoverable and all 175 subsequent database modification operations based on this 176 handle will be transactionally protected. If the call fails, 177 no database will have been created. 178 </p> 179 </li> 180 <li> 181 <p><a id="open_DB_CREATE"></a> 182 <code class="literal">DB_CREATE</code> 183 </p> 184 <p> 185 Create the database. If the database does not already exist 186 and the <code class="literal">DB_CREATE</code> flag is not specified, the 187 <code class="methodname">Db::open()</code> will fail. 188 </p> 189 </li> 190 <li> 191 <p><a id="open_DB_EXCL"></a> 192 <code class="literal">DB_EXCL</code> 193 </p> 194 <p> 195 Return an error if the database already exists. The 196 <code class="literal">DB_EXCL</code> flag is only meaningful 197 when specified with the <code class="literal">DB_CREATE</code>. 198 flag. 199 </p> 200 </li> 201 <li> 202 <p><a id="dbopen_DB_MULTIVERSION"></a> 203 <code class="literal">DB_MULTIVERSION</code> 204 </p> 205 <p> 206 Open the database with support for 207 <a href="../../programmer_reference/transapp_read.html" class="olink">multiversion concurrency control</a>. 208 This will cause updates to the database to follow a 209 copy-on-write protocol, which is required to support 210 snapshot isolation. The <code class="literal">DB_MULTIVERSION</code> 211 flag requires that the database be transactionally protected during its open 212 and is not supported by the queue format. 213 </p> 214 </li> 215 <li> 216 <p><a id="open_DB_NOMMAP"></a> 217 <code class="literal">DB_NOMMAP</code> 218 </p> 219 <p> 220 Do not map this database into process memory (see the 221 <a class="xref" href="envset_mp_mmapsize.html" title="DbEnv::set_mp_mmapsize()">DbEnv::set_mp_mmapsize()</a> 222 method for further information). 223 </p> 224 </li> 225 <li> 226 <p><a id="dbopen_DB_RDONLY"></a> 227 <code class="literal">DB_RDONLY</code> 228 </p> 229 <p> 230 Open the database for reading only. Any attempt to modify 231 items in the database will fail, regardless of the actual 232 permissions of any underlying files. 233 </p> 234 </li> 235 <li> 236 <p><a id="dbopen_DB_READ_UNCOMMITTED"></a> 237 <code class="literal">DB_READ_UNCOMMITTED</code> 238 </p> 239 <p> 240 Support transactional read operations with degree 1 241 isolation. Read operations on the database may request the 242 return of modified but not yet committed data. This flag 243 must be specified on all 244 <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> 245 handles used to perform dirty 246 reads or database updates, otherwise requests for dirty 247 reads may not be honored and the read may block. 248 </p> 249 </li> 250 <li> 251 <p><a id="open_DB_THREAD"></a> 252 <code class="literal">DB_THREAD</code> 253 </p> 254 <p> 255 Cause the <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> 256 handle returned by <code class="methodname">Db::open()</code> to be <span class="emphasis"><em>free-threaded</em></span>; that is, 257 concurrently usable by multiple threads in the address 258 space. 259 </p> 260 </li> 261 <li> 262 <p><a id="open_DB_TRUNCATE"></a> 263 <code class="literal">DB_TRUNCATE</code> 264 </p> 265 <p> 266 Physically truncate the underlying file, discarding all 267 previous databases it might have held. Underlying filesystem 268 primitives are used to implement this flag. For this reason, 269 it is applicable only to the file and cannot be used to 270 discard databases within a file. 271 </p> 272 <p> 273 The <code class="literal">DB_TRUNCATE</code> flag cannot be lock or 274 transaction-protected, and it is an error to specify it in a 275 locking or transaction-protected environment. 276 </p> 277 </li> 278 </ul> 279 </div> 280 </div> 281 <div class="sect3" lang="en" xml:lang="en"> 282 <div class="titlepage"> 283 <div> 284 <div> 285 <h4 class="title"><a id="id1640156"></a>mode</h4> 286 </div> 287 </div> 288 </div> 289 <p> 290 On Windows systems, the mode parameter is ignored. 291 </p> 292 <p> 293 On UNIX systems or in IEEE/ANSI Std 1003.1 (POSIX) environments, files 294 created by the database open are created with mode <span class="bold"><strong>mode</strong></span> (as described in <span class="bold"><strong>chmod</strong></span>(2)) and modified by the process' umask 295 value at the time of creation (see <span class="bold"><strong>umask</strong></span>(2)). Created files are owned by the 296 process owner; the group ownership of created files is based on the 297 system and directory defaults, and is not further specified by 298 Berkeley DB. System shared memory segments created by the database 299 open are created with mode <span class="bold"><strong>mode</strong></span>, 300 unmodified by the process' umask value. If <span class="bold"><strong>mode</strong></span> is 0, the database open will use a default 301 mode of readable and writable by both owner and group. 302 </p> 303 </div> 304 <div class="sect3" lang="en" xml:lang="en"> 305 <div class="titlepage"> 306 <div> 307 <div> 308 <h4 class="title"><a id="id1640343"></a>txnid</h4> 309 </div> 310 </div> 311 </div> 312 <p> 313 If the operation is part of an application-specified transaction, the 314 <span class="bold"><strong>txnid</strong></span> parameter is a transaction 315 handle returned from <a class="xref" href="txnbegin.html" title="DbEnv::txn_begin()">DbEnv::txn_begin()</a>; 316 if the operation is part of a Berkeley DB Concurrent Data Store group, the 317 <span class="bold"><strong>txnid</strong></span> parameter is a handle returned 318 from <a class="xref" href="envcdsgroup_begin.html" title="DbEnv::cdsgroup_begin()">DbEnv::cdsgroup_begin()</a>; 319 otherwise NULL. If no transaction handle is specified, but the 320 DB_AUTO_COMMIT flag is specified, the operation will be implicitly 321 transaction protected. Note that transactionally protected operations 322 on a <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> handle requires 323 the <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> handle itself be 324 transactionally protected during its open. Also note that the 325 transaction must be committed before the handle is closed; see <a href="../../programmer_reference/program_scope.html" class="olink">Berkeley DB handles</a> for more 326 information. 327 </p> 328 </div> 329 <div class="sect3" lang="en" xml:lang="en"> 330 <div class="titlepage"> 331 <div> 332 <div> 333 <h4 class="title"><a id="id1639885"></a>type</h4> 334 </div> 335 </div> 336 </div> 337 <p> 338 The <span class="bold"><strong>type</strong></span> parameter is of type DBTYPE, 339 and must be set to one of <code class="literal">DB_BTREE</code>, 340 <code class="literal">DB_HASH</code>, <code class="literal">DB_QUEUE</code>, 341 <code class="literal">DB_RECNO</code>, or <code class="literal">DB_UNKNOWN</code>. If <span class="bold"><strong>type</strong></span> is DB_UNKNOWN, the database must already 342 exist and <code class="methodname">Db::open()</code> will automatically determine its type. The 343 <a class="xref" href="dbget_type.html" title="Db::get_type()">Db::get_type()</a> method 344 may be used to determine the underlying type of databases opened using 345 DB_UNKNOWN. 346 </p> 347 <p> 348 It is an error to specify the incorrect <span class="bold"><strong>type</strong></span> 349 for a database that already exists. 350 </p> 351 </div> 352 </div> 353 <div class="sect2" lang="en" xml:lang="en"> 354 <div class="titlepage"> 355 <div> 356 <div> 357 <h3 class="title"><a id="id1639830"></a>Environment Variables</h3> 358 </div> 359 </div> 360 </div> 361 <p> 362 If the database was opened within a database environment, the 363 environment variable <span class="bold"><strong>DB_HOME</strong></span> may be used as the path of the 364 database environment home. 365 </p> 366 <p> 367 <code class="methodname">Db::open()</code> is affected by any database directory specified using the 368 <a class="xref" href="envset_data_dir.html" title="DbEnv::set_data_dir()">DbEnv::set_data_dir()</a> 369 method, or by setting the "set_data_dir" string in 370 the environment's 371 <a href="../../programmer_reference/env_db_config.html#env_db_config.DB_CONFIG" class="olink">DB_CONFIG</a> 372 file. 373 </p> 374 <div class="itemizedlist"> 375 <ul type="disc"> 376 <li> 377 <p> 378 <span class="bold"><strong>TMPDIR</strong></span> 379 </p> 380 <p> 381 If the <span class="bold"><strong>file</strong></span> 382 and <span class="bold"><strong>dbenv</strong></span> 383 parameters to <code class="methodname">Db::open()</code> are <code class="literal">NULL</code>, 384 the environment variable 385 <span class="bold"><strong>TMPDIR</strong></span> 386 may be used as a 387 directory in which to create temporary backing files 388 </p> 389 </li> 390 </ul> 391 </div> 392 </div> 393 <div class="sect2" lang="en" xml:lang="en"> 394 <div class="titlepage"> 395 <div> 396 <div> 397 <h3 class="title"><a id="id1640751"></a>Errors</h3> 398 </div> 399 </div> 400 </div> 401 <p> 402 The <code class="methodname">Db::open()</code> <span> 403 404 <span> 405 method may fail and throw a <a class="link" href="dbexception.html" title="Chapter 6. The DbException Class">DbException</a> 406 exception, encapsulating one of the following non-zero errors, or return one 407 of the following non-zero errors: 408 </span> 409 </span> 410 </p> 411 <div class="sect3" lang="en" xml:lang="en"> 412 <div class="titlepage"> 413 <div> 414 <div> 415 <h4 class="title"><a id="id1640382"></a><span>DbDeadlockException or </span>DB_LOCK_DEADLOCK</h4> 416 </div> 417 </div> 418 </div> 419 <p> 420 A transactional database environment operation was selected to resolve 421 a deadlock. 422 </p> 423 <p> 424 <a class="xref" href="dbdeadlock.html" title="DbDeadlockException">DbDeadlockException</a> is thrown if 425 your Berkeley DB API is configured to throw exceptions. 426 Otherwise, <code class="literal">DB_LOCK_DEADLOCK</code> is returned. 427 </p> 428 </div> 429 <div class="sect3" lang="en" xml:lang="en"> 430 <div class="titlepage"> 431 <div> 432 <div> 433 <h4 class="title"><a id="id1640694"></a><span>DbLockNotGrantedException or </span>DB_LOCK_NOTGRANTED</h4> 434 </div> 435 </div> 436 </div> 437 <p> 438 A Berkeley DB Concurrent Data Store database environment configured 439 for lock timeouts was unable to grant a lock in the allowed time. 440 </p> 441 <p> 442 <a class="xref" href="dblocknotgranted.html" title="DbLockNotGrantedException">DbLockNotGrantedException</a> is thrown if 443 your Berkeley DB API is configured to throw exceptions. 444 Otherwise, <code class="literal">DB_LOCK_NOTGRANTED</code> is returned. 445 </p> 446 </div> 447 <div class="sect3" lang="en" xml:lang="en"> 448 <div class="titlepage"> 449 <div> 450 <div> 451 <h4 class="title"><a id="id1639978"></a>ENOENT</h4> 452 </div> 453 </div> 454 </div> 455 <p> 456 The file or directory does not exist. 457 </p> 458 </div> 459 <div class="sect3" lang="en" xml:lang="en"> 460 <div class="titlepage"> 461 <div> 462 <div> 463 <h4 class="title"><a id="id1640026"></a>ENOENT</h4> 464 </div> 465 </div> 466 </div> 467 <p> 468 A nonexistent <span class="bold"><strong>re_source</strong></span> file was specified. 469 </p> 470 </div> 471 <div class="sect3" lang="en" xml:lang="en"> 472 <div class="titlepage"> 473 <div> 474 <div> 475 <h4 class="title"><a id="id1640725"></a>DB_OLD_VERSION</h4> 476 </div> 477 </div> 478 </div> 479 <p> 480 The database cannot be opened without being first upgraded. 481 </p> 482 </div> 483 <div class="sect3" lang="en" xml:lang="en"> 484 <div class="titlepage"> 485 <div> 486 <div> 487 <h4 class="title"><a id="id1640707"></a>EEXIST</h4> 488 </div> 489 </div> 490 </div> 491 <p> 492 <code class="literal">DB_CREATE</code> and <code class="literal">DB_EXCL</code> 493 were specified and the database exists. 494 </p> 495 </div> 496 <div class="sect3" lang="en" xml:lang="en"> 497 <div class="titlepage"> 498 <div> 499 <div> 500 <h4 class="title"><a id="id1640308"></a>EINVAL</h4> 501 </div> 502 </div> 503 </div> 504 <p> 505 If an unknown database type, page size, hash function, pad byte, byte order, or a flag value 506 or parameter that is incompatible with the specified database was specified; the 507 <a class="link" href="envopen.html#envopen_DB_THREAD">DB_THREAD</a> 508 flag was specified and fast mutexes are not available for this architecture; the 509 <a class="link" href="envopen.html#envopen_DB_THREAD">DB_THREAD</a> 510 flag was specified to <code class="methodname">Db::open()</code>, but was 511 not specified to the <code class="methodname">DbEnv::open()</code> call for the 512 environment in which the <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> 513 handle was created; a backing flat text file was specified with either the 514 <a class="link" href="envopen.html#envopen_DB_THREAD">DB_THREAD</a> 515 flag or the provided database environment supports transaction 516 processing; or if an invalid flag value or parameter was specified. 517 </p> 518 </div> 519 <div class="sect3" lang="en" xml:lang="en"> 520 <div class="titlepage"> 521 <div> 522 <div> 523 <h4 class="title"><a id="id1640889"></a><span>DbRepHandleDeadException or</span> DB_REP_HANDLE_DEAD</h4> 524 </div> 525 </div> 526 </div> 527 <p> 528 When a client synchronizes with the master, it is possible for committed 529 transactions to be rolled back. This invalidates all the database and cursor 530 handles opened in the replication environment. Once this occurs, an attempt to use 531 such a handle will 532 <span> 533 throw a <a class="xref" href="dbrephandledead.html" title="DbRepHandleDeadException">DbRepHandleDeadException</a> (if 534 your application is configured to throw exceptions), or 535 </span> 536 return <code class="literal">DB_REP_HANDLE_DEAD</code>. 537 The application will need to discard the handle and open a new one in order to 538 continue processing. 539 </p> 540 </div> 541 <div class="sect3" lang="en" xml:lang="en"> 542 <div class="titlepage"> 543 <div> 544 <div> 545 <h4 class="title"><a id="id1640738"></a><span>DbDeadlockException or </span>DB_REP_LOCKOUT</h4> 546 </div> 547 </div> 548 </div> 549 <p> 550 The operation was blocked by client/master synchronization. 551 </p> 552 <p> 553 <a class="xref" href="dbdeadlock.html" title="DbDeadlockException">DbDeadlockException</a> is thrown if 554 your Berkeley DB API is configured to throw exceptions. 555 Otherwise, <code class="literal">DB_REP_LOCKOUT</code> is returned. 556 </p> 557 </div> 558 </div> 559 <div class="sect2" lang="en" xml:lang="en"> 560 <div class="titlepage"> 561 <div> 562 <div> 563 <h3 class="title"><a id="id1640968"></a>Class</h3> 564 </div> 565 </div> 566 </div> 567 <p> 568 <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> 569 </p> 570 </div> 571 <div class="sect2" lang="en" xml:lang="en"> 572 <div class="titlepage"> 573 <div> 574 <div> 575 <h3 class="title"><a id="id1639918"></a>See Also</h3> 576 </div> 577 </div> 578 </div> 579 <p> 580 <a class="xref" href="db.html#dblist" title="Database and Related Methods">Database and Related Methods</a> 581 </p> 582 </div> 583 </div> 584 <div class="navfooter"> 585 <hr /> 586 <table width="100%" summary="Navigation footer"> 587 <tr> 588 <td width="40%" align="left"><a accesskey="p" href="dbkey_range.html">Prev</a> </td> 589 <td width="20%" align="center"> 590 <a accesskey="u" href="db.html">Up</a> 591 </td> 592 <td width="40%" align="right"> <a accesskey="n" href="dbput.html">Next</a></td> 593 </tr> 594 <tr> 595 <td width="40%" align="left" valign="top">Db::key_range() </td> 596 <td width="20%" align="center"> 597 <a accesskey="h" href="index.html">Home</a> 598 </td> 599 <td width="40%" align="right" valign="top"> Db::put()</td> 600 </tr> 601 </table> 602 </div> 603 </body> 604</html> 605