m4_comment([$Id: db_class.so,v 10.53 2007/10/26 14:52:37 bostic Exp $])

define(M4PAGELOCAL, [dbh_create, Db, DB_CXX_NO_EXCEPTIONS])
include(m4/m4.seealso)

ifelse(M4API, C_API, [dnl
m4_pf_header(m4_ref(dbh_create), [dnl
typedef struct __db DB;
m4_blank
int
db_create(DB **dbp, DB_ENV *dbenv, u_int32_t flags);
])])
ifelse(M4API, CXX_API, [dnl
m4_pf_header(m4_ref(Db), [dnl
class Db {
public:
	Db(DbEnv *dbenv, u_int32_t flags);
	~Db();
m4_blank
	DB *Db::get_DB();
	const DB *Db::get_const_DB() const;
	static Db *Db::get_Db(DB *db);
	static const Db *Db::get_const_Db(const DB *db);
	...
};])])

define(xa_create_tag, [dnl
m4_tag(m4_idef(DB_XA_CREATE), [dnl
Instead of creating a standalone database, create a database intended
to be accessed via applications running under an X/Open conformant
Transaction Manager.  The database will be opened in the environment
specified by the OPENINFO parameter of the GROUPS section of the
ubbconfig file.  See the m4_link(M4RELDIR/ref/xa/xa_intro, [XA
Introduction]) section in the m4_db Reference Guide for more information.])])

m4_p([dnl
The m4_ref(Db) handle is the handle for a m4_db database, which may or
may not be part of a database environment.])

m4_p([dnl
m4_ref(Db) handles are free-threaded if the m4_ref(DB_THREAD) flag is
specified to the m4_refT(dbh_open) when the database is opened or if the
database environment in which the database is opened is free-threaded.
The handle should not be closed while any other handle that refers to
the database is in use; for example, database handles must not be closed
while cursor handles into the database remain open, or transactions that
include operations on the database have not yet been committed or
aborted.  Once the m4_ref(dbh_close), m4_ref(dbh_remove),
m4_ref(dbh_rename), or m4_refT(dbh_verify)s are called, the handle may
not be accessed again, regardless of the method's return.])

ifelse(M4API, C_API, [dnl
m4_p([dnl
The m4_ref(dbh_create) function creates a m4_ref(Db) structure that is
the handle for a m4_db database.  This function allocates memory for the
structure, returning a pointer to the structure in the memory to which
m4_arg(dbp) refers.  To release the allocated memory and discard the
handle, call the m4_ref(dbh_close), m4_ref(dbh_remove),
m4_ref(dbh_rename), or m4_refT(dbh_verify)s.])

m4_p([dnl
The m4_ref(Db) handle contains a special field, "app_private", which is
declared as type "void *".  This field is provided for the use of the
application program.  It is initialized to NULL and is not further used
by m4_db in any way.])

m4_return(dbh_create, std)

m4_parambegin

m4_param(dbp, [dnl
The m4_arg(dbp) parameter references the memory into which the returned
structure pointer is stored.])

m4_param(dbenv, [dnl
If the m4_arg(dbenv) parameter is NULL, the database is standalone; that
is, it is not part of any m4_db environment.
m4_p([dnl
If the m4_arg(dbenv) parameter is not NULL, the database is created
within the specified m4_db environment.  The database access methods
automatically make calls to the other subsystems in m4_db, based on the
enclosing environment.  For example, if the environment has been
configured to use locking, the access methods will automatically acquire
the correct locks when reading and writing pages of the database.])])

m4_param(flags, [dnl
m4_sf_zmust(0)

m4_tagbegin
xa_create_tag
m4_tagend])
m4_paramend

m4_err(dbh_create, einval)],[dnl
m4_p([dnl
The constructor creates a m4_ref(Db) object that is the handle for a
m4_db database.  The constructor allocates memory internally; calling
the m4_ref(dbh_close), m4_ref(dbh_remove) or m4_refT(dbh_rename)s will
free that memory.])

m4_p([dnl
Each m4_ref(Db) object has an associated m4_refc(Db) struct, which is
used by the underlying implementation of m4_db and its C-language API.
The Db::get_DB method returns a pointer to this struct.  Given a const
m4_ref(Db) object, Db::get_const_DB returns a const pointer to the
same struct.])

m4_p([dnl
Given a m4_refc(Db) struct, the Db::get_Db method returns the
corresponding m4_ref(Db) object, if there is one.  If the m4_refc(Db)
object was not associated with a m4_ref(Db) (that is, it was not
returned from a call to Db::get_DB), then the result of Db::get_Db is
undefined.  Given a const m4_refc(Db) struct, Db::get_const_Db returns
the associated const m4_ref(Db) object, if there is one.])

m4_p([dnl
These methods may be useful for m4_db applications including  both C
and C++ language software.  It should not be necessary to use these
calls in a purely C++ application.])

m4_parambegin
m4_param(dbenv, [dnl
If no m4_arg(dbenv) value is specified, the database is standalone; that
is, it is not part of any m4_db environment.
m4_p([dnl
If a m4_arg(dbenv) value is specified, the database is created within
the specified m4_db environment. The database access methods
automatically make calls to the other subsystems in m4_db based on the
enclosing environment. For example, if the environment has been
configured to use locking, the access methods will automatically acquire
the correct locks when reading and writing pages of the database.])])

m4_param(flags, [dnl
m4_sf_or_may
m4_tagbegin
m4_tag(m4_idef(DB_CXX_NO_EXCEPTIONS), [dnl
The m4_db C++ API supports two different error behaviors.  By default,
whenever an error occurs, an exception is thrown that encapsulates the
error information.  This generally allows for cleaner logic for
transaction processing because a try block can surround a single
transaction.  However, if m4_ref(DB_CXX_NO_EXCEPTIONS) is specified,
exceptions are not thrown; instead, each individual function returns an
error code.
m4_p([dnl
If m4_arg(dbenv) is not null, this flag is ignored, and the error behavior
of the specified environment is used instead.])])

xa_create_tag
m4_tagend])
m4_paramend])

m4_seealso(Db)
m4_page_footer