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