docs/api_cxx/db_open.html

<!--$Id: db_open.so,v 10.124 2007/10/24 16:06:06 bostic Exp $-->
<!--Copyright (c) 1997,2008 Oracle.  All rights reserved.-->
<!--See the file LICENSE for redistribution information.-->
<html>
<head>
<title>Berkeley DB: Db::open</title>
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++">
</head>
<body bgcolor=white>
<table width="100%"><tr valign=top>
<td>
<b>Db::open</b>
</td>
<td align=right>
<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></td>
</tr></table>
<hr size=1 noshade>
<tt>
<b><pre>
#include &lt;db_cxx.h&gt;
<p>
int
Db::open(DbTxn *txnid, const char *file,
    const char *database, DBTYPE type, u_int32_t flags, int mode);
<p>
int
Db::get_dbname(const char **filenamep, const char **dbnamep);
<p>
int
Db::get_multiple()
<p>
int
Db::get_open_flags(u_int32_t *flagsp);
<p>
int
Db::get_transactional()
</pre></b>
<hr size=1 noshade>
<b>Description: Db::open</b>
<p>The Db::open method opens the database represented by the <b>file</b>
and <b>database</b> parameters for both reading and writing.</p>
<p>The currently supported Berkeley DB file formats (or <i>access
methods</i>) are Btree, Hash, Queue, and Recno.  The Btree format is a
representation of a sorted, balanced tree structure.  The Hash format
is an extensible, dynamic hashing scheme.  The Queue format supports
fast access to fixed-length records accessed sequentially or by logical
record number.  The Recno format supports fixed- or variable-length
records, accessed sequentially or by logical record number, and
optionally backed by a flat text file.</p>
<p>Storage and retrieval for the Berkeley DB access methods are based on key/data
pairs; see <a href="../api_cxx/dbt_class.html">Dbt</a> for more information.</p>
<p>Calling Db::open is a relatively expensive operation, and
maintaining a set of open databases will normally be preferable to
repeatedly opening and closing the database for each new query.</p>
<p>The Db::open method
either returns a non-zero error value
or throws an exception that encapsulates a non-zero error value on
failure, and returns 0 on success.
If Db::open fails, the <a href="../api_cxx/db_close.html">Db::close</a> method must be called to
discard the <a href="../api_cxx/db_class.html">Db</a> handle.
</p>
<b>Parameters</b> <br>
 <b>database</b><ul compact><li>The <b>database</b> parameter is optional, and allows applications to
have multiple databases in a single file.  Although no <b>database</b>
parameter needs to be specified, it is an error to attempt to open a
second database in a <b>file</b> that was not initially created using
a <b>database</b> name.  Further, the <b>database</b> parameter is not
supported by the Queue format.  Finally, when opening multiple databases
in the same physical file, it is important to consider locking and
memory cache issues; see <a href="../ref/am/opensub.html">Opening
multiple databases in a single file</a> for more information.
<p>In-memory databases never intended to be preserved on disk may be
created by setting the <b>file</b> parameter to NULL.  If the
<b>database</b> parameter is also NULL, the database is strictly
temporary and cannot be opened by any other thread of control, thus the
database can only be accessed by sharing the single database handle that
created it, in circumstances where doing so is safe.  If the
<b>database</b> parameter is not set to NULL, the database can be opened
by other threads of control and will be replicated to client sites in
any replication group.</p></ul>
 <b>file</b><ul compact><li>The <b>file</b> parameter is used as the name of an underlying file that
will be used to back the database; see <a href="../ref/env/naming.html">File naming</a> for more information.
<p>In-memory databases never intended to be preserved on disk may be
created by setting the <b>file</b> parameter to NULL.</p></ul>
<p>When using a Unicode build on Windows (the default), the <b>file</b>
argument will be interpreted as a UTF-8 string, which is equivalent to
ASCII for Latin characters.</p>
 <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
or more of the following values:
<br>
<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
succeeds, the open operation will be recoverable and all subsequent
database modification operations based on this handle will be
transactionally protected.  If the call fails, no database will have
been created.</ul>
<b><a name="DB_CREATE">DB_CREATE</a></b><ul compact><li>Create the database.  If the database does not already exist and the
DB_CREATE flag is not specified, the Db::open will fail.</ul>
<b><a name="DB_EXCL">DB_EXCL</a></b><ul compact><li>Return an error if the database already exists.  The DB_EXCL
flag is only meaningful when specified with the DB_CREATE
flag.</ul>
<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
database to follow a copy-on-write protocol, which is required to
support snapshot isolation.  The DB_MULTIVERSION flag requires
that the database be transactionally protected during its open and is
not supported by the queue format.</ul>
<b><a name="DB_NOMMAP">DB_NOMMAP</a></b><ul compact><li>Do not map this database into process memory (see the
<a href="../api_cxx/env_set_mp_mmapsize.html">DbEnv::set_mp_mmapsize</a> method for further information).</ul>
<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
database will fail, regardless of the actual permissions of any
underlying files.</ul>
<b><a name="DB_READ_UNCOMMITTED">DB_READ_UNCOMMITTED</a></b><ul compact><li>Support transactional read operations with degree 1 isolation.  Read
operations on the database may request the return of modified but not
yet committed data.  This flag must be specified on all <a href="../api_cxx/db_class.html">Db</a>
handles used to perform dirty reads or database updates, otherwise
requests for dirty reads may not be honored and the read may block.</ul>
<b><a name="DB_THREAD">DB_THREAD</a></b><ul compact><li>Cause the <a href="../api_cxx/db_class.html">Db</a> handle returned by Db::open to be
<i>free-threaded</i>; that is, concurrently usable by multiple
threads in the address space.</ul>
<b><a name="DB_TRUNCATE">DB_TRUNCATE</a></b><ul compact><li>Physically truncate the underlying file, discarding all previous
databases it might have held.  Underlying filesystem primitives are used
to implement this flag.  For this reason, it is applicable only to the
file and cannot be used to discard databases within a file.
<p>The DB_TRUNCATE flag cannot be lock or transaction-protected,
and it is an error to specify it in a locking or transaction-protected
environment.</p></ul>
<br></ul>
 <b>mode</b><ul compact><li>On Windows systems, the mode parameter is ignored.
<p>On UNIX systems or in IEEE/ANSI Std 1003.1 (POSIX) environments, files created by the database open
are created with mode <b>mode</b> (as described in <b>chmod</b>(2))
and modified by the process' umask value at the time of creation (see
<b>umask</b>(2)).  Created files are owned by the process owner; the
group ownership of created files is based on the system and directory
defaults, and is not further specified by Berkeley DB.  System shared memory
segments created by the database open are created with mode <b>mode</b>, unmodified
by the process' umask value.  If <b>mode</b> is 0, the database open will use a
default mode of readable and writable by both owner and group.</p></ul>
 <b>txnid</b><ul compact><li>If the operation is part of an application-specified transaction, the
<b>txnid</b> parameter is a transaction handle returned from
<a href="../api_cxx/txn_begin.html">DbEnv::txn_begin</a>; if the operation is part of a Berkeley DB Concurrent Data Store group, the
<b>txnid</b> parameter is a handle returned from
<a href="../api_cxx/env_cdsgroup_begin.html">DbEnv::cdsgroup_begin</a>; otherwise NULL.
If no transaction handle is
specified, but the
DB_AUTO_COMMIT flag is specified,
the operation will be implicitly transaction protected.
Note that transactionally protected operations on a <a href="../api_cxx/db_class.html">Db</a> handle
requires the <a href="../api_cxx/db_class.html">Db</a> handle itself be transactionally protected
during its open.  Also note that the transaction must be committed before
the handle is closed; see <a href="../ref/program/scope.html">Berkeley DB
handles</a> for more information.</ul>
 <b>type</b><ul compact><li>The <b>type</b> parameter is of type DBTYPE, and must be set to one of
<a name="DB_BTREE">DB_BTREE</a>, <a name="DB_HASH">DB_HASH</a>, <a name="DB_QUEUE">DB_QUEUE</a>,
<a name="DB_RECNO">DB_RECNO</a>, or <a name="DB_UNKNOWN">DB_UNKNOWN</a>.  If <b>type</b> is
DB_UNKNOWN, the database must already exist and Db::open will
automatically determine its type.  The <a href="../api_cxx/db_get_type.html">Db::get_type</a> method may be used
to determine the underlying type of databases opened using DB_UNKNOWN.</ul>
<br>
<br><b>Environment Variables</b>
<p>If the database was opened within a database environment, the
environment variable <b>DB_HOME</b> may be used as the path of the
database environment home.</p>
<p>Db::open is affected by any database directory specified using
the <a href="../api_cxx/env_set_data_dir.html">DbEnv::set_data_dir</a> method, or by setting the "set_data_dir" string
in the environment's <a href="../ref/env/db_config.html#DB_CONFIG">DB_CONFIG</a> file.</p>
<br>
<b>TMPDIR</b><ul compact><li>If the <b>file</b> and <b>dbenv</b> parameters to Db::open are
NULL, the environment variable <b>TMPDIR</b> may be used as a
directory in which to create temporary backing files</ul>
<br>
<br><b>Errors</b>
<br>
<b>ENOENT</b><ul compact><li>The file or directory does not exist.</ul>
<br>
<p>The Db::open method
may fail and throw
<a href="../api_cxx/except_class.html">DbException</a>,
encapsulating one of the following non-zero errors, or return one of
the following non-zero errors:</p>
<br>
<b>DB_OLD_VERSION</b><ul compact><li>The database cannot be opened without being first upgraded.</ul>
<br>
<br>
<b>EEXIST</b><ul compact><li>DB_CREATE and DB_EXCL were specified and the database exists.</ul>
<br>
<br>
<b>EINVAL</b><ul compact><li>If an unknown database type, page size, hash function, pad byte, byte
order, or a flag value or parameter that is incompatible with the
specified database was specified;
the <a href="../api_cxx/env_open.html#DB_THREAD">DB_THREAD</a> flag was specified and fast mutexes are not
available for this architecture;
the <a href="../api_cxx/env_open.html#DB_THREAD">DB_THREAD</a> flag was specified to Db::open, but was
not specified to the <a href="../api_cxx/env_open.html">DbEnv::open</a> call for the environment in
which the <a href="../api_cxx/db_class.html">Db</a> handle was created;
a backing flat text file was specified with either the <a href="../api_cxx/env_open.html#DB_THREAD">DB_THREAD</a>
flag or the provided database environment supports transaction
processing; or if an
invalid flag value or parameter was specified.</ul>
<br>
<br>
<b>ENOENT</b><ul compact><li>A nonexistent <b>re_source</b> file was specified.</ul>
<br>
<br>
<b>DB_REP_HANDLE_DEAD</b><ul compact><li>The database handle has been invalidated because a replication election
unrolled a committed transaction.</ul>
<br>
<br>
<b>DB_REP_LOCKOUT</b><ul compact><li>The operation was blocked by client/master synchronization.</ul>
<br>
<p>If a transactional database environment operation was selected to
resolve a deadlock, the Db::open method will fail and
either return <a href="../ref/program/errorret.html#DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a> or
throw a <a href="../api_cxx/deadlock_class.html">DbDeadlockException</a> exception.</p>
<p>If a Berkeley DB Concurrent Data Store database environment configured for lock timeouts was unable
to grant a lock in the allowed time, the Db::open method will fail and
either return <a href="../ref/program/errorret.html#DB_LOCK_NOTGRANTED">DB_LOCK_NOTGRANTED</a> or
throw a <a href="../api_cxx/lockng_class.html">DbLockNotGrantedException</a> exception.</p>
<hr size=1 noshade>
<b>Description: Db::get_dbname</b>
<p>The Db::get_dbname method returns the current filename and database
name.</p>
<b>Parameters</b> <br>
 <b>filenamep</b><ul compact><li>The <b>filenamep</b> parameter references memory into which
a pointer to the current filename is copied.</ul>
 <b>dbnamep</b><ul compact><li>The <b>dbnamep</b> parameter references memory into which
a pointer to the current database name is copied.</ul>
<br>
<p>The Db::get_dbname method may be called at any time during the life of the
application.</p>
<p>The Db::get_dbname method
either returns a non-zero error value
or throws an exception that encapsulates a non-zero error value on
failure, and returns 0 on success.
</p>
<hr size=1 noshade>
<b>Description: <a href="../api_cxx/db_open.html">Db::get_multiple</a></b>
<p>The <a href="../api_cxx/db_open.html">Db::get_multiple</a> method returns non-zero if the <a href="../api_cxx/db_class.html">Db</a> handle
references a physical file supporting multiple databases.</p>
<p>In this case, the <a href="../api_cxx/db_class.html">Db</a> handle is a handle on a database whose key
values are the names of the databases stored in the physical file and
whose data values are opaque objects.  No keys or data values may be
modified or stored using the database handle.</p>
<p>The <a href="../api_cxx/db_open.html">Db::get_multiple</a> method may not be called before the Db::open method is called.</p>
<hr size=1 noshade>
<b>Description: Db::get_open_flags</b>
<p>The Db::get_open_flags method returns the current open method flags.</p>
<p>The Db::get_open_flags method may not be called before the Db::open method is called.</p>
<p>The Db::get_open_flags method
either returns a non-zero error value
or throws an exception that encapsulates a non-zero error value on
failure, and returns 0 on success.
</p>
<b>Parameters</b> <br>
 <b>flagsp</b><ul compact><li>The Db::get_open_flags method returns  the
current open method flags in <b>flagsp</b>.</ul>
<br>
<hr size=1 noshade>
<b>Description: Db::get_transactional</b>
<p>The Db::get_transactional method returns non-zero if the <a href="../api_cxx/db_class.html">Db</a>
handle has been opened in a transactional mode.</p>
<p>The Db::get_transactional method may be called at any time during the life of the
application.</p>
<hr size=1 noshade>
<br><b>Class</b>
<a href="../api_cxx/db_class.html">Db</a>
<br><b>See Also</b>
<a href="../api_cxx/db_list.html">Databases and Related Methods</a>
</tt>
<table width="100%"><tr><td><br></td><td align=right>
<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>
</td></tr></table>
<p><font size=1>Copyright (c) 1996,2008 Oracle.  All rights reserved.</font>
</body>
</html>