# WHEN and NOTWHEN Search Operators

If you set `XMLFullStructure` to `True` in the configuration file, you can use the `WHEN` and `NOTWHEN` search operators to return documents in which XML fields occur with a common parent field. When you set `XMLFullStructure` to `True`, The IDOL Content component gives each occurrence of the same XML field name a different field code, so that it can identify each one uniquely.

To return only XML documents in which fields or attributes that have a specific value occur together, apply the `WHEN` operator to words or phrases. You can use the `WHEN` operator to return only those XML documents in which:

- two fields with the same parent field contain specified terms or phrases. See Example 1.

- two attributes that occur in the same field contain specified terms or phrases. See Example 2.

- a field contains a specified term or phrase, and has an attribute with a specific value. See Example 3.

To return only XML documents in which one field or attribute that has a specific value does not occur in the same parent field as another specified field or attribute and value, use the `NOTWHEN` operator. You can use the `NOTWHEN` operator in the same way as the `WHEN` operator. See Example 4.

## Example 1

You can use `WHEN` to return only XML documents in which two fields with the same parent field contain specified terms or phrases.

For example:

    action=Query&Text=audi:make+WHEN+red:color

This query returns only XML documents in which the `make` and `color` fields are children of the same parent field, and contain the values audi and red respectively.

For example, this query returns the following document:

    <XML>
          <car>
             <make>audi</make>
             <color>red</color>
          </car>
          <car>
    >         <make>mercedes</make>
             <color>silver</color>
          </car>
       </DOC>
    </XML>

It does not return the following document:

    <XML>
       <DOC>
          <car>
             <make>audi</make>
             <color>silver</color>
          </car>
          <car>
             <make>mercedes</make>
             <color>red</color>
          </car>
       </DOC>
    </XML>

You can also use complex nested expressions with the `WHEN` operator in query text. For example:

    action=Query&Text=(London:CITY WHEN English:LANG) WHEN ("United Kingdom":COUNTRY)

## Example 2

You can use `WHEN` to return only XML documents in which two attributes that occur in the same field contain specified terms or phrases. For example:

    action=Query&Text=English:_ATTR_LANG WHEN "Cape Town":_ATTR_CAPITAL

This query returns only XML documents in which the `LANG` and `CAPITAL` attributes occur in the same field, and contain the values English (in the `LANG` attribute) and Cape Town (in the `CAPITAL` attribute).

For example, this query returns the following document:

    <XML>
       <DOC>
          <COUNTRY CAPITAL="Cape Town" LANG="English" POP="44">South Africa</COUNTRY>
          <COUNTRY CAPITAL="Berlin" LANG="German" POP="80">Germany</COUNTRY>
       </DOC>
    </XML>

It does not return the following document:

    <XML>
       <DOC>
          <COUNTRY CAPITAL="Cape Town" LANG="Afrikaans" POP="10">South Africa</COUNTRY>
          <COUNTRY CAPITAL="London" LANG="English" POP="80">England</COUNTRY>
       </DOC>
    </XML>

## Example 3

You can also use `WHEN` to return only XML documents in which a field contains a specified term or phrase, and has an attribute that has a specific value. For example:

    action=Query&Text=Fr.html:_ATTR_HREF WHEN France:A

This query returns only XML documents in which an `A` field contains the value France, and has an `HREF` attributes with the value Fr.html.

For example, this query returns the following document:

    <XML>
       <DOC>
          <A HREF="Fr.html">France</A>
       </DOC>
    </XML>

## Example 4

You can use `NOTWHEN` to return XML documents that contain one field with a specified term and phrase, but that do not contain another field and value in the same parent field.

    action=Query&Text=audi:make+NOTWHEN+red:color

This query returns only XML documents in which the `make` field contains the value `audi`, under a parent field that does not also have a `color` field with the value `red`.

For example, this query returns the following document:

    <XML>
       <DOC>
          <car>
             <make>audi</make>
             <color>silver</color>
          </car>
          <car>
             <make>mercedes</make>
             <color>red</color>
          </car>
       </DOC>
    </XML>

It does not return the following document:

    <XML>
       <DOC>
          <car>
             <make>audi</make>
             <color>red</color>
          </car>
          <car>
             <make>mercedes</make>
             <color>silver</color>
          </car>
       </DOC>
    </XML>

## Specify the Number of Levels from the XML Root

You can add a numeric value to the `WHEN` operator to indicate the number of hierarchical levels from the XML root from which to match the terms or phrases.

For example, if you have the following XML document:

    <?xml version="1.0"?>
    <XML>
       <DOCUMENT>
          <DREREFERENCE>Reference_1</DREREFERENCE>
          <car>
             <make>ford</make>
             <color>
                <exterior>blue</exterior>
                <interior>black</interior>
             </color>
          </car>
       </DOCUMENT>
       <DOCUMENT>
          <DREREFERENCE>Reference_2</DREREFERENCE>
          <car>
             <make>ferrari</make>
             <color>
                <exterior>blue</exterior>
                <interior>brown</interior>
             </color>
          </car>
          <car>
             <make>ford</make>
             <color>
                <exterior>yellow</exterior>
                <interior>blue</interior>
             </color>
          </car>
       </DOCUMENT>
    </XML>

The following query returns both documents, because the `exterior` and `make` fields share the same parent field (`<DOCUMENT>`), which is two levels from the root, and contain blue and ford respectively.

    action=Query&Text=blue:EXTERIOR+WHEN2+ford:MAKE

The following query returns only `Reference_1`, because the `exterior` and `make` fields share the same parent field (`<car>`), which is three levels from the root, and contain blue and ford respectively.

    action=Query&Text=blue:EXTERIOR+WHEN3+ford:MAKE

The following query does not return either document, because the `exterior` and `make` fields do not share the same parent field four levels from the root.

    action=Query&Text=blue:EXTERIOR+WHEN4+ford:MAKE

_FT_HTML5_bannerTitle.htm