DbEnv
Prev | Chapter 5. The DbEnv Handle | Next

## DbEnv

    #include <db_cxx.h>

    class DbEnv {
    public:
            DbEnv(u_int32 flags);
            ~DbEnv();

            DB_ENV *DbEnv::get_DB_ENV();
            const DB_ENV *DbEnv::get_const_DB_ENV() const;
            static DbEnv *DbEnv::get_DbEnv(DB_ENV *dbenv);
            static const DbEnv *DbEnv::get_const_DbEnv(const DB_ENV *dbenv);
            ...
    };

The `DbEnv` object is the handle for a Berkeley DB environment — a collection including support for some or all of caching, locking, logging and transaction subsystems, as well as databases and log files. Methods of the `DbEnv` handle are used to configure the environment as well as to operate on subsystems and databases in the environment.

`DbEnv` handles are free-threaded if the DB_THREAD flag is specified to the DbEnv::open() method when the environment is opened. The `DbEnv` handle should not be closed while any other handle remains open that is using it as a reference (for example, Db or DbTxn). Once either the DbEnv::close() or DbEnv::remove() methods are called, the handle may not be accessed again, regardless of the method's return.

The constructor creates the `DbEnv` object. The constructor allocates memory internally; calling the DbEnv::close() or DbEnv::remove() methods will free that memory.

Before the handle may be used, you must open it using the DbEnv::open() method.

The flags parameter must be set to 0.

- `DB_CXX_NO_EXCEPTIONS`

  The Berkeley 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 `DB_CXX_NO_EXCEPTIONS` is specified, exceptions are not thrown; instead, each individual function returns an error code.

Each `DbEnv` object has an associated `DB_ENV` structure, which is used by the underlying implementation of Berkeley DB and its C-language API. The `DbEnv::get_DB_ENV()` method returns a pointer to this struct. Given a `const DbEnv` object, `DbEnv::get_const_DB_ENV()` returns a const pointer to the same struct.

Given a `DB_ENV` struct, the `DbEnv::get_DbEnv()` method returns the corresponding `DbEnv` object, if there is one. If the `DB_ENV` struct was not associated with a `DbEnv` (that is, it was not returned from a call to `DbEnv::get_DB_ENV()`), then the result of `DbEnv::get_DbEnv()` is undefined. Given a `const DB_ENV` struct, `DbEnv::get_const_Db_Env()` returns the associated `const DbEnv` object, if there is one.

These methods may be useful for Berkeley DB applications including both C and C++ language software. It should not be necessary to use these calls in a purely C++ application.

### Class

DbEnv

### See Also

Database Environments and Related Methods

Prev | Up | Next
DbEnv::close() | Home | DbEnv::dbremove()