1<!--$Id: db_open.so,v 10.124 2007/10/24 16:06:06 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->open</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->open</b> 14</td> 15<td align=right> 16<a href="../api_c/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.h> 23<p> 24int 25DB->open(DB *db, DB_TXN *txnid, const char *file, 26 const char *database, DBTYPE type, u_int32_t flags, int mode); 27<p> 28int 29DB->get_dbname(DB *db, const char **filenamep, const char **dbnamep); 30<p> 31int 32DB->get_multiple(DB *db); 33<p> 34int 35DB->get_open_flags(DB *db, u_int32_t *flagsp); 36<p> 37int 38DB->get_transactional(DB *db); 39</pre></b> 40<hr size=1 noshade> 41<b>Description: DB->open</b> 42<p>The DB->open method opens the database represented by the <b>file</b> 43and <b>database</b> parameters for both reading and writing.</p> 44<p>The currently supported Berkeley DB file formats (or <i>access 45methods</i>) are Btree, Hash, Queue, and Recno. The Btree format is a 46representation of a sorted, balanced tree structure. The Hash format 47is an extensible, dynamic hashing scheme. The Queue format supports 48fast access to fixed-length records accessed sequentially or by logical 49record number. The Recno format supports fixed- or variable-length 50records, accessed sequentially or by logical record number, and 51optionally backed by a flat text file.</p> 52<p>Storage and retrieval for the Berkeley DB access methods are based on key/data 53pairs; see <a href="../api_c/dbt_class.html">DBT</a> for more information.</p> 54<p>Calling DB->open is a relatively expensive operation, and 55maintaining a set of open databases will normally be preferable to 56repeatedly opening and closing the database for each new query.</p> 57<p>The DB->open method 58returns a non-zero error value on failure 59and 0 on success. 60If DB->open fails, the <a href="../api_c/db_close.html">DB->close</a> method must be called to 61discard the <a href="../api_c/db_class.html">DB</a> handle. 62</p> 63<b>Parameters</b> <br> 64 <b>database</b><ul compact><li>The <b>database</b> parameter is optional, and allows applications to 65have multiple databases in a single file. Although no <b>database</b> 66parameter needs to be specified, it is an error to attempt to open a 67second database in a <b>file</b> that was not initially created using 68a <b>database</b> name. Further, the <b>database</b> parameter is not 69supported by the Queue format. Finally, when opening multiple databases 70in the same physical file, it is important to consider locking and 71memory cache issues; see <a href="../ref/am/opensub.html">Opening 72multiple databases in a single file</a> for more information. 73<p>In-memory databases never intended to be preserved on disk may be 74created by setting the <b>file</b> parameter to NULL. If the 75<b>database</b> parameter is also NULL, the database is strictly 76temporary and cannot be opened by any other thread of control, thus the 77database can only be accessed by sharing the single database handle that 78created it, in circumstances where doing so is safe. If the 79<b>database</b> parameter is not set to NULL, the database can be opened 80by other threads of control and will be replicated to client sites in 81any replication group.</p></ul> 82 <b>file</b><ul compact><li>The <b>file</b> parameter is used as the name of an underlying file that 83will be used to back the database; see <a href="../ref/env/naming.html">File naming</a> for more information. 84<p>In-memory databases never intended to be preserved on disk may be 85created by setting the <b>file</b> parameter to NULL.</p></ul> 86<p>When using a Unicode build on Windows (the default), the <b>file</b> 87argument will be interpreted as a UTF-8 string, which is equivalent to 88ASCII for Latin characters.</p> 89 <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 90or more of the following values: 91<br> 92<b><a name="DB_AUTO_COMMIT">DB_AUTO_COMMIT</a></b><ul compact><li>Enclose the DB->open call within a transaction. If the call 93succeeds, the open operation will be recoverable and all subsequent 94database modification operations based on this handle will be 95transactionally protected. If the call fails, no database will have 96been created.</ul> 97<b><a name="DB_CREATE">DB_CREATE</a></b><ul compact><li>Create the database. If the database does not already exist and the 98DB_CREATE flag is not specified, the DB->open will fail.</ul> 99<b><a name="DB_EXCL">DB_EXCL</a></b><ul compact><li>Return an error if the database already exists. The DB_EXCL 100flag is only meaningful when specified with the DB_CREATE 101flag.</ul> 102<b><a name="DB_MULTIVERSION">DB_MULTIVERSION</a></b><ul compact><li>Open the database with support for <a href="../ref/transapp/read.html">multiversion concurrency control</a>. This will cause updates to the 103database to follow a copy-on-write protocol, which is required to 104support snapshot isolation. The DB_MULTIVERSION flag requires 105that the database be transactionally protected during its open and is 106not supported by the queue format.</ul> 107<b><a name="DB_NOMMAP">DB_NOMMAP</a></b><ul compact><li>Do not map this database into process memory (see the 108<a href="../api_c/env_set_mp_mmapsize.html">DB_ENV->set_mp_mmapsize</a> method for further information).</ul> 109<b><a name="DB_RDONLY">DB_RDONLY</a></b><ul compact><li>Open the database for reading only. Any attempt to modify items in the 110database will fail, regardless of the actual permissions of any 111underlying files.</ul> 112<b><a name="DB_READ_UNCOMMITTED">DB_READ_UNCOMMITTED</a></b><ul compact><li>Support transactional read operations with degree 1 isolation. Read 113operations on the database may request the return of modified but not 114yet committed data. This flag must be specified on all <a href="../api_c/db_class.html">DB</a> 115handles used to perform dirty reads or database updates, otherwise 116requests for dirty reads may not be honored and the read may block.</ul> 117<b><a name="DB_THREAD">DB_THREAD</a></b><ul compact><li>Cause the <a href="../api_c/db_class.html">DB</a> handle returned by DB->open to be 118<i>free-threaded</i>; that is, concurrently usable by multiple 119threads in the address space.</ul> 120<b><a name="DB_TRUNCATE">DB_TRUNCATE</a></b><ul compact><li>Physically truncate the underlying file, discarding all previous 121databases it might have held. Underlying filesystem primitives are used 122to implement this flag. For this reason, it is applicable only to the 123file and cannot be used to discard databases within a file. 124<p>The DB_TRUNCATE flag cannot be lock or transaction-protected, 125and it is an error to specify it in a locking or transaction-protected 126environment.</p></ul> 127<br></ul> 128 <b>mode</b><ul compact><li>On Windows systems, the mode parameter is ignored. 129<p>On UNIX systems or in IEEE/ANSI Std 1003.1 (POSIX) environments, files created by the database open 130are created with mode <b>mode</b> (as described in <b>chmod</b>(2)) 131and modified by the process' umask value at the time of creation (see 132<b>umask</b>(2)). Created files are owned by the process owner; the 133group ownership of created files is based on the system and directory 134defaults, and is not further specified by Berkeley DB. System shared memory 135segments created by the database open are created with mode <b>mode</b>, unmodified 136by the process' umask value. If <b>mode</b> is 0, the database open will use a 137default mode of readable and writable by both owner and group.</p></ul> 138 <b>txnid</b><ul compact><li>If the operation is part of an application-specified transaction, the 139<b>txnid</b> parameter is a transaction handle returned from 140<a href="../api_c/txn_begin.html">DB_ENV->txn_begin</a>; if the operation is part of a Berkeley DB Concurrent Data Store group, the 141<b>txnid</b> parameter is a handle returned from 142<a href="../api_c/env_cdsgroup_begin.html">DB_ENV->cdsgroup_begin</a>; otherwise NULL. 143If no transaction handle is 144specified, but the 145DB_AUTO_COMMIT flag is specified, 146the operation will be implicitly transaction protected. 147Note that transactionally protected operations on a <a href="../api_c/db_class.html">DB</a> handle 148requires the <a href="../api_c/db_class.html">DB</a> handle itself be transactionally protected 149during its open. Also note that the transaction must be committed before 150the handle is closed; see <a href="../ref/program/scope.html">Berkeley DB 151handles</a> for more information.</ul> 152 <b>type</b><ul compact><li>The <b>type</b> parameter is of type DBTYPE, and must be set to one of 153<a name="DB_BTREE">DB_BTREE</a>, <a name="DB_HASH">DB_HASH</a>, <a name="DB_QUEUE">DB_QUEUE</a>, 154<a name="DB_RECNO">DB_RECNO</a>, or <a name="DB_UNKNOWN">DB_UNKNOWN</a>. If <b>type</b> is 155DB_UNKNOWN, the database must already exist and DB->open will 156automatically determine its type. The <a href="../api_c/db_get_type.html">DB->get_type</a> method may be used 157to determine the underlying type of databases opened using DB_UNKNOWN.</ul> 158<br> 159<br><b>Environment Variables</b> 160<p>If the database was opened within a database environment, the 161environment variable <b>DB_HOME</b> may be used as the path of the 162database environment home.</p> 163<p>DB->open is affected by any database directory specified using 164the <a href="../api_c/env_set_data_dir.html">DB_ENV->set_data_dir</a> method, or by setting the "set_data_dir" string 165in the environment's <a href="../ref/env/db_config.html#DB_CONFIG">DB_CONFIG</a> file.</p> 166<br> 167<b>TMPDIR</b><ul compact><li>If the <b>file</b> and <b>dbenv</b> parameters to DB->open are 168NULL, the environment variable <b>TMPDIR</b> may be used as a 169directory in which to create temporary backing files</ul> 170<br> 171<br><b>Errors</b> 172<p>The DB->open method 173may fail and return one of the following non-zero errors:</p> 174<br> 175<b>DB_LOCK_DEADLOCK</b><ul compact><li>A transactional database environment operation was selected to resolve 176a deadlock.</ul> 177<b>DB_LOCK_NOTGRANTED</b><ul compact><li>A Berkeley DB Concurrent Data Store database environment configured for lock timeouts was unable 178to grant a lock in the allowed time.</ul> 179<br> 180<br> 181<b>ENOENT</b><ul compact><li>The file or directory does not exist.</ul> 182<br> 183<br> 184<b>DB_OLD_VERSION</b><ul compact><li>The database cannot be opened without being first upgraded.</ul> 185<br> 186<br> 187<b>EEXIST</b><ul compact><li>DB_CREATE and DB_EXCL were specified and the database exists.</ul> 188<br> 189<br> 190<b>EINVAL</b><ul compact><li>If an unknown database type, page size, hash function, pad byte, byte 191order, or a flag value or parameter that is incompatible with the 192specified database was specified; 193the <a href="../api_c/env_open.html#DB_THREAD">DB_THREAD</a> flag was specified and fast mutexes are not 194available for this architecture; 195the <a href="../api_c/env_open.html#DB_THREAD">DB_THREAD</a> flag was specified to DB->open, but was 196not specified to the <a href="../api_c/env_open.html">DB_ENV->open</a> call for the environment in 197which the <a href="../api_c/db_class.html">DB</a> handle was created; 198a backing flat text file was specified with either the <a href="../api_c/env_open.html#DB_THREAD">DB_THREAD</a> 199flag or the provided database environment supports transaction 200processing; or if an 201invalid flag value or parameter was specified.</ul> 202<br> 203<br> 204<b>ENOENT</b><ul compact><li>A nonexistent <b>re_source</b> file was specified.</ul> 205<br> 206<br> 207<b>DB_REP_HANDLE_DEAD</b><ul compact><li>The database handle has been invalidated because a replication election 208unrolled a committed transaction.</ul> 209<br> 210<br> 211<b>DB_REP_LOCKOUT</b><ul compact><li>The operation was blocked by client/master synchronization.</ul> 212<br> 213<hr size=1 noshade> 214<b>Description: DB->get_dbname</b> 215<p>The DB->get_dbname method returns the current filename and database 216name.</p> 217<b>Parameters</b> <br> 218 <b>filenamep</b><ul compact><li>The <b>filenamep</b> parameter references memory into which 219a pointer to the current filename is copied.</ul> 220 <b>dbnamep</b><ul compact><li>The <b>dbnamep</b> parameter references memory into which 221a pointer to the current database name is copied.</ul> 222<br> 223<p>The DB->get_dbname method may be called at any time during the life of the 224application.</p> 225<p>The DB->get_dbname method 226returns a non-zero error value on failure 227and 0 on success. 228</p> 229<hr size=1 noshade> 230<b>Description: <a href="../api_c/db_open.html">DB->get_multiple</a></b> 231<p>The <a href="../api_c/db_open.html">DB->get_multiple</a> method returns non-zero if the <a href="../api_c/db_class.html">DB</a> handle 232references a physical file supporting multiple databases.</p> 233<p>In this case, the <a href="../api_c/db_class.html">DB</a> handle is a handle on a database whose key 234values are the names of the databases stored in the physical file and 235whose data values are opaque objects. No keys or data values may be 236modified or stored using the database handle.</p> 237<p>The <a href="../api_c/db_open.html">DB->get_multiple</a> method may not be called before the DB->open method is called.</p> 238<hr size=1 noshade> 239<b>Description: DB->get_open_flags</b> 240<p>The DB->get_open_flags method returns the current open method flags.</p> 241<p>The DB->get_open_flags method may not be called before the DB->open method is called.</p> 242<p>The DB->get_open_flags method 243returns a non-zero error value on failure 244and 0 on success. 245</p> 246<b>Parameters</b> <br> 247 <b>flagsp</b><ul compact><li>The DB->get_open_flags method returns the 248current open method flags in <b>flagsp</b>.</ul> 249<br> 250<hr size=1 noshade> 251<b>Description: DB->get_transactional</b> 252<p>The DB->get_transactional method returns non-zero if the <a href="../api_c/db_class.html">DB</a> 253handle has been opened in a transactional mode.</p> 254<p>The DB->get_transactional method may be called at any time during the life of the 255application.</p> 256<hr size=1 noshade> 257<br><b>Class</b> 258<a href="../api_c/db_class.html">DB</a> 259<br><b>See Also</b> 260<a href="../api_c/db_list.html">Databases and Related Methods</a> 261</tt> 262<table width="100%"><tr><td><br></td><td align=right> 263<a href="../api_c/api_core.html"><img src="../images/api.gif" alt="API"></a><a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a> 264</td></tr></table> 265<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 266</body> 267</html> 268
