#include <DbXml.hpp> XmlResults XmlQueryExpression::execute( XmlQueryContext &queryContext, u_int32_t flags = 0) XmlResults XmlQueryExpression::execute( XmlTransaction &txn, XmlQueryContext &queryContext, u_int32_t flags = 0) XmlResults XmlQueryExpression::execute(const XmlValue &contextItem, XmlQueryContext &queryContext, u_int32_t flags = 0) XmlResults XmlQueryExpression::execute(XmlTransaction &txn, const XmlValue &contextItem, XmlQueryContext &queryContext, u_int32_t flags = 0)
Evaluates (runs) an XQuery query that was previously prepared by XmlManager::prepare and returns an XmlResults set.
There are two basic forms of this method: one that takes an
XmlValue
object, and another that does not. For methods that do not
take an XmlValue
, the XQuery must restrict the
scope of the query using either the collection()
or the doc()
XQuery
navigation functions, or an exception is thrown.
For those forms of this method that take an XmlValue , the query is applied against that object.
#include <DbXml.hpp> XmlResults XmlQueryExpression::execute( XmlQueryContext &queryContext, u_int32_t flags = 0) XmlResults XmlQueryExpression::execute( XmlTransaction &txn, XmlQueryContext &queryContext, u_int32_t flags = 0)
Evaluates the XQuery expression against the containers and
documents identified by the query, from within the scope of the
provided
XmlTransaction
object. To use this form of the
method, you must restrict the scope of the query using either
the collection()
or the
doc()
XQuery navigation functions,
or an exception is thrown.
Parameters are:
If the operation is to be transaction-protected, this parameter is an XmlTransaction handle returned from XmlManager::createTransaction.
The XmlQueryContext to use for this evaluation.
This parameter must be set to 0 or by bitwise inclusively OR'ing together one or more of the following values:
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_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
.
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.
DBXML_NO_AUTO_COMMIT
Do not create and automatically commit a transaction if one is not provided to this method. A query that performs an update under a transactional environment will automatically be transaction protected unless this flag is specified. This flag is only necessary if the update will make changes to both transactional and non-transactional containers.
#include <DbXml.hpp> XmlResults XmlQueryExpression::execute(const XmlValue &contextItem, XmlQueryContext &queryContext, u_int32_t flags = 0) XmlResults XmlQueryExpression::execute(XmlTransaction &txn, const XmlValue &contextItem, XmlQueryContext &queryContext, u_int32_t flags = 0)
Evaluates the XQuery expression against the provided context item.
Parameters are:
If the operation is to be transaction-protected, this parameter is an XmlTransaction handle returned from XmlManager::createTransaction.
The XmlValue object to perform the query against.
The XmlQueryContext to use for this evaluation.
This parameter must be set to 0 or by bitwise inclusively OR'ing together one or more of the following values:
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_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
.
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.
DBXML_NO_AUTO_COMMIT
Do not create and automatically commit a transaction if one is not provided to this method. A query that performs an update under a transactional environment will automatically be transaction protected unless this flag is specified. This flag is only necessary if the update will make changes to both transactional and non-transactional containers.
The XmlQueryExpression::execute
method
may fail and throw
XmlException
, encapsulating one of the
following non-zero errors: