1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>Berkeley DB configuration</title> 7 <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" /> 10 <link rel="up" href="stl.html" title="Chapter��7.��Standard Template Library API" /> 11 <link rel="prev" href="stl_examples.html" title="Dbstl examples" /> 12 <link rel="next" href="stl_db_advanced_usage.html" title="Using advanced Berkeley DB features with dbstl" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Berkeley DB configuration</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="stl_examples.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��7.��Standard Template Library API</th> 23 <td width="20%" align="right">��<a accesskey="n" href="stl_db_advanced_usage.html">Next</a></td> 24 </tr> 25 </table> 26 <hr /> 27 </div> 28 <div class="sect1" lang="en" xml:lang="en"> 29 <div class="titlepage"> 30 <div> 31 <div> 32 <h2 class="title" style="clear: both"><a id="stl_db_usage"></a>Berkeley DB configuration</h2> 33 </div> 34 </div> 35 </div> 36 <div class="toc"> 37 <dl> 38 <dt> 39 <span class="sect2"> 40 <a href="stl_db_usage.html#id1599352">Registering database and environment handles</a> 41 </span> 42 </dt> 43 <dt> 44 <span class="sect2"> 45 <a href="stl_db_usage.html#id1599734">Truncate requirements</a> 46 </span> 47 </dt> 48 <dt> 49 <span class="sect2"> 50 <a href="stl_db_usage.html#id1599105">Auto commit support</a> 51 </span> 52 </dt> 53 <dt> 54 <span class="sect2"> 55 <a href="stl_db_usage.html#id1599533">Database and environment identity checks</a> 56 </span> 57 </dt> 58 <dt> 59 <span class="sect2"> 60 <a href="stl_db_usage.html#id1599614">Products, constructors and configurations</a> 61 </span> 62 </dt> 63 </dl> 64 </div> 65 <p> 66 While dbstl behaves like the C++ STL APIs in most situations, there 67 are some Berkeley DB configuration activities that you can and 68 should perform using dbstl. These activities are described in the 69 following sections. 70 </p> 71 <div class="sect2" lang="en" xml:lang="en"> 72 <div class="titlepage"> 73 <div> 74 <div> 75 <h3 class="title"><a id="id1599352"></a>Registering database and environment handles</h3> 76 </div> 77 </div> 78 </div> 79 <p> 80 Remember the following things as you use Berkeley DB Database 81 and Environment handles with dbstl: 82 </p> 83 <div class="itemizedlist"> 84 <ul type="disc"> 85 <li> 86 <p> 87 If you share environment or database handles among multiple 88 threads, remember to specify the <a href="../api_reference/C/dbopen.html#open_DB_THREAD" class="olink">DB_THREAD</a> flag in the open call to 89 the handle. 90 </p> 91 </li> 92 <li> 93 <p> 94 If you create or open environment and/or database handles without 95 using the dbstl helper functions, 96 <code class="function">dbstl::open_db()</code> or 97 <code class="function">dbstl::open_env()</code>, remember that your 98 environment and database handles should be: 99 </p> 100 <div class="orderedlist"> 101 <ol type="1"> 102 <li> 103 <p> 104 Allocated in the heap via "new" operator. 105 </p> 106 </li> 107 <li> 108 <p> 109 Created using the <a href="../api_reference/CXX/envcreate.html#env_DB_CXX_NO_EXCEPTIONS" class="olink">DB_CXX_NO_EXCEPTIONS</a> flag. 110 </p> 111 </li> 112 <li> 113 <p> 114 In each thread sharing the handles, the handles are registered using 115 either <code class="function">dbstl::register_db()</code> or 116 <code class="function">dbstl::register_dbenv()</code>. 117 </p> 118 </li> 119 </ol> 120 </div> 121 </li> 122 <li> 123 <p> 124 If you opened the database or environment handle using the 125 <code class="function">open_db()</code> or <code class="function">open_env()</code> 126 functions, the thread opening the handles should not call 127 <code class="function">register_db()</code> or <code class="function">register_env()</code> 128 again. This is because they have already been registered by the 129 <code class="function">open_db()</code> or <code class="function">open_env()</code> 130 functions. However, other threads sharing these handles still must register 131 them locally. 132 </p> 133 </li> 134 </ul> 135 </div> 136 </div> 137 <div class="sect2" lang="en" xml:lang="en"> 138 <div class="titlepage"> 139 <div> 140 <div> 141 <h3 class="title"><a id="id1599734"></a>Truncate requirements</h3> 142 </div> 143 </div> 144 </div> 145 <p> 146 Some Berkeley DB operations require there to be no open cursors on the 147 database handle at the time the operation occurs. Dbstl is aware of 148 these requirements, and will attempt to close the cursors opened in the 149 current thread when it performs these operations. However, the scope of 150 dbstl's activities in this regard are limited to the current thread; it 151 makes no attempt to close cursors opened in other threads. So you 152 are required to ensure there are no open cursors on database handles 153 shared across threads when operations are performed that require all 154 cursors on that handle to be closed. 155</p> 156 <p> 157 158 There are only a a few operations which require all open cursors to be closed. 159 This include all container <code class="methodname">clear()</code> and 160 <code class="methodname">swap()</code> functions, and all versions of 161 <code class="methodname">db_vection<>::assign()</code> functions. These 162 functions require all cursors to be closed for the database because by default 163 they remove all key/data pairs from the database by truncating it. 164</p> 165 <p> 166 When a function removes all key/data pairs from a database, there are 167 two ways it can perform this activity: 168</p> 169 <div class="itemizedlist"> 170 <ul type="disc"> 171 <li> 172 <p> 173 The default method is to truncate the database, which is an 174 operation that requires all cursors to be closed. As mentioned 175 above, it is your responsibility to close cursors opened in other 176 threads before performing this operation. Otherwise, the operation 177 will fail. 178 </p> 179 </li> 180 <li> 181 <p> 182 Alternatively, you can specify that the database not be truncated. 183 Instead, you can cause dbstl to delete all key/data pairs 184 individually, one after another. In this situation, 185 open cursors in the database will not cause the delete operations to 186 fail. However, due to lock contention, the delete operations might not 187 complete until all cursors are closed, which is when all their read locks 188 are released. 189 </p> 190 </li> 191 </ul> 192 </div> 193 </div> 194 <div class="sect2" lang="en" xml:lang="en"> 195 <div class="titlepage"> 196 <div> 197 <div> 198 <h3 class="title"><a id="id1599105"></a>Auto commit support</h3> 199 </div> 200 </div> 201 </div> 202 <p> 203 204 Dbstl supports auto commit for some of its container's operations. When a dbstl 205 container is created using a <code class="classname">Db</code> or <code class="classname">DbEnv</code> 206 object, if that object was opened using the <a href="../api_reference/C/envset_flags.html#envset_flags_DB_AUTO_COMMIT" class="olink">DB_AUTO_COMMIT</a> flag, then 207 every operation subsequently performed on that object will be 208 automatically enclosed in a unique transaction (unless the operation is already in an 209 external transaction). This 210 is identical to how the Berkeley DB C, C++ and Java APIs behave. 211</p> 212 <p> 213 Note that only a subset of a container's operations support auto 214 commit. This is because those operations that accept or return an 215 iterator have to exist in an external transactional context and so 216 cannot support auto commit. 217</p> 218 <p> 219 The dbstl API documentation identifies when a method supports auto 220 commit transactions. 221</p> 222 </div> 223 <div class="sect2" lang="en" xml:lang="en"> 224 <div class="titlepage"> 225 <div> 226 <div> 227 <h3 class="title"><a id="id1599533"></a>Database and environment identity checks</h3> 228 </div> 229 </div> 230 </div> 231 <p> 232 When a container member function involves another container (for example, 233 <code class="methodname">db_vector::swap(self& v2)</code>), the two 234 containers involved in the operation must not use the same database. 235 Further, if the function is in an external or internal transaction context, 236 then both containers must belong 237 to the same transactional database environment; Otherwise, the two containers 238 can belong to the same database environment, or two different ones. 239</p> 240 <p> 241 For example, if <code class="methodname">db_vector::swap(self& v2)</code> 242 is an auto commit method or it is in an external transaction context, 243 then <code class="literal">v2</code> must be in the same transactional database 244 environment as this container, because a transaction is started 245 internally that must be used by both <code class="literal">v2</code> and this 246 container. If this container and the <code class="literal">v2</code> container 247 have different database environments, and either of them are using transactions, 248 an exception is thrown. This condition is checked in every such member 249 function. 250</p> 251 <p> 252 However, if the function is not in a transactional context, 253 then the databases used by these 254 containers can be in different environments because in this situation 255 dbstl makes no attempt to wrap container operations in a common transaction 256 context. 257</p> 258 </div> 259 <div class="sect2" lang="en" xml:lang="en"> 260 <div class="titlepage"> 261 <div> 262 <div> 263 <h3 class="title"><a id="id1599614"></a>Products, constructors and configurations</h3> 264 </div> 265 </div> 266 </div> 267 <p> 268 You can use dbstl with all Berkeley DB products (DS, CDS, TDS, and HA). 269 Because dbstl is a Berkeley DB interface, all necessary configurations 270 for these products are performed using Berkeley DB's standard 271 create/open/set APIs. 272</p> 273 <p> 274 As a result, the dbstl container constructors differ from those of C++ 275 STL because in dbstl no configuration is supported using the container 276 constructors. On the other hand, dbstl container constructors accept 277 already opened and configured environment and database handles. They 278 also provide functions to retrieve some handle configuration, such as 279 key comparison and hash functions, as required by the C++ STL 280 specifications. 281</p> 282 <p> 283 The constructors verify that the handles passed to them are well 284 configured. This means they ensure that no banned settings are used, as 285 well as ensuring that all required setting are performed. If the 286 handles are not well configured, an 287 <code class="classname">InvalidArgumentException</code> is thrown. 288</p> 289 <p> 290 If a container constructor is not passed a database or environment 291 handle, an internal anonymous database is created for you by dbstl. This anonymous 292 database does not provide data persistence. 293</p> 294 </div> 295 </div> 296 <div class="navfooter"> 297 <hr /> 298 <table width="100%" summary="Navigation footer"> 299 <tr> 300 <td width="40%" align="left"><a accesskey="p" href="stl_examples.html">Prev</a>��</td> 301 <td width="20%" align="center"> 302 <a accesskey="u" href="stl.html">Up</a> 303 </td> 304 <td width="40%" align="right">��<a accesskey="n" href="stl_db_advanced_usage.html">Next</a></td> 305 </tr> 306 <tr> 307 <td width="40%" align="left" valign="top">Dbstl examples��</td> 308 <td width="20%" align="center"> 309 <a accesskey="h" href="index.html">Home</a> 310 </td> 311 <td width="40%" align="right" valign="top">��Using advanced Berkeley DB features with dbstl</td> 312 </tr> 313 </table> 314 </div> 315 </body> 316</html> 317