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>Opening a Transactional Environment and Database</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="enabletxn.html" title="Chapter��2.��Enabling Transactions" />
11    <link rel="prev" href="enabletxn.html" title="Chapter��2.��Enabling Transactions" />
12    <link rel="next" href="usingtxns.html" title="Chapter��3.��Transaction Basics" />
13  </head>
14  <body>
15    <div class="navheader">
16      <table width="100%" summary="Navigation header">
17        <tr>
18          <th colspan="3" align="center">Opening a Transactional Environment and
19            <span>Database</span>
20            
21            
22        </th>
23        </tr>
24        <tr>
25          <td width="20%" align="left"><a accesskey="p" href="enabletxn.html">Prev</a>��</td>
26          <th width="60%" align="center">Chapter��2.��Enabling Transactions</th>
27          <td width="20%" align="right">��<a accesskey="n" href="usingtxns.html">Next</a></td>
28        </tr>
29      </table>
30      <hr />
31    </div>
32    <div class="sect1" lang="en" xml:lang="en">
33      <div class="titlepage">
34        <div>
35          <div>
36            <h2 class="title" style="clear: both"><a id="envopen"></a>Opening a Transactional Environment and
37            <span>Database</span>
38            
39            
40        </h2>
41          </div>
42        </div>
43      </div>
44      <p>
45            To enable transactions for your environment, you must initialize the
46            transactional subsystem. Note that doing this also initializes the
47            logging subsystem. In addition, you must initialize the memory pool
48            (in-memory cache). You must also initialize the locking subsystem.  
49            
50            
51            <span>
52                For example:
53            </span>
54            
55        </p>
56      <p>
57        Notice in the following example that you create your environment
58        handle using the <code class="function">db_env_create()</code> function before you open 
59        the environment:
60    </p>
61      <pre class="programlisting">#include &lt;stdio.h&gt;
62#include &lt;stdlib.h&gt;
63
64#include "db.h"
65
66int
67main(void)
68{
69    int ret, ret_c;
70    u_int32_t env_flags;
71    DB_ENV *envp;
72    const char *db_home_dir = "/tmp/myEnvironment";
73    
74    envp = NULL;
75
76    /* Open the environment */
77    ret = db_env_create(&amp;envp, 0);
78    if (ret != 0) {
79        fprintf(stderr, "Error creating environment handle: %s\n",
80            db_strerror(ret));
81        return (EXIT_FAILURE);
82    }
83                                                                                                                                  
84    env_flags = DB_CREATE |    /* Create the environment if it does 
85                                * not already exist. */
86                DB_INIT_TXN  | /* Initialize transactions */
87                DB_INIT_LOCK | /* Initialize locking. */
88                DB_INIT_LOG  | /* Initialize logging */
89                DB_INIT_MPOOL; /* Initialize the in-memory cache. */
90
91    ret = envp-&gt;open(envp, db_home_dir, env_flags, 0);
92    if (ret != 0) {
93        fprintf(stderr, "Error opening environment: %s\n",
94            db_strerror(ret));
95        goto err;
96    }
97
98err:
99    /* Close the environment */
100    if (envp != NULL) {
101        ret_c = envp-&gt;close(envp, 0);
102        if (ret_c != 0) {
103            fprintf(stderr, "environment close failed: %s\n",
104                db_strerror(ret_c));
105            ret = ret_c;
106        }
107    }
108
109    return (ret == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
110} </pre>
111      <p>
112        You then create and open your database(s) as you would for a non-transactional system.
113        <span>
114            The only difference is that you must pass the environment handle to
115            the 
116                <span>
117                    <code class="function">db_create()</code> function, 
118                </span>
119                
120             and you must open the database within a transaction.
121             Typically auto commit is used for this purpose. To do so, pass 
122            <code class="literal">DB_AUTO_COMMIT</code> to the database open command.
123            Also, make sure you close all your databases before you close 
124            your environment.
125            For example:
126        </span>
127
128        
129    </p>
130      <pre class="programlisting">#include &lt;stdio.h&gt;
131#include &lt;stdlib.h&gt;
132
133#include "db.h"
134
135int
136main(void)
137{
138    int ret, ret_c;
139    u_int32_t <strong class="userinput"><code>db_flags,</code></strong> env_flags;
140    <strong class="userinput"><code>DB *dbp;</code></strong>
141    DB_ENV *envp;
142    const char *db_home_dir = "/tmp/myEnvironment";
143    <strong class="userinput"><code>const char *file_name = "mydb.db";
144    
145    dbp = NULL;</code></strong>
146    envp = NULL;
147
148    /* Open the environment */
149    ret = db_env_create(&amp;envp, 0);
150    if (ret != 0) {
151        fprintf(stderr, "Error creating environment handle: %s\n",
152            db_strerror(ret));
153        return (EXIT_FAILURE);
154    }
155                                                                                                                                  
156    env_flags = DB_CREATE |    /* Create the environment if it does 
157                                * not already exist. */
158                DB_INIT_TXN  | /* Initialize transactions */
159                DB_INIT_LOCK | /* Initialize locking. */
160                DB_INIT_LOG  | /* Initialize logging */
161                DB_INIT_MPOOL; /* Initialize the in-memory cache. */
162
163    ret = envp-&gt;open(envp, db_home_dir, env_flags, 0);
164    if (ret != 0) {
165        fprintf(stderr, "Error opening environment: %s\n",
166            db_strerror(ret));
167        goto err;
168    }
169
170    <strong class="userinput"><code>/* Initialize the DB handle */
171    ret = db_create(&amp;dbp, envp, 0);
172    if (ret != 0) {
173        envp-&gt;err(envp, ret, "Database creation failed");
174        goto err;
175    }
176
177    db_flags = DB_CREATE | DB_AUTO_COMMIT;
178    ret = dbp-&gt;open(dbp,        /* Pointer to the database */
179                    NULL,       /* Txn pointer */
180                    file_name,  /* File name */
181                    NULL,       /* Logical db name */
182                    DB_BTREE,   /* Database type (using btree) */
183                    db_flags,   /* Open flags */
184                    0);         /* File mode. Using defaults */
185    if (ret != 0) {
186        envp-&gt;err(envp, ret, "Database '%s' open failed",
187            file_name);
188        goto err;
189    }</code></strong>
190
191
192err:
193    <strong class="userinput"><code>/* Close the database */
194    if (dbp != NULL) {
195        ret_c = dbp-&gt;close(dbp, 0);
196        if (ret_c != 0) {
197            envp-&gt;err(envp, ret_c, "Database close failed.");
198            ret = ret_c
199        }
200    }</code></strong>
201
202
203    /* Close the environment */
204    if (envp != NULL) {
205        ret_c = envp-&gt;close(envp, 0);
206        if (ret_c != 0) {
207            fprintf(stderr, "environment close failed: %s\n",
208                db_strerror(ret_c));
209            ret = ret_c;
210        }
211    }
212
213    return (ret == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
214} </pre>
215      <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
216        <h3 class="title">Note</h3>
217        <p>
218                Never close a database  that has active transactions. Make sure
219            all transactions are resolved (either committed or aborted)
220            before closing the database.
221        </p>
222      </div>
223    </div>
224    <div class="navfooter">
225      <hr />
226      <table width="100%" summary="Navigation footer">
227        <tr>
228          <td width="40%" align="left"><a accesskey="p" href="enabletxn.html">Prev</a>��</td>
229          <td width="20%" align="center">
230            <a accesskey="u" href="enabletxn.html">Up</a>
231          </td>
232          <td width="40%" align="right">��<a accesskey="n" href="usingtxns.html">Next</a></td>
233        </tr>
234        <tr>
235          <td width="40%" align="left" valign="top">Chapter��2.��Enabling Transactions��</td>
236          <td width="20%" align="center">
237            <a accesskey="h" href="index.html">Home</a>
238          </td>
239          <td width="40%" align="right" valign="top">��Chapter��3.��Transaction Basics</td>
240        </tr>
241      </table>
242    </div>
243  </body>
244</html>
245