# token-query

<token-query> causes a <query> to be performed in the source or destination datastore and returns the resulting <instance>'s.

The datastore to search is specified by datastore.

The base of the query is specified by either <arg-dn> or <arg-association>. If neither are specified, then the base will be the root of the datastore.

The scope of the query is specified by query.

The class of the query is specified by class-name. If omitted the query will look for all classes.

The set of attributes to search for is specified by the <arg-match-attr>'s.

The set of attributes to return is specified by the <arg-string>'s. If no <arg-string> are specified then no attributes will be read. If one of the <arg-string> evaluates to the asterisk character, then all attributes will be read.

If max-result-count is specified, then <query-ex> will be issued instead of a <query> and the results will be returned in batches. When used in the context of a <do-for-each> subsequent batches (if any) will be automatically retrieved.

### Example

>     <token-query class-name="User" datastore="dest" scope="subordinates">
>       <arg-dn>
>         <token-text>Users/</token-text>
>         <token-attr name="OU"/>
>       </arg-dn>
>       <arg-match-attr name="CN"/>
>       <arg-match-attr name="L">
>         <arg-value>
>           <token-text>Provo</token-text>
>         </arg-value>
>       </arg-match-attr>
>       <arg-string>
>         <token-text>Surname</token-text>
>       </arg-string>
>       <arg-string>
>         <token-text>Given Name</token-text>
>       </arg-string>
>     </token-query>

## 1. Allowed Content

> arg-dn
>   DN argument
> arg-association
>   association argument
> arg-match-attr
>   match attribute argument
> arg-string
>   string argument

## 2. Attributes

> Attribute | Value(s) | Default Value
> --- | --- | ---
> class-name | CDATA the class name of the query supports variable expansion | #IMPLIED
> datastore | src | dest the datastore to be queried | dest
> max-result-count | CDATA the maximum number of results to return per batch | #IMPLIED
> notrace | true | false true if this element should not be traced during execution of policy | false
> scope | entry | subordinates | subtree the scope of the query | subtree

## 3. Content Rule

> (( arg-dn | arg-association ) ? , arg-match-attr * , arg-string * )

## 4. Parent Elements

> arg-association
>   association argument
> arg-component
>   component argument
> arg-dn
>   DN argument
> arg-node-set
>   node set argument
> arg-password
>   password argument
> arg-string
>   string argument
> arg-value
>   value argument
> token-base64-decode
>   decode base64 data into a string
> token-base64-encode
>   encode a string into base64 data
> token-convert-time
>   convert a date/time from one format to another
> token-escape-for-dest-dn
>   convert a string for use in a destination DN
> token-escape-for-src-dn
>   convert a string for use in a source DN
> token-join
>   join a node-set into a string
> token-lower-case
>   convert a string to lower case
> token-map
>   map a string through a mapping table
> token-parse-dn
>   parse and/or convert a DN
> token-replace-all
>   replace all instances of a substring within a string
> token-replace-first
>   replace a single instance of a substring within a string
> token-split
>   split a string into a node-set
> token-substring
>   substring of a string
> token-upper-case
>   convert a string to upper case
> token-xml-parse
>   parse XML
> token-xml-serialize
>   serialize XML

Top Elements || All Elements || Tree