TOC PREV NEXT INDEX DOC LIST MASTER INDEX



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

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:

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:

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:

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:

set_current_task - adds tasks to the current task list

Syntax

set_current_task task...

Alias

curtsk

Description

Adds the named tasks to the user's current task list.

Parameters

Example

show_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

set_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

Example

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

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

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

Examples

list_task - lists selected fields of specified tasks

Syntax

list_task [options] task...

Alias

lstsk

Description

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

Examples

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

Example

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

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

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

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

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

This file must be included in the TASK_CUSTOMIZATION_KEY of the task domain's switch file which is found in

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:

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

Examples

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

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

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

control(Summit/TM) - places objects under configuration control

Syntax

control [options] files | directories | views...

Parameters

copy(Summit/TM) - copies objects

Syntax

copy [options] source... destination

Parameters

copy_view(Summit/TM) - copies views

Syntax

copy_view [options] views | configs... [destination]

Parameters

create(Summit/TM) - creates objects

Syntax

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

move(Summit/TM) - moves objects

Syntax

move [options] source... destination

Parameters

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

set_history(Summit/TM) - sets the history of objects

Syntax

set_history [options] history files | directories | views...

Parameters

set_version(Summit/TM) - sets the version of objects

Syntax

set_version [options] files | directories | views...

Parameters

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

Examples


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