#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)

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.

• If the operation is to be transaction-protected, the txn parameter is an XmlTransaction handle returned from XmlManager::createTransaction.

• The XQuery query string.

• The XmlQueryContext to use for this query.

• The flags parameter must be set to 0 or by bitwise inclusively OR'ing together one or more of the following values:
  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.
  DBXML_DOCUMENT_PROJECTION
  • When parsing a document in order to execute a query, use static analysis of the query to materialize only those portions of the document relevant to the query. This can significantly enhance performance of queries against documents from containers of type XmlContainer::WholedocContainer and documents not in a container. It should not be used if arbitrary navigation of the resulting nodes is to be performed, as not all nodes in the original document will be present and unexepcted results could be returned. This flag has no effect on documents in containers of type XmlContainer::NodeContainer.
  DB_READ_COMMITTED
  • This operation will have degree 2 isolation. This provides for cursor stability but not repeatable reads. Data items which have been previously read by this transaction may be deleted or modified by other transactions before this transaction completes.
  DB_READ_UNCOMMITTED
  • This operation will support degree 1 isolation; that is, read operations may return data that has been modified by other transactions but which has not yet been committed. Silently ignored if the DB_READ_UNCOMMITTED flag was not specified when the underlying container was opened.
  DB_RMW
  • Acquire write locks instead of read locks when doing the read, if locking is configured. 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_WELL_FORMED_ONLY
  • Force the use of a scanner that will neither validate nor read schema or dtds associated with the document during parsing. This is efficient, but can cause parsing errors if the document references information that might have come from a schema or dtd, such as entity references.
  
  

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

• Invalid flags to method XmlManager::query