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