mirror of
https://github.com/berkeleydb/libdb.git
synced 2024-11-17 09:36:24 +00:00
168 lines
8.9 KiB
HTML
168 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>
|