The IdmaScope interface provides methods specific to a DMA scope, such as executing a query.
This method must be supported in every implementation of this interface.
Syntax
DmaRC IdmaScope::ExecuteSearch (
Dmapv pIQueryObject,
Dmapv pICallback,
DmaBoolean bRequestElimination,
DMA_REFIID riidResultSet,
pDmapv ppIResultSet)
Parameters
Name | Mode | Description |
pIQueryObject | input | This is the query object that specifies the query to be performed. |
pICallback | input | This is a pointer to a callback interface whose ReportProgress method will optionally be called at regular intervals during this function call. This pointer may be NULL. |
bRequestElimination | input | If TRUE, this requests the scope to eliminate classes, properties, and operators it doesn’t fully understand using the rules of three valued logic. If the scope supports this capability, it will comply. If FALSE, an error will be returned if the scope encounters a class, property, or operator it doesn’t understand. |
riidResultSet | input | The desired interface on the result set object. |
ppIResultSet | output | The result set object returned by this method. The query result items are obtained by invoking methods on this object. |
The ExecuteSearch method processes the Query Object and internalizes the information contained therein. Neither the Query Object nor any of its subobjects are altered in any way by ExecuteSearch.
If the underlying scope is a merged scope, then, assuming preliminary processing succeeds, this function passes either the Query Object, or a newly constructed Query Object to the IdmaScope:: ExecuteSearch method of each component scope. If any of these calls returns an error, an error is returned.
In the case that a new Query Object is passed to a component scope, the new Query Object is not necessarily isomorphic to the Query Object passed in to this method. Examples of when this could occur include (1) three valued elimination is performed on the information in the original Query Object to develop the new copy, and/or (2) the Order By clause is added or extended in the new copy.
No internal pointers are kept to the Query Object or any of its descendant nodes. Once ExecuteSearch returns, changes to the Query Object or its descendant nodes will have no effect on the subsequent development of result rows during query execution.
If ExecuteSearch is successful, a Result Set object is returned. The IdmaResultSet:: GetNextResultRow method on the Result Set object is used to obtain each result row. The IdmaResultSet:: ReExecuteQuery method on the Result Set object may be used to terminate the current query, and prepare for reexecution of the query (without calling ExecuteSearch again), etc. The IdmaResultSet:: TerminateResults method on the Result Set object may be used to cancel further execution of the query. The TerminateResults method can be called asynchronously by a second thread in a multi-threaded application while the first thread is blocked internal to GetNextResultRow awaiting a result row to be returned. Multiple Result Set objects can be generated from a scope object. The Result Set objects are independent of each other, and, in a multi-threaded application, can be used concurrently.
It is recommended but not required that implementations defer most or all of the document space scope processing above and beyond the processing of the Query Object to the Result Set object, in order to make ExecuteSearch complete faster. If this is done, a multi-threaded application would then be more responsive to asynchronously canceling the potentially long running part of the query (i.e., generation of result rows) by calling IdmaResultSet:: TerminateResults on the Result Set object.
Clients desiring proper errors for their malformed Query Objects should pass DMA_FALSE for the bRequestElimination parameter to ExecuteSearch.
If DMA_FALSE is passed for bRequestElimination, and the query contains any undefined elements, ExecuteSearch will return an error.
If DMA_TRUE is passed for bRequestElimination, and the scope does not support three valued elimination, DMARC_3VE_NOT_SUPPORTED is returned.
If bRequestElimination is DMA_TRUE, and the query contains undefined elements, the scope performs three valued elimination as needed on the query object relative to its own metadata to develop a new copy of the information in the query object, which does not contain the undefined elements. Processing of the derived query object then proceeds.
If the scope is a merged scope, it delivers the query or a massaged copy of it to each component scope. For each component scope, the merged scope determines whether there are any undefined classes, properties, etc., in the possibly revised Query Object relative to the metadata of the component scope. If there are any undefined elements, and the component scope does not support three valued elimination, then the merged scope must perform three valued elimination to develop a revised query object which contains only elements defined relative to the metadata of the component scope. This insures that a query which is valid relative to the metadata of the merged scope will never fail because it contains undefined elements relative to any component scope. This behavior is independent of the setting of the Has Elimination property on the merged scope.
Return Values
Name | Description |
DMARC_3VE_NOT_SUPPORTED | The current scope does not support three valued elimination. |
DMARC_ABORT | The progress callback indicated that the method should be aborted. |
DMARC_BAD_CLASSID | The supplied identifier does not reference an available class of object. |
DMARC_BAD_COLLATION_SEQUENCE | The specified collation sequence is not known or supported by the scope. |
DMARC_BAD_FROM_EXPRESSION | The query contains an invalid From Expression. |
DMARC_BAD_INTERFACE | (E_NOINTERFACE) The requested interface is not supported by this object. |
DMARC_BAD_OBJECT | An inappropriate object was passed as parameter to this function. For example, the object does not support a required interface or is of an inappropriate class. |
DMARC_BAD_OPERAND | An operand is incorrect in datatype, form, or class. |
DMARC_BAD_OPERATOR | An operator ID is not defined in the metadata of the current scope. |
DMARC_BAD_ORDERBY_ELEMENT | Illegal 'order by' list element. |
DMARC_BAD_PROPID | A property identifier is not valid. |
DMARC_BAD_SC_OCCUR | The value of a query node's searchable class occurrence property is not present in the query. |
DMARC_BAD_SELECT_ELEMENT | Illegal select list element. |
DMARC_BAD_SUBQUERY_DATATYPE | The datatype of the query root node of an "IN" subquery does not match that of the property in the select list. |
DMARC_BAD_SUBQUERY_SELECT | The select list of a subquery contains an inappropriate number of elements |
DMARC_BAD_VALUE | The value given for a property or list element lies outside the permitted range or value set, or exceeds the maximum length allowed. |
DMARC_CLASS_NOT_SEARCHABLE | A class referred to in the From Expression is not searchable. |
DMARC_CLASSES_NOT_JOINABLE | A particular join operator in the query is supported, but the operator does not support the join between the particular operands specified in the query. |
DMARC_DISTINCT_NOT_SUPPORTED | The scope does not support the request for distinct result rows. |
DMARC_EXTRA_OPERANDS | A query node has extra operands. |
DMARC_MISSING_OPERANDS | A query node is missing one or more operands. |
DMARC_OK | (S_OK) Success. |
DMARC_PROPERTY_NOT_ORDERABLE | A property referred to in the query order by list is not orderable. |
DMARC_PROPERTY_NOT_SEARCHABLE | A property referred to in the Query Expression is not searchable. |
DMARC_PROPERTY_NOT_SELECTABLE | A property referred to in the Selections list is not selectable. |
DMARC_QUERY_TREE_LOOP | There is a circular reference loop or a shared node in the query. |
DMARC_REQUIRED_VALUE_ABSENT | A required property value has not been set. |
DMARC_STALE_METADATA | The metadata in the persistent store has been changed so that it does not match the client's current copy of the metadata. |
This method must be supported in every implementation of this interface.
Syntax
DmaRC IdmaScope::GetOperatorDescription (
pDmaId pOperatorId,
DMA_REFIID riid,
pDmapv ppIOperatorDesc)
Parameters
Name | Mode | Description |
pOperatorId | input | The Id of the operator whose description is desired. |
riid | input | The desired interface on the operator description object. |
ppIOperatorDesc | output | The operator description object returned. |
This method can be used to get the operator description object (an instance of dmaClass_QueryOperatorDescription) for a particular object. This can be useful in building or analyzing query expression hierarchies.
Return Values
Name | Description |
DMARC_BAD_INTERFACE | (E_NOINTERFACE) The requested interface is not supported by this object. |
DMARC_BAD_PARAMETER | (E_INVALIDARG) Invalid input parameter. |
DMARC_OK | (S_OK) Success. |