TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Task Query Language

Rational Summit/TM provides a task query language to retrieve tasks satisfying user-specified criteria. A task query is a script written in this language. Task queries facilitate management of large numbers of tasks.

A task query is executed to perform a search and retrieve task information. A task query describes the task-selection criteria and specifies how the results of a query should be ordered and presented. Fields of the selected tasks can be displayed, printed, or saved in a file. The pathnames of the tasks selected can be saved in a task list file.

The following sections are provided in this chapter:


Task Query Files

Task queries may be stored in files with the extension .taskquery. They may be edited as text files using the command

Task query files may be stored anywhere and may be controlled or uncontrolled. Queries may be created, edited, and executed via the Task Query Dialog (menu item Tasks > Query. They may also be executed via the task_query command.

Temporary queries which are not stored in files may also be specified using the Tasks > Query menu item or the task_query command.

When a task query file is identified by a simple name, the name is resolved by looking in the following directories in the given order:

1 . the current directory (for a command line reference only)

2 . the user's ~/.Rational directory

3 . the domains in the task domain path and the task kind directories associated with each of those domains, in order.

Thus, a user's ~/.Rational directory is a convenient place to store personal query files, while domains and task kind directories are convenient locations for shared query files.

The following simple queries are included in the predefined change task kind directory (see Change Management Task Kinds) which is in the subsystem identified by $APEX_BASE/task/task_kinds.ss:

todo.taskquery

Finds tasks assigned to the current user which have not been completed. Searches the user's domain path using the queries below.

mine.tasklist

Finds tasks assigned to the current user.

incomplete.taskquery

Finds tasks which are incomplete.


A Simple Query Example

The task query language is described in detail in the following sections. Here is a simple example that may help in understanding the sections that follow:

The example contains three query clauses, a select clause, a where clause, and an order by clause.

The select clause specifies which fields of the tasks found should be displayed when the query is executed. In this case, the task Id, Priority, and Summary fields are to be displayed (assuming these fields are meaningful for the kinds of tasks selected).

The where clause specifies the selection criteria. In this case, a task is selected by the query only if the Assigned field has the value Jones and the State field does not have the value Completed. Thus, this where clause finds tasks assigned to Jones which he has not completed.

The order by clause controls the order in which the tasks found are displayed when the query is executed. In this case, task are sorted first by Priority values. Tasks with the same priorities are further sorted by their task Id field.


Writing Task Queries

A query may be comprised of any combination of the following clauses. All of the clauses are optional and may appear in any order. Each clause may appear only once in a query

.
select
Specifies which task fields are to be displayed in the query output. By default the user's default fields are displayed.
from
Specifies the set of tasks to be searched by the query. This may include domains, task lists, and individual tasks. By default, the tasks in the default task domain are searched.
where
Specifies criteria for selecting a task through tests applied its fields. By default all searched tasks are selected.
order by
Specifies how the selected tasks are to be ordered for output. By default they are sorted by ascending task id.

Select Clause

The select clause is simply a list of names of fields whose values are to be included in the query output. Commas between the list names are optional. The order of the fields determines the order of the columns of field-values in the output. A field may be included more than once. In the absence of a select clause, the user's default fields are used (see Default Fields).

The Select clause

will cause the values of the Id, Assigned, and Summary fields to be included in the output for every task selected.

Field names are case-insensitive. The column headings output by a query will display the field names exactly as they are specified in the select clause. For example, the headings produced by the following select clauses will be different with respect to case.

(The select clause has no effect on which tasks are selected when the query is executed.)

From Clause

The from clause specifies the set of tasks to be searched. It consists of a list of elements which may optionally be separated by commas. Each element may be any of the following:

default_domain
Akeyword that indicates all tasks in the user's default domain should be included in the search.
domain_path
A keyword that indicates all tasks in all of the domains in the user's domain path should be included in the search.
domain pathname
The pathname of a specific domain whose tasks are to be included in the search.
task list pathname
The pathname of a task list whose member tasks are to be included in the search.
task pathname
The pathname of a task to be included in the search.

Wildcard characters included in a pathname are expanded when the query is executed. If the from clause is omitted, the user's default task domain is searched.

Order By Clause

The order by clause specifies how the tasks found by the query are to be ordered in the query output (either displayed output or task list output). It consist of a list of fields that may optionally be separated by commas. The tasks are sorted by the values of the specified fields in the specified order. Each field name may be followed by asc to indicate ascending order or by desc to indicate descending order. By default ascending is assumed. For example,

causes tasks to be sorted first by descending Priority field values, then by Assigned field values (in ascending order) and finally by task ids (in ascending order). Thus, the highest priority tasks will appear first. All tasks with a given Priority will be grouped and sorted by their Assigned field values; all tasks with the same Priority and Assigned field values will be grouped and sorted by task id.

The rules for comparing field values depend upon the type of field. These rules are described in the Where Clause section below.

In the absence of an order by clause, the tasks are sorted by ascending task ids.

Where Clause

The where clause contains an expression that is evaluated for each task that is searched by the query. If the value of the expression is true, the task is included in the result of the query. Otherwise, it is skipped.

The where clause is similar to a boolean expression in a programming language. It usually consists of one or more field comparisons which may be combined with logical operators like and, or, xor, and not.

Field Comparisons

A field comparison compares the value of a field of a task with another value or possibly another field-value. The general form is

field_name operator value

The field_name is the name of a field. The value may have the any of the following forms:

"characters" or 'characters' or

numeric_literal or

field_name or

$variable_name

The quoted forms are used for a literal value, for example

tests whether the Priority field of a task has the value High. A name which is not in quotes is assumed to be the name of a field. If a field name is given as value, the value of that field is used in the comparison. The last form of value retrieves the value of the UNIX environment variable named variable_name and treats it as a literal value.

The operator in a field comparison may be any of the following:

= - equal
== - equal
!= - not equal
<> - not equal
> - greater than
>= - greater equal
< - less than
<= - less equal

matches - matches regular expression

The right operand of the matches operator must be a regular expression (in quotes) of the from used with the Unix grep command. The operator searches the field's value for a match with the regular expression. The result is true if a match is found. For purposes of the matches operator, all fields are treated as text.

Fields values are compared according to the following rules:

enum and state fields
The value is given by the position of the enum value in the set of enum values specified in the field's definition in the task kind. The first value is lowest and the last value is highest.
date fields
Later dates are greater than earlier dates
int, fixed, float fields
Compared as numeric values.
other fields
The textual values are compared lexicographically (alphabetically).

Logical Operators

Sub-expressions within the where clause can be combined using the logical operators in expressions of the form:

where exp1 and exp2 are sub-expressions (for example, field comparisons) and operator is one of the following:

or - Logical or
True if either exp1 or exp2 is true. Exp2 is evaluated only if exp1 is false.
and - Logical and
True if both exp1 and exp2 are true. Exp2 is evaluated only if exp1 is true.
xor - Logical exclusive or
True if exactly one of exp1 and exp2 is true.

The unary not operator may also be used in front of a sub-expression to negate its logical value.

Sub-expressions may be enclosed in parenthesis to control the order of evaluation.

For example:

will select a task if its Priority is neither Critical nor High and it is in the Completed State.

The precedence of and is higher than or; xor has the same precedence as or. However, it is best to use parenthesis when more than one operator is involved.

Query Calls

It is possible to invoke another task query in the where clause. A query call has the form

where query is simply a keyword and query_name is the pathname of a task query file. The pathname may be a simple name or a full pathname. In the case of a simple name, the search rules for a task query files are applied as described in Task Query Files. The .taskquery extension may be omitted in either case.

When a query is called. the expression in it's where clause is evaluated for the task currently being checked. The boolean result of the where expression is the result of the query call. Only the where clause of the called query is used.

As an example, one could create a task query file in ~/.Rational called in_progress.taskquery containing the following Where clause:

It could be then called in another query, for example

to find tasks which are neither Completed nor Canceled and are assigned to the current user. Called queries can of course be more complex.

Query Evaluation

When a query is executed, it is evaluated as follows:

1 . Each element in the from clause is evaluated and the tasks specified by that element are added to the set of tasks to be searched.

2 . The where clause is evaluated for each task in the search set. If the result is true, the task is added to the selected set. The values of fields named in the select and order by clauses are gathered at this time.

3 . The selected tasks are sorted according to the order by clause.

4 . The pathnames of the selected tasks are saved in the specified task list file (if a task list file is requested when the query is executed).

5 . If an option for displaying field values is specified when the query is executed, the field values of the selected tasks are formatted into a columnar listing which may be displayed in a window, printed, or saved in a file.

Errors in Where Clause Evaluation

When the where clause of a query is evaluated certain errors can occur. If the type of a field is incompatible with the value that it is to be compared with, an error is reported indicating the task in which the error occurred. In this case the task is not selected. For example, the comparison

will fail if Priority is defined as an enum field for a task, but Highest is not legal value for that field.

A common error is illustrated in the following example:

Here, the quotes around High have been omitted and High is assumed to be the name of a field. If no such field exists, an error is reported for every task examined.

Another potential source of trouble is the inclusion of different kinds of tasks in the set of tasks to be searched. It is possible that fields such as State have different definitions for different task kinds. If a query is to be applied under these circumstances, the where clause should include tests for the task kind before testing any kind-dependent field. For example, in the query

the State value is compared with "Released" only for the "defect" task kind and with "Completed" only for the "change" task kind. Since the second part of each and expression is only evaluated when the Kind field has the appropriate value, no attempt to do an invalid comparison will result.

It is generally best to include such tests of the Kind fields in any query that may encounter multiple task kinds. It is also beneficial to include the Kind field in the order by clause before any fields that may have more than one definition among selected tasks.


Query Syntax Reference

This section provides a more formal definition of the query syntax outlined above. The syntax of the task query language is described using the following notation:

Clause Syntax

A query may contain any combination of four clauses: select, from, where, and order by.

select
Specifies fields to be displayed for all tasks satisfying the query. By default, the user's default fields (see Default Fields) are displayed. The display consists of a column per field, from left to right, in the given order. Fields may be repeated.
from
Specifies the set of task sources to be searched (domains, task lists, and specific tasks). By default, the user's default task domain is searched.
where
Specifies a boolean expression or predicate to be applied to each task. If the predicate is true for a task, the task is selected (included in the result). When the where clause is omitted, all of the from tasks are included in the result.
order by
Specifies how the resulting tasks are sorted, according to fields and directions. By default, tasks are sorted by ascending (asc) values of the Id field.

A <task_source> defines a set of task domains, task list files, and individual tasks to be searched. Multiple sources may be specified.

A <domain_name>, <task_list_name>, or <task_name> is a pathname. It may optionally appear in quotes. A simple <task_list_name> is resolved in the current directory or else in the user's ~/.Rational directory. A simple <task_name> is resolved in the current directory or in the default domain. The keyword default_domain includes tasks in the user's default task domain. The keyword domain_path includes tasks in all domains in the user's task domain path.

Where Clause Syntax

The where clause contains a <predicate> which is a logical expression that is evaluated for each task included in the search. The predicate generally contains relational expressions which test the values of various fields of each task. Relations may be combined using logical operators (and, or, xor, not).

Logical values are either true or false. The value of a field or expression is considered false if it is the empty string or the digit 0. All other values are interpreted as true. When a logical value results from the evaluation of a relation, the value 0 is produced for false and the value 1 for true.

Logical expressions are evaluated from left to right, however, the and operator has precedence over or and xor. If the left side of a <logical_and> evaluates to false, the right side is not evaluated. Similarly, if the left side of a <logical_or> is true, the right side is not evaluated.

A relational expression containing a <comparison_op> compares a field value with another value. Ordering is defined according to the field's type:

numeric types
Ordered by numeric value.
date
More recent dates are greater than earlier dates.
enum and state
Ordering is given by the order of enum literals in the field's definition. The first literal has the lowest value.
others
Ordering is lexicographical on the textual field contents.

The matches operator performs regular expression matching. The left side is a field value which is treated as a string regardless of the field's type. The <regular_expression> is a quoted string having the syntax defined by the Unix grep command. The matches relation is true if the value of the left side contains a substring matching the regular expression ignoring the case of letters. Regular expression matching is allowed for any field type.

A <primary> is a simple sub-expression. Parenthesized sub-expressions are evaluated first.

The not operator negates the truth value of the <primary> expression which follows it.

The query operator invokes the where clause of the query identified by the <pathname>. The result is the result of evaluating that clause for the current task. A simple name or the full pathname may be used. The .taskquery extension may be omitted.

A <field_name> refers to the value of that field in the task currently being examined.

An environment variable's value may be referenced using the usual UNIX csh notation where the name is preceded by '$'.

A literal specifies a particular value. An enum or state literal value must be enclosed in quotes. A <pathname> can be optionally enclosed in quotes.

Lexical Elements

Identifiers must begin with a letter and may contain underscores, letters, and digits. Identifiers and keywords are case-insensitive.

A <string_literal> may be enclosed in either single or double quotes. An embedded single quote is allowed if the string is enclosed in double quotes and vice versa. Embedded quotes of either type may also be included if preceded by '\' (backslash). A newline character can be included in the string using '\n'.

A <string_literal> can be continued on the next line by including a '\' (a backslash) immediately before the newline character.

The text following a pound sign ('#') or two minus signs ('––') on a line is treated as a comment and ignored.

Two tokens (lexical elements) of a query must always be separated by at least one of the above delimiter characters.

The above keywords are reserved and should not be used as field names. They are case-insensitive. In addition, the following keywords are reserved for future use and should be avoided.


Rational Software Corporation 
http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2001, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS