2
<!--Copyright 1997-2002 by Sleepycat Software, Inc.-->
3
<!--All rights reserved.-->
4
<!--See the file LICENSE for redistribution information.-->
7
<title>Berkeley DB: DbEnv.txn_begin</title>
8
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
9
<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
12
<a name="2"><!--meow--></a>
13
<table width="100%"><tr valign=top>
15
<h1>DbEnv.txn_begin</h1>
18
<a href="../api_java/c_index.html"><img src="../images/api.gif" alt="API"></a><a href="../reftoc.html"><img src="../images/ref.gif" alt="Ref"></a>
23
import com.sleepycat.db.*;
25
public DbTxn txn_begin(DbTxn parent, int flags)
29
<p>The DbEnv.txn_begin method creates a new transaction in the environment
30
and returns a <a href="../api_java/txn_class.html">DbTxn</a> that uniquely identifies it.
31
Calling the <a href="../api_java/txn_abort.html">DbTxn.abort</a>,
32
<a href="../api_java/txn_commit.html">DbTxn.commit</a> or <a href="../api_java/txn_discard.html">DbTxn.discard</a> methods will discard the returned
34
<p>If the <b>parent</b> argument is non-null, the new transaction will
35
be a nested transaction, with the transaction indicated by
36
<b>parent</b> as its parent. Transactions may be
38
In the presence of distributed transactions and two-phase commit,
39
only the parental transaction, that is a transaction without
40
a <b>parent</b> specified, should be passed as an argument to
41
<a href="../api_java/txn_prepare.html">DbTxn.prepare</a>.
42
<p>The <b>flags</b> value must be set to 0 or by bitwise inclusively <b>OR</b>'ing together one or
43
more of the following values:
45
<p><dt><a name="Db.DB_DIRTY_READ">Db.DB_DIRTY_READ</a><dd>All read operations performed by the transaction will read modified but
46
not yet committed data. Silently ignored if the <a href="../api_java/db_open.html#DB_DIRTY_READ">Db.DB_DIRTY_READ</a>
47
flag was not specified when the underlying database was opened.
48
<p><dt><a name="Db.DB_TXN_NOSYNC">Db.DB_TXN_NOSYNC</a><dd>Do not synchronously flush the log when this transaction commits or
49
prepares. This means the transaction will exhibit the ACI (atomicity,
50
consistency, and isolation) properties, but not D (durability); that is,
51
database integrity will be maintained but it is possible that this
52
transaction may be undone during recovery.
53
<p>This behavior may be set for a Berkeley DB environment using the
54
<a href="../api_java/env_set_flags.html">DbEnv.set_flags</a> interface. Any value specified in this
55
interface overrides that setting.
56
<p><dt><a name="Db.DB_TXN_NOWAIT">Db.DB_TXN_NOWAIT</a><dd>If a lock is unavailable for any Berkeley DB operation performed in the context
58
throw a <a href="../api_java/lockng_class.html">DbLockNotGrantedException</a>
59
immediately instead of blocking on the lock.
60
<p><dt><a name="Db.DB_TXN_SYNC">Db.DB_TXN_SYNC</a><dd>Synchronously flush the log when this transaction commits or prepares.
61
This means the transaction will exhibit all of the ACID (atomicity,
62
consistency, isolation, and durability) properties.
63
<p>This behavior is the default for Berkeley DB environments unless the
64
<a href="../api_java/env_set_flags.html#DB_TXN_NOSYNC">Db.DB_TXN_NOSYNC</a> flag was specified to the <a href="../api_java/env_set_flags.html">DbEnv.set_flags</a>
65
interface. Any value specified in this interface overrides that
68
<p><b>Note: A transaction may not span threads; that is, each transaction must
69
begin and end in the same thread, and each transaction may be used only
70
by a single thread.</b>
71
<p><b>Note: Cursors may not span transactions; that is, each cursor must be
72
opened and closed within a single transaction.</b>
73
<p><b>Note: A parent transaction may not issue any Berkeley DB operations -- except for
74
DbEnv.txn_begin, <a href="../api_java/txn_abort.html">DbTxn.abort</a> and <a href="../api_java/txn_commit.html">DbTxn.commit</a> -- while it has
75
active child transactions (child transactions that have not yet been
76
committed or aborted).</b>
77
<p>The DbEnv.txn_begin method throws an exception that encapsulates a non-zero error value on
80
<p>The DbEnv.txn_begin method may fail and throw an exception encapsulating a non-zero error for the following conditions:
82
<p><dt>ENOMEM<dd>The maximum number of concurrent transactions has been reached.
84
<p>The DbEnv.txn_begin method may fail and throw an exception for errors specified for other Berkeley DB and C library or system methods.
85
If a catastrophic error has occurred, the DbEnv.txn_begin method may fail and
86
throw a <a href="../api_java/runrec_class.html">DbRunRecoveryException</a>,
87
in which case all subsequent Berkeley DB calls will fail in the same way.
89
<a href="../api_java/env_class.html">DbEnv</a>, <a href="../api_java/txn_class.html">DbTxn</a>
91
<a href="../api_java/txn_list.html">Transaction Subsystem and Related Methods</a>
93
<table width="100%"><tr><td><br></td><td align=right>
94
<a href="../api_java/c_index.html"><img src="../images/api.gif" alt="API"></a><a href="../reftoc.html"><img src="../images/ref.gif" alt="Ref"></a>
96
<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>