#include <DbXml.hpp>

void XmlContainer::open(DbTxn *txn, u_int32_t flags=0, int mode=0);

Description: XmlContainer::open

The XmlContainer::open method opens the XmlContainer for reading and writing. The XmlContainer::open method may only be called on a closed container. A container is in the closed state after construction, and after the XmlContainer::close, XmlContainer::rename, or XmlContainer::remove methods have been called. A container can be reopened after it has been closed. The XmlContainer::isOpen method can be used to determine if a given container is currently open or closed.

A container is created using the XmlContainer::open method with the DB_CREATE flag. The container is created without any indices specified. The XmlContainer::getIndexSpecification method can be used to retrieve the container indexing specification, the XmlIndexSpecification::addIndex method can be used to add indexing strategies, and the XmlContainer::setIndexSpecification method can be used to set the indexing specification for the container.

Parameters

txn

If the operation is to be transaction-protected, the txn parameter is a transaction handle returned from DbEnv::txn_begin, otherwise, NULL.

flags

Specifies which modes the container will be opened in. The flags value must be set to zero, or a value created by bitwise inclusively OR'ing one or more of the following values:

DB_AUTO_COMMIT

Automatically transact all update operations, unless the application provides a transaction handle.

DB_CREATE

Create the XmlContainer if it does not already exist.

DB_DIRTY_READ

Support reading of modified, but not yet committed data.

DB_EXCL

Return an error if the container already exists. The DB_EXCL flag is only meaningful when specified with the DB_CREATE flag.

DB_NOMMAP

Do not map this container into process memory (see DbEnv::set_mp_mmapsize for further information).

DB_RDONLY

Open the XmlContainer for reading only. Subsequent attempts to modify the XmlContainer will fail.

DB_THREAD

Cause the XmlContainer handle returned by XmlContainer::open to be free-threaded; that is, usable by multiple threads within a single address space.

DBXML_CHKSUM_SHA1

Do checksum verification of pages read into the cache from the backing filestore. Berkeley DB XML uses the SHA1 Secure Hash Algorithm if encryption is configured and a general hash algorithm if it is not.

DBXML_ENCRYPT

Encrypt the database using the cryptographic password specified to the DbEnv::set_encrypt.

mode

On UNIX systems or in IEEE/ANSI Std 1003.1 (POSIX) environments, all files created by XmlContainer::open are created with mode mode (as described in chmod(2)) and modified by the process' umask value at the time of creation (see umask(2)). If mode is 0, XmlContainer::open will use a default mode of readable and writable by both owner and group. On Windows systems, the mode parameter is ignored. The group ownership of created files is based on the system and directory defaults, and is not further specified by Berkeley DB.

Errors

The XmlContainer::open method may fail and throw XmlException, encapsulating one of the following non-zero errors:

CONTAINER_EXISTS

The DB_CREATE flag was specified, but the container already exists.

CONTAINER_OPEN

The container is already open.

DATABASE_ERROR

An error occurred in an underlying Berkeley DB database. The XmlException::getDbError method will return the error code for the error.

VERSION_MISMATCH

The container version and dbxml library version differ; use the XmlContainer::upgrade method to update the container version.

Class