Before you can instantiate an XmlManager object, you have to make some decisions about your Berkeley DB Environment. BDB XML requires you to use a database environment. You can use an environment explicitly, or you can allow the XmlManager constructor to manage the environment for you.

If you explicitly create an environment, then you can turn on important features in BDB XML such as logging, transactional support, and support for multithreaded and multiprocess applications. It also provides you with an on-disk location to store all of your application's containers.

If you allow the XmlManager constructor to implicitly create and/or open an environment for you, then the environment is only configured to allow multithreaded sharing of the environment and the underlying databases (DB_PRIVATE is used). All other features are not enabled for the environment.

The next several sections describe the things you need to know in order to create and open an environment explicitly. We start with this activity first because it is likely to be the first thing you will do for all but the most trivial of BDB XML applications.

#include "DbXml.hpp"
...
u_int32_t env_flags = DB_CREATE     |  // If the environment does not
                                       // exist, create it.
                      DB_INIT_LOCK  |  // Initialize the locking subsystem
                      DB_INIT_LOG   |  // Initialize the logging subsystem
                      DB_INIT_MPOOL |  // Initialize the cache
                      DB_INIT_TXN;     // Initialize transactions
char *envHome = "/export1/testEnv";
DB_ENV *myEnv = NULL;
int dberr;

dberr = db_env_create(&myEnv, 0);
if (dberr) {
    std::cout << "Unable to create environment: " <<
              db_strerror(dberr) << std::endl;
    if (myEnv)
        myEnv->close(myEnv, 0);
    return (EXIT_FAILURE);
}

myEnv->open(myEnv, envHome, env_flags, 0);

// Do BDB XML work here


myEnv->close(myEnv, 0); 

You create an XmlManager object by calling its constructor. You destroy a XmlManager object by calling its destructor, either by using the delete operator or by allowing the object to go out of scope (if it was created on the stack). Note that XmlManager is closed and all of its resources released when the last open handle to the object is destroyed.

To construct an XmlManager object, you may or may not provide the constructor with an open DB_ENV object. If you do instantiate XmlManager with an opened environment handle, then XmlManager will close and destroy that DB_ENV object for you if you specify DBXML_ADOPT_DBENV for the XmlManager constructor.

If you provide an DB_ENV object to the constructor, then you can use that object to use whatever subsystems that you application may require (see Environment Open Flags for some common subsystems).

If you do not provide an environment object, then XmlManager will implicitly create an environment for you. In this case, the environment will not be configured to use any subsystems and it is only capable of being shared by multiple threads from within the same process. Also, in this case you can optionally identify the on-disk location where you want your containers to reside using one of the following mechanisms:

In either case, you can pass the XmlManager constructor a flag argument that controls that object's behavior with regard to the underlying containers (the flag is NOT passed directly to the underlying environment or databases). Valid values are:

For example, to instantiate an XmlManager with a default environment:

#include "DbXml.hpp"

...

using namespace DbXml;
int main(void)
{
    XmlManager myManager;   // The manager and underlying
                            // environment are closed when 
                            // this goes out of scope.

    return(0);
} 

And to instantiate an XmlManager using an explicit environment object:

#include "DbXml.hpp"
...

using namespace DbXml;
int main(void)
{
    u_int32_t env_flags = DB_CREATE     |  // If the environment does not
                                           // exist, create it.
                          DB_INIT_LOCK  |  // Initialize locking
                          DB_INIT_LOG   |  // Initialize logging
                          DB_INIT_MPOOL |  // Initialize the cache
                          DB_INIT_TXN;     // Initialize transactions

    char *envHome = "/export1/testEnv";
    DB_ENV *myEnv = NULL;
    int dberr;

    XmlManager *myManager = NULL;

    dberr = db_env_create(&myEnv, 0);
    if (dberr) {
        std::cout << "Unable to create environment: " <<
                  db_strerror(dberr) << std::endl;
    if (myEnv)
        myEnv->close(myEnv, 0);
    return (EXIT_FAILURE);

    myEnv->open(myEnv, envHome, env_flags, 0);
    myManager = 
        new XmlManager(myEnv, 
                       DBXML_ADOPT_DBENV); // The manager and
                                           // environment is closed
                                           // when this object is
                                           // destroyed.

    try {
        if (myManager != NULL) {
            delete myManager;
        }
    } catch(XmlException &xe) {
        std::cerr << "Error closing XmlManager: "
                  << xe.what() << std::endl;
    }
}