![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Summit/TM Command Line Interface This manual includes a complete discussion of the Rational Summit/TM command line interface. It also describes the Rational Summit/TM specific enhancements made to the Summit/CM (Configuration Management) commands that are also available without Rational Summit/TM. For the enhanced commands, only the added features are discussed here.
Please see the Command Reference for more information about the command line interface in general, and about the enhanced commands, in particular.
The following topics are covered here:
- Task Arguments
- Setting the Domain Path
- Deleting, Copying, and Moving Tasks
- Maintaining Task Lists
- Metrics and Reports
- Using Rational Summit/TM with Rational Summit/CM
Most Rational Summit/TM commands require task ids. Tasks identified by relative pathnames are found by looking first in the current context and then in the default task domain. The task file extension (.task) may be omitted, except in the visit command. For example, consider the three tasks:
/proj1/task_domain.ss/all.wrk/B00005.task /my/task_domain.ss/test.wrk/t16.task /bugs/bug_domain.ss/all.wrk/b00100.task
If the default task domain is /my/task_domain.ss/test.wrk and the current context is /bugs/bug_domain.ss/all.wrk, then these three tasks can be passed to the list_task command as follows:
% list_task /proj1/task_domain/all.wrk/B00005 t16.task b00100
Tasks may also be specified by identifying a file with the extension .tasklist that contains a list of task pathnames (one per line). The entries in the list are treated as though they were entered on the command line. Simple names of .tasklist files are resolved first in the current context and then in the current user`s ~/.Rational directory. The extension .tasklist cannot be omitted.
These identification rules also apply to the visit command (except when the -as_text option is used). However, since the visit command may be applied to many kinds of objects, the .task extension may not be omitted.
Rational Summit/TM and Summit/CM commands that call for a "task..." argument expect one or more task ids to be supplied. Other commands require (or allow) a –task task option. Unless specified otherwise, such commands will also accept one or more task ids. However, if more than one name is given in task, the list must be quoted. For example:
% check_in -task B12 file.c % check_in -task "B12 B14" file.c
Setting the Domain Path
The environment variable APEX_TASK_DOMAIN_PATH may specify a list of commonly used task domains. The first such domain in the list is called the default domain and is used to resolve relative task names. The setenv command may be used to set the default domain before Apex or Summit is started. In the following stylized example, the default domain is set to /task_domain.ss/all.wrk:
% setenv APEX_TASK_DOMAIN_PATH /task_domain.ss/all.wrk
set_current_task - adds tasks to the current task list
Syntax
set_current_task task...
Alias
curtskDescription
Adds the named tasks to the user's current task list.
Parameters
Example
set_current_task B00004 B00008show_current_task - displays the current task list
Syntax
show_current_task
Alias
shcurtsk
Description
Displays the contents of the user's current task list.
unset_current_task - removes tasks from the current task list
Syntax
unset_current_task task...
Alias
uncurtsk
Description
Removes the named tasks from the user's current task list.
Parameters
Example
unset_current_task B00004set_todo_task - adds tasks to the "to do" task list
Syntax
set_todo_task task...
Alias
tdtsk
Description
Adds the named tasks to the user's "to do" task list.
Parameters
show_todo_task - displays the "to do" task list
Syntax
show_todo_task
Alias
shtdtsk
Description
Displays the contents of the user's "to do" task list.
unset_todo_task - removes tasks from the "to do" task list
Syntax
unset_todo_task task...
Alias
untdtsk
Description
Removes the named tasks from the user's "to do" task list.
Parameters
create_task - creates new tasks
Syntax
create_task [options]
Alias
crtsk
Description
Creates one or more new tasks in a specified task domain. The –domain option is required. The –kind option is also required when the –template option is omitted.
Templates are used to initialize the new tasks when the –template option is specified or a default template exists for the kind. Any fields of a new task which are not initialized from values in a template are initialized to default values determined from the task kind. The default value for an enum field is the first enum value. The default value for a state machine field is the Default_State specified in the .sm file that defines the state machine. The default value for all other field types is the empty string.
A task template is similar to a task and can have relationships with other templates specified in fields of type task_path. Such relationships between templates are prototypes for initial relationships to be created. When the –template option is used, additional tasks are also created for each related template, transitively. In this case, the resulting tasks will have the same relationships to one another as the corresponding templates.
A template must always specify the value of the Kind field.
Parameters
- options
Specifies the task domain in which the new tasks will reside. This option is required. The keyword default may be used to indicate the user's default task domain, that is:
-domain default
Specifies the task kind of the new task. Only the simple name of the task kind is expected, because the full name is determined from the task domain's kind path. This option is required if the –template option is omitted.
Provides the task template to be used to initialize the fields of the new task. Additional tasks are created if the template is related to other templates, as described above.
If a simple name is specified, the current directory is searched. If the template is not found in the current directory and the –kind option is specified, the kind directory is also searched.
The task kind specified in a template supersedes the kind specified in the –kind option (if any).
Default value: The first template in the task kind's template path property.
Specifies an existing task that is to be the parent of the created task. The created task will be a child of this task. (This option must be omitted if a template that defines a Parent relationship is used.)
Default Value: None. (The newly created task will have no parent task unless there is a related Parent template.)
Specifies a 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 Kind Policy Switches" in Customizing Rational Summit/TM). When a task id is formed, the specified name is substituted for this element.
Names a file that will contain the generated task id of the new task if the task is successfully created.
Example
create_task -domain /proj/task_domain.ss/all.wrk -kind bug
visit(task) - displays tasks (Summit/TM only)
Syntax
visit [-as_text] task...
Description
This is an enhanced command, which, when supplied with the pathnames of one or more task files (including the .task extension), displays each task's field information using the task editor associated with the task's kind.
Parameters
- task...
Names of the tasks to be visited, including the .task extensions. Simple task names are resolved in the current directory, if possible, or else in the default task domain.
- options
Opens the file/task with a text editor rather than the task editor.
If the environment variable APEX_EDITOR is set to apex, the Tools > Editor command will also open task files in a text editor.
visit(tasklist) - displays tasklists in task summary windows (Summit/TM only)
Syntax
visit tasklist...
Description
This is an enhanced command, which, when supplied with the pathnames of one or more tasklist files (including the .tasklist extension), displays each tasklist in a separate summary window. The default fields of the tasks are displayed in the window (see "Default Fields" in Using Rational Summit/TM).
When a .tasklist file is visited, and a summary window for the task list already exits, the window is brought to the front but is not updated. The summary widow can be refreshed from the task list file using the File > Redisplay command.
Parameters
- tasklist...
Names of the task lists to be visited, including the .tasklist extensions. Simple tasklist names are resolved in the current directory, if possible, or else in the user's ~/.Rational directory.
Note: Objects of different types, such as a task and a tasklist can be visited with a single visit command.
task_query - finds and displays particular tasks
Syntax
task_query [options] [taskquery]
Description
Executes a task query (a search for tasks the meet specified criteria) and optionally produces a task list file, a summary window, a listing, a listing file, or a comma-separated value list file. The tasks satisfying the criteria are the selected tasks.
Parameters
- taskquery
Specifies the name of a file containing a task query written in the Summit/TM task query language, (see "Task Query Language" in Using Rational Summit/TM). If no extension is specified, .taskquery is assumed. If a simple name is specified, it is resolved in the current directory, the user's ~/.Rational directory, or in the task domains and associated task kinds included in the user's domain path.
When the taskquery file is omitted, the query to be executed is defined by other options or by default. Each clause of the query stored in the taskquery file can be overridden by options described below.
- options
Names the fields to be included in the output. The values of these fields (in the given order and aligned in columns) are listed for each selected task. This option overrides the select clause in the taskquery file (if any). Multiple field names must be enclosed in quotes and separated by spaces and/or commas.
When this option is specified, task ids are listed only if an appropriate field (Id or Name) is included.
Default value: The fields in the select clause of the taskquery file (if any). Otherwise, the default fields for the task kinds of the selected tasks.
For a given task kind, the default fields may be specified either in the Task_Field_List file (if any) in the user's ~/.Rational directory or else in the Default_Field_List switch (if any) in the task kind's Taskmgmt_Kind.sw file (see "User Environment" and "Task Kind Policy Switches" in Customizing Rational Summit/TM). Otherwise, the default fields are Id, State, Priority, Assigned and Summary.
Defines the set of tasks to searched. This option overrides the from clause in the taskquery file (if any). The tasks may be pathnames of domains, task list files, and tasks. The keywords default_domain and domain_path may be used to include the default domain or all domains on the domain path, respectively, in the search. Multiple elements must be enclosed in quotes and separated by spaces and/or commas.
Default value: The tasks specified by the from clause in the taskquery file (if any). Otherwise the user's default task domain.
Specifies the ordering of selected tasks in the output according to field values. This option overrides the order by clause in the taskquery file (if any). Each order_field has the form
field_name
[asc|desc]
which indicates a sort field and optionally a sort direction. The keyword asc indicates ascending field values (the default), while desc indicates descending field values. The query output is ordered by each field specified. All tasks which have the same value for a given order field are grouped and then ordered by the next field in the list.
Multiple order fields must be enclosed in quotes and separated by spaces and/or commas.
Default value: The order by clause in the taskquery file (if any). Otherwise, tasks are sorted by ascending task ids.
Specifies a boolean expression (predicate) to be evaluated for each task searched. Tasks which satisfy the predicate are included in the output. This option overrides the where clause in the taskquery file (if any). The expression must be enclosed in quotes.
Generally, the expression consists of field comparisons and logical operators (and, or, xor, and not). For example,
–where "Priority = 'High' and State != 'Completed'"
Note that, since the expression is enclosed in double quotes, single quotes must be used for string literals within the expression. The complete syntax of where expressions is described in the "Task Query Language" section of Using Rational Summit/TM.
Default value: The where clause expression in the taskquery file (if any). Otherwise, all searched tasks are included in the output.
Includes a heading in the output containing the field names above the respective columns of the field values. By default no headings are output.
Indicates the number of spaces to be used between the columns of field values. The default is value is 2.
Writes a sorted listing of field values for the selected tasks to standard output. This option is applied by default when the –list_file, –summary, –csv, –task_list, and –task_list_file options are all omitted.
Writes a sorted listing of field values for the selected tasks to the file designated by output_file.
Displays a sorted listing of field values for the selected tasks in a summary window. This option has no effect when the command is run in batch mode.
Writes the full pathnames of the selected and sorted tasks to a task list file in the user's ~/.Rational directory with the same simple name as the taskquery file and the extension .tasklist. The taskquery file must also be specified.
Writes the full pathnames of the selected and sorted tasks to the file tasklist. If no extension is specified, .tasklist is assumed. If a simple name is specified the user's ~/.Rational directory is assumed.
This option causes the sorted list of field values for the selected tasks to be written to the file csv_file, in the form of a comma-separated value file (see the Using Rational Summit/TM).
Examples
task_query # displays all tasks in the default domain
task_query todo # executes ~/.Rational/todo.taskquery # writes results to standard output
task_query -where "Priority = 'High'" \ -from todo.tasklist -summary # displays all High priority tasks in the user's # todo task list in a summary window
list_task - lists selected fields of specified tasks
Syntax
list_task [options] task...
Alias
lstskDescription
Lists the values of selected fields of the specified tasks. The output is ordered by ascending task ids. Without any options, this command lists the default fields of each task.
Parameters
- task...
Specifies the tasks to be listed. Tasks, task list files, and task domains may be specified.
- options
Names the fields to be included in the output. The values of these fields (in the given order and aligned in columns) are listed for each task. Multiple field names must be enclosed in quotes and separated by spaces and/or commas.
When this option is specified, the task ids are listed only if an appropriate field (Id or Name) is included.
Default value: The default fields for the task kinds of the tasks.
For a given task kind, the default fields may be specified in the Task_Field_List file LIST switch (if any) in the task kind's Taskmgmt_Kind.sw file (see "User Environment" and "Task Kind Policy Switches" in Customizing Rational Summit/TM). Otherwise, the default fields are Id, State, Priority, Assigned and Summary.
Includes a heading in the output containing the field names above the respective columns of the field values. By default no headings are output.
Indicates the number of spaces to be used between the columns of field values. The default value is 2.
Writes the field values of the tasks to output_file instead of standard output.
Writes the field values of the tasks to the file csv_file, as well, in the form of a comma-separated value file (see Using Rational Summit/TM).
Examples
list_task B00005 list_task -fields "Assigned Priority" my.tasklist
Note: The command
list_task [options] task...
is equivalent to
task_query [options] -from "task..."
if –file is changed to –list_file.modify_task - modifies selected fields of a task
Syntax
modify_task options field_value_pair...
Alias
modtsk
Description
Modifies the values of selected task fields within a single task. The –task option is required.
Parameters
- field_value_pair...
Provides the task field names and corresponding values. Each field_value_pair is actually two separate arguments, the first naming the field and the second giving a value.
field_name field_value
The empty string ("") may be specified for a field value.
By default, the value of each field named is replaced with the corresponding field value. However, if the -cumulative option is specified, each field named must be a list field and the corresponding value is appended to the list.
Field names are case insensitive, but case is always significant for values. An empty value and any value containing special characters or white space must be quoted.
A field_value can also be specified by the contents of a file using the notation:
where file_name is the pathname of the file containing the value to be used.
Task fields of type state can be changed only if the preconditions required by the associated state machine are satisfied. If not, then no fields are modified. If so, the changes are made and any appropriate post-actions are executed.
Task fields of type task_path or task_path* represent bidirectional relationships with other tasks. For example, the predefined Parent and Children fields represent parent/child relationships. When such fields are modified, the reverse fields in the related tasks are automatically updated to maintain the consistency of the relationships.
- options
Names the task to be modified. This is option is required.
Indicates that each value is to be appended to the existing list of values in the corresponding list field. By default the existing value is replaced. This option can only be used when the field of each field_value_pair has a list value type.
Example
modify_task -task B00016 Assigned fred Priority High
Deleting, Copying, and Moving Tasks
Special commands are provided for deleting, copying, and moving task objects. These commands should be used for task objects instead of the usual discard, copy, and move commands because they recognize and manage relationships involving the affected tasks and associations of those tasks with versions.
delete_task - deletes tasks
Syntax
delete_task [options] task...
Description
Deletes the specified task objects.
If a task object to be deleted is associated with a version, then either the –keep_versions option or the –update_versions option must be specified.
If a task object to be deleted has a relationship with another task object that is not to be deleted, then either the –keep_relationships or the –remove_relationships option must be specified.
Parameters
- task...
- options
Preserve the associations in versions to the deleted tasks.
Note: Associations in versions to non-existent tasks may result when this option is used.
Remove associations in versions to the deleted tasks.
Preserve relationships (in other tasks) to the deleted task objects.
Note: Relationships to non-existent tasks may result when this option is used.
copy_task - copies tasks
Syntax
copy_task [options] source... destination
Description
Copies the specified source task objects to the specified destination domain. The kind of each source task must be on the kind path of the destination domain.
If a source task object is associated with a version, then either the –keep_versions option or the –update_versions option must be specified.
If a source task object has a relationship with a task object, then either the –keep_relationships option, the –remove_relationships option, or the –remove_relationships option must be specified.
Parameters
- source...
The tasks to be copied. Tasks and task lists may be specified.
- destination
The domain in which the new copies are to be created.
- options
Preserve the associations to versions in the new tasks. The associations in versions to tasks are not updated.
Note: Associations in the new tasks to versions which have no corresponding reverse association to the tasks may result.
If a source task is associated with a version, create a similar association between the copy and that version.
Preserve the original outgoing relationships in the copies. Existing tasks are unaffected.
Note: Relationships in the new tasks with no corresponding reverse relationships may be created when this option is used.
If a source task is related to another source task, create a similar relationship between the corresponding new copies. Similarly, if a source task is related to a task which is not copied, create a corresponding relationship between the new copy and that task.
Do not copy relationships. The new copies will have no relationships.
move_task - moves tasks
Syntax
move_task [options] source... destination
Description
Moves the specified source task objects to the specified destination domain by copying and then deleting them. The kind of each source task must be on the kind path of the destination domain.
If a source task object is associated with a version, then either the –keep_versions option or the –update_versions option must be specified.
If a source task object has a relationship with a task object, then either the –keep_relationships option, the –remove_relationships option, or the –remove_relationships option must be specified.
Parameters
- source...
The tasks to be moved. Tasks and task lists may be specified.
- destination
The domain to which the tasks are to be moved.
- options
Preserve the associations of versions to the deleted source tasks.
Note: Associations in versions to non-existent tasks may result when this option is used.
Revise the associations of versions with the source tasks to be associations with the moved tasks.
Preserve the original outgoing relationships. The moved tasks are identical to the source tasks. Other existing tasks are unaffected.
Note: In the new tasks, relationships without corresponding reverse relationships and relationships to non-existent tasks may result when this option is used.
If a source task is related to another source task, create a similar relationship between the corresponding moved tasks. Similarly, if a source task is related to a task which is not moved, delete the old relationship and create a corresponding new relationship between the moved task and that task. Delete all relationships involving the source tasks.
Delete all relationships involving the source tasks before moving them. The moved tasks will have no relationships.
Maintaining Task Lists
The task_query command can be used to create a task list. The set_todo_task, unset_todo_task, set_current_task, and unset_current_task commands can be used create or clear the todo.tasklist and current.tasklist files, respectively, in the user's ~/.Rational directory.
In addition, the maintain_tasklist command is provided to create, update, and delete task lists in general.
maintain_tasklist - creates or modifies a tasklist
Syntax
maintain_tasklist [options] tasklist
Description
Creates or modifies the specified task list file. The –create, –update, and –delete options are mutually exclusive. At least one of these options must be specified.
Parameters
- tasklist
The name of the tasklist file. If a simple name is used the current directory is checked first and then the ~/.Rational directory. When creating a tasklist with a simple name the current directory is assumed. The .tasklist extension is required.
- options
Specifies the tasks to be added or deleted. (Task lists may be included.) Multiple names must be separated by spaces and enclosed in quotes. The task names are resolved and must identify existing tasks.
Creates a new task list file. If no tasks are specified, the new task list will be empty. Otherwise, the tasks specified by the –task option are stored in the new task list. If the task list file already exists, it is overwritten.
If the task list file does not exist, this option has the same effect as –create. Otherwise, the specified tasks are added to the existing task list file. Any tasks which are not already in the task list are added at the end, in the given order.
Deletes the specified tasks from the task list. If no tasks are specified, the task list file is deleted.
Metrics and Reports
Metrics Support
The standard task kinds include some limited support for collecting and reporting various task metrics. Currently, these metrics involve primarily the presentation of task state transitions (and other, more static, task information) over time. Since not all development teams will want to monitor task activity so closely, the collection of these metrics must be explicitly enabled. This can be easily accomplished by enabling a couple of task domain customization actions. Once enabled, these actions will keep track of the history of a task's state transitions. Reports on the histories of a set of tasks can then be generated using the change traffic and stability metric reporting tool, traffic.
Task Domain Customization Actions
In order to record when a task's state transition occurs, the post create task and post modify task customization actions must be enabled. In the directory for the change task kind, you should find the following file
task_domain.actions
This file must be included in the TASK_CUSTOMIZATION_KEY of the task domain's switch file which is found in
task_domain_subsystem/Policy/Taskmgmt.sw
For example, the switch should look something like this (only on a single line) after you have added it to the switch file
TASK_CUSTOMIZATION_KEY:change_task_kind_directory/task_domain.actions
Note that this customization action file can be used by any task kind.
Once these customization actions are established, then whenever a task is created or modified in the associated task domain, the appropriate action in the task_domain.actions file will be executed. These actions merely check the associated task's kind directory for a script file by the name of task_kind_actions.ash. If such a file is found, then it is executed. The specific effect of this script is dependent on the task kind in which it is found. However, in general, such scripts do two things. First, they initialize certain fields in a newly created task that have a dynamic value. For example, in the change task kind, the Create_Date is set to the current date and the Originator field is set to the name of the user creating the task. Second, they record any changes to the State field of a task (including its initial value) by appending the current date and time, the user id, and the new state value to the Task_History field of the task.
Metrics Reporting Tool
The traffic tool can be used to generate reports on various metrics associated with any kind of task. However, to be able to use this tool to its fullest extent, you must enable the collection of various task history information as discussed in the previous section on Metrics Support.
One specific indicator of the progress and quality of a software development activity is the overall change traffic. This metric provides insight into the stability of the software and its convergence towards stability (or divergence towards instability). Schedule predictability is the primary value of this metric. It is mostly a general indicator of how well the software development activity is performing its job.
By default, the traffic tool will collect and present the information needed to evaluate this change traffic and stability metric. It does so by displaying the cumulative number of tasks that have been created (opened) and the number that have been closed, over a selected period of time. If the gap between the number of opened and closed tasks continues to widen over time, then that is an indication that the project is diverging toward instability and may need remedial action.
Here is an example of a traffic report for this metric:
Date 9/95 10/95 11/95 12/95 1/96 2/96 3/96 =================================================== Opened 7 20 33 48 56 62 65 -------------------------------------------------- Closed 0 1 5 12 31 47 58 ===================================================
This example indicates that for the first three months it looked like things were getting out of hand for the development team since new tasks were being added much faster than they could be closed. However, in the final three months, the project showed greater signs of stability as the rate of newly created tasks dropped and the development team took care of the backlog.
traffic - generates reports on traffic and other metrics
Syntax
traffic [options] tasks...
Description
By default, this tool generates a report on the change traffic and stability metric, for the specified tasks, as described in the previous section. It can also produce tables showing the cumulative (frequency) count for the various values stored in a particular field. For example, how many tasks have been assigned to particular developers or how many tasks are in the various task states or of a particular priority. The report is sent to the standard output.
Parameters
- tasks...
Specifies the tasks whose metrics are to be reported. These tasks can be of any task kind.
- options
Defines the starting date from which metrics reporting is desired. Any task activity before this date is ignored. Some examples of legal date options are:
-start 12/31/95 -start Dec/31/95 -start "Dec 31 1995"
Default value: one year before the given -end date
Provides the ending date to which metrics reporting is desired. Any task activity after this date is ignored.
Default value: today's dateSpecifies what type of task information to report (for each row) and how to organize this information in the generated tables. A simple row_spec contains just the name of a task field and indicates that information about that field for the given tasks should be summarized. For example:
-rows Priority
The pseudo field name, Opened_Closed, indicates that a special summary derived from the State field of the tasks should be generated. For this summary, a task is defined as an "opened" task as soon as it is created, and it remains so for the rest of its lifetime, even after it is "closed". A task is counted among the "closed" tasks when it enters any state specified by the -closed_states option.
The values for a simple row_spec field are presented in a sorted order. By default, the order is determined by the type of the field: ints and floats are sorted numerically, enums are sorted in enumeration order and all other types are sorted alphabetically. In addition, for enumeration types, all field values are displayed, even those that are never used by any task. The default order can be reversed by following the field name with a minus sign, '-'. The order can be forced to be alphabetic by placing an ampersand sign, '@', after the field name. Finally, the traffic tool will only display those field values that are actually used if the name is followed by a plus sign, '+'. These field-specific display options can be used in combination, but no spaces can separate them from the field name. For example:
-rows Assigned+ -rows Priority-@
Two or more simple row_specs can be generated in one table by separating them with commas or spaces as in these examples:
-rows State,Opened_Closed -rows "Assigned Priority"
The information for each simple row_spec is independent of the others. They are just presented together in the same table.
More complex, multi-dimensional row_specs can be given in order to tabulate subsets of information. This is accomplished by enclosing the subset row_specs in parentheses immediately after the super row_spec as in these examples:
-rows "Opened_Closed(Priority)" -rows "State+(Assigned+(Priority+-))"
By default, only data for the lower-most subset row_spec will be computed and displayed. If results for a super row_spec is desired as well, its name must be followed by the special number sign, '#', as in this example:
-rows "Opened_Closed#(Priority)"
Alternatively, a total for all of a particular field's values will be displayed at the end of those values, if the field name is followed by an equal sign, '=', as in:
-rows "State=(Priority)" -rows Assigned+=
Specifies which field should be used for the columns in the generated table. Only one field name can be given. The default value causes the changes over time to be displayed. Other field names just present the current (latest) values for the given field. The special field-specific options '-', '@', '+', and '=' can follow the field name and have the same effect on the column field as they have on row fields as described for the -rows option. If column_spec is just '=', then only a total of the frequencies of the specified row fields are produced. For example:
-columns State -columns Assigned= -columns Priority-+ -columns =
Indicates that the information in the tables should be displayed on a day by day basis. This option is mutually exclusive with respect to the other time interval options.
Default value: falseIndicates that the information in the tables should be displayed on a week by week basis. This option is mutually exclusive with respect to the other time interval options.
Default value: falseIndicates that the information in the tables should be displayed on a month by month basis. This option is mutually exclusive with respect to the other time interval options.
Default value: trueIndicates that the information in the tables should be displayed on a quarter by quarter basis. This option is mutually exclusive with respect to the other time interval options.
Default value: falseIndicates that the information in the tables should be displayed on a year by year basis. This option is mutually exclusive with respect to the other time interval options.
Default value: falseSpecifies that any zero values in the resultant displayed table should be replaced by blanks so that non-zero entries are more obvious.
Default value: falseSpecifies to what level of subset row nesting "break lines" (a line containing only "-" or "=" characters) should be inserted in the displayed table to improve readability.
Default value: 2Identifies which states are to be treated as "closed" when used with the special Opened_Closed field.
Default value: "Completed Canceled"Controls the width of all columns of output containing the compiled statistics. Can make the columns narrower or wider than the default.
Default value: width of the longest value in each columnSpecifies the name of a file into which the tabulated results of the metrics report are stored in the "comma separated value" format. This file is suitable for transporting the information to a spreadsheet program where the data can be used to generate useful graphs.
Default value: ""Indicates that only a comma separated value file should be generated (assuming the -csv_file option is also given). No table of results is displayed.
Default value: falseCauses the report to be output to the named file instead of to standard output.
Default value: ""Indicates that the current date should be displayed (centered) at the top of the report.
Default value: falseCauses the settings of the -rows and -columns options to be displayed (centered) at the top of the report.
Default value: falseCauses rows of data which contain only zero values to be left out of the displayed table to reduce the amount of extraneous information.
Default value: falseSuppresses warning messages. This option may be used in circumstances where many expected, but unimportant warnings are generated (for example, warnings involving State comparisons).
Default value: falseCauses the report to be generated using a format similar to that produced by the Microsoft Excel "Pivot Table" feature.
Default value: falseSpecifies a string to be displayed (centered) at the very beginning of the report.
Default value: ""Examples
- Generate the change traffic and stability metric on all change tasks in the default task domain over the past year on a month by month basis:
traffic "C*.task"
- List the number of tasks each developer has been assigned for the last year on a quarterly basis and break this number down by task priority:
traffic -start 1/1/95 -end 1/1/96 -quarterly -rows "Assigned#(Priority)" "C*.task"
- Determine how many tasks are currently assigned to each developer on a priority basis as well as overall.
traffic "*.task" -rows Assigned@+ -columns Priority-=
Using Rational Summit/TM with Rational Summit/CM
This 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.
abandon(Summit/TM) - cancels check outs
Syntax
abandon [options] files | directories | views...
Description
If there are any task associations with an abandoned version, then they are removed.
accept_changes(Summit/TM) - updates objects
Syntax
accept_changes [options]files | directories | views...
Parameters
- options
Specifies tasks whose associated controlled object versions are to be accepted into the destination. This option is mutually exclusive with the –latest, –source, and –source_version options.
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 when the –source_task option is specified:
If a task is accepted, also accept the descendants of the task. (The descendants of a task are its child tasks and their children, recursively.)
Do not accept a task unless it is possible to accept all versions associated with it.
Do not allow history changes which cause a task regression (the loss of changes associated with a previously accepted task).
If accepting a designated task causes versions from other tasks to be accepted, also accept those tasks.
Fail if accepting a designated task causes versions from other tasks to be accepted. This is mutually exclusive with –accept_implicit_tasks. When neither option is specified, the other tasks are not accepted, but a warning message is issued and processing continues.
The following procedure determines which versions are used to update the destination files. All of the versions associated with the given tasks in the –source_task option are collected. If the –recursive option is also specified, then the versions associated the descendants of any accepted task are also collected. If the –accept_implicit_tasks option is specified, any additional tasks associated with the accepted versions are similarly 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 (if specified).
Note that since all source objects are controlled when this option is used, the –control option can have no effect.
add_task - adds tasks to specific versions of objects
Syntax
add_task [options] -task task files | directories | views...
Alias
addtsk
Description
Add the tasks to versions of the specified objects.
Parameters
- files | directories | views...
Specifies the objects to whose versions the tasks are to be associated.
check_in(Summit/TM) - checks in objects
Syntax
check_in [options] files | directories | views...
Parameters
check_out(Summit/TM) - checks out objects
Syntax
check_out [options] files | directories | views...
Parameters
- options
Privately checked out versions cannot be associated with tasks. However, a task can be associated with a private check out when it is upgraded to a normal check out.
Specifies the tasks to associate with the checked out versions.
control(Summit/TM) - places objects under configuration control
Syntax
control [options] files | directories | views...
Parameters
- options
If a new version is created by this command, then this option names the tasks to be associated with the new version. A new version is created either when the file is uncontrolled to start with or the file is controlled, different than the latest version of the object, and the –create option is given.
copy(Summit/TM) - copies objects
Syntax
copy [options] source... destination
Parameters
- options
Any task associations with an abandoned version are removed.
If an object being copied is checked out and the –check_in option is also provided, then this option names the tasks to be associated with the checked in version of that object. These tasks are also associated with any new version created under other circumstances.
copy_view(Summit/TM) - copies views
Syntax
copy_view [options] views | configs... [destination]
Parameters
- options
Any task associations with an abandoned version are removed.
If an object being copied is checked out and the –check_in option is also provided, then this option names the tasks to be associated with the checked in version of that object. These tasks are also associated with any new version created under other circumstances.
create(Summit/TM) - creates objects
Syntax
create [options] names... create_file [options] names... create_ada [options] names... create_body [options] names.. create_spec [options] names... create_c [options] names... create_cpp [options] names.. create_class [options] names... create_configuration [options] names...Description
The previously listed file creation commands have all been enhanced in exactly the same way for Rational Summit/TM.
Parameters
discard(Summit/TM) - deletes objects
Syntax
discard [options] files | directories | views | subsystems...
Parameters
- options
Any task associations with an abandoned version are removed.
If an object being deleted is checked out and the –check_in option is also provided, then this option names the tasks to be associated with the checked in version of that object. If a "deleted version" is created as a result of this command, then these tasks are also associated with that deleted version.
move(Summit/TM) - moves objects
Syntax
move [options] source... destination
Parameters
- options
Any task associations with an abandoned version are removed.
If an object being moved is checked out and the –check_in option is also provided, then this option names the tasks to be associated with the checked in version of that object. These tasks are also associated with any new version created under other circumstances.
remove_task - removes tasks from specific versions of objects
Syntax
remove_task [options] -task task files | directories | views...
Alias
rmtsk
Description
Remove the tasks from versions of the specified objects. That is, the existing associations between the given tasks and the specified versions are deleted.
Parameters
- files | directories | views...
Specifies the objects from whose versions the task associations are to be removed.
- options
Specifies that if any configuration files are passed as parameters to this command, the operation is applied to the views referenced by the configuration and not to the configuration itself.
Default value: false
Aliases: –expand_configs, –ecEnters the text as a note associated with the versions.
Default value: ""Enters the contents of the file as a note associated with the versions.
Default value: ""Disassociates the named tasks from the given versions. This option is required.
Specifies which version of the objects to use.
Default value: currentset_history(Summit/TM) - sets the history of objects
Syntax
set_history [options] history files | directories | views...
Parameters
- options
Any task associations with an abandoned version are removed.
If an object, whose history is being changed, is checked out and the –check_in option is also provided, then this option names the tasks to be associated with the checked in version of that object. The tasks are also associated with any new version that is created as the result of this command. Such a new version can be created when the –control or –create options are provided.
set_version(Summit/TM) - sets the version of objects
Syntax
set_version [options] files | directories | views...
Parameters
- options
Any task associations with an abandoned version are removed.
If an object, whose version is being changed, is checked out and the –check_in option is also provided, then this option names the tasks to be associated with the checked in version of that object.
show_status(Summit/TM) - shows CM status and associated tasks
Syntax
show_status [options] [files | directories | views...]
Description
When used with the –verbose option, this enhanced command displays the tasks associated with the given versions along with the other status information.
show_versions(Summit/TM) - shows versions and associated tasks
Syntax
show_versions [options] files | directories | views...
Description
In addition to its usual output, this enhanced command displays the tasks that are associated with the given versions.
show_tasks - shows tasks associated with specific versions
Syntax
show_tasks [options] files | directories | views...
Alias
shtsk
Description
Show the tasks associated with the specified versions.
Parameters
- files | directories | views...
Specifies the objects whose task associations are to be displayed.
- options
Show task associations for all controlled files.
Default value: true, if –checked_out option is not set, otherwise, falseOnly show tasks associated with checked out files. If neither –checked_out nor –all are set, then –all is assumed. If both are set, then –all overrides –checked_out.
Default value: falseShow tasks associated with previous versions as well as the current version. Thus a file in the object set is considered to be associated with a task if a previous version was associated with the task.
Default value: falseSpecifies that if any configuration files are passed as parameters to this command, the operation is applied to the views referenced by the configuration and not to the configuration itself.
Default value: false
Aliases: –expand_configs, –ecShow only associations with the named tasks. If no tasks are named, then all otherwise eligible tasks are shown.
Specifies which version of the objects to use.
Default value: currentExamples
show_tasks -all test.wrkShows all task associations with the current versions of all controlled objects in view test.wrk.
show_tasks -task 123 -checked_out *.ss/test.wrkShows all task associations between task "123" and any checked out versions in the set of views matched.
show_tasks -task 123 -cumulative test.wrkWithin view test.wrk, find all versions of all objects, whether the current ones or previous ones, associated with task "123".
Rational Software Corporation http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2001, Rational Software Corporation. All rights reserved. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |