1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
|
<?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 12.1.6.1</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>
|
