| DBcursor->get |
|
#include <db.h>int DBcursor->get(DBC *DBcursor, DBT *key, DBT *data, u_int32_t flags);
int DBcursor->pget(DBC *DBcursor, DBT *key, DBT *pkey, DBT *data, u_int32_t flags);
The DBcursor->get method retrieves key/data pairs from the database. The address and length of the key are returned in the object to which key refers (except for the case of the DB_SET flag, in which the key object is unchanged), and the address and length of the data are returned in the object to which data refers.
When called on a cursor opened on a database that has been made into a secondary index using the DB->associate method, the DBcursor->get and DBcursor->pget methods return the key from the secondary index and the data item from the primary database. In addition, the DBcursor->pget method returns the key from the primary database. In databases that are not secondary indices, the DBcursor->pget method will always fail.
Modifications to the database during a sequential scan will be reflected in the scan; that is, records inserted behind a cursor will not be returned while records inserted in front of a cursor will be returned.
In Queue and Recno databases, missing entries (that is, entries that were never explicitly created or that were created and then deleted) will be skipped during a sequential scan.
Unless otherwise specified, the DBcursor->get method returns a non-zero error value on failure and 0 on success.
If DBcursor->get fails for any reason, the state of the cursor will be unchanged.
ParametersThe DBcursor->get method will return DB_KEYEMPTY if DB_CURRENT is set and the cursor key/data pair was deleted.
If the database is a Queue or Recno database, DBcursor->get using the DB_FIRST flag will ignore any keys that exist but were never explicitly created by the application, or were created and later deleted.
The DBcursor->get method will return DB_NOTFOUND if DB_FIRST is set and the database is empty.
When used with the DBcursor->pget method version of this method on a secondary index handle, both the secondary and primary keys must be matched by the secondary and primary key item in the database. It is an error to use the DB_GET_BOTH flag with the DBcursor->get version of this method and a cursor that has been opened on a secondary index handle.
For DB_GET_RECNO to be specified, the underlying database must be of type Btree, and it must have been created with the DB_RECNUM flag.
When called on a cursor opened on a database that has been made into a secondary index, the DBcursor->get and DBcursor->pget methods return the record number of the primary database in data. In addition, the DBcursor->pget method returns the record number of the secondary index in pkey. If either underlying database is not of type Btree or is not created with the DB_RECNUM flag, the out-of-band record number of 0 is returned.
For DB_JOIN_ITEM to be specified, the underlying cursor must have been returned from the DB->join method.
If the database is a Queue or Recno database, DBcursor->get using the DB_LAST flag will ignore any keys that exist but were never explicitly created by the application, or were created and later deleted.
The DBcursor->get method will return DB_NOTFOUND if DB_LAST is set and the database is empty.
If the database is a Queue or Recno database, DBcursor->get using the DB_NEXT flag will skip any keys that exist but were never explicitly created by the application, or those that were created and later deleted.
The DBcursor->get method will return DB_NOTFOUND if DB_NEXT is set and the cursor is already on the last record in the database.
The DBcursor->get method will return DB_NOTFOUND if DB_NEXT_DUP is set and the next key/data pair of the database is not a duplicate data record for the current key/data pair.
If the database is a Queue or Recno database, DBcursor->get using the DB_NEXT_NODUP flag will ignore any keys that exist but were never explicitly created by the application, or those that were created and later deleted.
The DBcursor->get method will return DB_NOTFOUND if DB_NEXT_NODUP is set and no non-duplicate key/data pairs occur after the cursor position in the database.
If the database is a Queue or Recno database, DBcursor->get using the DB_PREV flag will skip any keys that exist but were never explicitly created by the application, or those that were created and later deleted.
The DBcursor->get method will return DB_NOTFOUND if DB_PREV is set and the cursor is already on the first record in the database.
The DBcursor->get method will return DB_NOTFOUND if DB_PREV_DUP is set and the previous key/data pair of the database is not a duplicate data record for the current key/data pair.
If the database is a Queue or Recno database, DBcursor->get using the DB_PREV_NODUP flag will ignore any keys that exist but were never explicitly created by the application, or those that were created and later deleted.
The DBcursor->get method will return DB_NOTFOUND if DB_PREV_NODUP is set and no non-duplicate key/data pairs occur before the cursor position in the database.
The DBcursor->get method will return DB_NOTFOUND if DB_SET is set and no matching keys are found. The DBcursor->get method will return DB_KEYEMPTY if DB_SET is set and the database is a Queue or Recno database, and the specified key exists, but was never explicitly created by the application or was later deleted. In the presence of duplicate key values, DBcursor->get will return the first data item for the given key.
For DB_SET_RECNO to be specified, the underlying database must be of type Btree, and it must have been created with the DB_RECNUM flag.
In the case of Btree or Hash databases, duplicate data items for the current key, starting at the current cursor position, are entered into the buffer. Subsequent calls with both the DB_NEXT_DUP and DB_MULTIPLE flags specified will return additional duplicate data items associated with the current key or DB_NOTFOUND if there are no additional duplicate data items to return. Subsequent calls with both the DB_NEXT and DB_MULTIPLE flags specified will return additional duplicate data items associated with the current key or if there are no additional duplicate data items will return the next key and its data items or DB_NOTFOUND if there are no additional keys in the database.
In the case of Queue or Recno databases, data items starting at the current cursor position are entered into the buffer. The record number of the first record will be returned in the key parameter. The record number of each subsequent returned record must be calculated from this value. Subsequent calls with the DB_MULTIPLE flag specified will return additional data items or DB_NOTFOUND if there are no additional data items to return.
The buffer to which the data parameter refers must be provided from user memory (see DB_DBT_USERMEM). The buffer must be at least as large as the page size of the underlying database, aligned for unsigned integer access, and be a multiple of 1024 bytes in size. If the buffer size is insufficient, then upon return from the call the size field of the data parameter will have been set to an estimated buffer size, and the error DB_BUFFER_SMALL is returned. (The size is an estimate as the exact size needed may not be known until all entries are read. It is best to initially provide a relatively large buffer, but applications should be prepared to resize the buffer as necessary and repeatedly call the method.)
The multiple data items can be iterated over using the DB_MULTIPLE_NEXT macro.
The DB_MULTIPLE flag may only be used with the DB_CURRENT, DB_FIRST, DB_GET_BOTH, DB_GET_BOTH_RANGE, DB_NEXT, DB_NEXT_DUP, DB_NEXT_NODUP, DB_SET, DB_SET_RANGE, and DB_SET_RECNO options. The DB_MULTIPLE flag may not be used when accessing databases made into secondary indices using the DB->associate method.
Key and data pairs, starting at the current cursor position, are entered into the buffer. Subsequent calls with both the DB_NEXT and DB_MULTIPLE_KEY flags specified will return additional key and data pairs or DB_NOTFOUND if there are no additional key and data items to return.
In the case of Btree or Hash databases, the multiple key and data pairs can be iterated over using the DB_MULTIPLE_KEY_NEXT macro.
In the case of Queue or Recno databases, the multiple record number and data pairs can be iterated over using the DB_MULTIPLE_RECNO_NEXT macro.
The buffer to which the data parameter refers must be provided from user memory (see DB_DBT_USERMEM). The buffer must be at least as large as the page size of the underlying database, aligned for unsigned integer access, and be a multiple of 1024 bytes in size. If the buffer size is insufficient, then upon return from the call the size field of the data parameter will have been set to an estimated buffer size, and the error DB_BUFFER_SMALL is returned. (The size is an estimate as the exact size needed may not be known until all entries are read. It is best to initially provide a relatively large buffer, but applications should be prepared to resize the buffer as necessary and repeatedly call the method.)
The DB_MULTIPLE_KEY flag may only be used with the DB_CURRENT, DB_FIRST, DB_GET_BOTH, DB_GET_BOTH_RANGE, DB_NEXT, DB_NEXT_DUP, DB_NEXT_NODUP, DB_SET, DB_SET_RANGE, and DB_SET_RECNO options. The DB_MULTIPLE_KEY flag may not be used when accessing databases made into secondary indices using the DB->associate method.
The DBcursor->get method may fail and return one of the following non-zero errors:
|
|
Copyright (c) 1996,2008 Oracle. All rights reserved.