![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Tasks > Query (Summit/TM)The Tasks > Query command is used to search a set of candidate tasks for tasks that satisfy user-specified criteria. The query to be performed is expressed in the Summit task query language. The query language is described in detail in the Summit/TM User's Guide.
The Task Query dialog (displayed by this command) can be used to compose, edit, and execute a query. The dialog can produce a task list file containing the pathnames of the matching tasks. It can also display a sorted listing of selected fields of these tasks in a task summary window.
When you choose this command, the Query Task dialog box appears.
The upper part of the dialog (labeled Query Text:) displays the current text comprising the query. This text may be edited directly or via other components of the dialog.
The lower part of the dialog contains an options menu that displays alternative pages of the dialog that support specific functions as follows:
In the case of a simple query that is not to be saved in a file, it is often necessary to compose only a where clause. Hence, for convenience, the Where Clause page is displayed initially. On the other hand, if the dialog is accessed through a task query file, the Query File page will be displayed initially.
Task Query Dialog Box Fields:
- Query Text
Displays the current query text and may be edited directly. When the query text is edited indirectly, using the Select, From, Where, or Order By Clause page, the query text is automatically updated in this window.
- Edited Check Box
Indicates that the query text has been modified since it was last saved in a file. Clearing this check box has the same effect as the Save button under the Task Query field on the Query File page; the query text is saved in the specified file.
- Undo Button
Restores the query text to its state just before the last editing operation. Successive presses restore earlier states. The number of undo's is limited to 10.
- Redo Button
Each press of this button redoes a prior undo, i.e. it reapplies an edit which has been undone.
- Del <- Button
Deletes text from the current cursor position to the left until a blank is reached.
- Del -> Button
Deletes text from the current cursor position to the right until a blank is reached.
- Del (...) Button
Deletes all text within and including the innermost matching parentheses surrounding the current cursor position,
- Clear Button
Deletes all of the query text.
- Recheck Check Box
Indicates that the query text has been edited, either directly, or via the above deletion buttons, or using the Where Clause page. In these cases, the query text may become syntactically incorrect (as a result of editing). The Select Clause, From Clause, and Order By Clause pages are disabled when this check box is set until the syntax is rechecked.
Clicking the Recheck box when it is set, invokes the task query compiler to recheck the text. If compilation is successful, the Recheck box is cleared, and the Select Clause, From Clause, and Order By Clause pages are automatically updated and re-enabled. If the compilation fails, a message box appears and one or more syntax errors are displayed in the message window. The Recheck box will remain set until the text is successfully compiled.
When the query text is modified via the Select Clause, From Clause or Order By Clause page, it always remains syntactically correct.
- Apply Button
This button executes the query text specified in the Query Text window. If the query text is empty, but a query file is specified in the Task Query file field on the Query File page, that query file is automatically loaded and executed. If the Recheck box is set, the query is automatically compiled before it is executed.
- OK Button
Same as Apply but closes the dialog. This button also saves the query text in the file ~/.Rational/tmp/saved.taskquery if it has been edited but not saved.
Where Clause Page
Edits the where clause of the query. The where clause contains an expression that is evaluated for each task searched to determine whether that task should be selected by the query and included in the output.
The where clause usually contains one or more field-value comparisons which may be combined using logical operators (and, or, xor, and not) and parentheses.
- Kind Field
Specifies the simple name of a task kind. It is used to change the current task kind for the dialog and to add task kind comparisons to the where expression.
The Alternatives icon displays the task kinds associated with the current domain (see Task Kind Page below). This field and the Kind field on the Task Kind Page are automatically kept identical. Therefore the value in this field affects the field names displayed by Alternatives icons of the field-name fields in the dialog.
The Kind field can also be used to test for a particular kind of task. When a query is expected to search different kinds of tasks, any field comparisons which are applicable to a particular task kind should be qualified with a test for that task kind. For example, the following where clause
where (Kind = "defect" and State = "released") or (Kind = "change" and State = "completed")
tests whether the State field is "released", if the kind of the task is "defect" or whether the State is "completed" if the kind of the task is "change".
- Add Comparison: Kind = kind Button
Adds an equality comparison of the Kind field with the value in the Kind field of the dialog (see above), to the query text at the current cursor position. For example, if the contents of Kind is defect then
Kind = "defect"
- Field Comparison Form - Field Op Value
This portion of the Where Clause Page is used to add a comparison of a field with a value to the where clause expression in the query text. The name of the field is specified in the Field field, an operator is selected from the Op options and a value is entered in the Value field.
The Add Comparison > Field-Op-Value button inserts the entire field-value comparison into the query text at the current cursor position.
After a field comparison is added, if another field comparison is immediately inserted, without adding a logical operator (and, or, or xor), the and operator is automatically inserted.
- Field Field
Specifies a field name. The Alternatives icon displays the fields defined by the current task kind.
- Op Radio Buttons
Specifies a comparison operator. The operators are
= - equal
!= - not equal
> - greater than
>= - greater equal
< - less than
<= - less equal
matches - matches a regular expressionFor enum and state fields, the values increase from the first enum item or state to the last. Numeric fields are compared numerically. Dates are compared chronologically; recent dates are greater than earlier dates. All other field types are compared lexicographically as text.
State field comparisons are useful in selecting tasks in various stages of development, especially when the states are ordered to follow the usual development sequence.
The matches operator performs regular expression matching (as in the UNIX grep command) on a field's textual value.
- Value Field
Specifies a literal value or a regular expression. The Alternatives icon displays the possible values when the Field field contains the name of an enum or state field of the current task kind.
Note: Numeric literals can be represented in the where clause with or without quotes.
- Add Comparison > Field-Op-Value Button
Inserts the field, operator, and value at the current cursor position.
- Call Query Field
Specifies the name of another query (in a task query file) that is to be called by the current query. A query call is evaluated by evaluating the where expression in the called task query file for the task currently being tested.
The Alternatives icon displays all queries visible by their simple names. The full pathname of a query may also be specified.
The Add: button adds a call to the query at the current cursor position in the query text.
- Add > not ( ) and or xor... Buttons
These buttons at the bottom of the Where Clause Page are used to add operators, parentheses, spaces and newlines. The symbol on the button pressed is inserted into the query text at the current cursor position. Of course, the symbols can also be typed directly into the query text window. The available operators are:
and, or, xor - binary logical operators
not - unary logical negationSub-expressions may be enclosed in parentheses to control the order of evaluation. However, and has higher precedence than or and xor.
Simple Examples Using only the Where Page
Find all tasks (in the default task domain) that are assigned to "fred":
- 1. . Enter "assigned" in Field
- 2. . Enter "fred" in Value
- 3. . Press Add Comparison > Field-Op-Value
- 4. . Press OK
where assigned = "fred"
Find all tasks that are assigned to "fred" and have the priority "medium" or higher:
- 1. . Enter "assigned" in Field
- 2. . Enter "fred" in Value
- 3. . Press Add Comparison > Field-Op-Value
- 4. . Enter "priority" in Field
- 5. . Select ">=" in Op
- 6. . Enter "medium" in Value
- 7. . Press Add Comparison > Field-Op-Value
- 8. . Press OK
In this example, the and operator is inserted automatically. The query text is
where assigned = "fred" and priority >= "medium"
Find all tasks that are assigned to either "fred" or "mary":
- 1. . Enter "assigned" in Field
- 2. . Enter "fred" in Value
- 3. . Press Add Comparison > Field-Op-Value
- 4. . Press or
- 5. . Enter "mary" in Value
- 6. . Press Add Comparison > Field-Op-Value
- 7. . Press OK (tasks assigned to "fred" or "mary" are displayed)
where assigned = "fred" or assigned = "mary"
Query File Page
This page is used to load and save task query files and to specify output options for query execution
![]()
- Task Query Field
Specifies the name of a task query file. The Alternatives icon displays all of the task query files (files with the .taskquery extension) in the user's ~/.Rational directory, in all domains on the domain path, and in the associated kind directories. When a simple query name is entered, the search rules described in "Tasks Query Fields" in the Summit/TM User's Guide are used. If an extension is omitted, .taskquery is assumed.
The specified query file is loaded automatically if the Apply or OK button is used and the query text window is empty.
- Load Button
Loads the contents of the specified query file into the Query Text window.
- Save Button
Saves the contents of the Query Text window in the specified query file. The query text can also be saved by clicking the Edited check box when it is set.
- Task List Field
Specifies the name of a task list file to set when the query is executed. The full pathnames of the sorted, selected tasks are saved in this file.
The task list file name is implicit when the ~/.Rational option or the Temporary option is selected (see below).
- Task List Options
The following mutually exclusive options are provided for specifying the task list output file:
- Mode Options
Specify how the task list is used. There are two mutually exclusive options:
- Show in Window Check Box
Displays the resulting task list and field values in a task summary window, when set. Otherwise, the selected tasks are not displayed. This option is automatically set when the Temporary option is used.
Task Kind Page
Specifies the "current" task kind and domain for the dialog. The fields defined by the current task kind are displayed by the Alternatives icons of the field-name fields in the dialog
![]()
- Kind Field
The simple name of the current task kind for the dialog. This name is interpreted in the context of the domain specified by the Domain field. The Alternatives icon displays the task kinds associated with this domain. By default, the first kind in the kind path of the domain is displayed.
- Domain Field
The current task domain. The name in the Kind field is interpreted in the context of this domain. The Alternatives icon displays the domains in the user's task domain path.
Select Clause Page
Edits the select clause of the query. The select clause contains of a list of task fields to be displayed in the query output. If this clause is omitted, the default fields for the task kinds of the selected tasks are displayed.
When this page is grayed (insensitive), the Recheck box described earlier must be cleared to revalidate the query before the page can be used
![]()
- Fields List Box
Displays the fields in the select clause. When the query is executed, the values of the specified fields are displayed in the task summary window in columns in the specified order. A given field may appear more than once. A heading is displayed at the top of each column. The alphabetic case of the field name in the heading is the same as specified in the list box.
A field is added by entering its name in the text field below the list box and pressing the Add: button on the left. New fields are added after the last selected entry in the list, or as the first entry, when no list entry is selected.
The Alternatives icon displays the field names defined by the current task kind (see Task Kind Page above).
- Remove Button
Removes all selected fields in the list box.
- Move Up Button
Moves the selected field up one position in the list box.
- Move Down Button
Moves the selected field down one position in the list box.
- Add > All Order By Fields Button
Adds all of the fields in the order by clause to the select clause list box. Fields already in the list box are not added.
From Clause Page
Edits the from clause of the query. The from clause specifies the set of tasks to be searched. If this clause is omitted, the tasks in the default domain are searched
![]()
- Search Tasks From List Box
This list box displays the list of elements in the from clause. The list may include task domains, task lists, tasks and the keywords default_domain and domain_path.
Elements are added by entering pathnames in the fields below the list box and pressing the associated Add: buttons.
- Remove Button
Removes all selected elements in the list box.
- Move Up Button
Moves the selected element up one position in the list box.
- Move Down Button
Moves the selected element down one position in the list box.
Note: The order of elements in the Select Tasks From list box has no effect on the execution of the query.
- Domain Field
The name of a task domain. The domain is added to the list box by pressing the Add: button, indicating that the domain is to be searched by the query. The Alternatives icon displays the domains in the user's task domain path.
- Add > default_domain Button
Adds the keyword default_domain to the list which indicates that the user's default task domain is to be searched.
- Add > domain_path Button
Adds the keyword domain_path to the list which indicates that all domains in the user's task domain path are to be searched.
- Task List Field
The name of a task list file. The task list is added to the From list box by pressing the Add: button, indicating that the tasks in the list are to be searched by the query.
The Alternatives icon displays the task list files in the user's ~/.Rational directory.
- Task Field
Specifies a task name. The task is added to the From list box by pressing the Add: button, indicating that the task is to be included in the search.
The navigate button invokes the Select Tasks dialog which can be used to select multiple tasks. The Alternatives icon displays the contents of the user's todo task list.
Order By Page
Edits the order by clause of the query. The order by clause determines how the selected tasks are sorted, according to field values. If this clause is omitted, task are sorted by ascending task ids
![]()
A sort field is added by entering its name in the text field below the list box and pressing the Add: button on the left. The Field Direction option indicates whether the field is to be sorted by ascending or descending values. New fields are added after the last selected entry in the list, or as the first entry, when no list entry is selected. A given field may appear only once.
The Alternatives icon displays the field names defined by the current task kind (see Task Kind Page above).
- Remove Button
Removes all selected fields in the list box.
- Move Up Button
Moves the selected field up one position in the list box.
- Move Down Button
Moves the selected field down one position in the list box.
- Reverse Button
Changes the sort direction of the selected field from ascending to descending or vice versa.
- Add > All Select Fields Button
Adds all of the fields in the select clause to the order by clause list box. Fields already in the list box are not added.
Additional Topics
Rational Software Corporation http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2001, Rational Software Corporation. All rights reserved. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |