# query

<query> is a command used to find and/or read objects from eDirectory or the application. Full functionality for DirXML rules, object migration, etc. depends on full implementation of the query command by the driver.

The base object of the <query> is specified by either by the dest-dn attribute or by an <association>. If both are present, the <association> takes precedence. If neither are present, the base object defaults to the root object in a hierarchical name space or all objects in a non-hierarchical name space.

Possible scopes for the query are:

entry
  The base object only.
subordinates
  The objects contained by the base object.
subtree
  The objects in the subtree whose root is the base object, including the base object.

By default, all objects in the specified scope are selected. For scopes other than "entry", selected objects can be further limited by <search-class> and <search-attr>. For scope "entry", the effect of <search-attr> and <search-class> are undefined.

When there are <search-class> elements, only objects whose base class matches one of the <search-class> elements will be selected.

When there are <search-attr> elements, only objects with attributes matching all of the values specified by all of the <search-attr> elements will be selected.

By default all, object attributes for the selected objects are to be read. The attributes to be read can be limited by <read-attr>. To read none of the object attributes, a single nameless <read-attr> should be specified.

The <parent> of the selected selected objects will also be read if and only if <read-parent> is specified.

The <parent> of the selected selected objects will also be read if and only if <read-parent> is specified.

A response to <query> should include an <instance> for each of the selected objects.

A response to <query> should also include a <status> indicating whether or not the <query> was processed successfully. It should not be considered an error if no objects exist that match the search criteria!

Example

>     <!-- search the whole application for a User object with the Surname of Jones -->
>     <!-- don't read any attributes but read the parent -->
>     <query class-name="User" event-id="0" scope="subtree">
>      <search-class class-name="User"/>
>      <search-attr attr-name="Surname">
>       <value type="string">Jones</value>
>      </search-attr>
>      <read-attr/>
>      <read-parent/>
>     </query>

>     <!-- read the User object whose foreign key is 1011 -->
>     <!-- read Surname,cn,Given Name and Telephone Number attributes -->
>     <query class-name="User" event-id="1" scope="entry">
>      <association>1011</association>
>      <read-attr attr-name="Surname"/>
>      <read-attr attr-name="cn"/>
>      <read-attr attr-name="Given Name"/>
>      <read-attr attr-name="Telephone Number"/>
>     </query>

## 1. Allowed Content

> association
>   Unique key of the application object.
> 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
> --- | --- | ---
> 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
> scope | entry | subordinates | subtree The scope of the query. | subtree

## 3. Content Rule

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

## 4. Parent Elements

> config-object
>   eDirectory object to use for additional configuration data.
> input
>   Input events or commands.

Top Elements || All Elements || Tree