Selecting Issue Records with a Query

The simplest kind of query selects one or more issue records by comparing the value of one field with a literal value (a constant) — for example, “is the value of the issueNum field equal to 415?” or “does the shortDescription field contain the string ‘busted’?”.

For such simple queries, you can adapt the one we used in section Determining the Field-ID / Field-Name Correspondence above. This query finds all issue records whose productType value is Frammis.

<queryIssue issueDB="XXXXX">
    6 == "Frammis"
</queryIssue>

The output of a query is an XML document whose top-level <issues> element contains zero or more <issue> sub-elements:

>>> accurev xml -l query-filename
<issues>
    <issue>
        ... individual field-name elements ...
    </issue>
    <issue>
        ... individual field-name elements ...
    </issue>

        ...

</issues>

Where’s the Change Package?

You may notice that in the output of a query, the <issue> subelements do not include the issue records’ change package data. Use the <cpkdescribe> query to retrieve an issue record’s change package data. See Listing the Contents of a Change Package on page 270.

More Complex Queries

You can compose and run arbitrarily complex queries. If the query goes just a bit beyond the simplest, you can probably compose it manually. For example, this query finds all issue records whose productType value is Frammis or Widget:

<queryIssue issueDB = "dpt38" useAltQuery = "false">
    <OR>
        <condition>6 == "Frammis"</condition>
        <condition>6 == "Widget"</condition>
    </OR>
</queryIssue>

With more complex queries, be sure to include the useAltQuery = "false" attribute in the <queryIssue> start-tag.

But to minimize the chance of getting lost in the syntax of more complex queries, we strongly recommend that you compose the complex query graphically, then “export” the query to a text file:

1.	In the AccuRev GUI, enter the command Issues > Queries to enter the Query Editor.

2.	Create a new query, give it a name, and specify the query logic.

3.	Click the Save All Queries button.

4.	Place an XML-format dump of all your queries in a text file:

accurev getconfig -p depot-name -u user-name -r query.xml > myqueries.txt

This getconfig command retrieves the contents of the configuration file that stores your queries:

AccuRev-install-dir/storage/depots/depot-name/dispatch/config/user/user-name/query.xml

5.	Use a text editor to extract the XML <queryIssue> element that defines the query. (Don’t extract the entire <query> element, which includes the query’s name and output field definitions.)

6.	Store the <queryIssue> element code in a separate file, say frammis_or_widget.xml.

You can now invoke the query with the CLI:

accurev xml -l frammis_or_widget.xml

Example: This GUI-composed query ...

... is represented by this XML code:

<queryIssue issueDB = "dpt38" useAltQuery = "false">
<AND>

<condition>
1 >= &quot;4500&quot;

</condition>
<OR>

<condition>
14 == &quot;2&quot;

</condition>

<condition>
14 == &quot;24&quot;

</condition>
</OR>
</AND>
</queryIssue>

This code is perfectly good XML, even though it’s not “pretty-printed”. Also note the use of the XML entity reference &quot; which is equivalent to a double-quote character.

Special Field Types

Each field in an AccuWork issue has a field type: Text, Choose, List, etc. For a field of type User (such as the submittedBy field in the example in section Determining the Field-ID / Field-Name Correspondence above), a query defaults to reporting users by their integer user-IDs, rather than by their usernames (principal-names):

    ...
<submittedBy
fid="10">40</submittedBy>
    ...

In this case, you could use the output of the accurev show users command to determine that user john has user-ID 40. Alternatively, you can modify the query to set the attribute expandUsers in the <queryIssue> start-tag:

<queryIssue issueDB = "dpt38"
            useAltQuery = "false"
            expandUsers = "true">
...

Setting expandUsers causes the query to report the values of User fields with usernames instead of user-IDs:

    ...
<submittedBy
    fid="10">john</submittedBy>
    ...

For a field of type Timestamp (such as the dateSubmitted field in the example in section Determining the Field-ID / Field-Name Correspondence above), a query always reports the timestamp as a large integer, representing the number of seconds since Jan 1, 1970 UTC:

    ...
<dateSubmitted
    fid="11">1083606273</dateSubmitted>
    ...

(This is the standard UNIX/Linux timestamp scheme.) You can use Perl to convert the integer into a human-readable string:

>>> perl -e "print scalar localtime(1083606273)"
Mon May 3 13:44:33 2004