Description

The query command is an input command or event. Both the publisher and the subscriber must implement all defined possibilities. A query is used to find and read information about entries in eDirectory and the external application.

Definition

  <!ELEMENT query    (association?, 
                        (search-class | 
                         search-attr | 
                         read-attr | 
                         read-parent)*)>
  <!ATTLIST query
            dest-dn         CDATA              #IMPLIED
            dest-entry-id   CDATA              #IMPLIED
            class-name      CDATA              #IMPLIED
            scope           (%Search-Scope;)   "subtree"
            event-id        CDATA              #IMPLIED>
  
  <!ELEMENT search-class    EMPTY>
  <!ATTLIST search-class
            class-name      CDATA              #REQUIRED>
  
  <!ELEMENT search-attr     (value)+ >
  <!ATTLIST search-attr
            attr-name       CDATA              #REQUIRED>
  
  <!ELEMENT read-attr       EMPTY>
  <!ATTLIST read-attr
            attr-name       CDATA              #IMPLIED
            type      (%Read-attr-type;)       "default">
  
  <!ELEMENT read-parent      EMPTY>
  

Attributes

dest-dn

Specifies the distinguished name for the starting point for the search. If both the dest-dn attribute and <association> have values, the <association> value is used as the starting point for the search. If neither have values, the search begins at the root of the directory.

dest-entry-id

Specifies the entry ID in the name space of the receiver. It is used internally by the DirXML engine and should be ignored by the driver.

class-name

Specifies the base class of the dest-dn attribute.

scope

Specifies the extent of the search. This attribute supports the following values:

• subtree —indicates to search the base entry and all entries in its branch of the directory tree. If no scope is specified, subtree is used as the default value.
• subordinates —indicates to search the immediate subordinates of the base entry (the base entry is not searched).
• entry— indicates to search just the base entry.

For scopes other than entry, the selected entries can be further limited by the <search-class> and <search-attr> elements. For scopes of entry, the <search-class> and <search-attr> elements are ignored.

event-id

Specifies an identifier used to identify a particular instance of the command or event.

Elements

association

Specifies the unique identifier for the entry where the search begins. If both the dest-dn attribute and <association> have values, the <association> value is used as the starting point for the search. If neither have values, the search begins at the root of the directory.

search-class

Specifies the search filter for object classes. If the query contains no <search-class> elements, all entries matching the scope and the <search-attr> elements are returned.

search-attr

Specifies the search filter for attribute values. If more than one <search-attr> element is specified, the entry must match all attributes to be returned.

read-attr

Specifies which attribute values are returned with entries that match the search filters. If no attributes are specified, all attributes are returned. If a <read-attr> element is specified without an attr-name attribute, no attributes are returned.

<read-parent>

Specifies whether the parent of the entry is returned with the entry.

Request Format

A query can include any of the following defined elements and attributes:

Whenever the DirXML engine sends your driver a query, your driver should be prepared to parse the query for all of the above elements and attributes.

Whenever your driver sends the DirXML engine a query, your driver should be prepared to include all of the above element and attributes except the dest-entry-id attribute.

For possible entry points when the DirXML engine or the DirXML driver sends a query, see Section 4.5, Event Processing.

Reply Format

The receiving application should respond to a query with an instance command for each entry returned. The response should also include a status command indicating whether the query was processed successfully. A query should return a successful status even when no entries exist that match the search criteria.

Parent

• input
• config-object

Remarks

A query is search operation. When the query is searching for a match, the following elements and attributes are used to specify matching criteria:

A query is a read operation. When the query is requesting entry and attribute information, the following elements and attributes are used to specify the information returned.

Example

The following examples illustrate two queries which search different parts of the directory and return different information about the entry.

  <!-- Example #1                                         -->
  <!-- Search the whole application for a User entry with -->
  <!-- the Surname of Jones.                              -->
  <!-- Don’t read any attributes, but read the parent entry-->
  <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>
  

  <!-- Example #2                                    -->
  <!-- Read the User entry whose foreign key is 1011 -->
  <!-- Read the 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>