Edit File - File Manager

Edit File: curget.html

<html>
<head>
<title>Berkeley DB Reference Guide: Retrieving records with a 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>
<a name="2"></a><a name="3"></a>
<table width="100%"><tr valign=top>
<td><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></td>
<td align=right><a href="../am/cursor.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../am/curput.html"><img src="../../images/next.gif" alt="Next"></a>
</td></tr></table>
Retrieving records with a cursor
The <a href="../../api_c/dbc_get.html">DBcursor-&gt;get</a> method retrieves records from the database using a cursor.
The <a href="../../api_c/dbc_get.html">DBcursor-&gt;get</a> method takes a flag which controls how the cursor is
positioned within the database and returns the key/data item associated
with that positioning. Similar to <a href="../../api_c/db_get.html">DB-&gt;get</a>, <a href="../../api_c/dbc_get.html">DBcursor-&gt;get</a> may
also take a supplied key and retrieve the data associated with that key
from the database. There are several flags that you can set to
customize retrieval.
Cursor position flags
 
<a href="../../api_c/dbc_get.html#DB_FIRST">DB_FIRST</a>, <a href="../../api_c/dbc_get.html#DB_LAST">DB_LAST</a><ul compact><li>Return the first (last) record in the database.</ul>
<a href="../../api_c/dbc_get.html#DB_NEXT">DB_NEXT</a>, <a href="../../api_c/dbc_get.html#DB_PREV">DB_PREV</a><ul compact><li>Return the next (previous) record in the database.</ul>
<a href="../../api_c/dbc_get.html#DB_NEXT_DUP">DB_NEXT_DUP</a><ul compact><li>Return the next record in the database, if it is a duplicate data item
for the current key.</ul>
<a href="../../api_c/dbc_get.html#DB_NEXT_NODUP">DB_NEXT_NODUP</a>, <a href="../../api_c/dbc_get.html#DB_PREV_NODUP">DB_PREV_NODUP</a><ul compact><li>Return the next (previous) record in the database that is not a
duplicate data item for the current key.</ul>
<a href="../../api_c/dbc_get.html#DB_CURRENT">DB_CURRENT</a><ul compact><li>Return the record from the database to which the cursor currently refers.</ul>
 
Retrieving specific key/data pairs
 
<a href="../../api_c/dbc_get.html#DB_SET">DB_SET</a><ul compact><li>Return the record from the database that matches the supplied key. In
the case of duplicates the first duplicate is returned and the cursor
is positioned at the beginning of the duplicate list. The user can then
traverse the duplicate entries for the key.</ul>
<a href="../../api_c/dbc_get.html#DB_SET_RANGE">DB_SET_RANGE</a><ul compact><li>Return the smallest record in the database greater than or equal to the
supplied key. This functionality permits partial key matches and range
searches in the Btree access method.</ul>
<a href="../../api_c/db_get.html#DB_GET_BOTH">DB_GET_BOTH</a><ul compact><li>Return the record from the database that matches both the supplied key
and data items. This is particularly useful when there are large
numbers of duplicate records for a key, as it allows the cursor to
easily be positioned at the correct place for traversal of some part of
a large set of duplicate records.</ul>
<a href="../../api_c/db_get.html#DB_GET_BOTH_RANGE">DB_GET_BOTH_RANGE</a><ul compact><li>Return the smallest record in the database greater than or equal to the
supplied key and data items.</ul>
 
Retrieving based on record numbers
 
<a href="../../api_c/db_get.html#DB_SET_RECNO">DB_SET_RECNO</a><ul compact><li>If the underlying database is a Btree, and was configured so that it is
possible to search it by logical record number, retrieve a specific
record based on a record number argument.</ul>
<a href="../../api_c/dbc_get.html#DB_GET_RECNO">DB_GET_RECNO</a><ul compact><li>If the underlying database is a Btree, and was configured so that it is
possible to search it by logical record number, return the record number
for the record to which the cursor refers.</ul>
 
Special-purpose flags
 
<a href="../../api_c/db_get.html#DB_CONSUME">DB_CONSUME</a><ul compact><li>Read-and-delete: the first record (the head) of the queue is returned and
deleted. The underlying database must be a Queue.</ul>
<a href="../../api_c/dbc_get.html#DB_RMW">DB_RMW</a><ul compact><li>Read-modify-write: acquire write locks instead of read locks during
retrieval. This can enhance performance in threaded applications by
reducing the chance of deadlock.</ul>
 
In all cases, the cursor is repositioned by a <a href="../../api_c/dbc_get.html">DBcursor-&gt;get</a> operation
to point to the newly-returned key/data pair in the database.
The following is a code example showing a cursor walking through a
database and displaying the records it contains to the standard
output:
<blockquote><pre>int
display(database)
	char *database;
{
	DB *dbp;
	DBC *dbcp;
	DBT key, data;
	int close_db, close_dbc, ret;

	close_db = close_dbc = 0;

	/* Open the database. */
	if ((ret = db_create(&dbp, NULL, 0)) != 0) {
		fprintf(stderr,
		 "%s: db_create: %s\n", progname, db_strerror(ret));
		return (1);
	}
	close_db = 1;

	/* Turn on additional error output. */
	dbp-&gt;set_errfile(dbp, stderr);
	dbp-&gt;set_errpfx(dbp, progname);

	/* Open the database. */
	if ((ret =
	 dbp-&gt;open(dbp, NULL, database, NULL, DB_UNKNOWN, DB_RDONLY, 0)) != 0) {
		dbp-&gt;err(dbp, ret, "%s: DB-&gt;open", database);
		goto err;
	}

	/* Acquire a cursor for the database. */
	if ((ret = dbp-&gt;cursor(dbp, NULL, &dbcp, 0)) != 0) {
		dbp-&gt;err(dbp, ret, "DB-&gt;cursor");
		goto err;
	}
	close_dbc = 1;

	/* Initialize the key/data return pair. */
	memset(&key, 0, sizeof(key));
	memset(&data, 0, sizeof(data));

	/* Walk through the database and print out the key/data pairs. */
	while ((ret = dbcp-&gt;c_get(dbcp, &key, &data, DB_NEXT)) == 0)
		printf("%.*s : %.*s\n",
		 (int)key.size, (char *)key.data,
		 (int)data.size, (char *)data.data);
	if (ret != DB_NOTFOUND) {
		dbp-&gt;err(dbp, ret, "DBcursor-&gt;get");
		goto err;
	}

err:	if (close_dbc && (ret = dbcp-&gt;c_close(dbcp)) != 0)
		dbp-&gt;err(dbp, ret, "DBcursor-&gt;close");
	if (close_db && (ret = dbp-&gt;close(dbp, 0)) != 0)
		fprintf(stderr,
		 "%s: DB-&gt;close: %s\n", progname, db_strerror(ret));
	return (0);
}</pre></blockquote>
<table width="100%"><tr><td> </td><td align=right><a href="../am/cursor.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../am/curput.html"><img src="../../images/next.gif" alt="Next"></a>
</td></tr></table>
Copyright (c) 1996,2008 Oracle. All rights reserved.
</body>
</html>

Back to File Manager