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>DbEnv::txn_begin()</title> 7 <link rel="stylesheet" href="apiReference.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 C++ API Reference" /> 10 <link rel="up" href="txn.html" title="Chapter 13. The DbTxn Handle" /> 11 <link rel="prev" href="txnabort.html" title="DbTxn::abort()" /> 12 <link rel="next" href="txncheckpoint.html" title="DbEnv::txn_checkpoint()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">DbEnv::txn_begin()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="txnabort.html">Prev</a> </td> 22 <th width="60%" align="center">Chapter 13. 23 The DbTxn Handle 24 </th> 25 <td width="20%" align="right"> <a accesskey="n" href="txncheckpoint.html">Next</a></td> 26 </tr> 27 </table> 28 <hr /> 29 </div> 30 <div class="sect1" lang="en" xml:lang="en"> 31 <div class="titlepage"> 32 <div> 33 <div> 34 <h2 class="title" style="clear: both"><a id="txnbegin"></a>DbEnv::txn_begin()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db_cxx.h> 39 40int 41DbEnv::txn_begin(DbTxn *parent, DbTxn **tid, u_int32_t flags);</pre> 42 <p> 43 The <code class="methodname">DbEnv::txn_begin()</code> method creates a new transaction in the 44 environment and copies a pointer to a <a class="link" href="txn.html" title="Chapter 13. The DbTxn Handle">DbTxn</a> that 45 uniquely identifies it into the memory to which <span class="bold"><strong>tid</strong></span> 46 refers. Calling the <a class="xref" href="txnabort.html" title="DbTxn::abort()">DbTxn::abort()</a>, 47 <a class="xref" href="txncommit.html" title="DbTxn::commit()">DbTxn::commit()</a> or 48 <a class="xref" href="txndiscard.html" title="DbTxn::discard()">DbTxn::discard()</a> methods will 49 discard the returned handle. 50 </p> 51 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> 52 <h3 class="title">Note</h3> 53 <p> 54 Transactions may only span threads if they do so serially; that is, each transaction 55 must be active in only a single thread of control at a time. This restriction holds 56 for parents of nested transactions as well; no two children may be concurrently active 57 in more than one thread of control at any one time. 58 </p> 59 </div> 60 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> 61 <h3 class="title">Note</h3> 62 <p> 63 Cursors may not span transactions; that is, each cursor must be opened and closed within 64 a single transaction. 65 </p> 66 </div> 67 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> 68 <h3 class="title">Note</h3> 69 <p> 70 A parent transaction may not issue any Berkeley DB operations — except for 71 <code class="methodname">DbEnv::txn_begin()</code>, 72 <a class="xref" href="txnabort.html" title="DbTxn::abort()">DbTxn::abort()</a> 73 and <a class="xref" href="txncommit.html" title="DbTxn::commit()">DbTxn::commit()</a> — while it 74 has active child transactions (child transactions that have not yet 75 been committed or aborted). 76 </p> 77 </div> 78 <p> 79 The <code class="methodname">DbEnv::txn_begin()</code> <span> 80 81 <span> 82 method either returns a non-zero error value or throws an 83 exception that encapsulates a non-zero error value on 84 failure, and returns 0 on success. 85 </span> 86 </span> 87 </p> 88 <div class="sect2" lang="en" xml:lang="en"> 89 <div class="titlepage"> 90 <div> 91 <div> 92 <h3 class="title"><a id="id1713416"></a>Parameters</h3> 93 </div> 94 </div> 95 </div> 96 <div class="sect3" lang="en" xml:lang="en"> 97 <div class="titlepage"> 98 <div> 99 <div> 100 <h4 class="title"><a id="id1713420"></a>flags</h4> 101 </div> 102 </div> 103 </div> 104 <p> 105 The <span class="bold"><strong>flags</strong></span> parameter must be set to 0 106 or by bitwise inclusively <span class="bold"><strong>OR</strong></span>'ing 107 together one or more of the following values: 108 </p> 109 <div class="itemizedlist"> 110 <ul type="disc"> 111 <li> 112 <p> 113 <code class="literal">DB_READ_COMMITTED</code> 114 </p> 115 <p> 116 This transaction will have degree 2 isolation. This provides for 117 cursor stability but not repeatable reads. Data items which have been 118 previously read by this transaction may be deleted or modified by 119 other transactions before this transaction completes. 120 </p> 121 </li> 122 <li> 123 <p> 124 <code class="literal">DB_READ_UNCOMMITTED</code> 125 </p> 126 <p> 127 This transaction will have degree 1 isolation. Read operations 128 performed by the transaction may read modified but not yet committed 129 data. Silently ignored if the <code class="literal">DB_READ_UNCOMMITTED</code> 130 flag was not specified when the underlying database was opened. 131 </p> 132 </li> 133 <li> 134 <p> 135 <code class="literal">DB_TXN_NOSYNC</code> 136 </p> 137 <p> 138 Do not synchronously flush the log when this transaction commits or 139 prepares. This means the transaction will exhibit the ACI (atomicity, 140 consistency, and isolation) properties, but not D (durability); that 141 is, database integrity will be maintained but it is possible that this 142 transaction may be undone during recovery. 143 </p> 144 <p> 145 This behavior may be set for a Berkeley DB environment using the 146 <a class="xref" href="envset_flags.html" title="DbEnv::set_flags()">DbEnv::set_flags()</a> 147 method. Any value specified to this method overrides that setting. 148 </p> 149 </li> 150 <li> 151 <p><a id="txnbegin_DB_TXN_NOWAIT"></a> 152 <code class="literal">DB_TXN_NOWAIT</code> 153 </p> 154 <p> 155 If a lock is unavailable for any Berkeley DB operation performed in 156 the context of this transaction, cause the operation to return <a href="../../programmer_reference/program_errorret.html#program_errorret.DB_LOCK_DEADLOCK" class="olink">DB_LOCK_DEADLOCK</a> 157 (or <a href="../../programmer_reference/program_errorret.html#program_errorret.DB_LOCK_NOTGRANTED" class="olink">DB_LOCK_NOTGRANTED</a> 158 if the database environment has been configured using the 159 <a class="link" href="envset_flags.html#envset_flags_DB_TIME_NOTGRANTED">DB_TIME_NOTGRANTED</a> 160 flag). 161 </p> 162 <p> 163 This behavior may be set for a Berkeley DB environment using the 164 <a class="xref" href="envset_flags.html" title="DbEnv::set_flags()">DbEnv::set_flags()</a> 165 method. Any value specified to this method overrides that setting. 166 </p> 167 </li> 168 <li> 169 <p><a id="txnbegin_DB_TXN_SNAPSHOT"></a> 170 <code class="literal">DB_TXN_SNAPSHOT</code> 171 </p> 172 <p> 173 This transaction will execute with 174 <a href="../../programmer_reference/transapp_read.html" class="olink">snapshot isolation</a>. For 175 databases with the 176 <a class="link" href="dbopen.html#dbopen_DB_MULTIVERSION">DB_MULTIVERSION</a> 177 flag set, data values will be read as they are when the transaction 178 begins, without taking read locks. Silently ignored for operations on 179 databases with 180 <a class="link" href="dbopen.html#dbopen_DB_MULTIVERSION">DB_MULTIVERSION</a> 181 not set on the underlying database (read locks are acquired). 182 </p> 183 <p> 184 The error <code class="literal">DB_LOCK_DEADLOCK</code> will be 185 returned from update operations if a snapshot transaction attempts to 186 update data which was modified after the snapshot transaction read it. 187 </p> 188 </li> 189 <li> 190 <p> 191 <code class="literal">DB_TXN_SYNC</code> 192 </p> 193 <p> 194 Synchronously flush the log when this transaction commits or prepares. 195 This means the transaction will exhibit all of the ACID (atomicity, 196 consistency, isolation, and durability) properties. 197 </p> 198 <p> 199 This behavior is the default for Berkeley DB environments unless the 200 <code class="literal">DB_TXN_NOSYNC</code> flag was specified to the 201 <a class="xref" href="envset_flags.html" title="DbEnv::set_flags()">DbEnv::set_flags()</a> method. 202 Any value specified to this method overrides that setting. 203 </p> 204 </li> 205 <li> 206 <p> 207 <code class="literal">DB_TXN_WAIT</code> 208 </p> 209 <p> 210 If a lock is unavailable for any Berkeley DB operation performed in 211 the context of this transaction, wait for the lock. 212 </p> 213 <p> 214 This behavior is the default for Berkeley DB environments unless the 215 <code class="literal">DB_TXN_NOWAIT</code> flag was specified to the 216 <a class="xref" href="envset_flags.html" title="DbEnv::set_flags()">DbEnv::set_flags()</a> method. 217 Any value specified to this method overrides that setting. 218 </p> 219 </li> 220 <li> 221 <p> 222 <code class="literal">DB_TXN_WRITE_NOSYNC</code> 223 </p> 224 <p> 225 Write, but do not synchronously flush, the log when this transaction 226 commits. This means the transaction will exhibit the ACI (atomicity, 227 consistency, and isolation) properties, but not D (durability); that 228 is, database integrity will be maintained, but if the system fails, it 229 is possible some number of the most recently committed transactions 230 may be undone during recovery. The number of transactions at risk is 231 governed by how often the system flushes dirty buffers to disk and how 232 often the log is flushed or checkpointed. 233 </p> 234 <p> 235 This behavior may be set for a Berkeley DB environment using the 236 <a class="xref" href="envset_flags.html" title="DbEnv::set_flags()">DbEnv::set_flags()</a> 237 method. Any value specified to this method overrides that setting. 238 </p> 239 </li> 240 </ul> 241 </div> 242 </div> 243 <div class="sect3" lang="en" xml:lang="en"> 244 <div class="titlepage"> 245 <div> 246 <div> 247 <h4 class="title"><a id="id1713997"></a>parent</h4> 248 </div> 249 </div> 250 </div> 251 <p> 252 If the <span class="bold"><strong>parent</strong></span> parameter is non-NULL, 253 the new transaction will be a nested transaction, with the transaction 254 indicated by <span class="bold"><strong>parent</strong></span> as its parent. 255 Transactions may be nested to any level. In the presence of 256 distributed transactions and two-phase commit, only the parental 257 transaction, that is a transaction without a <span class="bold"><strong>parent</strong></span> specified, should be passed as an 258 parameter to <a class="xref" href="txnprepare.html" title="DbTxn::prepare()">DbTxn::prepare()</a>. 259 </p> 260 </div> 261 </div> 262 <div class="sect2" lang="en" xml:lang="en"> 263 <div class="titlepage"> 264 <div> 265 <div> 266 <h3 class="title"><a id="id1714105"></a>Errors</h3> 267 </div> 268 </div> 269 </div> 270 <p> 271 The <code class="methodname">DbEnv::txn_begin()</code> <span> 272 273 <span> 274 method may fail and throw a <a class="link" href="dbexception.html" title="Chapter 6. The DbException Class">DbException</a> 275 exception, encapsulating one of the following non-zero errors, or return one 276 of the following non-zero errors: 277 </span> 278 </span> 279 </p> 280 <div class="sect3" lang="en" xml:lang="en"> 281 <div class="titlepage"> 282 <div> 283 <div> 284 <h4 class="title"><a id="id1713659"></a><span>DbMemoryException</span> or ENOMEM</h4> 285 </div> 286 </div> 287 </div> 288 <p> 289 The maximum number of concurrent transactions has been 290 reached. 291 </p> 292 <p> 293 <a class="xref" href="dbmemory.html" title="DbMemoryException">DbMemoryException</a> is thrown if 294 your Berkeley DB API is configured to throw exceptions. 295 Otherwise, <code class="literal">ENOMEM</code> is returned. 296 </p> 297 </div> 298 </div> 299 <div class="sect2" lang="en" xml:lang="en"> 300 <div class="titlepage"> 301 <div> 302 <div> 303 <h3 class="title"><a id="id1713954"></a>Class</h3> 304 </div> 305 </div> 306 </div> 307 <p> 308 <a class="link" href="env.html" title="Chapter 5. The DbEnv Handle">DbEnv</a>, <a class="link" href="txn.html" title="Chapter 13. The DbTxn Handle">DbTxn</a> 309 </p> 310 </div> 311 <div class="sect2" lang="en" xml:lang="en"> 312 <div class="titlepage"> 313 <div> 314 <div> 315 <h3 class="title"><a id="id1714069"></a>See Also</h3> 316 </div> 317 </div> 318 </div> 319 <p> 320 <a class="xref" href="txn.html#txnlist" title="Transaction Subsystem and Related Methods">Transaction Subsystem and Related Methods</a> 321 </p> 322 </div> 323 </div> 324 <div class="navfooter"> 325 <hr /> 326 <table width="100%" summary="Navigation footer"> 327 <tr> 328 <td width="40%" align="left"><a accesskey="p" href="txnabort.html">Prev</a> </td> 329 <td width="20%" align="center"> 330 <a accesskey="u" href="txn.html">Up</a> 331 </td> 332 <td width="40%" align="right"> <a accesskey="n" href="txncheckpoint.html">Next</a></td> 333 </tr> 334 <tr> 335 <td width="40%" align="left" valign="top">DbTxn::abort() </td> 336 <td width="20%" align="center"> 337 <a accesskey="h" href="index.html">Home</a> 338 </td> 339 <td width="40%" align="right" valign="top"> DbEnv::txn_checkpoint()</td> 340 </tr> 341 </table> 342 </div> 343 </body> 344</html> 345