1<!--$Id: curget.so,v 10.20 2003/10/18 19:15:52 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 Reference Guide: Retrieving records with a 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<a name="2"><!--meow--></a><a name="3"><!--meow--></a> 12<table width="100%"><tr valign=top> 13<td><b><dl><dt>Berkeley DB Reference Guide:<dd>Access Methods</dl></b></td> 14<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> 15</td></tr></table> 16<p align=center><b>Retrieving records with a cursor</b></p> 17<p>The <a href="../../api_c/dbc_get.html">DBcursor->get</a> method retrieves records from the database using a cursor. 18The <a href="../../api_c/dbc_get.html">DBcursor->get</a> method takes a flag which controls how the cursor is 19positioned within the database and returns the key/data item associated 20with that positioning. Similar to <a href="../../api_c/db_get.html">DB->get</a>, <a href="../../api_c/dbc_get.html">DBcursor->get</a> may 21also take a supplied key and retrieve the data associated with that key 22from the database. There are several flags that you can set to 23customize retrieval.</p> 24<b>Cursor position flags</b> 25<br> 26<b><a href="../../api_c/dbc_get.html#DB_FIRST">DB_FIRST</a>, <a href="../../api_c/dbc_get.html#DB_LAST">DB_LAST</a></b><ul compact><li>Return the first (last) record in the database.</ul> 27<b><a href="../../api_c/dbc_get.html#DB_NEXT">DB_NEXT</a>, <a href="../../api_c/dbc_get.html#DB_PREV">DB_PREV</a></b><ul compact><li>Return the next (previous) record in the database.</ul> 28<b><a href="../../api_c/dbc_get.html#DB_NEXT_DUP">DB_NEXT_DUP</a></b><ul compact><li>Return the next record in the database, if it is a duplicate data item 29for the current key.</ul> 30<b><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></b><ul compact><li>Return the next (previous) record in the database that is not a 31duplicate data item for the current key.</ul> 32<b><a href="../../api_c/dbc_get.html#DB_CURRENT">DB_CURRENT</a></b><ul compact><li>Return the record from the database to which the cursor currently refers.</ul> 33<br> 34<b>Retrieving specific key/data pairs</b> 35<br> 36<b><a href="../../api_c/dbc_get.html#DB_SET">DB_SET</a></b><ul compact><li>Return the record from the database that matches the supplied key. In 37the case of duplicates the first duplicate is returned and the cursor 38is positioned at the beginning of the duplicate list. The user can then 39traverse the duplicate entries for the key.</ul> 40<b><a href="../../api_c/dbc_get.html#DB_SET_RANGE">DB_SET_RANGE</a></b><ul compact><li>Return the smallest record in the database greater than or equal to the 41supplied key. This functionality permits partial key matches and range 42searches in the Btree access method.</ul> 43<b><a href="../../api_c/db_get.html#DB_GET_BOTH">DB_GET_BOTH</a></b><ul compact><li>Return the record from the database that matches both the supplied key 44and data items. This is particularly useful when there are large 45numbers of duplicate records for a key, as it allows the cursor to 46easily be positioned at the correct place for traversal of some part of 47a large set of duplicate records.</ul> 48<b><a href="../../api_c/db_get.html#DB_GET_BOTH_RANGE">DB_GET_BOTH_RANGE</a></b><ul compact><li>Return the smallest record in the database greater than or equal to the 49supplied key and data items.</ul> 50<br> 51<b>Retrieving based on record numbers</b> 52<br> 53<b><a href="../../api_c/db_get.html#DB_SET_RECNO">DB_SET_RECNO</a></b><ul compact><li>If the underlying database is a Btree, and was configured so that it is 54possible to search it by logical record number, retrieve a specific 55record based on a record number argument.</ul> 56<b><a href="../../api_c/dbc_get.html#DB_GET_RECNO">DB_GET_RECNO</a></b><ul compact><li>If the underlying database is a Btree, and was configured so that it is 57possible to search it by logical record number, return the record number 58for the record to which the cursor refers.</ul> 59<br> 60<b>Special-purpose flags</b> 61<br> 62<b><a href="../../api_c/db_get.html#DB_CONSUME">DB_CONSUME</a></b><ul compact><li>Read-and-delete: the first record (the head) of the queue is returned and 63deleted. The underlying database must be a Queue.</ul> 64<b><a href="../../api_c/dbc_get.html#DB_RMW">DB_RMW</a></b><ul compact><li>Read-modify-write: acquire write locks instead of read locks during 65retrieval. This can enhance performance in threaded applications by 66reducing the chance of deadlock.</ul> 67<br> 68<p>In all cases, the cursor is repositioned by a <a href="../../api_c/dbc_get.html">DBcursor->get</a> operation 69to point to the newly-returned key/data pair in the database.</p> 70<p>The following is a code example showing a cursor walking through a 71database and displaying the records it contains to the standard 72output:</p> 73<blockquote><pre>int 74display(database) 75 char *database; 76{ 77 DB *dbp; 78 DBC *dbcp; 79 DBT key, data; 80 int close_db, close_dbc, ret; 81<p> 82 close_db = close_dbc = 0; 83<p> 84 /* Open the database. */ 85 if ((ret = db_create(&dbp, NULL, 0)) != 0) { 86 fprintf(stderr, 87 "%s: db_create: %s\n", progname, db_strerror(ret)); 88 return (1); 89 } 90 close_db = 1; 91<p> 92 /* Turn on additional error output. */ 93 dbp->set_errfile(dbp, stderr); 94 dbp->set_errpfx(dbp, progname); 95<p> 96 /* Open the database. */ 97 if ((ret = 98 dbp->open(dbp, NULL, database, NULL, DB_UNKNOWN, DB_RDONLY, 0)) != 0) { 99 dbp->err(dbp, ret, "%s: DB->open", database); 100 goto err; 101 } 102<p> 103 /* Acquire a cursor for the database. */ 104 if ((ret = dbp->cursor(dbp, NULL, &dbcp, 0)) != 0) { 105 dbp->err(dbp, ret, "DB->cursor"); 106 goto err; 107 } 108 close_dbc = 1; 109<p> 110 /* Initialize the key/data return pair. */ 111 memset(&key, 0, sizeof(key)); 112 memset(&data, 0, sizeof(data)); 113<p> 114 /* Walk through the database and print out the key/data pairs. */ 115 while ((ret = dbcp->c_get(dbcp, &key, &data, DB_NEXT)) == 0) 116 printf("%.*s : %.*s\n", 117 (int)key.size, (char *)key.data, 118 (int)data.size, (char *)data.data); 119 if (ret != DB_NOTFOUND) { 120 dbp->err(dbp, ret, "DBcursor->get"); 121 goto err; 122 } 123<p> 124err: if (close_dbc && (ret = dbcp->c_close(dbcp)) != 0) 125 dbp->err(dbp, ret, "DBcursor->close"); 126 if (close_db && (ret = dbp->close(dbp, 0)) != 0) 127 fprintf(stderr, 128 "%s: DB->close: %s\n", progname, db_strerror(ret)); 129 return (0); 130}</pre></blockquote> 131<table width="100%"><tr><td><br></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> 132</td></tr></table> 133<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 134</body> 135</html> 136
