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 DBcursor Handle" /> 11 <link rel="prev" href="dbc.html" title="Chapter��3.�� The DBcursor Handle" /> 12 <link rel="next" href="dbcclose.html" title="DBcursor->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 DBcursor 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.h> 39 40int 41DB->cursor(DB *db, DB_TXN *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 <span> 52 method returns a non-zero error value on failure and 0 on success. 53 </span> 54 55 </span> 56 </p> 57 <div class="sect2" lang="en" xml:lang="en"> 58 <div class="titlepage"> 59 <div> 60 <div> 61 <h3 class="title"><a id="id1653048"></a>Parameters</h3> 62 </div> 63 </div> 64 </div> 65 <div class="sect3" lang="en" xml:lang="en"> 66 <div class="titlepage"> 67 <div> 68 <div> 69 <h4 class="title"><a id="id1653224"></a>cursorp</h4> 70 </div> 71 </div> 72 </div> 73 <p> 74 The <span class="bold"><strong>cursorp</strong></span> parameter references 75 memory into which a pointer to the allocated cursor is copied. 76 </p> 77 </div> 78 <div class="sect3" lang="en" xml:lang="en"> 79 <div class="titlepage"> 80 <div> 81 <div> 82 <h4 class="title"><a id="id1653442"></a>flags</h4> 83 </div> 84 </div> 85 </div> 86 <p> 87 The <span class="bold"><strong>flags</strong></span> parameter must be set to 0 88 or by bitwise inclusively <span class="bold"><strong>OR</strong></span>'ing 89 together one or more of the following values: 90 </p> 91 <div class="itemizedlist"> 92 <ul type="disc"> 93 <li> 94 <p><a id="cursor_DB_BULK"></a> 95 <code class="literal">DB_BULK</code> 96 </p> 97 <p> 98 Configure a cursor to optimize for bulk operations. Each 99 successive operation on a cursor configured with this flag 100 attempts to continue on the same database page as the previous 101 operation, falling back to a search if a different page is 102 required. This avoids searching if there is a high degree of 103 locality between cursor operations. This flag is currently 104 only effective with the btree access method: for other access 105 methods it is ignored. 106 </p> 107 </li> 108 <li> 109 <p><a id="cursor_DB_READ_COMMITTED"></a> 110 <code class="literal">DB_READ_COMMITTED</code> 111 </p> 112 <p> 113 Configure a transactional cursor to have degree 2 isolation. This 114 ensures the stability of the current data item read by this cursor but 115 permits data read by this cursor to be modified or deleted prior to 116 the commit of the transaction for this cursor. 117 </p> 118 </li> 119 <li> 120 <p><a id="cursor_DB_READ_UNCOMMITTED"></a> 121 <code class="literal">DB_READ_UNCOMMITTED</code> 122 </p> 123 <p> 124 Configure a transactional cursor to have degree 1 isolation. Read 125 operations performed by the cursor may return modified but not yet 126 committed data. Silently ignored if the 127 <a class="link" href="dbopen.html#dbopen_DB_READ_UNCOMMITTED">DB_READ_UNCOMMITTED</a> 128 flag was not specified when the underlying database was opened. 129 </p> 130 </li> 131 <li> 132 <p><a id="cursor_DB_WRITECURSOR"></a> 133 <code class="literal">DB_WRITECURSOR</code> 134 </p> 135 <p> 136 Specify that the cursor will be used to update the database. The 137 underlying database environment must have been opened using the 138 <a class="link" href="envopen.html#envopen_DB_INIT_CDB">DB_INIT_CDB</a> flag. 139 </p> 140 </li> 141 <li> 142 <p><a id="cursor_DB_TXN_SNAPSHOT"></a> 143 <code class="literal">DB_TXN_SNAPSHOT</code> 144 </p> 145 <p> 146 Configure a transactional cursor to operate with read-only <a href="../../programmer_reference/transapp_read.html" class="olink">snapshot isolation</a>. For 147 databases with the 148 <a class="link" href="dbopen.html#dbopen_DB_MULTIVERSION">DB_MULTIVERSION</a> 149 flag set, data values will be read as they are when the cursor is 150 opened, without taking read locks. 151 </p> 152 <p> 153 This flag implicitly begins a transaction that is committed when the cursor is 154 closed. 155 </p> 156 <p> 157 This flag is silently ignored if 158 <a class="link" href="dbopen.html#dbopen_DB_MULTIVERSION">DB_MULTIVERSION</a> 159 is not set on the underlying database or if a transaction is supplied in 160 the <span class="bold"><strong>txnid</strong></span> parameter. 161 </p> 162 </li> 163 </ul> 164 </div> 165 </div> 166 <div class="sect3" lang="en" xml:lang="en"> 167 <div class="titlepage"> 168 <div> 169 <div> 170 <h4 class="title"><a id="id1653602"></a>txnid</h4> 171 </div> 172 </div> 173 </div> 174 <p> 175 To transaction-protect cursor operations, cursors must be 176 opened and closed within the context of a transaction. The 177 <span class="bold"><strong>txnid</strong></span> parameter specifies the 178 transaction context in which the cursor may be used. 179 </p> 180 <p> 181 Cursor operations are not automatically transaction-protected, even if the 182 <a class="link" href="envset_flags.html#envset_flags_DB_AUTO_COMMIT">DB_AUTO_COMMIT</a> 183 flag is specified to the 184 <a class="xref" href="envset_flags.html" title="DB_ENV->set_flags()">DB_ENV->set_flags()</a> or 185 <a class="xref" href="dbopen.html" title="DB->open()">DB->open()</a> methods. If 186 cursor operations are to be transaction-protected, the <span class="bold"><strong>txnid</strong></span> parameter must be a transaction handle 187 returned from <a class="xref" href="txnbegin.html" title="DB_ENV->txn_begin()">DB_ENV->txn_begin()</a>; otherwise, 188 NULL. 189 </p> 190 </div> 191 </div> 192 <div class="sect2" lang="en" xml:lang="en"> 193 <div class="titlepage"> 194 <div> 195 <div> 196 <h3 class="title"><a id="id1653677"></a>Errors</h3> 197 </div> 198 </div> 199 </div> 200 <p> 201 The <code class="methodname">DB->cursor()</code> <span> 202 <span> 203 method may fail and return one of the following non-zero errors: 204 </span> 205 206 </span> 207 </p> 208 <div class="sect3" lang="en" xml:lang="en"> 209 <div class="titlepage"> 210 <div> 211 <div> 212 <h4 class="title"><a id="id1630409"></a> DB_REP_HANDLE_DEAD</h4> 213 </div> 214 </div> 215 </div> 216 <p> 217 When a client synchronizes with the master, it is possible for committed 218 transactions to be rolled back. This invalidates all the database and cursor 219 handles opened in the replication environment. Once this occurs, an attempt to use 220 such a handle will 221 222 return <code class="literal">DB_REP_HANDLE_DEAD</code>. 223 The application will need to discard the handle and open a new one in order to 224 continue processing. 225 </p> 226 </div> 227 <div class="sect3" lang="en" xml:lang="en"> 228 <div class="titlepage"> 229 <div> 230 <div> 231 <h4 class="title"><a id="id1652890"></a>DB_REP_LOCKOUT</h4> 232 </div> 233 </div> 234 </div> 235 <p> 236 The operation was blocked by client/master synchronization. 237 </p> 238 </div> 239 <div class="sect3" lang="en" xml:lang="en"> 240 <div class="titlepage"> 241 <div> 242 <div> 243 <h4 class="title"><a id="id1653570"></a>EINVAL</h4> 244 </div> 245 </div> 246 </div> 247 <p> 248 An invalid flag value or parameter was specified. 249 </p> 250 </div> 251 </div> 252 <div class="sect2" lang="en" xml:lang="en"> 253 <div class="titlepage"> 254 <div> 255 <div> 256 <h3 class="title"><a id="id1653468"></a>Class</h3> 257 </div> 258 </div> 259 </div> 260 <p> 261 <a class="link" href="db.html" title="Chapter��2.�� The DB Handle">DB</a> 262 </p> 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="id1653508"></a>See Also</h3> 269 </div> 270 </div> 271 </div> 272 <p> 273 <a class="xref" href="dbc.html#dbclist" title="Database Cursors and Related Methods">Database Cursors and Related Methods</a> 274 </p> 275 </div> 276 </div> 277 <div class="navfooter"> 278 <hr /> 279 <table width="100%" summary="Navigation footer"> 280 <tr> 281 <td width="40%" align="left"><a accesskey="p" href="dbc.html">Prev</a>��</td> 282 <td width="20%" align="center"> 283 <a accesskey="u" href="dbc.html">Up</a> 284 </td> 285 <td width="40%" align="right">��<a accesskey="n" href="dbcclose.html">Next</a></td> 286 </tr> 287 <tr> 288 <td width="40%" align="left" valign="top">Chapter��3.�� 289 The DBcursor Handle 290 ��</td> 291 <td width="20%" align="center"> 292 <a accesskey="h" href="index.html">Home</a> 293 </td> 294 <td width="40%" align="right" valign="top">��DBcursor->close()</td> 295 </tr> 296 </table> 297 </div> 298 </body> 299</html> 300