m4_comment([$Id: db_cursor.so,v 10.55 2007/10/24 16:06:06 bostic Exp $])

define(M4PAGELOCAL, dbh_cursor)
include(m4/m4.seealso)

m4_pf_header(m4_ref(dbh_cursor),
ifelse(M4API, C_API, [dnl
int
DB-__GT__cursor(DB *db,
    DB_TXN *txnid, DBC **cursorp, u_int32_t flags);
])
ifelse(M4API, CXX_API, [dnl
int
Db::cursor(DbTxn *txnid, Dbc **cursorp, u_int32_t flags);
]))

m4_p([dnl
The m4_refT(dbh_cursor) returns a created database cursor.])

m4_p([dnl
Cursors may span threads, but only serially, that is, the application
must serialize access to the cursor handle.])

m4_return(dbh_cursor, std)

m4_parambegin
m4_param_co(cursorp, allocated cursor, REF)

m4_param(flags, [dnl
m4_sf_or_may

m4_tagbegin
m4_tag(m4_idef(DB_READ_COMMITTED), [dnl
Configure a transactional cursor to have degree 2 isolation.  This ensures
the stability of the current data item read by this cursor but permits data
read by this cursor to be modified or deleted prior to the commit of the
transaction for this cursor.])

m4_tag(m4_idef(DB_READ_UNCOMMITTED), [dnl
Configure a transactional cursor to have degree 1 isolation.  Read
operations performed by the cursor may return 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_WRITECURSOR), [dnl
Specify that the cursor will be used to update the database.  The
underlying database environment must have been opened using the
m4_ref(DB_INIT_CDB) flag.])

m4_tag(m4_idef(DB_TXN_SNAPSHOT), [dnl
Configure a transactional cursor to operate with read-only
m4_link(M4RELDIR/ref/transapp/read, snapshot isolation).  For databases
with the m4_ref(DB_MULTIVERSION) flag set, data values will be read as
they are when the cursor is opened, without taking read locks.  This
flag implicitly begins a transaction that is committed when the cursor
is closed.  Silently ignored if m4_ref(DB_MULTIVERSION) not set on the
underlying database or if a transaction is supplied in the m4_arg(txnid)
parameter.])
m4_tagend])

m4_param(txnid, [dnl
Cursor operations are not automatically transaction-protected, even if
the m4_ref(DB_AUTO_COMMIT) flag is specified to the
m4_ref(dbenv_set_flags) or m4_refT(dbh_open)s.  If cursor operations are
to be transaction-protected, the m4_arg(txnid) parameter must be a
transaction handle returned from m4_ref(txn_begin); otherwise, NULL.  To
transaction-protect cursor operations, cursors must be opened and closed
within the context of a transaction, and the m4_arg(txnid) parameter
specifies the transaction context in which the cursor may be used.])

m4_paramend

m4_err(dbh_cursor, rephandle, replockout, einval)

m4_seealso(Dbc)
m4_page_footer