Sophie

Sophie

distrib > Mandriva > 2007.0 > x86_64 > media > main-release > by-pkgid > a4c98df40e78f6c892308fd6841f950a > files > 220

lib64db4.2-devel-4.2.52-11mdv2007.0.x86_64.rpm

<!--$Id: db_open.so,v 10.101 2003/12/02 13:38:39 bostic Exp $-->
<!--Copyright 1997-2003 by Sleepycat Software, Inc.-->
<!--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,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++">
</head>
<body bgcolor=white>
<a name="2"><!--meow--></a>
<table width="100%"><tr valign=top>
<td>
<h3>Db::open</h3>
</td>
<td align=right>
<a href="../../db42-devel-4.2.52/api_cxx/api_index.html"><img src="../../db42-4.2.52/images/api.gif" alt="API"></a>
<a href="../../db42-devel-4.2.52/ref/toc.html"><img src="../../db42-4.2.52/images/ref.gif" alt="Ref"></a>
</td></tr></table>
<hr size=1 noshade>
<tt>
<h3><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_open_flags(u_int32_t *flagsp);
<p>
int
Db::get_transactional()
</pre></h3>
<hr size=1 noshade>
<h3>Description: Db::open</h3>
<a name="3"><!--meow--></a>
<a name="4"><!--meow--></a>
<a name="5"><!--meow--></a>
<a name="6"><!--meow--></a>
<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="../../db42-devel-4.2.52/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="../../db42-devel-4.2.52/api_cxx/db_close.html">Db::close</a> method should be called to
discard the <a href="../../db42-devel-4.2.52/api_cxx/db_class.html">Db</a> handle.
</p>
<h3>Parameters</h3>
<p><dl compact>
<p><dt><b>database</b><dd>
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="../../db42-devel-4.2.52/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 both the <b>file</b> and <b>database</b> parameters
to NULL.  Note that in-memory databases can only ever be shared by
sharing the single database handle that created them, in circumstances
where doing so is safe.</p>
<p><dt><b>file</b><dd>
The <b>file</b> parameter is used as the name of an underlying file that
will be used to back the database.
<p>In-memory databases never intended to be preserved on disk may be
created by setting both the <b>file</b> and <b>database</b> parameters
to NULL.  Note that in-memory databases can only ever be shared by
sharing the single database handle that created them, in circumstances
where doing so is safe.</p>
<p><dt><b>flags</b><dd>
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:
<p><dl compact>
<p><dt><a name="DB_AUTO_COMMIT">DB_AUTO_COMMIT</a><dd>Enclose the Db::open call within a transaction.  If the call
succeeds, the open operation will be recoverable.  If the call fails,
no database will have been created.
<p><dt><a name="DB_CREATE">DB_CREATE</a><dd>Create the database.  If the database does not already exist and the
DB_CREATE flag is not specified, the Db::open will
fail.
<p><dt><a name="DB_DIRTY_READ">DB_DIRTY_READ</a><dd>Support dirty reads; that is, 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="../../db42-devel-4.2.52/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.
<p><dt><a name="DB_EXCL">DB_EXCL</a><dd>Return an error if the database already exists.  The DB_EXCL
flag is only meaningful when specified with the DB_CREATE
flag.
<p><dt><a name="DB_NOMMAP">DB_NOMMAP</a><dd>Do not map this database into process memory (see the
<a href="../../db42-devel-4.2.52/api_cxx/env_set_mp_mmapsize.html">DbEnv::set_mp_mmapsize</a> method for further information).
<p><dt><a name="DB_RDONLY">DB_RDONLY</a><dd>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.
<p><dt><a name="DB_THREAD">DB_THREAD</a><dd>Cause the <a href="../../db42-devel-4.2.52/api_cxx/db_class.html">Db</a> handle returned by Db::open to be
<i>free-threaded</i>; that is, usable by multiple threads within a
single address space.
<p><dt><a name="DB_TRUNCATE">DB_TRUNCATE</a><dd>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>
</dl>
<p><dt><b>mode</b><dd>
On UNIX systems or in IEEE/ANSI Std 1003.1 (POSIX) environments, all 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)).  If <b>mode</b> is 0, the database open will use a default
mode of readable and writable by both owner and group.  On Windows
systems, the mode parameter is ignored. The group ownership of created
files is based on the system and directory defaults, and is not further
specified by Berkeley DB.
<p><dt><b>txnid</b><dd>
If the operation is to be transaction-protected,
(other than by specifying the DB_AUTO_COMMIT flag),
the <b>txnid</b> parameter is a transaction handle returned from
<a href="../../db42-devel-4.2.52/api_cxx/txn_begin.html">DbEnv::txn_begin</a>; otherwise, NULL.  Note that transactionally protected operations on a <a href="../../db42-devel-4.2.52/api_cxx/db_class.html">Db</a> handle
requires the <a href="../../db42-devel-4.2.52/api_cxx/db_class.html">Db</a> handle itself be transactionally protected
during its open.
<p><dt><b>type</b><dd>
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="../../db42-devel-4.2.52/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.
</dl>
<h3>Environment Variables</h3>
<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="../../db42-devel-4.2.52/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 <b>DB_CONFIG</b> file.</p>
<p><dl compact>
<p><dt>TMPDIR<dd>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
</dl>
<h3>Errors</h3>
<p><dl compact>
<p><dt>ENOENT<dd>The file or directory does not exist.
</dl>
<p>The Db::open method
may fail and throw
<a href="../../db42-devel-4.2.52/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>
<p><dl compact>
<p><dt>DB_OLD_VERSION<dd>The database cannot be opened without being first upgraded.
</dl>
<p><dl compact>
<p><dt>EEXIST<dd>DB_CREATE and DB_EXCL were specified and the database exists.
</dl>
<p><dl compact>
<p><dt>EINVAL<dd>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="../../db42-devel-4.2.52/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="../../db42-devel-4.2.52/api_cxx/env_open.html#DB_THREAD">DB_THREAD</a> flag was specified to Db::open, but was
not specified to the <a href="../../db42-devel-4.2.52/api_cxx/env_open.html">DbEnv::open</a> call for the environment in
which the <a href="../../db42-devel-4.2.52/api_cxx/db_class.html">Db</a> handle was created;
a backing flat text file was specified with either the <a href="../../db42-devel-4.2.52/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.
</dl>
<p><dl compact>
<p><dt>ENOENT<dd>A nonexistent <b>re_source</b> file was specified.
</dl>
<p><dl compact>
<p><dt>DB_REP_HANDLE_DEAD<dd>The database handle has been invalidated because a replication election
unrolled a committed transaction.
</dl>
<p>If a transactional database environment operation was selected to
resolve a deadlock, the Db::open method will fail and
either return <a href="../../db42-devel-4.2.52/ref/program/errorret.html#DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a> or
throw a <a href="../../db42-devel-4.2.52/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="../../db42-devel-4.2.52/ref/program/errorret.html#DB_LOCK_NOTGRANTED">DB_LOCK_NOTGRANTED</a> or
throw a <a href="../../db42-devel-4.2.52/api_cxx/lockng_class.html">DbLockNotGrantedException</a> exception.</p>
<hr size=1 noshade>
<h3>Description: Db::get_database</h3>
<p>The Db::get_database method returns the current filename and database
name.</p>
<h3>Parameters</h3>
<p><dl compact>
<p><dt><b>filenamep</b><dd>
The <b>filenamep</b> parameter references memory into which
a pointer to the current filename is copied.
<p><dt><b>dbnamep</b><dd>
The <b>dbnamep</b> parameter references memory into which
a pointer to the current database name is copied.
</dl>
<p>The Db::get_database method may be called at any time during the life of the
application.</p>
<p>The Db::get_database 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>
<h3>Description: Db::get_open_flags</h3>
<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 has been
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>
<h3>Parameters</h3>
<p><dl compact>
<p><dt><b>flagsp</b><dd>
The Db::get_open_flags method returns  the
current open method flags in <b>flagsp</b>.
</dl>
<hr size=1 noshade>
<h3>Description: Db::get_transactional</h3>
<p>The Db::get_transactional method returns non-zero if the <a href="../../db42-devel-4.2.52/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>
<h3>Class</h3>
<a href="../../db42-devel-4.2.52/api_cxx/db_class.html">Db</a>
<h3>See Also</h3>
<a href="../../db42-devel-4.2.52/api_cxx/db_list.html">Databases and Related Methods</a>
</tt>
<table width="100%"><tr><td><br></td><td align=right>
<a href="../../db42-devel-4.2.52/api_cxx/api_index.html"><img src="../../db42-4.2.52/images/api.gif" alt="API"></a><a href="../../db42-devel-4.2.52/ref/toc.html"><img src="../../db42-4.2.52/images/ref.gif" alt="Ref"></a>
</td></tr></table>
<p><font size=1><a href="../../db42-devel-4.2.52/sleepycat/legal.html">Copyright (c) 1996-2003</a> <a href="http://www.sleepycat.com">Sleepycat Software, Inc.</a> - All rights reserved.</font>
</body>
</html>

Perl :: Catalyst :: PostgreSQL :: RPM Valid HTML 4.01 Transitional