1<!--$Id: fop.so,v 1.8 2004/08/13 03:39:01 bostic Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 6<title>Berkeley DB Reference Guide: Release 4.1: DB->associate, DB->open, DB->remove, DB->rename</title> 7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<table width="100%"><tr valign=top> 12<td><b><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></b></td> 13<td align=right><a href="../upgrade.4.1/excl.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../upgrade.4.1/log_register.html"><img src="../../images/next.gif" alt="Next"></a> 14</td></tr></table> 15<p align=center><b>Release 4.1: DB->associate, DB->open, DB->remove, DB->rename</b></p> 16<p>Historic releases of Berkeley DB transaction-protected the <a href="../../api_c/db_open.html">DB->open</a>, 17<a href="../../api_c/db_remove.html">DB->remove</a> and <a href="../../api_c/db_rename.html">DB->rename</a> methods, but did it in an implicit 18way, that is, applications did not specify the <a href="../../api_c/txn_class.html">DB_TXN</a> handles 19associated with the operations. This approach had a number of problems, 20the most significant of which was there was no way to group operations 21that included database creation, removal or rename. For example, 22applications wanting to maintain a list of the databases in an 23environment in a well-known database had no way to update the well-known 24database and create a database within a single transaction, and so there 25was no way to guarantee the list of databases was correct for the 26environment after system or application failure. Another example might 27be the creation of both a primary database and a database intended to 28serve as a secondary index, where again there was no way to group the 29creation of both databases in a single atomic operation.</p> 30<p>In the 4.1 release of Berkeley DB, this is no longer the case. The 31<a href="../../api_c/db_open.html">DB->open</a> and <a href="../../api_c/db_associate.html">DB->associate</a> methods now take a <a href="../../api_c/txn_class.html">DB_TXN</a> 32handle returned by <a href="../../api_c/txn_begin.html">DB_ENV->txn_begin</a> as an optional argument. New 33<a href="../../api_c/env_dbremove.html">DB_ENV->dbremove</a> and <a href="../../api_c/env_dbrename.html">DB_ENV->dbrename</a> methods taking a 34<a href="../../api_c/txn_class.html">DB_TXN</a> handle as an optional argument have been added.</p> 35<p>To upgrade, applications must add a <a href="../../api_c/txn_class.html">DB_TXN</a> parameter in the 36appropriate location for the <a href="../../api_c/db_open.html">DB->open</a> method calls, and the 37<a href="../../api_c/db_associate.html">DB->associate</a> method calls (in both cases, the second argument for 38the C API, the first for the C++ or Java APIs).</p> 39<p>Applications wanting to transaction-protect their <a href="../../api_c/db_open.html">DB->open</a> and 40<a href="../../api_c/db_associate.html">DB->associate</a> method calls can add a NULL <a href="../../api_c/txn_class.html">DB_TXN</a> 41argument and specify the <a href="../../api_c/env_set_flags.html#DB_AUTO_COMMIT">DB_AUTO_COMMIT</a> flag to the two calls, 42which wraps the operation in an internal Berkeley DB transaction. 43Applications wanting to transaction-protect the remove and rename 44operations must rewrite their calls to the <a href="../../api_c/db_remove.html">DB->remove</a> and 45<a href="../../api_c/db_rename.html">DB->rename</a> methods to be, instead, calls to the new 46<a href="../../api_c/env_dbremove.html">DB_ENV->dbremove</a> and <a href="../../api_c/env_dbrename.html">DB_ENV->dbrename</a> methods. Applications not 47wanting to transaction-protect any of the operations can add a NULL 48argument to their <a href="../../api_c/db_open.html">DB->open</a> and <a href="../../api_c/db_associate.html">DB->associate</a> method calls and 49require no further changes.</p> 50<p>For example, an application currently opening and closing a database as 51follows:</p> 52<blockquote><pre>DB *dbp; 53DB_ENV *dbenv; 54int ret; 55<p> 56if ((ret = db_create(&dbp, dbenv, 0)) != 0) 57 goto err_handler; 58<p> 59if ((ret = dbp->open(dbp, "file", NULL, DB_BTREE, DB_CREATE, 0664)) != 0) { 60 (void)dbp->close(dbp); 61 goto err_handler; 62}</pre></blockquote> 63<p>could transaction-protect the <a href="../../api_c/db_open.html">DB->open</a> call as follows:</p> 64<blockquote><pre>DB *dbp; 65DB_ENV *dbenv; 66int ret; 67<p> 68if ((ret = db_create(&dbp, dbenv, 0)) != 0) 69 goto err_handler; 70<p> 71if ((ret = dbp->open(dbp, 72 NULL, "file", NULL, DB_BTREE, DB_CREATE | DB_AUTO_COMMIT, 0664)) != 0) { 73 (void)dbp->close(dbp); 74 goto err_handler; 75}</pre></blockquote> 76<p>An application currently removing a database as follows:</p> 77<blockquote><pre>DB *dbp; 78DB_ENV *dbenv; 79int ret; 80<p> 81if ((ret = db_create(&dbp, dbenv, 0)) != 0) 82 goto err_handler; 83<p> 84if ((ret = dbp->remove(dbp, "file", NULL, 0)) != 0) 85 goto err_handler;</pre></blockquote> 86<p>could transaction-protect the database removal as follows:</p> 87<blockquote><pre>DB *dbp; 88DB_ENV *dbenv; 89int ret; 90<p> 91if ((ret = 92 dbenv->dbremove(dbenv, NULL, "file", NULL, DB_AUTO_COMMIT)) != 0) 93 goto err_handler;</pre></blockquote> 94<p>An application currently renaming a database as follows:</p> 95<blockquote><pre>DB *dbp; 96DB_ENV *dbenv; 97int ret; 98<p> 99if ((ret = db_create(&dbp, dbenv, 0)) != 0) 100 goto err_handler; 101<p> 102if ((ret = dbp->rename(dbp, "file", NULL, "newname", 0)) != 0) 103 goto err_handler;</pre></blockquote> 104<p>could transaction-protect the database renaming as follows:</p> 105<blockquote><pre>DB *dbp; 106DB_ENV *dbenv; 107int ret; 108<p> 109if ((ret = dbenv->dbrename( 110 dbenv, NULL, "file", NULL, "newname", DB_AUTO_COMMIT)) != 0) 111 goto err_handler;</pre></blockquote> 112<p>These examples are the simplest possible translation, and will result in 113behavior matching that of previous releases. For further discussion on 114how to transaction-protect <a href="../../api_c/db_open.html">DB->open</a> method calls, see 115<a href="../../ref/transapp/data_open.html">Opening the databases</a>.</p> 116<p><a href="../../api_c/db_class.html">DB</a> handles that will later be used for transaction-protected 117operations must be opened within a transaction. Specifying a 118transaction handle to operations using handles not opened within a 119transaction will return an error. Similarly, not specifying a 120transaction handle to operations using handles that were opened within 121a transaction will also return an error.</p> 122<table width="100%"><tr><td><br></td><td align=right><a href="../upgrade.4.1/excl.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../upgrade.4.1/log_register.html"><img src="../../images/next.gif" alt="Next"></a> 123</td></tr></table> 124<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 125</body> 126</html> 127
