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>Transactional Cursors</title>
7    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
8    <meta name="generator" content="DocBook XSL Stylesheets V1.62.4" />
9    <link rel="home" 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="previous" href="nestedtxn.html" title="Nested Transactions" />
12    <link rel="next" href="txnindices.html" title="Secondary Indices with Transaction Applications" />
13  </head>
14  <body>
15    <div class="navheader">
16      <table width="100%" summary="Navigation header">
17        <tr>
18          <th colspan="3" align="center">Transactional Cursors</th>
19        </tr>
20        <tr>
21          <td width="20%" align="left"><a accesskey="p" href="nestedtxn.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="txnindices.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="txncursor"></a>Transactional Cursors</h2>
33          </div>
34        </div>
35        <div></div>
36      </div>
37      <p>
38            You can transaction-protect your cursor operations by
39            specifying a transaction handle at the time that you create
40            your cursor.  Beyond that, you do not ever
41            provide a transaction handle directly to a cursor method.
42        </p>
43      <p>
44            Note that if you transaction-protect a cursor, then you must
45            make sure that the cursor is closed before you either commit or
46            abort the transaction. For example:
47        </p>
48      <pre class="programlisting">#include &lt;stdio.h&gt;
49#include &lt;stdlib.h&gt;
50
51#include "db.h"
52
53int
54main(void)
55{
56    DBT key, data;
57    DBC *cursorp;
58    DB_TXN *txn = NULL;
59    int ret, c_ret;
60    char *replacementString = "new string";
61
62    ...
63    /* environment and db handle creation omitted */
64    ...
65
66    /* Get the txn handle */
67    txn = NULL;
68    ret = envp-&gt;txn_begin(envp, NULL, &amp;txn, 0);
69    if (ret != 0) {
70        envp-&gt;err(envp, ret, "Transaction begin failed.");
71        goto err;
72    }
73
74    /* Get the cursor, supply the txn handle at that time */
75    ret = dbp-&gt;cursor(dbp, txn, &amp;cursorp, 0);
76    if (ret != 0) {
77        envp-&gt;err(envp, ret, "Cursor open failed.");
78        txn-&gt;abort(txn);
79        goto err;
80    }
81
82    /* 
83     * Now use the cursor. Note that we do not supply any txn handles to these
84     * methods.
85     */
86    /* Prepare the DBTs */
87    memset(&amp;key, 0, sizeof(DBT));
88    memset(&amp;data, 0, sizeof(DBT));
89    while (cursor-&gt;get(&amp;key, &amp;data, DB_NEXT) == 0) {
90        data-&gt;data = (void *)replacementString;
91        data-&gt;size = (strlen(replacementString) + 1) * sizeof(char);
92        c_ret = cursor-&gt;put(cursor, &amp;key, &amp;data, DB_CURRENT);
93        if (c_ret != 0) {
94            /* abort the transaction and goto error */ 
95            envp-&gt;err(envp, ret, "Cursor put failed.");
96            cursorp-&gt;close(cursorp);
97            cursorp = NULL;
98            txn-&gt;abort(txn);
99            goto err;
100        }
101    }
102
103    /* 
104     * Commit the transaction. Note that the transaction handle
105     * can no longer be used.
106     */ 
107    ret = cursorp-&gt;close(cursorp);
108    if (ret != 0) {
109        envp-&gt;err(envp, ret, "Cursor close failed.");
110        txn-&gt;abort(txn);
111        goto err;
112    }
113    ret = txn-&gt;commit(txn, 0);
114    if (ret != 0) {
115        envp-&gt;err(envp, ret, "Transaction commit failed.");
116        goto err;
117    }
118
119err:
120    /* Close the cursor (if the handle is not NULL)
121     * and perform whatever other cleanup is required */
122
123    /* Close the database */
124
125    /* Close the environment */
126
127    ...
128
129    if (c_ret != 0)
130        ret = c_ret;
131    
132    return (ret == 0 ? EXIT_SUCCESS : EXIT_FAILURE);
133} </pre>
134    </div>
135    <div class="navfooter">
136      <hr />
137      <table width="100%" summary="Navigation footer">
138        <tr>
139          <td width="40%" align="left"><a accesskey="p" href="nestedtxn.html">Prev</a> </td>
140          <td width="20%" align="center">
141            <a accesskey="u" href="usingtxns.html">Up</a>
142          </td>
143          <td width="40%" align="right"> <a accesskey="n" href="txnindices.html">Next</a></td>
144        </tr>
145        <tr>
146          <td width="40%" align="left" valign="top">Nested Transactions </td>
147          <td width="20%" align="center">
148            <a accesskey="h" href="index.html">Home</a>
149          </td>
150          <td width="40%" align="right" valign="top"> Secondary Indices with Transaction Applications</td>
151        </tr>
152      </table>
153    </div>
154  </body>
155</html>
156