1<!--$Id: db_cursor.so,v 10.55 2007/10/24 16:06:06 bostic Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 6<title>Berkeley DB: DB->cursor</title> 7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<table width="100%"><tr valign=top> 12<td> 13<b>DB->cursor</b> 14</td> 15<td align=right> 16<a href="/api_c/api_core.html"><img src="/images/api.gif" alt="API"></a> 17<a href="/ref/toc.html"><img src="/images/ref.gif" alt="Ref"></a></td> 18</tr></table> 19<hr size=1 noshade> 20<tt> 21<b><pre> 22#include <db.h> 23<p> 24int 25DB->cursor(DB *db, 26 DB_TXN *txnid, DBC **cursorp, u_int32_t flags); 27</pre></b> 28<hr size=1 noshade> 29<b>Description: DB->cursor</b> 30<p>The DB->cursor method returns a created database cursor.</p> 31<p>Cursors may span threads, but only serially, that is, the application 32must serialize access to the cursor handle.</p> 33<p>The DB->cursor method 34returns a non-zero error value on failure 35and 0 on success. 36</p> 37<b>Parameters</b> <br> 38 <b>cursorp</b><ul compact><li>The <b>cursorp</b> parameter references memory into which 39a pointer to the allocated cursor is copied.</ul> 40 <b>flags</b><ul compact><li>The <b>flags</b> parameter must be set to 0 or by bitwise inclusively <b>OR</b>'ing together one 41or more of the following values: 42<br> 43<b><a name="DB_READ_COMMITTED">DB_READ_COMMITTED</a></b><ul compact><li>Configure a transactional cursor to have degree 2 isolation. This ensures 44the stability of the current data item read by this cursor but permits data 45read by this cursor to be modified or deleted prior to the commit of the 46transaction for this cursor.</ul> 47<b><a name="DB_READ_UNCOMMITTED">DB_READ_UNCOMMITTED</a></b><ul compact><li>Configure a transactional cursor to have degree 1 isolation. Read 48operations performed by the cursor may return modified but not yet 49committed data. Silently ignored if the <a href="/api_c/db_open.html#DB_READ_UNCOMMITTED">DB_READ_UNCOMMITTED</a> 50flag was not specified when the underlying database was opened.</ul> 51<b><a name="DB_WRITECURSOR">DB_WRITECURSOR</a></b><ul compact><li>Specify that the cursor will be used to update the database. The 52underlying database environment must have been opened using the 53<a href="/api_c/env_open.html#DB_INIT_CDB">DB_INIT_CDB</a> flag.</ul> 54<b><a name="DB_TXN_SNAPSHOT">DB_TXN_SNAPSHOT</a></b><ul compact><li>Configure a transactional cursor to operate with read-only 55<a href="/ref/transapp/read.html">snapshot isolation</a>. For databases 56with the <a href="/api_c/db_open.html#DB_MULTIVERSION">DB_MULTIVERSION</a> flag set, data values will be read as 57they are when the cursor is opened, without taking read locks. This 58flag implicitly begins a transaction that is committed when the cursor 59is closed. Silently ignored if <a href="/api_c/db_open.html#DB_MULTIVERSION">DB_MULTIVERSION</a> not set on the 60underlying database or if a transaction is supplied in the <b>txnid</b> 61parameter.</ul> 62<br></ul> 63 <b>txnid</b><ul compact><li>Cursor operations are not automatically transaction-protected, even if 64the <a href="/api_c/env_set_flags.html#DB_AUTO_COMMIT">DB_AUTO_COMMIT</a> flag is specified to the 65<a href="/api_c/env_set_flags.html">DB_ENV->set_flags</a> or <a href="/api_c/db_open.html">DB->open</a> methods. If cursor operations are 66to be transaction-protected, the <b>txnid</b> parameter must be a 67transaction handle returned from <a href="/api_c/txn_begin.html">DB_ENV->txn_begin</a>; otherwise, NULL. To 68transaction-protect cursor operations, cursors must be opened and closed 69within the context of a transaction, and the <b>txnid</b> parameter 70specifies the transaction context in which the cursor may be used.</ul> 71<br> 72<br><b>Errors</b> 73<p>The DB->cursor method 74may fail and return one of the following non-zero errors:</p> 75<br> 76<b>DB_REP_HANDLE_DEAD</b><ul compact><li>The database handle has been invalidated because a replication election 77unrolled a committed transaction.</ul> 78<br> 79<br> 80<b>DB_REP_LOCKOUT</b><ul compact><li>The operation was blocked by client/master synchronization.</ul> 81<br> 82<br> 83<b>EINVAL</b><ul compact><li>An 84invalid flag value or parameter was specified.</ul> 85<br> 86<hr size=1 noshade> 87<br><b>Class</b> 88<a href="/api_c/dbc_class.html">DBC</a> 89<br><b>See Also</b> 90<a href="/api_c/dbc_list.html">Database Cursors and Related Methods</a> 91</tt> 92<table width="100%"><tr><td><br></td><td align=right> 93<a href="/api_c/api_core.html"><img src="/images/api.gif" alt="API"></a><a href="/ref/toc.html"><img src="/images/ref.gif" alt="Ref"></a> 94</td></tr></table> 95<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 96</body> 97</html> 98
