1<!--$Id: scope.so,v 10.12 2007/06/14 17:41:59 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: Berkeley DB handles</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<a name="2"><!--meow--></a><a name="3"><!--meow--></a> 12<table width="100%"><tr valign=top> 13<td><b><dl><dt>Berkeley DB Reference Guide:<dd>Programmer Notes</dl></b></td> 14<td align=right><a href="../program/mt.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../program/namespace.html"><img src="../../images/next.gif" alt="Next"></a> 15</td></tr></table> 16<p align=center><b>Berkeley DB handles</b></p> 17<p>The Berkeley DB library has a number of object handles. The following table 18lists those handles, their scope, and whether they are free-threaded 19(that is, whether multiple threads within a process can share them).</p> 20<br> 21<b><a href="../../api_c/env_class.html">DB_ENV</a></b><ul compact><li>The <a href="../../api_c/env_class.html">DB_ENV</a> handle, created by the <a href="../../api_c/env_class.html">db_env_create</a> method, refers 22to a Berkeley DB database environment -- a collection of Berkeley DB subsystems, 23log files and databases. <a href="../../api_c/env_class.html">DB_ENV</a> handles are free-threaded if 24the <a href="../../api_c/env_open.html#DB_THREAD">DB_THREAD</a> flag is specified to the <a href="../../api_c/env_open.html">DB_ENV->open</a> method when 25the environment is opened. The handle should not be closed while any 26other handle remains open that is using it as a reference (for example, 27<a href="../../api_c/db_class.html">DB</a> or <a href="../../api_c/txn_class.html">DB_TXN</a>). Once either the <a href="../../api_c/env_close.html">DB_ENV->close</a> or 28<a href="../../api_c/env_remove.html">DB_ENV->remove</a> methods are called, the handle may not be accessed again, 29regardless of the method's return.</ul> 30<b><a href="../../api_c/txn_class.html">DB_TXN</a></b><ul compact><li>The <a href="../../api_c/txn_class.html">DB_TXN</a> handle, created by the <a href="../../api_c/txn_begin.html">DB_ENV->txn_begin</a> method, refers to 31a single transaction. The handle is not free-threaded. Transactions 32may span threads, but only serially, that is, the application must 33serialize access to the <a href="../../api_c/txn_class.html">DB_TXN</a> handles. In the case of nested 34transactions, since all child transactions are part of the same parent 35transaction, they must observe the same constraints. That is, children 36may execute in different threads only if each child executes serially. 37<p>Once the <a href="../../api_c/txn_abort.html">DB_TXN->abort</a> or <a href="../../api_c/txn_commit.html">DB_TXN->commit</a> methods are called, the 38handle may not be accessed again, regardless of the method's return. 39In addition, parent transactions may not issue any Berkeley DB operations 40while they have active child transactions (child transactions that 41have not yet been committed or aborted) except for <a href="../../api_c/txn_begin.html">DB_ENV->txn_begin</a>, 42<a href="../../api_c/txn_abort.html">DB_TXN->abort</a> and <a href="../../api_c/txn_commit.html">DB_TXN->commit</a>.</p></ul> 43<b><a href="../../api_c/logc_class.html">DB_LOGC</a></b><ul compact><li>The <a href="../../api_c/logc_class.html">DB_LOGC</a> handle refers to a cursor into the log files. The 44handle is not free-threaded. Once the <a href="../../api_c/logc_close.html">DB_LOGC->close</a> method is called, 45the handle may not be accessed again, regardless of the method's 46return.</ul> 47<b><a href="../../api_c/mempfile_class.html">DB_MPOOLFILE</a></b><ul compact><li>The <a href="../../api_c/mempfile_class.html">DB_MPOOLFILE</a> handle refers to an open file in the shared 48memory buffer pool of the database environment. The handle is not 49free-threaded. Once the <a href="../../api_c/memp_fclose.html">DB_MPOOLFILE->close</a> method is called, the handle may 50not be accessed again, regardless of the method's return.</ul> 51<b><a href="../../api_c/db_class.html">DB</a></b><ul compact><li>The <a href="../../api_c/db_class.html">DB</a> handle, created by the <a href="../../api_c/db_class.html">db_create</a> method, refers to a 52single Berkeley DB database, which may or may not be part of a database 53environment. <a href="../../api_c/db_class.html">DB</a> handles are free-threaded if the 54<a href="../../api_c/env_open.html#DB_THREAD">DB_THREAD</a> flag is specified to the <a href="../../api_c/db_open.html">DB->open</a> method when the 55database is opened or if the database environment in which the database 56is opened is free-threaded. The handle should not be closed while any 57other handle that refers to the database is in use; for example, 58database handles should be left open while cursor handles into the 59database remain open, or transactions that include operations on the 60database have not yet been committed or aborted. Once the 61<a href="../../api_c/db_close.html">DB->close</a>, <a href="../../api_c/db_remove.html">DB->remove</a>, or <a href="../../api_c/db_rename.html">DB->rename</a> methods are 62called, the handle may not be accessed again, regardless of the method's 63return.</ul> 64<b><a href="../../api_c/dbc_class.html">DBC</a></b><ul compact><li>The <a href="../../api_c/dbc_class.html">DBC</a> handle refers to a cursor into a Berkeley DB database. The 65handle is not free-threaded. Cursors may span threads, but only 66serially, that is, the application must serialize access to the 67<a href="../../api_c/dbc_class.html">DBC</a> handles. If the cursor is to be used to perform operations 68on behalf of a transaction, the cursor must be opened and closed within 69the context of that single transaction. Once <a href="../../api_c/dbc_close.html">DBcursor->close</a> has been 70called, the handle may not be accessed again, regardless of the 71method's return.</ul> 72<br> 73<table width="100%"><tr><td><br></td><td align=right><a href="../program/mt.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../program/namespace.html"><img src="../../images/next.gif" alt="Next"></a> 74</td></tr></table> 75<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 76</body> 77</html> 78
