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>Db::cursor()</title> 7 <link rel="stylesheet" href="apiReference.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Berkeley DB C++ API Reference" /> 10 <link rel="up" href="dbc.html" title="Chapter 3. The Dbc Handle" /> 11 <link rel="prev" href="dbc.html" title="Chapter 3. The Dbc Handle" /> 12 <link rel="next" href="dbcclose.html" title="Dbc::close()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Db::cursor()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="dbc.html">Prev</a> </td> 22 <th width="60%" align="center">Chapter 3. 23 The Dbc Handle 24 </th> 25 <td width="20%" align="right"> <a accesskey="n" href="dbcclose.html">Next</a></td> 26 </tr> 27 </table> 28 <hr /> 29 </div> 30 <div class="sect1" lang="en" xml:lang="en"> 31 <div class="titlepage"> 32 <div> 33 <div> 34 <h2 class="title" style="clear: both"><a id="dbcursor"></a>Db::cursor()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db_cxx.h> 39 40int 41Db::cursor(DbTxn *txnid, Dbc **cursorp, u_int32_t flags);</pre> 42 <p> 43 The <code class="methodname">Db::cursor()</code> method returns a created database cursor. 44 </p> 45 <p> 46 Cursors may span threads, but only serially, that is, the application 47 must serialize access to the cursor handle. 48 </p> 49 <p> 50 The <code class="methodname">Db::cursor()</code> <span> 51 52 <span> 53 method either returns a non-zero error value or throws an 54 exception that encapsulates a non-zero error value on 55 failure, and returns 0 on success. 56 </span> 57 </span> 58 </p> 59 <div class="sect2" lang="en" xml:lang="en"> 60 <div class="titlepage"> 61 <div> 62 <div> 63 <h3 class="title"><a id="id1654455"></a>Parameters</h3> 64 </div> 65 </div> 66 </div> 67 <div class="sect3" lang="en" xml:lang="en"> 68 <div class="titlepage"> 69 <div> 70 <div> 71 <h4 class="title"><a id="id1654350"></a>cursorp</h4> 72 </div> 73 </div> 74 </div> 75 <p> 76 The <span class="bold"><strong>cursorp</strong></span> parameter references 77 memory into which a pointer to the allocated cursor is copied. 78 </p> 79 </div> 80 <div class="sect3" lang="en" xml:lang="en"> 81 <div class="titlepage"> 82 <div> 83 <div> 84 <h4 class="title"><a id="id1654639"></a>flags</h4> 85 </div> 86 </div> 87 </div> 88 <p> 89 The <span class="bold"><strong>flags</strong></span> parameter must be set to 0 90 or by bitwise inclusively <span class="bold"><strong>OR</strong></span>'ing 91 together one or more of the following values: 92 </p> 93 <div class="itemizedlist"> 94 <ul type="disc"> 95 <li> 96 <p><a id="cursor_DB_BULK"></a> 97 <code class="literal">DB_BULK</code> 98 </p> 99 <p> 100 Configure a cursor to optimize for bulk operations. Each 101 successive operation on a cursor configured with this flag 102 attempts to continue on the same database page as the previous 103 operation, falling back to a search if a different page is 104 required. This avoids searching if there is a high degree of 105 locality between cursor operations. This flag is currently 106 only effective with the btree access method: for other access 107 methods it is ignored. 108 </p> 109 </li> 110 <li> 111 <p><a id="cursor_DB_READ_COMMITTED"></a> 112 <code class="literal">DB_READ_COMMITTED</code> 113 </p> 114 <p> 115 Configure a transactional cursor to have degree 2 isolation. This 116 ensures the stability of the current data item read by this cursor but 117 permits data read by this cursor to be modified or deleted prior to 118 the commit of the transaction for this cursor. 119 </p> 120 </li> 121 <li> 122 <p><a id="cursor_DB_READ_UNCOMMITTED"></a> 123 <code class="literal">DB_READ_UNCOMMITTED</code> 124 </p> 125 <p> 126 Configure a transactional cursor to have degree 1 isolation. Read 127 operations performed by the cursor may return modified but not yet 128 committed data. Silently ignored if the 129 <a class="link" href="dbopen.html#dbopen_DB_READ_UNCOMMITTED">DB_READ_UNCOMMITTED</a> 130 flag was not specified when the underlying database was opened. 131 </p> 132 </li> 133 <li> 134 <p><a id="cursor_DB_WRITECURSOR"></a> 135 <code class="literal">DB_WRITECURSOR</code> 136 </p> 137 <p> 138 Specify that the cursor will be used to update the database. The 139 underlying database environment must have been opened using the 140 <a class="link" href="envopen.html#envopen_DB_INIT_CDB">DB_INIT_CDB</a> flag. 141 </p> 142 </li> 143 <li> 144 <p><a id="cursor_DB_TXN_SNAPSHOT"></a> 145 <code class="literal">DB_TXN_SNAPSHOT</code> 146 </p> 147 <p> 148 Configure a transactional cursor to operate with read-only <a href="../../programmer_reference/transapp_read.html" class="olink">snapshot isolation</a>. For 149 databases with the 150 <a class="link" href="dbopen.html#dbopen_DB_MULTIVERSION">DB_MULTIVERSION</a> 151 flag set, data values will be read as they are when the cursor is 152 opened, without taking read locks. 153 </p> 154 <p> 155 This flag implicitly begins a transaction that is committed when the cursor is 156 closed. 157 </p> 158 <p> 159 This flag is silently ignored if 160 <a class="link" href="dbopen.html#dbopen_DB_MULTIVERSION">DB_MULTIVERSION</a> 161 is not set on the underlying database or if a transaction is supplied in 162 the <span class="bold"><strong>txnid</strong></span> parameter. 163 </p> 164 </li> 165 </ul> 166 </div> 167 </div> 168 <div class="sect3" lang="en" xml:lang="en"> 169 <div class="titlepage"> 170 <div> 171 <div> 172 <h4 class="title"><a id="id1654875"></a>txnid</h4> 173 </div> 174 </div> 175 </div> 176 <p> 177 To transaction-protect cursor operations, cursors must be 178 opened and closed within the context of a transaction. The 179 <span class="bold"><strong>txnid</strong></span> parameter specifies the 180 transaction context in which the cursor may be used. 181 </p> 182 <p> 183 Cursor operations are not automatically transaction-protected, even if the 184 <a class="link" href="envset_flags.html#envset_flags_DB_AUTO_COMMIT">DB_AUTO_COMMIT</a> 185 flag is specified to the 186 <a class="xref" href="envset_flags.html" title="DbEnv::set_flags()">DbEnv::set_flags()</a> or 187 <a class="xref" href="dbopen.html" title="Db::open()">Db::open()</a> methods. If 188 cursor operations are to be transaction-protected, the <span class="bold"><strong>txnid</strong></span> parameter must be a transaction handle 189 returned from <a class="xref" href="txnbegin.html" title="DbEnv::txn_begin()">DbEnv::txn_begin()</a>; otherwise, 190 NULL. 191 </p> 192 </div> 193 </div> 194 <div class="sect2" lang="en" xml:lang="en"> 195 <div class="titlepage"> 196 <div> 197 <div> 198 <h3 class="title"><a id="id1654799"></a>Errors</h3> 199 </div> 200 </div> 201 </div> 202 <p> 203 The <code class="methodname">Db::cursor()</code> <span> 204 205 <span> 206 method may fail and throw a <a class="link" href="dbexception.html" title="Chapter 6. The DbException Class">DbException</a> 207 exception, encapsulating one of the following non-zero errors, or return one 208 of the following non-zero errors: 209 </span> 210 </span> 211 </p> 212 <div class="sect3" lang="en" xml:lang="en"> 213 <div class="titlepage"> 214 <div> 215 <div> 216 <h4 class="title"><a id="id1654466"></a><span>DbRepHandleDeadException or</span> DB_REP_HANDLE_DEAD</h4> 217 </div> 218 </div> 219 </div> 220 <p> 221 When a client synchronizes with the master, it is possible for committed 222 transactions to be rolled back. This invalidates all the database and cursor 223 handles opened in the replication environment. Once this occurs, an attempt to use 224 such a handle will 225 <span> 226 throw a <a class="xref" href="dbrephandledead.html" title="DbRepHandleDeadException">DbRepHandleDeadException</a> (if 227 your application is configured to throw exceptions), or 228 </span> 229 return <code class="literal">DB_REP_HANDLE_DEAD</code>. 230 The application will need to discard the handle and open a new one in order to 231 continue processing. 232 </p> 233 </div> 234 <div class="sect3" lang="en" xml:lang="en"> 235 <div class="titlepage"> 236 <div> 237 <div> 238 <h4 class="title"><a id="id1630002"></a><span>DbDeadlockException or </span>DB_REP_LOCKOUT</h4> 239 </div> 240 </div> 241 </div> 242 <p> 243 The operation was blocked by client/master synchronization. 244 </p> 245 <p> 246 <a class="xref" href="dbdeadlock.html" title="DbDeadlockException">DbDeadlockException</a> is thrown if 247 your Berkeley DB API is configured to throw exceptions. 248 Otherwise, <code class="literal">DB_REP_LOCKOUT</code> is returned. 249 </p> 250 </div> 251 <div class="sect3" lang="en" xml:lang="en"> 252 <div class="titlepage"> 253 <div> 254 <div> 255 <h4 class="title"><a id="id1654776"></a>EINVAL</h4> 256 </div> 257 </div> 258 </div> 259 <p> 260 An invalid flag value or parameter was specified. 261 </p> 262 </div> 263 </div> 264 <div class="sect2" lang="en" xml:lang="en"> 265 <div class="titlepage"> 266 <div> 267 <div> 268 <h3 class="title"><a id="id1654707"></a>Class</h3> 269 </div> 270 </div> 271 </div> 272 <p> 273 <a class="link" href="db.html" title="Chapter 2. The Db Handle">Db</a> 274 </p> 275 </div> 276 <div class="sect2" lang="en" xml:lang="en"> 277 <div class="titlepage"> 278 <div> 279 <div> 280 <h3 class="title"><a id="id1654698"></a>See Also</h3> 281 </div> 282 </div> 283 </div> 284 <p> 285 <a class="xref" href="dbc.html#dbclist" title="Database Cursors and Related Methods">Database Cursors and Related Methods</a> 286 </p> 287 </div> 288 </div> 289 <div class="navfooter"> 290 <hr /> 291 <table width="100%" summary="Navigation footer"> 292 <tr> 293 <td width="40%" align="left"><a accesskey="p" href="dbc.html">Prev</a> </td> 294 <td width="20%" align="center"> 295 <a accesskey="u" href="dbc.html">Up</a> 296 </td> 297 <td width="40%" align="right"> <a accesskey="n" href="dbcclose.html">Next</a></td> 298 </tr> 299 <tr> 300 <td width="40%" align="left" valign="top">Chapter 3. 301 The Dbc Handle 302 </td> 303 <td width="20%" align="center"> 304 <a accesskey="h" href="index.html">Home</a> 305 </td> 306 <td width="40%" align="right" valign="top"> Dbc::close()</td> 307 </tr> 308 </table> 309 </div> 310 </body> 311</html> 312