mirror of
https://github.com/berkeleydb/libdb.git
synced 2024-11-17 09:36:24 +00:00
169 lines
8.9 KiB
HTML
169 lines
8.9 KiB
HTML
|
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|||
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|||
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|||
|
|
<head>
|
|||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
|||
|
|
<title>DB->associate, DB->open, DB->remove, DB->rename</title>
|
|||
|
|
<link rel="stylesheet" href="gettingStarted.css" type="text/css" />
|
|||
|
|
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
|
|||
|
|
<link rel="start" href="index.html" title="Berkeley DB Upgrade Guide" />
|
|||
|
|
<link rel="up" href="upgrade_4_1_toc.html" title="Chapter 9. Upgrading Berkeley DB 4.0 applications to Berkeley DB 4.1" />
|
|||
|
|
<link rel="prev" href="upgrade_4_1_excl.html" title="DB_EXCL" />
|
|||
|
|
<link rel="next" href="upgrade_4_1_log_register.html" title="DB_ENV->log_register" />
|
|||
|
|
</head>
|
|||
|
|
<body>
|
|||
|
|
<div xmlns="" class="navheader">
|
|||
|
|
<div class="libver">
|
|||
|
|
<p>Library Version 11.2.5.2</p>
|
|||
|
|
</div>
|
|||
|
|
<table width="100%" summary="Navigation header">
|
|||
|
|
<tr>
|
|||
|
|
<th colspan="3" align="center">DB->associate, DB->open, DB->remove, DB->rename</th>
|
|||
|
|
</tr>
|
|||
|
|
<tr>
|
|||
|
|
<td width="20%" align="left"><a accesskey="p" href="upgrade_4_1_excl.html">Prev</a> </td>
|
|||
|
|
<th width="60%" align="center">Chapter 9. Upgrading Berkeley DB 4.0 applications to Berkeley DB 4.1</th>
|
|||
|
|
<td width="20%" align="right"> <a accesskey="n" href="upgrade_4_1_log_register.html">Next</a></td>
|
|||
|
|
</tr>
|
|||
|
|
</table>
|
|||
|
|
<hr />
|
|||
|
|
</div>
|
|||
|
|
<div class="sect1" lang="en" xml:lang="en">
|
|||
|
|
<div class="titlepage">
|
|||
|
|
<div>
|
|||
|
|
<div>
|
|||
|
|
<h2 class="title" style="clear: both"><a id="upgrade_4_1_fop"></a>DB->associate, DB->open, DB->remove, DB->rename</h2>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<p>Historic releases of Berkeley DB transaction-protected the <a href="../api_reference/C/dbopen.html" class="olink">DB->open()</a>,
|
|||
|
|
<a href="../api_reference/C/dbremove.html" class="olink">DB->remove()</a>, and <a href="../api_reference/C/dbrename.html" class="olink">DB->rename()</a> methods, but did it in an implicit
|
|||
|
|
way, that is, applications did not specify the <a href="../api_reference/C/txn.html" class="olink">TXN</a> handles
|
|||
|
|
associated with the operations. This approach had a number of problems,
|
|||
|
|
the most significant of which was there was no way to group operations
|
|||
|
|
that included database creation, removal or rename. For example,
|
|||
|
|
applications wanting to maintain a list of the databases in an
|
|||
|
|
environment in a well-known database had no way to update the well-known
|
|||
|
|
database and create a database within a single transaction, and so there
|
|||
|
|
was no way to guarantee the list of databases was correct for the
|
|||
|
|
environment after system or application failure. Another example might
|
|||
|
|
be the creation of both a primary database and a database intended to
|
|||
|
|
serve as a secondary index, where again there was no way to group the
|
|||
|
|
creation of both databases in a single atomic operation.</p>
|
|||
|
|
<p>In the 4.1 release of Berkeley DB, this is no longer the case. The
|
|||
|
|
<a href="../api_reference/C/dbopen.html" class="olink">DB->open()</a> and <a href="../api_reference/C/dbassociate.html" class="olink">DB->associate()</a> methods now take a <a href="../api_reference/C/txn.html" class="olink">TXN</a>
|
|||
|
|
handle returned by <a href="../api_reference/C/txnbegin.html" class="olink">DB_ENV->txn_begin()</a> as an optional argument. New
|
|||
|
|
<a href="../api_reference/C/envdbremove.html" class="olink">DB_ENV->dbremove()</a> and <a href="../api_reference/C/envdbrename.html" class="olink">DB_ENV->dbrename()</a> methods taking a
|
|||
|
|
<a href="../api_reference/C/txn.html" class="olink">TXN</a> handle as an optional argument have been added.</p>
|
|||
|
|
<p>To upgrade, applications must add a <a href="../api_reference/C/txn.html" class="olink">TXN</a> parameter in the
|
|||
|
|
appropriate location for the <a href="../api_reference/C/dbopen.html" class="olink">DB->open()</a> method calls, and the
|
|||
|
|
<a href="../api_reference/C/dbassociate.html" class="olink">DB->associate()</a> method calls (in both cases, the second argument for
|
|||
|
|
the C API, the first for the C++ or Java APIs).</p>
|
|||
|
|
<p>Applications wanting to transaction-protect their <a href="../api_reference/C/dbopen.html" class="olink">DB->open()</a> and
|
|||
|
|
<a href="../api_reference/C/dbassociate.html" class="olink">DB->associate()</a> method calls can add a NULL <a href="../api_reference/C/txn.html" class="olink">TXN</a>
|
|||
|
|
argument and specify the <a href="../api_reference/C/envset_flags.html#envset_flags_DB_AUTO_COMMIT" class="olink">DB_AUTO_COMMIT</a> flag to the two calls,
|
|||
|
|
which wraps the operation in an internal Berkeley DB transaction.
|
|||
|
|
Applications wanting to transaction-protect the remove and rename
|
|||
|
|
operations must rewrite their calls to the <a href="../api_reference/C/dbremove.html" class="olink">DB->remove()</a> and
|
|||
|
|
<a href="../api_reference/C/dbrename.html" class="olink">DB->rename()</a> methods to be, instead, calls to the new
|
|||
|
|
<a href="../api_reference/C/envdbremove.html" class="olink">DB_ENV->dbremove()</a> and <a href="../api_reference/C/envdbrename.html" class="olink">DB_ENV->dbrename()</a> methods. Applications not
|
|||
|
|
wanting to transaction-protect any of the operations can add a NULL
|
|||
|
|
argument to their <a href="../api_reference/C/dbopen.html" class="olink">DB->open()</a> and <a href="../api_reference/C/dbassociate.html" class="olink">DB->associate()</a> method calls and
|
|||
|
|
require no further changes.</p>
|
|||
|
|
<p>For example, an application currently opening and closing a database as
|
|||
|
|
follows:</p>
|
|||
|
|
<pre class="programlisting">DB *dbp;
|
|||
|
|
DB_ENV *dbenv;
|
|||
|
|
int ret;
|
|||
|
|
|
|||
|
|
if ((ret = db_create(&dbp, dbenv, 0)) != 0)
|
|||
|
|
goto err_handler;
|
|||
|
|
|
|||
|
|
if ((ret = dbp->open(dbp, "file", NULL, DB_BTREE,
|
|||
|
|
DB_CREATE, 0664)) != 0) {
|
|||
|
|
(void)dbp->close(dbp);
|
|||
|
|
goto err_handler;
|
|||
|
|
}</pre>
|
|||
|
|
<p>could transaction-protect the <a href="../api_reference/C/dbopen.html" class="olink">DB->open()</a> call as follows:</p>
|
|||
|
|
<pre class="programlisting">DB *dbp;
|
|||
|
|
DB_ENV *dbenv;
|
|||
|
|
int ret;
|
|||
|
|
|
|||
|
|
if ((ret = db_create(&dbp, dbenv, 0)) != 0)
|
|||
|
|
goto err_handler;
|
|||
|
|
|
|||
|
|
if ((ret = dbp->open(dbp,
|
|||
|
|
NULL, "file", NULL, DB_BTREE, DB_CREATE |
|
|||
|
|
DB_AUTO_COMMIT, 0664)) != 0) {
|
|||
|
|
(void)dbp->close(dbp);
|
|||
|
|
goto err_handler;
|
|||
|
|
}</pre>
|
|||
|
|
<p>An application currently removing a database as follows:</p>
|
|||
|
|
<pre class="programlisting">DB *dbp;
|
|||
|
|
DB_ENV *dbenv;
|
|||
|
|
int ret;
|
|||
|
|
|
|||
|
|
if ((ret = db_create(&dbp, dbenv, 0)) != 0)
|
|||
|
|
goto err_handler;
|
|||
|
|
|
|||
|
|
if ((ret = dbp->remove(dbp, "file", NULL, 0)) != 0)
|
|||
|
|
goto err_handler;</pre>
|
|||
|
|
<p>could transaction-protect the database removal as follows:</p>
|
|||
|
|
<pre class="programlisting">DB *dbp;
|
|||
|
|
DB_ENV *dbenv;
|
|||
|
|
int ret;
|
|||
|
|
|
|||
|
|
if ((ret =
|
|||
|
|
dbenv->dbremove(dbenv, NULL, "file", NULL, DB_AUTO_COMMIT)) != 0)
|
|||
|
|
goto err_handler;</pre>
|
|||
|
|
<p>An application currently renaming a database as follows:</p>
|
|||
|
|
<pre class="programlisting">DB *dbp;
|
|||
|
|
DB_ENV *dbenv;
|
|||
|
|
int ret;
|
|||
|
|
|
|||
|
|
if ((ret = db_create(&dbp, dbenv, 0)) != 0)
|
|||
|
|
goto err_handler;
|
|||
|
|
|
|||
|
|
if ((ret = dbp->rename(dbp, "file", NULL, "newname", 0)) != 0)
|
|||
|
|
goto err_handler;</pre>
|
|||
|
|
<p>could transaction-protect the database renaming as follows:</p>
|
|||
|
|
<pre class="programlisting">DB *dbp;
|
|||
|
|
DB_ENV *dbenv;
|
|||
|
|
int ret;
|
|||
|
|
|
|||
|
|
if ((ret = dbenv->dbrename(
|
|||
|
|
dbenv, NULL, "file", NULL, "newname", DB_AUTO_COMMIT)) != 0)
|
|||
|
|
goto err_handler;</pre>
|
|||
|
|
<p>These examples are the simplest possible translation, and will result in
|
|||
|
|
behavior matching that of previous releases. For further discussion on
|
|||
|
|
how to transaction-protect <a href="../api_reference/C/dbopen.html" class="olink">DB->open()</a> method calls, see
|
|||
|
|
<a href="../programmer_reference/transapp_data_open.html" class="olink">Opening the databases</a>.</p>
|
|||
|
|
<p><a href="../api_reference/C/db.html" class="olink">DB</a> handles that will later be used for transaction-protected
|
|||
|
|
operations must be opened within a transaction. Specifying a
|
|||
|
|
transaction handle to operations using handles not opened within a
|
|||
|
|
transaction will return an error. Similarly, not specifying a
|
|||
|
|
transaction handle to operations using handles that were opened within
|
|||
|
|
a transaction will also return an error.</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="navfooter">
|
|||
|
|
<hr />
|
|||
|
|
<table width="100%" summary="Navigation footer">
|
|||
|
|
<tr>
|
|||
|
|
<td width="40%" align="left"><a accesskey="p" href="upgrade_4_1_excl.html">Prev</a> </td>
|
|||
|
|
<td width="20%" align="center">
|
|||
|
|
<a accesskey="u" href="upgrade_4_1_toc.html">Up</a>
|
|||
|
|
</td>
|
|||
|
|
<td width="40%" align="right"> <a accesskey="n" href="upgrade_4_1_log_register.html">Next</a></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr>
|
|||
|
|
<td width="40%" align="left" valign="top">DB_EXCL </td>
|
|||
|
|
<td width="20%" align="center">
|
|||
|
|
<a accesskey="h" href="index.html">Home</a>
|
|||
|
|
</td>
|
|||
|
|
<td width="40%" align="right" valign="top"> DB_ENV->log_register</td>
|
|||
|
|
</tr>
|
|||
|
|
</table>
|
|||
|
|
</div>
|
|||
|
|
</body>
|
|||
|
|
</html>
|