XmlContainer::open

APIRef

#include <DbXml.hpp>

void XmlContainer::open(DbTxn *txnid, u_int32_t flags, int mode);

Description

The XmlContainer::open method opens the XmlContainer for both reading and writing. The container name, passed through the constructor, is used as the base name for a set of underlying Berkeley DB databases that are used to back the container.

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 method has been called. Note that it is allowable to re-open a container after it has been closed.

An open XmlContainer must be closed, by calling the XmlContainer::close method, before the XmlContainer object is destroyed. Otherwise the underlying database resources will not be released.

If the operation is to be transaction-protected (other than by specifying the DB_AUTO_COMMIT flag), the txnid parameter is a transaction handle returned from DbEnv::txn_begin; otherwise, NULL.

The flags and mode arguments specify how files will be opened and/or created if they do not already exist.

The flags value must be set to 0 or by bitwise inclusively OR'ing together one or more of the following values:

DB_AUTO_COMMIT
Enclose the XmlContainer::open call within a transaction. If the call succeeds, the open operation will be recoverable. If the call fails, no container will have been created.

DB_CREATE
Create the container. If the container does not already exist and the DB_CREATE flag is not specified, the XmlContainer::open will fail.

DB_DIRTY_READ
Support dirty reads; that is, read operations on the container may request the return 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 the description of the DbEnv::set_mp_mmapsize method for further information).

DB_RDONLY
Open the container for reading only. Any attempt to modify items in the container will fail, regardless of the actual permissions of any underlying files.

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.

On UNIX systems or in IEEE/ANSI Std 1003.1 (POSIX) environments, all files created by the container 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, the container open will use a default mode of readable and writable by both owner and group. On Windows systems, the mode argument is ignored. The group ownership of created files is based on the system and directory defaults, and is not further specified by Berkeley DB.

Calling XmlContainer::open is a reasonably expensive operation, and maintaining a set of open containers will normally be preferable to repeatedly opening and closing the container for each new query.

The XmlContainer::open method throws an exception that encapsulates a non-zero error value on failure. If XmlContainer::open fails, the XmlContainer::close method should be called to discard the XmlContainer handle.

Environment Variables

DB_HOME
If a dbenv argument to db_create was specified, the environment variable DB_HOME may be used as the path of the database environment home.

XmlContainer::open is affected by any database directory specified using the DbEnv::set_data_dir method, or by setting the "set_data_dir" string in the environment's DB_CONFIG file.

TMPDIR
If the file and dbenv arguments to XmlContainer::open are NULL, the environment variable TMPDIR may be used as a directory in which to create temporary backing files

Errors

The XmlContainer::open method may fail and throw an exception encapsulating a non-zero error for the following conditions:

DB_OLD_VERSION
The container cannot be opened without being first upgraded.

EEXIST
DB_CREATE and DB_EXCL were specified and the container exists.

EINVAL
An invalid flag value or parameter was specified.

The DB_THREAD flag was specified and fast mutexes are not available for this architecture.

The DB_THREAD flag was specified to XmlContainer::open, but was not specified to the DbEnv::open call for the environment in which the XmlContainer handle was created.

The XmlContainer::open method may fail and throw an exception for errors specified for other Berkeley DB and C library or system methods. If a catastrophic error has occurred, the XmlContainer::open method may fail and throw a DbRunRecoveryException, in which case all subsequent Berkeley DB calls will fail in the same way.

Class

XmlContainer, XmlDocument, XmlQueryContext

See Also

XmlContainer::close, XmlContainer::declareIndex, XmlContainer::deleteDocument, XmlContainer::getDocument, XmlContainer::getName, XmlContainer::open, XmlContainer::putDocument and XmlContainer::queryWithXPath.

XmlDocument::getAttributeValue, XmlDocument::getContent, XmlDocument::getID, XmlDocument::getName, XmlDocument::getType, XmlDocument::setContent, XmlDocument::setName, and XmlDocument::setType.

APIRef

Copyright Sleepycat Software