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