New Page 1

xflminterface IF_Query : public XF_RefCount

The IF_Query interface allows an application to perform queries on an XFLAIM database. An IF_Query object is obtained by calling the IF_DbSystem::createIFQuery method. The methods on an IF_Query object allow an application to define query criteria and then retrieve query results. It also allows query results to be sorted, and absolute positioning to be done within the result set.

Method Summary
RCODE	setLanguage - Set the language for string comparisons.
RCODE	setCollection - Set the database collection that is to be searched.
RCODE	setupQueryExpr(1) - Setup query criteria from a unicode string that is an XPATH expression.
RCODE	setupQueryExpr(2) - Setup query criteria from a native string that is an XPATH expression.
RCODE	copyCriteria - Copy query criteria from another query object into this object.
RCODE	addXPathComponent - Add an XPATH component to the query criteria.
RCODE	addOperator - Add an operator to the query criteria.
RCODE	addUnicodeValue - Add a unicode string operand to the query criteria.
RCODE	addUTF8Value - Add a UTF8 string operand to the query criteria.
RCODE	addBinaryValue - Add a binary value operand to the query criteria.
RCODE	addUINTValue - Add an unsigned integer operand to the query criteria.
RCODE	addINTValue - Add a signed integer operand to the query criteria.
RCODE	addUINT64Value - Add a 64 bit unsigned integer operand to the query criteria.
RCODE	addINT64Value - Add a 64 bit signed integer operand to the query criteria.
RCODE	addBoolean - Add a boolean predicate to the query criteria.
RCODE	addFunction(1) - Add a predefined function operand or predicate to the query criteria.
RCODE	addFunction(2) - Add an application defined function operand or predicate to the query criteria.
RCODE	getFirst - Return the first node or document of the query result set.
RCODE	getLast - Return the last node or document of the query result set.
RCODE	getNext - Return the next node or document of the query result set. If not positioned, start from first node or document.
RCODE	getPrev - Return the previous node or document of the query result set. If not positioned, start from last node or document.
RCODE	getCurrent - Return the current node or document of the query result set. Must have already retrieved a node or document from the result set.
RCODE	resetQuery - Clears the query criteria and sets the query object to its initialized state.
RCODE	getStatsAndOptInfo - Return optimization and statistics information about the query.
RCODE	freeStatsAndOptInfo - Free optimization and statistics information that was returned by getStatsAndOptInfo.
RCODE	setDupHandling - Configure whether query should allow returning of same document more than once.
RCODE	setIndex - Set the index to be used by the query. Zero may be specified to force a database scan.
RCODE	getIndex - Returns index being used in query.
RCODE	addSortKey - Specify a sort key component for the query result set.
RCODE	enablePositioning - Enable absolute positioning within the query result set.
RCODE	positionTo(1) - Position to an absolute position within the query result set.
RCODE	positionTo(2) - Position to a specific key within a query result set that has sort keys.
RCODE	getPosition - Get the current absolute position within a query result set.
RCODE	buildResultSet - Build the query result set - usually called when it is desirable to build the result set in a background thread.
RCODE	stopBuildingResultSet - Stop another thread that is building the result set via buildResultSet.
RCODE	getCounts - Get the current counts for the query result set.
RCODE	enableResultSetEncryption - If a temporary result set needs to be built for the query result set, ensure that it is encrypted when going to disk.
RCODE	setQueryStatusObject - Set the query status object for the query.
RCODE	setQueryValidatorObject - Set the query validator object for the query.

Method Detail

setLanguage

RCODE setLanguage(

FLMUINT uiLanguage);

Set the language for string comparisons.

Parameters In:

FLMUINT uiLanguage The language for string comparisons.

Example Code:

    IF_Query *   pQuery;    //Assume that we get the pQuery object by calling createIFQuery.

    RCODE        rc;

    // Set query string comparison language to US english.

    rc = pQuery->setLanguage( XFLM_US_LANG);

See Also:

IF_Db * pDb	Pointer to database object.
FLMUNICODE * puzQuery	The unicode string that contains the XPATH expression. This string will be parsed and setup as the query criteria for this query. Element names and attribute names in the string will be looked up in the database dictionary (pDb's dictionary), verified, and translated to the appropriate name id.

IF_Db * pDb	Pointer to database object.
char * pszQuery	The native string that contains the XPATH expression. This string will be parsed and setup as the query criteria for this query. Element names and attribute names in the string will be looked up in the database dictionary (pDb's dictionary), verified, and translated to the appropriate name id.

eXPathAxisTypes eXPathAxis	The axis of this component. The axis specifies this components relationship to the prior component (if any) - such as parent, child, attribute, previous sibling, etc.
eDomNodeType eNodeType	The type of node for this component.
FLMUINT uiNameId	The name id for the component. This is only used if the node type (eNodeType) is ELEMENT_NODE, DATA_NODE, or ATTRIBUTE_NODE.
IF_QueryNodeSource * pNodeSource	The axis of this component. The axis specifies this components relationship to the prior component (if any) - such as parent, child, attribute, previous sibling, etc.

eQueryOperators eOperator	The operator to be added to the criteria.
FLMUINT uiCompareRules	For string operands, additional comparison rules may be specified (such as case insensitive, compress whitespace, etc.).
IF_OperandComparer * pOpComparer	An object that will perform the comparison. If NULL, the comparison is done internally by XFLAIM using the predefined rules it has for each operator and the comparison rules. If non-NULL, operands are passed to compare method on this object for comparison.

void * pvVal	The binary value operand.
FLMUINT uiValLen	The length of the binary value in bytes.

FLMBOOL bVal	The boolean value of TRUE or FALSE. NOTE: This parameter is ignored if the bUnknown parameter is TRUE. In that case, the value for the predicate will be UNKNOWN.
FLMBOOL bUnknown	If TRUE, the value of the predicate is UNKNOWN, and the bVal parameter is ignored.

IF_QueryValFunc * pFuncObj	This is a pointer to the object whose methods will be called to obtain a value for the function during query evaluation.
FLMBOOL bHasXPathExpr	This indicates whether or not the function takes an XPATH expression parameter. The XPATH expression, if expected, must be specified inside parentheses, and must evaluate to a set of one or more DOM nodes. See example.

IF_Db * pDb	Pointer to database object. This should represent the database that is to be searched.
FLMUINT uiTimeLimit	Time limit for this operation (in milliseconds). A value of zero indicates that there is no time limit.

IF_DOMNode * ppNode	Found node or document is returned here. Note that if *ppNode is pointing to another node, it will be released before returning the found node or document.
FLMUINT * puiNumSkipped	Returns the number of nodes or documents that were skipped over. The count includes the current node or document, which is always skipped. Thus, if a next node or document is found, the "skipped" count will always be at least one. If no next node or document is found, this count will be zero.

FLMUINT * puiNumOptInfos	Number of XFLM_OPT_INFO structures in the array represented by *ppOptInfo.
XFLM_OPT_INFO ** ppOptInfo	Returns a pointer to an array of XFLM_OPT_INFO structures that contain optimization and statistics information on the query. When the application is done with this array, it should free it by calling IF_DbSystem::freeMem.

FLMUINT * puiIndex	Returns index that is being used, if any. Zero is returned if no index is being used.
FLMBOOL * pbHaveMultiple	Returns a flag indicating whether more than one index is being used.

void * pvSortKeyContext	Each sort key component specifies either an element or an attribute in an XML document that is relative to another element or attribute in the same XML document. This parameter is a handle to a sort key component that was previously created by calling addSortKey (returned via the ppvContext parameter). In this way, the sort keys for a query result set may be made up of virtually any combination of elements and/or attributes within documents of the result set. Note that it is legitimate to add sort key components that are not actually used for sorting - but are used to specify context for the components that are to be used in sorting. Non-sorting components are given by passing a zero in the uiKeyComponent parameter.
FLMBOOL bChildToContext	Is this sort key component a child or sibling of the component specified by pvSortKeyContext?
FLMBOOL bElement	Is this sort key component an attribute or an element?
FLMUINT uiNameId	Element name id or attribute name id for this component.
FLMUINT uiCompareRules	If the component is a string data type, this specifies the comparison rules to be used during sort compare operations.
FLMUINT uiLimit	If the component is a string data type, this specifies the maximum number of characters that will be used in the sort key component. NOTE: This does NOT mean that the entire value will not be compared during sort operations. It simply limits the amount of data that will be stored in the keys in the b-tree that will be used to create the sorted result set. It is important to have a limit so that the sort keys don't grow too large to hold in the b-tree.
FLMUINT uiKeyComponent	Specifies whether this sort key component is a primary key component (#1), secondary key component (#2), etc. A value of zero specifies that this component is not to be used in sorting at all, but is provided to specify context for other components. If there are N components with non-zero values in this parameter, those values must include all of the numbers between 1 and N. It does not matter what order they are defined in, as long as all numbers between 1 and N were specified once and only once. There must be at least one component with a non-zero value in this parameter.
FLMBOOL bSortDescending	Specifies whether this sort key component should be sorted in ascending order (FALSE) or descending order (TRUE).
FLMBOOL bSortMissingHigh	Specifies what to do when this sort key component is missing from the document that is being sorted. Missing components may be sorted "high" (TRUE) - meaning they sort AFTER all other values, or "low" (FALSE) - meaning they sort BEFORE all other values.

IF_Db * pDb	Pointer to database object - should be database that is going to be queried.
FLMUINT uiTimeLimit	Time limit for this operation (in milliseconds). A value of zero indicates that there is no time limit.
FLMUINT uiPosition	Absolute position to position to in result set. This is zero based. If there are N nodes or documents in the result set, this must be a number between 0 and N-1.

FLMUINT * puiReadCount	Number of nodes or documents that have been "read" and evaluated so far while building the result set.
FLMUINT * puiPassedCount	Number of nodes or documents that passed the query criteria so far and are currently in the result set.
FLMUINT * puiPositionableToCount	Number of nodes or documents that can be positioned to so far. NOTE: This will always either be zero, or will be the same as *puiPassedCount. If it is non-zero, it means that we don't have to collect all of the result set and then sort it - the items can go into the result set in the order we find them. This is either a) because we are not sorting the result set, or b) the sort keys match the index we are using for optimization.
FLMBOOL * pbDoneBuildingResultSet	Flag indicating whether the entire result set has been collected. If TRUE, puiPassedCount and puiPositionableCount should be the same.