85 lines
3.1 KiB
Plaintext
85 lines
3.1 KiB
Plaintext
m4_comment([$Id: db_put.so,v 10.60 2007/10/24 16:06:06 bostic Exp $])
|
|
|
|
define(M4PAGELOCAL, [dbh_put, DB_APPEND, DB_NODUPDATA, DB_NOOVERWRITE])
|
|
include(m4/m4.seealso)
|
|
|
|
m4_pf_header(m4_ref(dbh_put),
|
|
ifelse(M4API, C_API, [dnl
|
|
int
|
|
DB-__GT__put(DB *db,
|
|
DB_TXN *txnid, DBT *key, DBT *data, u_int32_t flags);
|
|
])
|
|
ifelse(M4API, CXX_API, [dnl
|
|
int
|
|
Db::put(DbTxn *txnid, Dbt *key, Dbt *data, u_int32_t flags);
|
|
]))
|
|
|
|
m4_p([dnl
|
|
The m4_refT(dbh_put) stores key/data pairs in the database. The default
|
|
behavior of the m4_ref(dbh_put) function is to enter the new key/data
|
|
pair, replacing any previously existing key if duplicates are disallowed,
|
|
or adding a duplicate data item if duplicates are allowed. If the database
|
|
supports duplicates, the m4_refT(dbh_put) adds the new data value at the
|
|
end of the duplicate set. If the database supports sorted duplicates,
|
|
the new data value is inserted at the correct sorted location.])
|
|
|
|
m4_return(dbh_put, prev)
|
|
|
|
m4_parambegin
|
|
m4_param(flags, [dnl
|
|
m4_sf_zmust(1)
|
|
|
|
m4_tagbegin
|
|
m4_tag(m4_idef(DB_APPEND), [dnl
|
|
Append the key/data pair to the end of the database. For the
|
|
DB_APPEND flag to be specified, the underlying database must be
|
|
a Queue or Recno database. The record number allocated to the record is
|
|
returned in the specified m4_arg(key).
|
|
m4_p([dnl
|
|
There is a minor behavioral difference between the Recno and Queue access
|
|
methods for the m4_ref(DB_APPEND) flag. If a transaction enclosing a
|
|
m4_ref(dbh_put) operation with the m4_ref(DB_APPEND) flag aborts, the
|
|
record number may be decremented (and later reallocated by a subsequent
|
|
m4_ref(DB_APPEND) operation) by the Recno access method, but will not be
|
|
decremented or reallocated by the Queue access method.])])
|
|
|
|
m4_tag(m4_idef(DB_NODUPDATA), [dnl
|
|
In the case of the Btree and Hash access methods, enter the new key/data
|
|
pair only if it does not already appear in the database.
|
|
m4_p([dnl
|
|
The DB_NODUPDATA flag may only be specified if the underlying
|
|
database has been configured to support sorted duplicates. The
|
|
DB_NODUPDATA flag may not be specified to the Queue or Recno
|
|
access methods.])
|
|
m4_return(dbh_put, specific, DB_KEYEXIST,
|
|
[if m4_ref(DB_NODUPDATA) is set and the key/data pair already appears
|
|
in the database])])
|
|
|
|
m4_tag(m4_idef(DB_NOOVERWRITE), [dnl
|
|
Enter the new key/data pair only if the key does not already appear in the
|
|
database. The m4_refT(dbh_put) call with the DB_NOOVERWRITE flag
|
|
set will fail if the key already exists in the database, even if the database
|
|
supports duplicates.
|
|
m4_return(dbh_put, specific, DB_KEYEXIST,
|
|
[if m4_ref(DB_NOOVERWRITE) is set and the key already appears in the
|
|
database])])
|
|
m4_tagend])
|
|
|
|
m4_param_data
|
|
m4_param_key
|
|
m4_param_txn(dbh_put)
|
|
m4_paramend
|
|
|
|
m4_idefz(DB_REP_HANDLE_DEAD)
|
|
m4_idefz(DB_REP_LOCKOUT)
|
|
m4_err(dbh_put, deadlock, rephandle, replockout, readonly, einval,
|
|
[a record number of 0 was specified;
|
|
an attempt was made to add a record to a fixed-length database that was too
|
|
large to fit;
|
|
an attempt was made to do a partial put;
|
|
an attempt was made to add a record to a secondary index],
|
|
ENOSPC, [A btree exceeded the maximum btree depth (255).])
|
|
|
|
m4_seealso(Db)
|
|
m4_page_footer
|