1
<!--$Id: txn_begin.so,v 10.48 2001/07/02 01:03:12 bostic Exp $-->
2
<!--Copyright 1997-2001 by Sleepycat Software, Inc.-->
3
<!--All rights reserved.-->
6
<title>Berkeley DB: txn_begin</title>
7
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
8
<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
11
<a name="2"><!--meow--></a>
12
<table width="100%"><tr valign=top>
17
<a href="../api_c/c_index.html"><img src="../images/api.gif" alt="API"></a><a href="../reftoc.html"><img src="../images/ref.gif" alt="Ref"></a>
25
txn_begin(DB_ENV *env,
26
DB_TXN *parent, DB_TXN **tid, u_int32_t flags);
29
<p>The txn_begin method creates a new transaction in the environment
30
and copies a pointer to a DB_TXN that uniquely identifies it into
31
the memory to which <b>tid</b> refers.
32
<p>If the <b>parent</b> argument is non-NULL, the new transaction will
33
be a nested transaction, with the transaction indicated by
34
<b>parent</b> as its parent. Transactions may be
36
In the presence of distributed transactions and two-phase commit,
37
only the parental transaction, that is a transaction without
38
a <b>parent</b> specified, should be passed as an argument to
39
<a href="../api_c/txn_prepare.html">txn_prepare</a>.
40
<p>The <b>flags</b> value must be set to 0 or by bitwise inclusively <b>OR</b>'ing together one or
41
more of the following values:
43
<p><dt><a name="DB_DIRTY_READ">DB_DIRTY_READ</a><dd>All read operations performed by the transaction will read modified but
44
not yet committed data. Silently ignored if the <a href="../api_c/db_open.html#DB_DIRTY_READ">DB_DIRTY_READ</a>
45
flag was not specified when the underlying database was opened.
46
<p><dt><a name="DB_TXN_NOSYNC">DB_TXN_NOSYNC</a><dd>Do not synchronously flush the log when this transaction commits or
47
prepares. This means the transaction will exhibit the ACI (atomicity,
48
consistency, and isolation) properties, but not D (durability); that is,
49
database integrity will be maintained but it is possible that this
50
transaction may be undone during recovery.
51
<p>This behavior may be set for a Berkeley DB environment using the
52
<a href="../api_c/env_set_flags.html">DB_ENV->set_flags</a> interface. Any value specified in this
53
interface overrides that setting.
54
<p><dt><a name="DB_TXN_NOWAIT">DB_TXN_NOWAIT</a><dd>If a lock is unavailable for any Berkeley DB operation performed in the context
55
of this transaction, return immediately instead of blocking on the lock.
56
The error return in the case will be <a href="../ref/program/errorret.html#DB_LOCK_NOTGRANTED">DB_LOCK_NOTGRANTED</a>.
57
<p><dt><a name="DB_TXN_SYNC">DB_TXN_SYNC</a><dd>Synchronously flush the log when this transaction commits or prepares.
58
This means the transaction will exhibit all of the ACID (atomicity,
59
consistency, isolation, and durability) properties.
60
<p>This behavior is the default for Berkeley DB environments unless the
61
<a href="../api_c/env_open.html#DB_TXN_NOSYNC">DB_TXN_NOSYNC</a> flag was specified to the <a href="../api_c/env_set_flags.html">DB_ENV->set_flags</a>
62
interface. Any value specified in this interface overrides that
65
<p><b>Note: A transaction may not span threads; that is, each transaction must
66
begin and end in the same thread, and each transaction may be used only
67
by a single thread.</b>
68
<p><b>Note: Cursors may not span transactions; that is, each cursor must be
69
opened and closed within a single transaction.</b>
70
<p><b>Note: A parent transaction may not issue any Berkeley DB operations -- except for
71
txn_begin, <a href="../api_c/txn_abort.html">txn_abort</a> and <a href="../api_c/txn_commit.html">txn_commit</a> -- while it has
72
active child transactions (child transactions that have not yet been
73
committed or aborted).</b>
74
<p>The txn_begin function returns a non-zero error value on failure and 0 on success.
76
<p>The txn_begin function may fail and return a non-zero error for the following conditions:
78
<p><dt>ENOMEM<dd>The maximum number of concurrent transactions has been reached.
80
<p>The txn_begin function may fail and return a non-zero error for errors specified for other Berkeley DB and C library or system functions.
81
If a catastrophic error has occurred, the txn_begin function may fail and return
82
<a href="../ref/program/errorret.html#DB_RUNRECOVERY">DB_RUNRECOVERY</a>, in which case all subsequent Berkeley DB calls will fail
85
<a href="../api_c/env_set_tx_max.html">DB_ENV->set_tx_max</a>,
86
<a href="../api_c/env_set_tx_recover.html">DB_ENV->set_tx_recover</a>,
87
<a href="../api_c/env_set_tx_timestamp.html">DB_ENV->set_tx_timestamp</a>,
88
<a href="../api_c/txn_abort.html">txn_abort</a>,
89
<a href="../api_c/txn_begin.html">txn_begin</a>,
90
<a href="../api_c/txn_checkpoint.html">txn_checkpoint</a>,
91
<a href="../api_c/txn_commit.html">txn_commit</a>,
92
<a href="../api_c/txn_discard.html">txn_discard</a>,
93
<a href="../api_c/txn_id.html">txn_id</a>,
94
<a href="../api_c/txn_prepare.html">txn_prepare</a>,
95
<a href="../api_c/txn_recover.html">txn_recover</a>,
97
<a href="../api_c/txn_stat.html">txn_stat</a>.
99
<table width="100%"><tr><td><br></td><td align=right>
100
<a href="../api_c/c_index.html"><img src="../images/api.gif" alt="API"></a><a href="../reftoc.html"><img src="../images/ref.gif" alt="Ref"></a>
102
<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
added
removed
db/docs/api_c/txn_begin.html
