<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:

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>


<!-- 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 additional results based on the above query, assuming that
the results of the above included the query-token illustrated -->

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

1. Allowed Content

Unique key of the application object.
Opaque handle for query-ex commands.
Query search class filter.
Query search attribute value filter.
Return specified object attribute value(s).
Return object parent/container.
Query search condition filter.
Operation additional custom data.
Operation additional custom data used by the drivershim.

2. Attributes

AttributeValue(s)Default Value
cached-time CDATA
The time the event was placed into the driver cache. The format is CCYYMMDDhhmmss.mmmZ, always in UTC.
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.
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.
dest-dn CDATA
The distinguished name of the target object in the namespace of the receiver.
dest-entry-id CDATA
The entry id of the target object in the namespace of the receiver.

(Reserved) Should be ignored by the driver.
event-id CDATA
An identifier used to tag the results of an event or command.
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.
return-on-first-match true   |  false
Determines the behavior of the query.
get-token true   |  false
Determines whether token is returned for next set of results.Default behavior is to always fetch the token
scope entry   |  subordinates   |  subtree
The scope of the query. Note that "entry" scope makes little sense with query-ex, but is supported

3. Content Rule

( association ? , query-token ? , ( search-class | search-attr | read-attr | read-parent | search-condition ) * , operation-data ? , driver-operation-data ? )

4. Parent Elements

  Input events or commands.

Top Elements || All Elements || Tree