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