![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Graphical User Interface The Rational Summit/TM commands described in this chapter are accessed via menus. If there is a dialog box associated with the menu entry, then the item will be followed by an ellipsis (...), otherwise the item represents a command that will be executed immediately.
Common Dialogs and WindowsThis section describes those dialogs and windows that are commonly accessible via many Rational Summit/TM commands.
Using Dialog Boxes
Please refer to Using Dialog Boxes in the Online Reference for information about the special dialog icons (the Navigator, Alternatives, History, and Completion icons), the File Selection dialog box and the dialog box button panel.
Task Entry Fields
Many dialogs have a text field for entering the names of tasks. For example, the Check Out dialog (see Figure 1 below) has a task entry field called Associate Tasks which is used to associate one or more tasks with the new versions checked out.
Figure 1 Check Out Dialog
![]()
When a simple task name is specified in a task entry field, the default task domain is assumed, unless the dialog also has a Domain field. In that case, the specified domain is assumed. The .task suffix may be omitted.
Most task entry fields are automatically initialized with your current task list, the tasks in the current.tasklist file (if any) in your Rational home directory (~/.Rational).
Entering Task Lists
You may also enter the name of a task list file. In this case, the effect is the same as entering the name of each task in the list. When you use the simple name of a task list, your Rational home directory (~/.Rational) is assumed. The .tasklist suffix is required.
Navigator Icon
A task entry field has a special Navigator icon which brings up the Select Tasks dialog instead of the usual File Selection dialog. (The Navigator icon for Task Id field of the Select Tasks dialog itself is an exception.) The Select Tasks dialog provides additional assistance in selecting tasks (see Select Tasks Dialog). For example, you can select from a different domain, choose from task lists, run task queries, and create or visit tasks.
Alternatives Icon
A task entry field also has an Alternatives icon which pops up a menu containing the tasks in your "to do" task list. Your "to do" list is in the file todo.tasklist in your Rational home directory (~/.Rational). If your "to do" list is empty or missing, the popup menu will be empty.
The menu displays the simple task id and the Summary field of each task in the "to do" list. When you click on a task in the menu, the task name is placed in the task entry field.
You can construct a "to do" list containing those tasks which you access most frequently. This will make it easier to select tasks. A maximum of 128 tasks can be displayed in the popup menu. The "to do" task list can be created and edited using the Tasks > Query command, the Tasks > Set ToDo command, or a text editor by first creating the file ~/.Rational/todo.tasklist and then using the visit command
visit -as_text ~/.Rational/todo.tasklist
The -as_text option causes the task list to be treated as text. (Otherwise, visit creates a summary window displaying the tasks in the list.) The task names should be specified one per line. If you use full path names, the interpretation of the list will not be affected by the current default task domain.
Select Tasks Dialog
The Select Tasks dialog is used to choose tasks. It is invoked via the Navigator icons of task entry fields in other dialogs, for example, the Parent field in the New Task dialog or the Associate Tasks field in the Check Out dialog.
A slightly modified form of the Select Tasks dialog is also displayed by the Tasks > Set Current and Tasks > Set ToDo commands.
The Selected Tasks list box (see Figure 2) of this dialog initially contains the tasks (if any) that were already in the task entry field when the Navigator icon was pressed (for example, the tasks in the Associate Tasks field of the Check Out dialog).
Figure 2 Select Tasks Dialog - Domain Page
![]()
The set of tasks in the Selected Tasks list box can be modified. These tasks are transferred to the original task entry field when the OK or Apply button is selected.
The top part of the Select Tasks dialog manages the list of selected tasks (see Figure 2 above). The bottom part of the dialog contains an options menu (labeled Select Tasks From:) that displays different dialog pages to assist in the selection of tasks from different sources:
Domain - Selects tasks from a domain. This is the default page. It initially displays the tasks in the default domain.
Task List - Selects tasks from a task list file.
Task Query - Executes a task query (see Task Query Language) and selects tasks from those matching the query.
Selected Tasks Area
The top part of the dialog that manages the list of selected tasks. These are the tasks transferred to the task entry field when the OK or Apply button is pressed.
Selected Tasks List Box
The selected tasks. The buttons on the right are related to the list box:
Task Id / Summary Fields
The name of a task to be selected. The Summary field displays the value of the Summary field of the task. The Summary field of the dialog is not editable.
The Navigator icon invokes the File Selector dialog in the context of the task domain specified by the text field in the Domain page below. If this field is empty, the default task domain is used.
The Alternatives icon displays the tasks in the user's "to do" task list (file ~/.Rational/todo.tasklist) and their Summary field values.
The following buttons are associated with the Task Id and Summary fields:
Whenever a task in the Selected Tasks list box is selected, the task's name is automatically placed in the Task Id field and its Summary field is displayed in the Summary field of the dialog.
Select Tasks From > Pages
The lower part of the dialog is variable. The page displayed is selected from the Select Tasks From: options menu.
Each of the pages (Domain, Task List, and Task Query) includes a list box in which the tasks (in the domain, in the task list, or matching the query, respectively) may be displayed. By default, the tasks are displayed in this list box, for example, in the Tasks in Domain list box on the Domain page (see Figure 2 above). Alternatively, the tasks may be displayed in a separate window.
When a task in the list box is selected, its task id and Summary field value are automatically displayed in the Task Id / Summary fields above. The task can then be added to the Selected Tasks list using the Add: button next to the Task Id field.
In addition, the Add Selected Tasks button just above the list box adds all selected tasks to the Selected Tasks list box directly.
The Display Options near the bottom of the dialog determine which task fields are displayed and whether they are displayed in the list box or in a separate summary window. The display options are described in more detail later.
Domain Page
Selects tasks from a domain. The text field names the domain (see Figure 2 above). By default, the tasks are displayed in the Tasks in Domain list box. Initially, the default domain is displayed.
The Alternatives icon displays the domains in the user's task domain path. The buttons immediately below the domain text field are:
Task List Page
Selects tasks from a task list. The text field names the task list file (see Figure 3). By default, the tasks in the list are displayed in the Tasks in List list box.
Figure 3 Select Tasks Dialog - Task List Page
![]()
If no extension is specified, the .tasklist extension is assumed. If a simple name is specified, the user's ~/.Rational directory is assumed. The Alternatives icon displays the simple names of the task list files in that directory. The buttons immediately below the task list field are:
Task Query Page
Selects tasks from those that match a task query (see Task Query Language). The text field names a task query file (see Figure 4). By default, the tasks matching the query are displayed in the Tasks from Query list box.
Figure 4 Select Tasks Dialog - Task Query Page
![]()
If no extension is specified, the .taskquery extension is assumed. If a simple name is specified, the search rules described in Task Query Files apply. In particular, the search includes user's ~/.Rational directory, the domain views in the task domain path and the associated task kind directories. The Alternatives icon displays the task query files that are visible via their simple names.
The buttons immediately below the task query field are:
Display Options
The Display Options near the bottom of the dialog control how tasks are displayed for the Select Tasks From: pages.
The following options control which task fields are displayed:
By default, only the task ids are displayed. Whenever, the Summary or the default field values are requested, the task query mechanism is invoked to retrieve the field values. This may take several seconds if a large number of tasks are involved.
The following options control where the tasks are displayed:
Above Display the tasks in the list box immediately above (the default).
In a Window Display the tasks in a separate summary window.
Usually, it is convenient to display the tasks in the list box, since they can easily be selected and added to the Selected Tasks list box. However, sometimes it may be desirable to display multiple sources of tasks at the same time, for example several task lists. The In a Window option will create an independent summary window for each set of tasks.
To select tasks from a summary window and add them to the Selected Tasks list box, use the drag and drop mechanism as follows:
- 1 . Select the desired tasks in the summary window (using the Control key to select more than one).
- 2 . Press the middle mouse button with the mouse positioned over one of the selected tasks.
- 3 . While keeping the mouse button depressed, drag the mouse to the Task Id field and release the button. This drops a space-separated list of the selected tasks into that field.
- 4 . Press the Add: button next to the Task Id field to add the tasks to the Selected Tasks list box.
Additional Topics
For additional information, refer to these topics:
Task Summary Windows
Task summary windows are useful for examining a long list of tasks in a concise format. Information about each task is presented in a tabular form including the current values of selected fields. By default these are the Id, State, Priority, Assigned and Summary fields. The fields displayed can be altered by changing the default fields for the appropriate task kinds (see Default Fields).
In general, a task summary window is produced as the result of visiting a task list file (a file with the extension.tasklist which contains the names of tasks) or by executing a task query. In particular, the Tasks > Query and Tasks > ToDo commands create such windows.
Within a task summary window, a task which has child tasks can be expanded (with the View > Expand command) causing the children to be listed immediately below the parent and indented slightly.
Tasks can be selected from a summary window and placed into the task entry fields of many dialogs by using the mouse to drag and drop the selected tasks.
Here is an example of a task summary window.
Figure 5 Task Summary Window
![]()
Set Current Button
Pressing this button initiates the Tasks > Set Current command that allows you to examine and change the value of the current task list. Any selected tasks in the task summary window are used as the potential new value for the current task list (which will replace the old value if confirmed). Otherwise, the current value is used.
Clear Current Button
Pressing this button performs the Tasks > Clear Current command that sets the current task list to none.
Set ToDo Button
Pressing this button initiates the Tasks > Set ToDo command that allows you to examine and change the value of the "to do" task list. Any selected tasks in the task summary window will be used as the potential new value for the "to do" task list (which will replace the old value if confirmed). Otherwise, the existing value will be used.
Additional Topics
For additional information, refer to these topics:
Rational Summit/TM EnvironmentTasks > Set Domains
The Tasks > Set Domains command is used to examine and change the value of the user's task domain path for the current session. It is also used to select which task domain in the task domain path is to serve as the default task domain.
If one or more task domain objects are selected before initiating this command, those domains will appear in the Domains field and the Default Domain field will be empty. If no objects are selected, then the current values for the task domain path are displayed in the Domains field and the default task domain is displayed in the Default Domain field. When you choose this command, the Set Task Domains dialog box appears (see Figure 6).
Figure 6 Set Task Domains Dialog
![]()
Domains Field
Displays the list of the task domains which will be used as the new value for the task domain path if the OK or Apply button is pressed. Domains can be deleted from this list by selecting them and pressing the Remove button.
Default Domain Field
Displays the task domain which will serve as the new default task domain if the OK or Apply button is pressed.
Domain Field
Specifies the name of a task domain to be acted upon. If the Add button is pressed, the domain is added to the Domains field. If the Set Default button is pressed, the domain is added to the Domains field and also placed in the Default Domain field.
Additional Topics
For additional information, refer to these topics:
Tasks > Set Current
The Tasks > Set Current command is used to examine and change the value of the current task list. The tasks in the current task list are used to initialize task entry fields in other dialogs, for example the Associate Tasks fields in Summit/CM dialogs.
When you choose this command, the Set Current Tasks dialog box appears. This dialog is identical to the Select Tasks dialog, excepting the following differences:
- The dialog title is Set Current Tasks,
- There is no Set Current button, and
- The OK and Apply buttons set the user's current task list by saving the tasks in the Selected Tasks list box in the user's ~/.Rational/current.tasklist file (replacing the old value). If there are no selected tasks, the current task list will be empty.
If one or more task objects are selected before initiating this command, those tasks will appear in the Selected Tasks field. If no tasks are selected, the tasks in the current task list (if any) are displayed in the Selected Tasks field.
Additional Topics
For additional information, refer to these topics:
Tasks > Clear Current
The Tasks > Clear Current command simply makes the current task list empty. Subsequently, task id entry fields in dialogs that are initialized with the current task list will be initially empty.
Additional Topics
For additional information, refer to these topics:
Tasks > Set ToDo
The Tasks > Set ToDo command is used to examine and change the value of the user's "to do" task list. The tasks in the "to do" task list appear in the menu displayed by the Alternatives icons associated with task id fields in other dialogs, for example the Associate Tasks fields in Summit/CM dialogs. Hence, it is convenient to keep the names of tasks you are currently working on in this list.
When you choose this command, the Set ToDo Tasks dialog box appears. This dialog is identical to the Select Tasks dialog (see Select Tasks Dialog), excepting the following differences:
- The dialog title is Set ToDo Tasks and
- The OK and Apply buttons set the user's "to do" task list by saving the tasks in the Selected Tasks list box in the user's ~/.Rational/todo.tasklist file (replacing the old value). If there are no selected tasks, the "to do" task list will be empty.
If one or more task objects are selected before initiating this command, those tasks will appear in the Selected Tasks field. If no tasks are selected, then the current value for the "to do" task list is displayed in the Selected Tasks field.
Additional Topics
For additional information, refer to these topics:
Tasks > Reset Task Info
This command ensures that task control information and user settings (stored in task domains, in task kinds, and in the user's ~/.Rational directory) are refreshed from those sources before executing further commands. A question dialog is displayed which allows the command to be canceled.
This command may be used, for example, after a new field has been added to a task kind, after the task editor for a task kind has been changed, or after a Task_Gui or Task_Roles file has been altered or added.
The command causes Summit/TM to discard any cached task control information and reload it from the source files as needed. Any dialogs which are open when the command is issued will be canceled to ensure that commands executed subsequently will use the refreshed task control information. As a side affect of this action, the Dialog Server process is restarted and the initial Apex or Summit dialog is redisplayed.
Creating Tasks, Domains, and KindsFile > New > New Task
The File > New > New Task command is used to create one or more new tasks within a given task domain. Multiple tasks are created when a task template is used that has relationships to other templates.
When you choose this command, the New Task dialog box appears. This dialog can also be invoked from some other dialogs such as the Set Current Tasks dialog. The new tasks are not actually created until either the OK or Apply buttons are pressed. Task ids for the new tasks are generated using the task id generation policies of the specified task domain and the task kinds.
Figure 7 New Task Dialog
![]()
Domain Field
The task domain in which to create the new task. Initially displays the default task domain. The Navigator icon can be used to locate some other task domain. The Alternatives icon displays the domains in the task domain path.
Parent Field
The parent task (if any) for the new task. By default, a new task will have no parent task unless one is specified by the template used. The Navigator icon invokes the Select Tasks dialog which can be used to search for the desired parent task. The Alternatives icon displays the tasks in the user's "to do" task list with their Summary fields.
Kind Field
The task kind of the new task. The Alternatives icon lists only those task kinds which are supported by the given task domain as defined by the domain's kind path. The default value for this field is just the first task kind on the domain's kind path.
Template Field
The task template which will be used to define the initial values of the new task's fields. If the template has relationships with other templates, tasks corresponding to each of the related templates (transitively) are also created. The created tasks are related to one another in the same way as the corresponding templates.
The Alternatives icon lists only those task templates which are supported by the given task kind as defined by the task kind's template path.
The default value for this field is just the first task template on the task kind's template path.
Name Field
Specifies an optional name to be included in each new task id. The task kind policy switch file (for each kind of task created) must have an Id_Format field that includes the <user_id> element (see Task Id Generation Policy). When a task id is formed, the specified name is substituted for this element.
Visit It Check Box
Causes the new task's associated Task Editor dialog to be invoked after the task is created.
Additional Topics
For additional information, refer to these topics:
- Default Task Domain
- Select Tasks Dialog
- Task Domain Kind Path
- Task Editor
- Task Id
- Task Id Generation Policy
- Task Kind
- Template Path
- Task Template
File > New > New Task Domain
The File > New > New Task Domain command is used to create a new task domain view. When you choose this command, the New Task Domain dialog box appears. The new domain view is not actually created until either the OK or Apply button is pressed.
Figure 8 New Task Domain Dialog
![]()
New Domain View
The name of the new task domain view to be created. The Name and Context fields must together name a view which does not already exist.
Name Field
The name of the new view. If this is a relative pathname, the Context field is used to qualify the name, if the context field is empty, the current context is used.
Context Field
A pathname used to qualify the Name field, if that field contains a relative name. This field is initialized with the current context.
Subsystem Status Label
Indicates whether the subsystem specified by the Name and Context fields already exists. This label is set automatically by the dialog. There are three possible values:
When a new subsystem is created, default values are displayed from the installation prototype task domain, which is accessed by the pathname:
$APEX_BASE/task/task_domain_prototype.ss
Kind Path List Box
This list specifies the task kind directories that will comprise the task kind path of the task domain. If the domain subsystem already exists, the existing kinds (if any) are initially displayed. If the subsystem does not exist, the kinds displayed are those in the installation prototype task domain.
The existing kind path (if any) will be replaced with the kinds specified when the domain view is created.
Text Field
The text field below the Kind Path list box is used to enter the name of a task kind directory to be added to the kind path.
Add Button
Adds the contents of the text field to the Kind Path list box.
Remove Button
Removes selected entries from the Kind Path list box.
Clear Button
Removes all entries from the Kind Path list box.
"Allow invalid kind directory..." Check Box
By default, if any of the kind directories in the Kind Path do not exist, the new domain view will not be created. However, if this check box is set, the domain view will be created even if some or all of the kinds specified do not yet exist.
Task Id Options
This box specifies options used in generating ids for new tasks created in the domain subsystem. If the task domain subsystem already exists, the existing option values are displayed. The options specified will replace the existing subsystem options (if any) when the domain view is created.
Prefix Field
The character(s) to be used as a prefix in forming a task id.
Width Field
The minimum number of digits used in the task index part of generated task ids. If the task index has fewer digits it is padded with zeros (0's) on the left.
Suffix Field
The character(s) to be used as a suffix in forming a task id.
Tasks > Copy Kind Directory
The Tasks > Copy Kind Directory command creates a new task kind directory by copying an existing task kind directory. This command should be used to copy task kinds instead of File > Copy Object because it automatically updates the task editor files and template files to reflect the new kind name. (Template relationships are not modified.)
When you choose this command, the Copy Task Kind dialog box appears. The copy operation does not take place until either the OK or Apply button is pressed.
Figure 9 Copy Kind Directory Dialog
![]()
Source Kind Directory Field
The pathname of an existing task kind directory to be copied. For example, one of the kind directories in the standard task kinds can be copied. These kind directories are located in
$APEX_BASE/task/task_kinds.ss/view
Destination Kind Context Field
The context for the Destination Kind Directory Name, if a relative pathname is used.
Destination Kind Directory Name Field
The name of a directory. If this is a relative pathname, it is qualified by the Destination Kind Context field.
The directory specified (by the Context and Name fields) must include a view within an existing subsystem. If the view does not exist, it will be created. If the directory specified is a view or an existing subdirectory of a view, the new kind directory is created as a subdirectory of that directory with the same simple name as the source kind directory. Otherwise, if the specified destination directory does not exist, then it is created and used as the directory of the new task kind.
Make It Controlled Check Box
This check box causes all of the copied files to be made controlled objects.
Additional Topics
For additional information, refer to these topics:
Viewing and Modifying TasksView > Expand
Within a directory viewer window or a task summary window the View > Expand command can be used on a task object. If the task has child tasks, then the children are listed immediately below the parent and indented slightly.
The View > Expand command can also be applied to a task list object. In this case, the tasks belonging to the list are displayed immediately below the task list and indented slightly.
In either case, the default fields of the tasks are displayed (see Default Fields).
Additional Topics
For additional information, refer to these topics:
Navigate > Visit - Task Lists
When the Navigate > Visit or Navigate > Visit In Place command is issued on a selected task list, a summary window is created which displays the values of the default fields of the tasks in the list.
Navigate > Visit - Task Editor Dialogs
When the Navigate > Visit or Navigate > Visit In Place command is issued on a selected task object, the Task Editor dialog associated with that task is invoked. This dialog is defined in the task's task kind directory. The dialog is used to examine and modify the information stored in the task. Any changes made to a task's fields are not permanently recorded until either the OK or Apply button is pressed.
Since Task Editor's are customizable, the following dialog is only a representative example.
Figure 10 Task Editor Dialog
![]()
Domain Field
Displays the task domain in which the task is stored. It cannot be modified.
Id Field
The task id number that was generated when the task was created. It cannot be modified.
Kind Field
The task kind used to create the task. It cannot be modified.
Parent Field
The parent task. If the task has no parent, then this field will not appear. It cannot be modified.
Edit Check Box
Indicates that the fields of the task are to be modified. It is set automatically when an editable field of the task is changed. It can also be set manually to reserve the right to modify the task.
When the Edit check box is set, the task is locked against editing by others. The lock is released and the check box is reset when the OK, Apply, Reset, or Cancel buttons are pressed. If the check box is reset manually, after fields have been changed, but before the changes have been saved, a message box appears to ask for confirmation that changes should be discarded.
State Transition Menu
The field labeled State initially displays the current value of the state field. The popup menu contains a list of potential transitions from the current state to successor states (as defined by the state machine in the task kind). Some state transitions listed may not be selectable because the user does not have the necessary task role privileges to perform that transition.
If a state transition is selected, the transition will be attempted when the OK or Apply button is pressed. The state transition will be carried out only if all preconditions associated with that transition (if any, as defined by the state machine) are successfully performed. If the preconditions succeed, then the state field is set to the new state. Finally, any post-actions associated with the transition are executed. Other task fields changed in the dialog are saved regardless of whether a state transition occurs.
Priority Field
The priority of the task. This field has an enumerated field type so its Alternatives icon lists all the field's legal values.
Assigned Field
The user assigned to the task. This field has an enumerated field type so its Alternatives icon lists all the field's legal values.
Summary Field
Displays a single line summary description of the task.
Pages Menu
Lists a number of dialog pages, that can be individually selected to view additional information about the task. The available pages are:
Description
Related Tasks
Version History InformationThe contents of these pages are:
- Description Page
Displays a detailed description of the task.
- Related Tasks Page
Displays the task's parent task, if any. This is a read-only field. Double-clicking on this window will visit the parent task.
Displays any child tasks belonging to the task. This field cannot be changed directly, but new children can be added to the list via the File > New > New Task command and or the New Child button. Double-clicking on a child in this list has the same effect as selecting the child and then clicking the Visit button described below.
Activates the New Task dialog which can be used to create a new child task for the task.
Visits a selected child task or the parent task. The parent task, if any, is visited when no child is selected. The selected task's Task Editor dialog is invoked. The parent or any child can also be visited by double-clicking on the Parent field or on the child in the Children field, respectively.
- Version History Information Page
Version History Information Field
Lists all of the controlled object versions which are currently associated with the task. This list cannot be changed directly, but it can be modified via the various Summit/CM commands which check out, check in and abandon controlled object versions as well as the Tasks > Add and Tasks > Remove commands.
Double-clicking on a version in this list has the same effect as selecting the version and then clicking the Visit Current button described below.
Visits the current version of the selected object in the Version History Information field. Note that the version number from the selection is ignored; instead, the current version in the same view is visited.
Creates a temporary file containing the image of the exact version selected in the Version History Information and visits it. The object name, history number and version number are used to form the name of the temporary file.
Additional Topics
For additional information, refer to these topics:
- File > New > New Task
- State Machine
- Task Domain
- Task Id
- Task Kind
- Role
- State
- Tasks > Add
- Tasks > Remove
Tasks > Query
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/TM task query language. The query language is described in detail in Task Query Language.
The Task Query dialog (displayed by this command) may 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.
The upper part of the dialog (labeled Query Text:) displays the current text comprising the query (see Figure 11 below). This text may be edited directly or via other components of the dialog.
Figure 11 Task Query Dialog - Where Page
![]()
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 (see Figure 11). On the other hand, if the dialog is accessed through a task query file, the Query File page will be displayed initially.
Query Text
Displays the current query text and may be edited directly (see Figure 11). 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 (see Figure 11). 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
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 (according to the rules for resolving these names, see Task Query Files). 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 (see Figure 12).
Figure 12 Task Query Dialog - Query File Page
![]()
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 Task Query Files 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.
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.
Figure 13 Task Query Dialog - Task Kind Page
![]()
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 (see Figure 14). 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 (see Default Fields).
When this page is grayed (insensitive), the Recheck box described earlier must be cleared to revalidate the query before the page can be used.
Figure 14 Task Query Dialog - Select Clause Page
![]()
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).
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 (see Figure 15). The from clause specifies the set of tasks to be searched. If this clause is omitted, the tasks in the default domain are searched.
Figure 15 Task Query Dialog - From Clause Page
![]()
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.
Note: The order of elements in the Search 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.
Figure 16 Task Query Dialog - Order By Clause Page
![]()
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).
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
For additional information, refer to these topics:
- Task Query Language
- Default Task Domain
- Task Domain Kind Path
- Task Field Type
- Task Kind
- Task Summary Windows
- Default Fields
Tasks > ToDo
The Tasks > To Do command simply presents the tasks in the user's current "to do" task list in a task summary window.
Additional Topics
For additional information, refer to these topics:
Generating ReportsTasks > Run Report
The Tasks > Run Report command provides a convenient interface for running various report generation scripts. As described in detail below, this command is best suited for running scripts with a special naming convention and internal format. Some of the sample scripts, included with the product, produce such reports as:
- A table showing how many tasks are in each state, broken down by assigned developer and priority.
- The change traffic and stability metric.
- A project status report on all tasks collectively and individually.
- A listing of all the versions associated with a set of tasks.
- A summary window listing all completed tasks.
The end result of successfully running a report script is typically either a report output file (which is "visited" in the user's default text editor) or a listing of a group of tasks (which is displayed in a summary window). The actual outcome is determined by the script executed.
These scripts can be customized for particular applications and new ones can be easily added. Such customized scripts should follow the conventions established by the provided example scripts. In particular, they need to follow the same argument passing convention.
When you choose this command, the Task Reports dialog box appears. A report script is not executed until either the OK or Apply button is pressed or a particular report selection is double clicked. When a script is executed, it runs in a separate process so that you can still work on something else while the report is being generated.
Any objects selected within the window from which this dialog is invoked are placed into the Actual Arguments for Report Script field.
If changes are made to a report script file after this dialog has been started and those changes are intended to affect the information displayed by the dialog, then the Reset button must be pressed in order for the dialog information to be updated.
Figure 17 Run Report Dialog
![]()
Selected Report Field
The pathname of an existing report script to be executed. It is most easily set by clicking on one of the report selections in the Reports To Choose From list box. Alternatively, this field can be entered directly or via its associated search icons.
Visit Report Script Button
This button causes the report script file identified by the Selected Report field to be viewed in a text editor. This is useful for examining or modifying a script.
Reports to Choose From List Box
This list box displays the known report generation scripts that are available to run along with an informative title. Scripts other than the ones listed can also be executed, but they must be manually selected within the Selected Report field. The reports listed are determined by searching for files with a .taskreport suffix within the following directories:
- The directory context of the window from which this dialog was initiated.
- The user's ~/.Rational directory.
- All task domains in the user's task domain search path.
- All task kinds referenced by the task domains in the user's task domain search path.
The report scripts from a particular directory are listed only once, where ever the directory first appears in the above search order.
Selecting a report from this list will cause the Selected Report, Argument List Usage for Report Script, and Report Output File fields to be filled in with information derived from the report script file. If a report from this list is double clicked, then the report script will be immediately executed with no opportunity to specify any additional arguments.
The title displayed for a given report is derived from information contained in the report's script file. A source line from this file with the following prefix will be used as the title:
# Title:
# Title: Produce Project Status Report
Argument List Usage for Report Script Field
This field usually displays information about what kinds of arguments can or must be passed to the selected report script. It can also contain any other information that might be helpful to the user in understanding how to use the report script or what the report actually generates. The information in this field cannot be changed. It is derived directly from the script file itself. Any script source lines that begin with the following string are placed in this field:
# Arguments:
Multiple source lines of this form can be placed in a script file, but they must be adjacent to one another. For example:
# Arguments: // This report has two help lines
# Arguments: [task] // and one optional argument
Actual Arguments for Report Script Field
The actual arguments to be passed to the report script can be specified in this field. Since they are passed to the script as command line arguments, special characters, such as spaces must be explicitly quoted. Although multiple lines of arguments can be entered, the lines are combined into one (space separated) before being passed to the report script.
Note that the full pathnames of any objects that are selected in the window from which this dialog is invoked are initially placed in this field. Thus, selected tasks, for example, can be conveniently passed to a given report script.
Report Output File Field
This field specifies the file into which the output of the report is saved. The user can accept the default value displayed or replace it with a different file name. Whether it is used at all or how it is used is determined by the report selected. A report script advertises the fact that it will produce a report output file by including a source line with this prefix:
# Report:
At most one such source line of this form should appear in a script file. For example:
# Report: /project/status_report.out
The example report scripts provided with the product use the following convention for report output file names:
~/.Rational/report_name_%y_%m_%d.rpt
The special characters, %y_%m_%d, are actually replaced by the script with the current year, month and day.
Customized report scripts can be written using their own report output file naming conventions.
Report scripts, that successfully generate a report output file, typically "visit" the file in the user's default text editor, at the conclusion of the report's execution.
Using Rational Summit/TM with Summit/CMThis section describes those features of Rational Summit/TM which are integrated with Rational Summit/CM, the Summit Configuration Management (CM) system which is an integral part of Apex and Rational Summit.
The commands included in the Rational Summit/TM CM Commands subsection below (near the end of this section) are only available with Rational Summit/TM and are fully documented in that subsection.
The rest of the commands discussed in this section are also available in versions of Apex that do not include Rational Summit/TM. For these commands, only the Rational Summit/TM-specific enhancements are described here. The common features of these commands can be found in the Online Reference manual.
Creation Commands
The following file creation commands have all been enhanced in exactly the same way for Rational Summit/TM.
File > New Ada
File > New C
File > New C++
File > New File
File > New ConfigurationAssociate Tasks Field
This field appears only when the Make it controlled check box is set. It specifies the tasks to be associated with the newly created and controlled file. It is initialized with the current task list. The Navigator icon can be used to select a different set of tasks by activating the Select Tasks dialog. The Alternatives icon pops up a menu of tasks in the "to do" task list with their Summary fields.
Additional Topics
For additional information, refer to these topics:
Common Commands
File > Delete Object
Tasks to Associate with Controlled Objects Field
This field specifies the tasks to be associated with any controlled objects that are deleted. It is initialized with the current task list. The Navigator icon can be used to select a different set of tasks by activating the Select Tasks dialog. The Alternatives icon pops up a menu of tasks in the "to do" task list with their Summary fields.
Additional Topics
For additional information, refer to these topics:
File > Copy Object
Tasks to Associate with Checked In Versions Field
This field appears only when the Check In Before Copy radio button is selected. It specifies the tasks to be associated with the checked in object. It is initialized with the current task list. The Navigator icon can be used to select a different set of tasks by activating the Select Tasks dialog. The Alternatives icon pops up a menu of tasks in the "to do" task list with their Summary fields.
Additional Topics
For additional information, refer to these topics:
Version Control Commands
Control > Check In
Associate Tasks Field
Specifies the tasks to associate with the checked in objects. It is initialized with the current task list. The Navigator icon can be used to select a different set of tasks by activating the Select Tasks dialog. The Alternatives icon pops up a menu of tasks in the "to do" task list with their Summary fields.
Additional Topics
For additional information, refer to these topics:
Control > Check Out
Associate Tasks Field
Specifies the tasks to associate with the checked out objects. It is initialized with the current task list. The Navigator icon can be used to select a different set of tasks by activating the Select Tasks dialog. The Alternatives icon pops up a menu of tasks in the "to do" task list with their Summary field values.
Note: Task association is not supported for private check outs.
Additional Topics
For additional information, refer to these topics:
Control > Abandon
When a checked out version of an object is abandoned, any task associations, made to that particular version (for example. when the object was checked out or via the Tasks > Add command), are removed since the version no longer exists.
Additional Topics
For additional information, refer to these topics:
Control > Update Objects & Views
Tasks Field
This field is displayed only when the radio button called Accept newer versions associated with tasks below is selected. The Tasks field specifies tasks whose associated controlled object versions are to be accepted into the destinations identified by the Objects or Views field at the top of the dialog.
The Navigator icon can be used to select a different set of tasks by activating the Select Tasks dialog. The Alternatives icon pops up a menu of tasks in the "to do" task list with their Summary fields.
When the versions associated with a task are accepted, the task is said to be "accepted". Since a task represents a unit of work, it is often important that tasks should either be completely accepted or not be accepted at all. The following options control the completeness of task acceptance:
It is possible that accepting a designated task will cause versions from other tasks to be accepted. The following mutually exclusive options determine how this is handled:
Accept other tasks Accept any other tasks that are associated with accepted versions.
Warn (and continue) Do not accept the other tasks. Issue a warning and continue.
Fail Do not accept any tasks.
The following procedure determines which versions are used to update the destination files. All of the versions associated with the given tasks in the Tasks field are collected. If the Accept dependant tasks check box is also selected, then the versions associated the descendants of any accepted task are also collected. (The descendants of a task are its child tasks and their children, recursively.) If the Accept other tasks check box is selected, any additional tasks associated with the accepted versions are also accepted.
If an object has more than one version in the set, then all but the latest version are removed. The remaining versions are the source versions to be accepted. They are checked for conformance with the No incomplete tasks and No task regression options.
Control > Object Properties
Associate Tasks Field
This field appears only when either changing an uncontrolled object to a controlled object or changing the "checked in/out" state of a controlled object. It specifies the tasks to be associated with the newly controlled or checked in/out object. It is initialized with the current task list. The Navigator icon can be used to select a different set of tasks by activating the Select Tasks dialog. The Alternatives icon pops up a menu of tasks in the "to do" task list with their Summary fields.
Note: Task association is not supported for private check outs.
Additional Topics
For additional information, refer to these topics:
Control > Change Object Properties
Tasks for CMVC Operations Field
This field appears only when one of the following radio buttons is selected in which case it has the indicated purpose:
In all cases, the field is initialized with the current task list. The Navigator icon can be used to select a different set of tasks by activating the Select Tasks dialog. The Alternatives icon pops up a menu of tasks in the "to do" task list with their Summary fields.
Additional Topics
For additional information, refer to these topics:
Rational Summit/TM CM Commands
This section describes those commands which are only available with Rational Summit/TM and only work in conjunction with Summit/CM.
Tasks > Add
The Tasks > Add command is used to associate tasks with specified controlled object versions. Adding a task that is already associated with a given version has no effect. When you choose this command, the Add Tasks to Objects dialog box appears.
Figure 18 Add Tasks to Objects Dialog
![]()
Objects List
Names the controlled objects to which task associations will be added. It is initialized with the current object selection. Additional objects can be added to this list via the Add: button and its related text field. Objects can be deleted from this list by selecting the objects and pressing the Remove button. The Clear button removes all of the objects.
Version Field
Specifies which version of each object is affected. By default, the current version of each object is affected.
Associate Tasks Field
Identifies the tasks that are to be associated with the given controlled objects when the OK or Apply buttons are pressed. It is initialized with the current task list. The Navigator icon can be used to select a different set of tasks by activating the Select Tasks dialog. The Alternatives icon pops up a menu of tasks in the "to do" task list with their Summary fields.
Additional Topics
For additional information, refer to these topics:
Tasks > Remove
The Tasks > Remove command is used to disassociate tasks from specified controlled object versions. Removing a task association that does not exist has no effect. When you choose this command, the Remove Tasks from Objects dialog box appears.
Figure 19 Remove Tasks from Objects Dialog
![]()
Objects List
Names of the controlled objects from which task associations will be removed. It is initialized with the current object selection. Additional objects can be added to this list via the Add: button and its related text field. Objects can be deleted from this list by selecting the objects and pressing the Remove button. The Clear button removes all of the objects.
Version Field
Specifies which version of each object is affected. By default, the current version of each object is affected.
Disassociate Tasks Field
Identifies the tasks that are to be disassociated with the given controlled objects when the OK or Apply buttons are pressed. It is initialized with the current task list. The Navigator icon can be used to select a different set of tasks by activating the Select Tasks dialog. The Alternatives icon pops up a menu of tasks in the "to do" task list with their Summary fields.
Additional Topics
For additional information, refer to these topics:
Tasks > Show
The Tasks > Show command displays tasks related to the currently selected objects in a directory window. For an ordinary controlled object, the related tasks are the tasks associated with the current version of the object in the containing view. For a file with the suffix .tasklist, the related tasks are the tasks named in the task list file.
For each related task, a one-line summary is displayed containing the values of the default fields of the task (see Default Fields). There is one exception to this rule described below.
The Show command has two modes of operation. The mode is selected via the shift key. If the shift key is not depressed when Show is selected, the related task information is displayed, in place, in the same directory window. The summaries of the related tasks for a selected object are placed immediately below the selected object and slightly indented within the directory window. These task summaries can be removed by using the View > Elide command on the selected objects.
If the shift key is held down when Show is selected and there is more than one related task, then the related tasks are displayed in a newly created summary window. The selected objects do not appear in that window, just their related tasks.
If the shift key is held down when Show is selected and there is only one related task, then the related task is displayed within its task editor dialog.
Rational Software Corporation http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2001, Rational Software Corporation. All rights reserved. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |