345 lines
15 KiB
Plaintext
345 lines
15 KiB
Plaintext
m4_comment([$Id: dbc_get.so,v 10.121 2007/10/24 16:06:07 bostic Exp $])
|
|
|
|
define(M4PAGELOCAL,
|
|
[dbc_get, dbc_pget, DB_CURRENT, DB_FIRST, DB_GET_BOTH,
|
|
DB_GET_BOTH_RANGE, DB_GET_RECNO, DB_IGNORE_LEASE, DB_JOIN_ITEM,
|
|
DB_LAST, DB_MULTIPLE, DB_MULTIPLE_KEY, DB_NEXT, DB_NEXT_DUP,
|
|
DB_NEXT_NODUP, DB_PREV, DB_PREV_DUP, DB_PREV_NODUP, DB_SET,
|
|
DB_SET_RANGE, DB_SET_RECNO])
|
|
|
|
include(m4/m4.seealso)
|
|
|
|
m4_pf_header(m4_ref(dbc_get),
|
|
ifelse(M4API, C_API, [dnl
|
|
int
|
|
DBcursor-__GT__get(DBC *DBcursor,
|
|
DBT *key, DBT *data, u_int32_t flags);
|
|
m4_blank
|
|
int
|
|
DBcursor-__GT__pget(DBC *DBcursor,
|
|
DBT *key, DBT *pkey, DBT *data, u_int32_t flags);
|
|
])
|
|
ifelse(M4API, CXX_API, [dnl
|
|
int
|
|
Dbc::get(Dbt *key, Dbt *data, u_int32_t flags);
|
|
m4_blank
|
|
int
|
|
Dbc::pget(Dbt *key, Dbt *pkey, Dbt *data, u_int32_t flags);
|
|
]))
|
|
|
|
m4_p([dnl
|
|
The m4_refT(dbc_get) retrieves key/data pairs from the database. The
|
|
address and length of the key are returned in the object to which
|
|
m4_arg(key) refers (except for the case of the m4_ref(DB_SET) flag, in
|
|
which the m4_arg(key) object is unchanged), and the address and length
|
|
of the data are returned in the object to which m4_arg(data) refers.])
|
|
|
|
m4_p([dnl
|
|
When called on a cursor opened on a database that has been made into a
|
|
secondary index using the m4_refT(dbh_associate), the m4_ref(dbc_get)
|
|
and m4_refT(dbc_pget)s return the key from the secondary index and the
|
|
data item from the primary database. In addition, the m4_refT(dbc_pget)
|
|
returns the key from the primary database. In databases that are not
|
|
secondary indices, the m4_refT(dbc_pget) will always fail.])
|
|
|
|
m4_p([dnl
|
|
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.])
|
|
|
|
m4_p([dnl
|
|
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.])
|
|
|
|
m4_return(dbc_get, prev)
|
|
|
|
m4_p([dnl
|
|
If m4_ref(dbc_get) fails for any reason, the state of the cursor will be
|
|
unchanged.])
|
|
|
|
m4_parambegin
|
|
m4_param_data
|
|
m4_param(flags, [dnl
|
|
m4_sf_must
|
|
|
|
m4_tagbegin
|
|
m4_tag(m4_idef(DB_CURRENT), [dnl
|
|
Return the key/data pair to which the cursor refers.
|
|
m4_return(dbc_get, specific, DB_KEYEMPTY,
|
|
[if m4_ref(DB_CURRENT) is set and the cursor key/data pair was deleted])])
|
|
|
|
m4_tag([m4_idef(DB_FIRST)], [dnl
|
|
The cursor is set to refer to the first key/data pair of the database,
|
|
and that pair is returned. If the first key has duplicate values, the
|
|
first data item in the set of duplicates is returned.
|
|
m4_p([dnl
|
|
If the database is a Queue or Recno database, m4_ref(dbc_get) using the
|
|
m4_ref(DB_FIRST) flag will ignore any keys that exist but were never
|
|
explicitly created by the application, or were created and later
|
|
deleted.])
|
|
m4_return(dbc_get, specific, DB_NOTFOUND,
|
|
[if m4_ref(DB_FIRST) is set and the database is empty])])
|
|
|
|
m4_tag(m4_idef(DB_GET_BOTH), [dnl
|
|
The m4_ref(DB_GET_BOTH) flag is identical to the m4_ref(DB_SET) flag,
|
|
except that both the key and the data parameters must be matched by the
|
|
key and data item in the database.
|
|
m4_p([dnl
|
|
When used with the m4_refT(dbc_pget) 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 m4_ref(DB_GET_BOTH) flag with the m4_ref(dbc_get)
|
|
version of this method and a cursor that has been opened on a secondary
|
|
index handle.])])
|
|
|
|
m4_tag(m4_idef(DB_GET_BOTH_RANGE), [dnl
|
|
The m4_ref(DB_GET_BOTH_RANGE) flag is identical to the m4_ref(DB_GET_BOTH)
|
|
flag, except that, in the case of any database supporting sorted
|
|
duplicate sets, the returned key/data pair is the smallest data item
|
|
greater than or equal to the specified data item (as determined by the
|
|
comparison function), permitting partial matches and range searches in
|
|
duplicate data sets.])
|
|
|
|
m4_tag(m4_idef(DB_GET_RECNO), [dnl
|
|
Return the record number associated with the cursor. The record number
|
|
will be returned in m4_arg(data), as described in m4_ref(Dbt). The
|
|
m4_arg(key) parameter is ignored.
|
|
m4_p([dnl
|
|
For m4_ref(DB_GET_RECNO) to be specified, the underlying database must be
|
|
of type Btree, and it must have been created with the m4_ref(DB_RECNUM)
|
|
flag.])
|
|
m4_p([dnl
|
|
When called on a cursor opened on a database that has been made into a
|
|
secondary index, the m4_ref(dbc_get) and m4_refT(dbc_pget)s return the
|
|
record number of the primary database in m4_arg(data). In addition, the
|
|
m4_refT(dbc_pget) returns the record number of the secondary index in
|
|
m4_arg(pkey). If either underlying database is not of type Btree or is
|
|
not created with the m4_ref(DB_RECNUM) flag, the out-of-band record
|
|
number of 0 is returned.])])
|
|
|
|
m4_tag(m4_idef(DB_JOIN_ITEM), [dnl
|
|
Do not use the data value found in all of the cursors as a lookup key for
|
|
the primary database, but simply return it in the key parameter instead.
|
|
The data parameter is left unchanged.
|
|
m4_p([dnl
|
|
For m4_ref(DB_JOIN_ITEM) to be specified, the underlying cursor must have
|
|
been returned from the m4_refT(dbh_join).])])
|
|
|
|
m4_tag([m4_idef(DB_LAST)], [dnl
|
|
The cursor is set to refer to the last key/data pair of the database,
|
|
and that pair is returned. If the last key has duplicate values, the
|
|
last data item in the set of duplicates is returned.
|
|
m4_p([dnl
|
|
If the database is a Queue or Recno database, m4_ref(dbc_get) using the
|
|
m4_ref(DB_LAST) flag will ignore any keys that exist but were never
|
|
explicitly created by the application, or were created and later
|
|
deleted.])
|
|
m4_return(dbc_get, specific, DB_NOTFOUND,
|
|
[if m4_ref(DB_LAST) is set and the database is empty])])
|
|
|
|
m4_tag([m4_idef(DB_NEXT)], [dnl
|
|
If the cursor is not yet initialized, m4_ref(DB_NEXT) is identical to
|
|
m4_ref(DB_FIRST). Otherwise, the cursor is moved to the next key/data
|
|
pair of the database, and that pair is returned. In the presence of
|
|
duplicate key values, the value of the key may not change.
|
|
m4_p([dnl
|
|
If the database is a Queue or Recno database, m4_ref(dbc_get) using the
|
|
m4_ref(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.])
|
|
m4_return(dbc_get, specific, DB_NOTFOUND,
|
|
[if m4_ref(DB_NEXT) is set and the cursor is already on the last record
|
|
in the database])])
|
|
|
|
m4_tag(m4_idef(DB_NEXT_DUP), [dnl
|
|
If the next key/data pair of the database is a duplicate data record for
|
|
the current key/data pair, the cursor is moved to the next key/data pair
|
|
of the database, and that pair is returned.
|
|
m4_return(dbc_get, specific, DB_NOTFOUND,
|
|
[if m4_ref(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])])
|
|
|
|
m4_tag([dnl
|
|
m4_idef(DB_NEXT_NODUP)], [dnl
|
|
If the cursor is not yet initialized, m4_ref(DB_NEXT_NODUP) is identical
|
|
to m4_ref(DB_FIRST). Otherwise, the cursor is moved to the next
|
|
non-duplicate key of the database, and that key/data pair is returned.
|
|
m4_p([dnl
|
|
If the database is a Queue or Recno database, m4_ref(dbc_get) using the
|
|
m4_ref(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.])
|
|
m4_return(dbc_get, specific, DB_NOTFOUND,
|
|
[if m4_ref(DB_NEXT_NODUP) is set and no non-duplicate key/data pairs
|
|
occur after the cursor position in the database])])
|
|
|
|
m4_tag([m4_idef(DB_PREV)], [dnl
|
|
If the cursor is not yet initialized, m4_ref(DB_PREV) is identical to
|
|
m4_ref(DB_LAST). Otherwise, the cursor is moved to the previous
|
|
key/data pair of the database, and that pair is returned. In the
|
|
presence of duplicate key values, the value of the key may not change.
|
|
m4_p([dnl
|
|
If the database is a Queue or Recno database, m4_ref(dbc_get) using the
|
|
m4_ref(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.])
|
|
m4_return(dbc_get, specific, DB_NOTFOUND,
|
|
[if m4_ref(DB_PREV) is set and the cursor is already on the first record
|
|
in the database])])
|
|
|
|
m4_tag(m4_idef(DB_PREV_DUP), [dnl
|
|
If the previous key/data pair of the database is a duplicate data record
|
|
for the current key/data pair, the cursor is moved to the previous key/data
|
|
pair of the database, and that pair is returned.
|
|
m4_return(dbc_get, specific, DB_NOTFOUND,
|
|
[if m4_ref(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])])
|
|
|
|
m4_tag([dnl
|
|
m4_idef(DB_PREV_NODUP)], [dnl
|
|
If the cursor is not yet initialized, m4_ref(DB_PREV_NODUP) is identical
|
|
to m4_ref(DB_LAST). Otherwise, the cursor is moved to the previous
|
|
non-duplicate key of the database, and that key/data pair is returned.
|
|
m4_p([dnl
|
|
If the database is a Queue or Recno database, m4_ref(dbc_get) using the
|
|
m4_ref(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.])
|
|
m4_return(dbc_get, specific, DB_NOTFOUND,
|
|
[if m4_ref(DB_PREV_NODUP) is set and no non-duplicate key/data pairs
|
|
occur before the cursor position in the database])])
|
|
|
|
m4_tag(m4_idef(DB_SET), [dnl
|
|
Move the cursor to the specified key/data pair of the database, and
|
|
return the datum associated with the given key.
|
|
m4_return(dbc_get, specific, DB_NOTFOUND, [if m4_ref(DB_SET) is set and
|
|
no matching keys are found],
|
|
specific, DB_KEYEMPTY, [if m4_ref(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, m4_ref(dbc_get) will return the
|
|
first data item for the given key.])])
|
|
|
|
m4_tag(m4_idef(DB_SET_RANGE), [dnl
|
|
The m4_ref(DB_SET_RANGE) flag is identical to the m4_ref(DB_SET) flag,
|
|
except that in the case of the Btree access method, the key is returned
|
|
as well as the data item and the returned key/data pair is the smallest
|
|
key greater than or equal to the specified key (as determined by the
|
|
Btree comparison function), permitting partial key matches and range
|
|
searches.])
|
|
|
|
m4_tag(m4_idef(DB_SET_RECNO), [dnl
|
|
Move the cursor to the specific numbered record of the database, and
|
|
return the associated key/data pair. The m4_arg(data) field of the
|
|
specified m4_arg(key) must be a pointer to a memory location from which
|
|
a m4_ref(db_recno_t) may be read, as described in m4_ref(Dbt). This
|
|
memory location will be read to determine the record to be retrieved.
|
|
m4_p([dnl
|
|
For m4_ref(DB_SET_RECNO) to be specified, the underlying database must be
|
|
of type Btree, and it must have been created with the m4_ref(DB_RECNUM)
|
|
flag.])])
|
|
m4_tagend
|
|
|
|
m4_sf_or_add(1)
|
|
|
|
m4_tagbegin
|
|
m4_tag(m4_idef(DB_IGNORE_LEASE), [dnl
|
|
Return the data item irrespective of the state of master leases. The
|
|
item will be returned under all conditions: if master leases are not
|
|
configured, if the request is made to a client, if the request is made
|
|
to a master with a valid lease, or if the request is made to a master
|
|
without a valid lease.])
|
|
|
|
m4_tag(m4_idef(DB_READ_UNCOMMITTED), [dnl
|
|
Database items read during a transactional call will have degree 1
|
|
isolation, including modified but not yet committed data. Silently
|
|
ignored if the m4_ref(DB_READ_UNCOMMITTED) flag was not specified when
|
|
the underlying database was opened.])
|
|
|
|
m4_tag(m4_idef(DB_MULTIPLE), [dnl
|
|
Return multiple data items in the m4_arg(data) parameter.
|
|
m4_p([dnl
|
|
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 m4_ref(DB_NEXT_DUP) and
|
|
m4_ref(DB_MULTIPLE) flags specified will return additional duplicate
|
|
data items associated with the current key or m4_ref(DB_NOTFOUND) if
|
|
there are no additional duplicate data items to return. Subsequent
|
|
calls with both the m4_ref(DB_NEXT) and m4_ref(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 m4_ref(DB_NOTFOUND) if there
|
|
are no additional keys in the database.])
|
|
m4_p([dnl
|
|
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 m4_arg(key) parameter. The
|
|
record number of each subsequent returned record must be calculated from
|
|
this value. Subsequent calls with the m4_ref(DB_MULTIPLE) flag
|
|
specified will return additional data items or m4_ref(DB_NOTFOUND) if
|
|
there are no additional data items to return.])
|
|
m4_p([dnl
|
|
m4_bulk_mem])
|
|
m4_p([dnl
|
|
The multiple data items can be iterated over using the
|
|
ifelse(M4API, C_API, m4_ref(DB_MULTIPLE_NEXT) macro,
|
|
m4_ref(DbMultipleDataIterator) class).])
|
|
m4_p([dnl
|
|
The m4_ref(DB_MULTIPLE) flag may only be used with the
|
|
m4_ref(DB_CURRENT), m4_ref(DB_FIRST), m4_ref(DB_GET_BOTH),
|
|
m4_ref(DB_GET_BOTH_RANGE), m4_ref(DB_NEXT), m4_ref(DB_NEXT_DUP),
|
|
m4_ref(DB_NEXT_NODUP), m4_ref(DB_SET), m4_ref(DB_SET_RANGE), and
|
|
m4_ref(DB_SET_RECNO) options. The m4_ref(DB_MULTIPLE) flag may not be
|
|
used when accessing databases made into secondary indices using the
|
|
m4_refT(dbh_associate).])])
|
|
|
|
m4_tag(m4_idef(DB_MULTIPLE_KEY), [dnl
|
|
Return multiple key and data pairs in the m4_arg(data) parameter.
|
|
m4_p([dnl
|
|
Key and data pairs, starting at the current cursor position, are entered
|
|
into the buffer. Subsequent calls with both the m4_ref(DB_NEXT) and
|
|
m4_ref(DB_MULTIPLE_KEY) flags specified will return additional key and data
|
|
pairs or m4_ref(DB_NOTFOUND) if there are no additional key and data
|
|
items to return.])
|
|
m4_p([dnl
|
|
In the case of Btree or Hash databases,
|
|
the multiple key and data pairs can be iterated over using the
|
|
ifelse(M4API, C_API, m4_ref(DB_MULTIPLE_KEY_NEXT) macro,
|
|
m4_ref(DbMultipleKeyDataIterator) class).])
|
|
m4_p([dnl
|
|
In the case of Queue or Recno databases,
|
|
the multiple record number and data pairs can be iterated over using the
|
|
ifelse(M4API, C_API, m4_ref(DB_MULTIPLE_RECNO_NEXT) macro,
|
|
m4_ref(DbMultipleRecnoDataIterator) class).])
|
|
m4_p([dnl
|
|
m4_bulk_mem])
|
|
m4_p([dnl
|
|
The m4_ref(DB_MULTIPLE_KEY) flag may only be used with the
|
|
m4_ref(DB_CURRENT), m4_ref(DB_FIRST), m4_ref(DB_GET_BOTH),
|
|
m4_ref(DB_GET_BOTH_RANGE), m4_ref(DB_NEXT), m4_ref(DB_NEXT_DUP),
|
|
m4_ref(DB_NEXT_NODUP), m4_ref(DB_SET), m4_ref(DB_SET_RANGE), and
|
|
m4_ref(DB_SET_RECNO) options. The m4_ref(DB_MULTIPLE_KEY) flag may not
|
|
be used when accessing databases made into secondary indices using the
|
|
m4_refT(dbh_associate).])])
|
|
|
|
m4_rmw_flag()
|
|
m4_tagend])
|
|
|
|
m4_param_key
|
|
|
|
m4_param(pkey, [The secondary index key m4_ref(Dbt) operated on.])
|
|
m4_paramend
|
|
|
|
m4_err(dbc_get,
|
|
buffersmall,
|
|
[requested item could not be returned due to undersized buffer],
|
|
deadlock, rephandle, replease, replockout, secondary_bad, einval,
|
|
[the m4_ref(DB_CURRENT), m4_ref(DB_NEXT_DUP) or m4_ref(DB_PREV_DUP) flags
|
|
were specified and the cursor has not been initialized;
|
|
the m4_refT(dbc_pget) was called with a cursor that does not refer to a
|
|
secondary index])
|
|
|
|
m4_seealso(Dbc)
|
|
m4_page_footer
|