268 lines
14 KiB
HTML
268 lines
14 KiB
HTML
<!--$Id: db_open.html 63573 2008-05-23 21:43:21Z trent.nelson $-->
|
|
<!--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_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></td>
|
|
</tr></table>
|
|
<hr size=1 noshade>
|
|
<tt>
|
|
<b><pre>
|
|
#include <db.h>
|
|
<p>
|
|
int
|
|
DB->open(DB *db, DB_TXN *txnid, const char *file,
|
|
const char *database, DBTYPE type, u_int32_t flags, int mode);
|
|
<p>
|
|
int
|
|
DB->get_dbname(DB *db, const char **filenamep, const char **dbnamep);
|
|
<p>
|
|
int
|
|
DB->get_multiple(DB *db);
|
|
<p>
|
|
int
|
|
DB->get_open_flags(DB *db, u_int32_t *flagsp);
|
|
<p>
|
|
int
|
|
DB->get_transactional(DB *db);
|
|
</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_c/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
|
|
returns a non-zero error value on failure
|
|
and 0 on success.
|
|
If DB->open fails, the <a href="../api_c/db_close.html">DB->close</a> method must be called to
|
|
discard the <a href="../api_c/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_c/env_set_mp_mmapsize.html">DB_ENV->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_c/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_c/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_c/txn_begin.html">DB_ENV->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_c/env_cdsgroup_begin.html">DB_ENV->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_c/db_class.html">DB</a> handle
|
|
requires the <a href="../api_c/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_c/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_c/env_set_data_dir.html">DB_ENV->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>
|
|
<p>The DB->open method
|
|
may fail and return one of the following non-zero errors:</p>
|
|
<br>
|
|
<b>DB_LOCK_DEADLOCK</b><ul compact><li>A transactional database environment operation was selected to resolve
|
|
a deadlock.</ul>
|
|
<b>DB_LOCK_NOTGRANTED</b><ul compact><li>A Berkeley DB Concurrent Data Store database environment configured for lock timeouts was unable
|
|
to grant a lock in the allowed time.</ul>
|
|
<br>
|
|
<br>
|
|
<b>ENOENT</b><ul compact><li>The file or directory does not exist.</ul>
|
|
<br>
|
|
<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_c/env_open.html#DB_THREAD">DB_THREAD</a> flag was specified and fast mutexes are not
|
|
available for this architecture;
|
|
the <a href="../api_c/env_open.html#DB_THREAD">DB_THREAD</a> flag was specified to DB->open, but was
|
|
not specified to the <a href="../api_c/env_open.html">DB_ENV->open</a> call for the environment in
|
|
which the <a href="../api_c/db_class.html">DB</a> handle was created;
|
|
a backing flat text file was specified with either the <a href="../api_c/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>
|
|
<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
|
|
returns a non-zero error value on failure
|
|
and 0 on success.
|
|
</p>
|
|
<hr size=1 noshade>
|
|
<b>Description: <a href="../api_c/db_open.html">DB->get_multiple</a></b>
|
|
<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
|
|
references a physical file supporting multiple databases.</p>
|
|
<p>In this case, the <a href="../api_c/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_c/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
|
|
returns a non-zero error value on failure
|
|
and 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_c/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_c/db_class.html">DB</a>
|
|
<br><b>See Also</b>
|
|
<a href="../api_c/db_list.html">Databases and Related Methods</a>
|
|
</tt>
|
|
<table width="100%"><tr><td><br></td><td align=right>
|
|
<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>
|
|
</td></tr></table>
|
|
<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font>
|
|
</body>
|
|
</html>
|