NDS DTD: query-ex element

<query-ex> is a <query> variant used to limit the number of search results returned at one time. See <query> for general information on searches and queries.

The results of a query-ex command may include a <query-token> element. The query-token element is used in subsequent query-ex commands to retrieve additional results. If query-ex results do not contain a query-token element then all of the available results for that query-ex command have been returned. Note that a different query-token may be returned with each result set. It is not sufficient to use only the query-token returned with the first result set.

The query-ex command has additional attributes that the query command does not:

The max-result-count attribute which specifies the maximum number of <instance> elements to return as the result of a single query-ex command.
The cancel attribute which is used to cancel a query-ex sequence, thereby freeing any resources associated with the search.

A query-ex command sequence may consist of multiple query-ex commands issued sequentially. The first query-ex command establishes the parameters of the search, returns the initial result set, and, if there are more results than can be returned with the initial result set, also returns a <query-token> to be used with subsequent query-ex commands. Subsequent query-ex commands contain the query-token element and are issued repeatedly to obtain additional result sets from the initial search. This process continues until no query-token element appears in the result set.

Note that subsequent query-ex commands using a token returned from a previous query-ex do not change the parameters of a search, regardless of any attributes or child elements.

A query-ex sequence may be abandoned before all results have been returned by setting the cancel attribute equal to "true" on a query-ex command.

Not all application shims support query-ex. Those that do report their support to the DirXML Engine at shim start up time by returning the following as a child of the <instance> element that is returned as the response to the driver identification query:

<attr attr-name="query-ex-supported">
 <value type="state">true</value>
</attr>

Example

<!-- search the whole application for all User objects -->
<!-- don't read any attributes -->
<query-ex class-name="User" event-id="0" scope="subtree" max-result-count="50">
 <search-class class-name="User"/>
 <read-attr/>
</query-ex>

<!-- read additional results based on the above query, assuming that
the results of the above included the query-token illustrated -->
<query-ex>
 <query-token>rO0ABXNyACxjb20ubm92ZWxsLm5kcy5kaXJ4bWwuZW5naW5lLk5EU1JlYWRlciRUb2tlbuWeJE0ga5xBAgACSgAFc3RhbXBJAAlzdGF0ZUhhc2h4cAAAAQQLokQbAbjW9w==</query-token>
</query-ex>

<!-- cancel a query-ex before having read all results -->
<query-ex cancel="true">
 <query-token>rO0ABXNyACxjb20ubm92ZWxsLm5kcy5kaXJ4bWwuZW5naW5lLk5EU1JlYWRlciRUb2tlbuWeJE0ga5xBAgACSgAFc3RhbXBJAAlzdGF0ZUhhc2h4cAAAAQQLokQbAbjW9w==</query-token>
</query-ex>

2. Attributes

Attribute Value(s) Default Value

cached-time CDATA

The time the event was placed into the driver cache. The format is CCYYMMDDhhmmss.mmmZ, always in UTC.
#IMPLIED

cancel true | false

If set to "true" on a query-ex command containing a <query-token> element then the search is abandoned and all associated resources are freed by the search target.
#IMPLIED

class-name CDATA

The name of the base class of the object.
The class name is mapped between the application and eDirectory name spaces by the schema mapping rule so that DirXML will see the name in the eDirectory namespace and a driver will see the name in the application name space.

This is required for proper schema mapping of any attribute names specified in the search. It should not be used to limit the search.
#IMPLIED

dest-dn CDATA

The distinguished name of the target object in the namespace of the receiver.
#IMPLIED

dest-entry-id CDATA

The entry id of the target object in the namespace of the receiver.

(Reserved) Should be ignored by the driver.
#IMPLIED

event-id CDATA

An identifier used to tag the results of an event or command.
#IMPLIED

max-result-count CDATA

Specifies the maximum number of <instance> elements to return as a result of a query-ex command. Valid values are positive, decimal integers.
#IMPLIED

scope entry | subordinates | subtree

The scope of the query. Note that "entry" scope makes little sense with query-ex, but is supported
subtree

query-ex

1. Allowed Content

2. Attributes

3. Content Rule

4. Parent Elements

Attribute	Value(s)	Default Value
cached-time	CDATA The time the event was placed into the driver cache. The format is CCYYMMDDhhmmss.mmmZ, always in UTC.	#IMPLIED
cancel	true \| false If set to "true" on a query-ex command containing a <query-token> element then the search is abandoned and all associated resources are freed by the search target.	#IMPLIED
class-name	CDATA The name of the base class of the object. The class name is mapped between the application and eDirectory name spaces by the schema mapping rule so that DirXML will see the name in the eDirectory namespace and a driver will see the name in the application name space. This is required for proper schema mapping of any attribute names specified in the search. It should not be used to limit the search.	#IMPLIED
dest-dn	CDATA The distinguished name of the target object in the namespace of the receiver.	#IMPLIED
dest-entry-id	CDATA The entry id of the target object in the namespace of the receiver. (Reserved) Should be ignored by the driver.	#IMPLIED
event-id	CDATA An identifier used to tag the results of an event or command.	#IMPLIED
max-result-count	CDATA Specifies the maximum number of <instance> elements to return as a result of a query-ex command. Valid values are positive, decimal integers.	#IMPLIED
scope	entry \| subordinates \| subtree The scope of the query. Note that "entry" scope makes little sense with query-ex, but is supported	subtree