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 might 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 are returned. A different query-token might 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 might 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 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.
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 can be abandoned before all results are 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 Metadirectory engine at shim startup 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>
<!-- 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 thatthe 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>
|
Attribute |
Possible Values |
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 he name of the base class of the object. The class name is mapped between the application and eDirectory namespaces by the Schema Mapping policy so that Identity Manager sees the name in the eDirectory namespace and a driver sees the name in the application namespace. 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. Entry scope makes little sense with query-ex, but is supported. |
subtree |
( association ? , query-token ? , ( search-class | search-attr | read-attr | read-parent ) * , operation-data ? )