XmlManager::query

API Ref

#include <DbXml.hpp>

XmlResults XmlManager::query(const std::string &xquery, XmlQueryContext &context, u_int32_t flags = 0)

XmlResults XmlManager::query(XmlTransaction &txn, const std::string &xquery, XmlQueryContext &context, u_int32_t flags = 0)


Description: XmlManager::query

Executes a query in the context of the XmlManager object. This method is the equivalent of calling XmlManager::prepare and then XmlQueryExpression::execute on the prepared query.

The scope of the query can be restricted using one of the XQuery navigational functions. For example:

"collection('mycontainer.dbxml')/foo"

or:

"doc('dbxml:/mycontainer.dbxml/mydoc.xml')/foo/@attr1='bar'"

The scope of a query can also be controlled by passing an appropriate contextItem object to XmlQueryExpression::execute.

Note that this method is suitable for performing one-off queries. If you want to execute a query more than once, you should use XmlManager::prepare to compile the expression, and then use XmlQueryExpression::execute to run it.

This method returns an XmlResults object. You then iterate over the results set contained in that object using XmlResults::next and XmlResults::previous.

For more information on querying containers and documents, see the Berkeley DB XML Getting Started Guide.

Parameters

txn
If the operation is to be transaction-protected, the txn parameter is an XmlTransaction handle returned from XmlManager::createTransaction.
xquery
The XQuery query string.
context
The XmlQueryContext to use for this query.
flags
The flags parameter must be set to 0 or by bitwise inclusively OR'ing together one or more of the following values:
DB_DIRTY_READ
Only meaningful for transactional containers. Causes the container to Support dirty reads; that is, read operations on the container may return data that has been modified by other transactions but which has not yet been committed.
DB_RMW
Acquire write locks instead of read locks when doing the retrieval. Setting this flag can eliminate deadlock during a read-modify-write cycle by acquiring the write lock during the read part of the cycle so that another thread of control acquiring a read lock for the same item, in its own read-modify-write cycle, will not result in deadlock.
DBXML_LAZY_DOCS
Retrieve the document lazily. That is, retrieve document content and document metadata only on an as needed basis when reading the document.

Errors

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

INVALID_VALUE
Invalid flags to method XmlManager::query

APIRef

Copyright (c) 1996-2004 Sleepycat Software, Inc. - All rights reserved.