![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
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 FilesTask queries may be stored in files with the extension .taskquery. They may be edited as text files using the command
visit -as_text name.taskquery
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:
Finds tasks assigned to the current user which have not been completed. Searches the user's domain path using the queries below.
Finds tasks assigned to the current user.
Finds tasks which are incomplete.
A Simple Query ExampleThe 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:
select Id, Priority, Summary where Assigned = "Jones" and State != "Completed" order by Priority, Id
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 QueriesA 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 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).
select Id, Assigned, Summary
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.
select Id, Priority select id, priority
(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:
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,
order by Priority desc, Assigned, Id
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
The field_name is the name of a field. The value may have the any of the following forms:
"characters" or 'characters' or
The quoted forms are used for a literal value, for example
where Priority = "High"
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 equalmatches - 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:
Logical Operators
Sub-expressions within the where clause can be combined using the logical operators in expressions of the form:
exp1 operator exp2
where exp1 and exp2 are sub-expressions (for example, field comparisons) and operator is one of the following:
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.
where not (Priority = "Critical" or Priority = "High") and State = "Completed"
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
queryquery_name
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:
where State != "Completed" and State != "Canceled"
It could be then called in another query, for example
where query in_progress and Assigned = $USER
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
Priority = "Highest"
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:
Priority = High
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
where (Kind = "defect" and State = "Released") or (Kind = "change" and State = "Completed")
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 ReferenceThis 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:
-- -- starts a comment about thesyntax
<name> -- a syntactic construct called 'name'
<a>: e -- the syntax of <a> is given bysyntax expression 'e'
<a>: e1 | e2 -- the syntax of <a> is given by'e1' or 'e2'
[e] -- 'e' is optional
e... -- one or more occurrences of 'e'
e,... -- one or more occurrences of 'e' optionally separated -- by commas
{text
} -- a syntactic entity described bytext
Clause Syntax
<query>: [select <field_name>,...] | [from <task_source>,...] | [where <predicate>] | [order by <order_field>,...]
<task_source>: <domain_name> | default_domain | domain_path | <task_list_name> | <task_name>
<order_field>: <field_name> [asc | desc]
A query may contain any combination of four clauses: select, from, where, and order by.
A <task_source> defines a set of task domains, task list files, and individual tasks to be searched. Multiple sources may be specified.
<domain_name>: <pathname> <task_list_name>: <pathname> <task_name>: <pathname>
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.
<predicate>: <logical_expression>
<logical_expression>: <logical_or>
<logical_or>: <logical_and> | <logical_and> or <logical_or> | <logical_and> xor <logical_or>
<logical_and>: <relational> | <relational> and <logical_and>
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.
<relational>: <primary> | <field_name> <comparison_op> <primary>
<comparison_op>: = | == -- equal != | <> | -- not equal > | -- greater than < | -- less than <= | -- less than or equal to >= | -- greater than or equal to matches -- regular expression matches
<regular_expression>: <string_literal>
A relational expression containing a <comparison_op> compares a field value with another value. Ordering is defined according to the field's type:
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.
<primary>: ( <logical_expression> ) | not <primary> | query <pathname> | <field_name> | <literal> | $<identifier>
<field_name>: <identifier>
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 '$'.
<literal>: <enum_literal> | <state_literal> | <integer_literal> | <fixed_literal> | <float_literal> | <string_literal> | <date_literal> | <pathname>
<enum_literal>: <string_literal>
<state_literal>: <string_literal>
<pathname>: <string_literal> | {pathname with no commas or white space}
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
<identifier>: <letter> [<underscore> | <letter> | <digit>]...
Identifiers must begin with a letter and may contain underscores, letters, and digits. Identifiers and keywords are case-insensitive.
<integer_literal>: <digits>
<digits>: <digits>...
<float_literal>: <digits>.[<digits>][E|e[+|-]<digits>]
<fixed_literal>: <float_literal>
<date_literal>: <string_literal>
<string_literal>: "[<literal_character>...]" | '[<literal_character>...]'
<literal_character>: {any graphic character except the enclosing quote and newline} | \n | -- interpreted as a newline \" | -- interpreted as " \' | -- interpreted as ' \\ -- interpreted as \
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.
<comment>: [#|--]{arbitrary text to end of the current line}
The text following a pound sign ('#') or two minus signs ('––') on a line is treated as a comment and ignored.
<delimiters>: space | -- blank , | -- comma ( | -- left parenthesis ) | -- right parenthesis " | -- double quote ' | -- single quote $ | -- dollar sign # | -- pound sign -- -- minus minus
Two tokens (lexical elements) of a query must always be separated by at least one of the above delimiter characters.
<keywords>: and | asc | by | default_domain | domain_path | from | matches | not | or | order | query | select | where | xor
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.
<future_keywords>: any | between | every | for | in | is | null | this
Rational Software Corporation http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2001, Rational Software Corporation. All rights reserved. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |