### XmlContainer::queryWithXPath |

`

###

    #include <DbXml.hpp>

    XmlResults XmlContainer::queryWithXPath(
    	DbTxn *txn, XmlQueryExpression &expression, u_int32_t flags=0) const;

    XmlResults XmlContainer::queryWithXPath(
    	DbTxn *txn, const std::string &query, XmlQueryContext *context=0, u_int32_t flags=0);

### Description: XmlContainer::queryWithXPath

The XmlContainer::queryWithXPath method executes an XPath expression against the XmlContainer, and returns the results.

In this case the expression is provided as a string.

The query may optionally be executed within an XmlQueryContext, which describes how the query is to be performed. If no context is specified the default context is used. The default query context defines the namespace prefix "dbxml", contains no variable bindings, specifies eager evaluation, and specifies that the method should return the set of XmlDocuments matching the XPath expression.

### Parameters

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

query
  The XPath expression is provided as a string and must conform to the syntax defined in the W3C XPath 1.0 specification.

context
  The context within which the query is to be performed. The context contains the variable bindings, the namespace prefix to URI mapping, and the query processing flags.

flags
  The flags parameter must be set to zero or one of the following values:

  DB_DIRTY_READ
    Read modified but not yet committed data. Silently ignored if the DB_DIRTY_READ flag was not specified when the underlying XmlContainer was opened.

  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.

    Because the XmlContainer::getDocument method will not hold locks across Berkeley DB interface calls in non-transactional environments, passing the DB_RMW flag to the XmlContainer::getDocument method is meaningful only in the presence of transactions.

Returns the result of the XPath query.

### Errors

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

CONTAINER_CLOSED
  The container is closed.

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

DOM_PARSER_ERROR
  The DOM parser was unable to parse an XML document.

NO_VARIABLE_BINDING
  The XPath expression referred to an undefined variable.

XPATH_EVALUATION_ERROR
  The XPath evaluator was unable to execute the XPath expression.

XPATH_PARSER_ERROR
  The XPath parser could not parse the XPath expression.

### Description: XmlContainer::queryWithXPath

The XmlContainer::queryWithXPath method executes an XPath expression against the XmlContainer, and returns the results.

In this case the expression is provided in the form of an XmlQueryExpression object. This is a pre-parsed XPath expression created by a call to the XmlContainer::parseXPathExpression method.

The query may optionally be executed within an XmlQueryContext, which describes how the query is to be performed. If no context is specified the default context is used. The default query context defines the namespace prefix "dbxml", contains no variable bindings, specifies eager evaluation, and specifies that the method should return the set of XmlDocuments matching the XPath expression.

### Parameters

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

query
  The query to be performed, expressed as an XmlQueryExpression object.

flags
  The flags parameter must be set to zero or one of the following values:

  DB_DIRTY_READ
    Read modified but not yet committed data. Silently ignored if the DB_DIRTY_READ flag was not specified when the underlying XmlContainer was opened.

  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.

    Because the XmlContainer::getDocument method will not hold locks across Berkeley DB interface calls in non-transactional environments, passing the DB_RMW flag to the XmlContainer::getDocument method is meaningful only in the presence of transactions.

Returns the result of the XPath query.

### Errors

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

CONTAINER_CLOSED
  The container is closed.

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

DOM_PARSER_ERROR
  The DOM parser was unable to parse an XML document.

NO_VARIABLE_BINDING
  The XPath expression referred to an undefined variable.

XPATH_EVALUATION_ERROR
  The XPath evaluator was unable to execute the XPath expression.

XPATH_PARSER_ERROR
  The XPath parser could not parse the XPath expression.

### Class

XmlContainer, XmlDocument, XmlException, XmlIndexSpecification, XmlQueryContext, XmlQueryExpression, XmlResults, XmlUpdateContext, XmlValue`

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