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>Configuring the Transaction Subsystem</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="Getting Started with Berkeley DB Transaction Processing" />
10    <link rel="up" href="usingtxns.html" title="Chapter 3. Transaction Basics" />
11    <link rel="prev" href="txnindices.html" title="Secondary Indices with Transaction Applications" />
12    <link rel="next" href="txnconcurrency.html" title="Chapter 4. Concurrency" />
13  </head>
14  <body>
15    <div class="navheader">
16      <table width="100%" summary="Navigation header">
17        <tr>
18          <th colspan="3" align="center">Configuring the Transaction Subsystem</th>
19        </tr>
20        <tr>
21          <td width="20%" align="left"><a accesskey="p" href="txnindices.html">Prev</a> </td>
22          <th width="60%" align="center">Chapter 3. Transaction Basics</th>
23          <td width="20%" align="right"> <a accesskey="n" href="txnconcurrency.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="maxtxns"></a>Configuring the Transaction Subsystem</h2>
33          </div>
34        </div>
35      </div>
36      <p>
37            Most of the configuration activities that you need to perform
38            for your transactional DB application will involve the
39            locking and logging subsystems. See 
40            <a class="xref" href="txnconcurrency.html" title="Chapter 4. Concurrency">Concurrency</a>
41            and
42            <a class="xref" href="filemanagement.html" title="Chapter 5. Managing DB Files">Managing DB Files</a>
43            for details.
44        </p>
45      <p>
46            However, there are a couple of things that you can do to
47            configure your transaction subsystem directly. These things
48            are:
49        </p>
50      <div class="itemizedlist">
51        <ul type="disc">
52          <li>
53            <span>
54                <p>
55                    
56                    <span>
57                        Configure 
58                    </span>
59                        
60                    the maximum number of simultaneous
61                    transactions needed by your application. 
62                    In general, you should not need to do this unless you
63                    use deeply nested transactions or you have many threads all
64                    of which have active transactions. In addition, you may
65                    need to configure a higher maximum number of transactions if you
66                    are using snapshot isolation. See
67                    <a class="xref" href="isolation.html#sisolation_maxtxn" title="Snapshot Isolation Transactional Requirements">Snapshot Isolation Transactional Requirements</a>
68                    for details.
69                </p>
70                <p>
71                    By default, your application can support 20 active
72                    transactions. 
73                </p>
74                <p>
75                    You can set the maximum number of simultaneous
76                    transactions supported by your application using
77                    <span>
78                        the
79                        
80                        <code class="methodname">DbEnv::set_tx_max()</code>
81                        method. Note that this method must be called
82                        before the environment has been opened.
83                    </span>
84                    
85                </p>
86                <p>
87                    If your application has exceeded this maximum value,
88                    then any attempt to begin a new transaction will fail.
89                </p>
90                <p>
91                    This value can also be set using the
92                    <code class="literal">DB_CONFIG</code> file's
93                    <code class="literal">set_tx_max</code> parameter. Remember that
94                    the <code class="literal">DB_CONFIG</code> must reside in your
95                    environment home directory.
96                </p>
97</span>
98          </li>
99          <li>
100            <span>
101                  <p>
102                    <span>
103                    Configure the timeout value for your transactions. 
104                    </span>
105                    
106                    
107                    This value represents the longest period of time a
108                    transaction can be active. Note, however, that
109                    transaction timeouts are checked only when DB
110                    examines its lock tables for blocked locks
111                    (see <a class="xref" href="blocking_deadlocks.html" title="Locks, Blocks, and Deadlocks">Locks, Blocks, and Deadlocks</a>
112                    for more information). Therefore, a transaction's timeout can
113                    have expired, but the application will not be notified until DB 
114                    has a reason to examine its lock tables.
115                </p>
116                <p>
117                    Be aware that some transactions may be
118                    inappropriately timed out before the transaction has a
119                    chance to complete. You should therefore use this
120                    mechanism only if you know your application
121                    might have unacceptably long transactions and
122                    you want to make sure your application will
123                    not stall during their execution.
124                    (This might happen if, for example, your
125                    transaction blocks or requests too much
126                    data.)
127                </p>
128                <p>
129                    Note that by default transaction timeouts are set to 0 seconds, which means that they never time
130                    out.
131                </p>
132                <p>
133                    To set the maximum timeout value for your transactions,
134                    use  the
135                            
136                            <span><code class="methodname">DbEnv::set_timeout()</code></span>
137                            
138                        method. This method configures the entire
139                        environment; not just the handle used to set the
140                        configuration. Further, this value may
141                        be set at any time during the application's
142                        lifetime. 
143                </p>
144                <p>
145                    This value can also be set using the
146                    <code class="literal">DB_CONFIG</code> file's
147                    <code class="literal">set_txn_timeout</code> parameter.
148                </p> 
149                
150</span>
151          </li>
152        </ul>
153      </div>
154      <p>
155            For example:
156        </p>
157      <pre class="programlisting">#include "db_cxx.h"
158
159...
160                                                                                                                                  
161int main(void)
162{
163    u_int32_t env_flags = DB_CREATE     |  // If the environment does not
164                                           // exist, create it.
165                          DB_INIT_LOCK  |  // Initialize locking
166                          DB_INIT_LOG   |  // Initialize logging
167                          DB_INIT_MPOOL |  // Initialize the cache
168                          DB_THREAD     |  // Free-thread the env handle
169                          DB_INIT_TXN;     // Initialize transactions
170
171    std::string envHome("/export1/testEnv");
172    DbEnv myEnv(0);
173
174    try {
175
176        // Configure a maximum transaction timeout of 1 second.
177        myEnv.set_timeout(1000000, DB_SET_TXN_TIMEOUT);
178        // Configure 40 maximum transactions.
179        myEnv.set_tx_max(40);
180        myEnv.open(envHome.c_str(), env_flags, 0);
181
182        // From here, you open your databases, proceed with your 
183        // database operations, and respond to deadlocks as 
184        // is normal (omitted for brevity).
185
186        
187        ...</pre>
188    </div>
189    <div class="navfooter">
190      <hr />
191      <table width="100%" summary="Navigation footer">
192        <tr>
193          <td width="40%" align="left"><a accesskey="p" href="txnindices.html">Prev</a> </td>
194          <td width="20%" align="center">
195            <a accesskey="u" href="usingtxns.html">Up</a>
196          </td>
197          <td width="40%" align="right"> <a accesskey="n" href="txnconcurrency.html">Next</a></td>
198        </tr>
199        <tr>
200          <td width="40%" align="left" valign="top">Secondary Indices with Transaction Applications </td>
201          <td width="20%" align="center">
202            <a accesskey="h" href="index.html">Home</a>
203          </td>
204          <td width="40%" align="right" valign="top"> Chapter 4. Concurrency</td>
205        </tr>
206      </table>
207    </div>
208  </body>
209</html>
210