# query-ex

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

## 1. Allowed Content

> association
>   Unique key of the application object.
> query-token
>   Opaque handle for query-ex commands.
> search-class
>   Query search class filter.
> search-attr
>   Query search attribute value filter.
> read-attr
>   Return specified object attribute value(s).
> read-parent
>   Return object parent/container.
> operation-data
>   Operation additional custom data.

## 2. Attributes

> Attribute | Value(s) | Default Value
> --- | --- | ---
> 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

## 3. Content Rule

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

## 4. Parent Elements

> input
>   Input events or commands.

Top Elements || All Elements || Tree