TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Getting Started

This chapter describes the basics of using Rational Summit/TM with Apex or Rational Summit. It goes through a simple demonstration of the commonly used commands and discusses how to set up the Rational Summit/TM user environment.


Quick Start Demonstration

The following demonstration should acquaint you with the basic features of the Rational Summit/TM system. It shows you how to create your own task domain, create a task, examine a task, modify a task and associate tasks with Summit/CM versions. This demonstration assumes that you are using the graphical user interface.

The demonstration also expects that you already know enough about Apex or Summit to manipulate its user interface and to examine and create directories and other objects. It also assumes that you have read the "Introduction" and have at least a basic understanding of the Rational Summit/TM concepts that are involved.

Starting Up Apex or Summit

Before starting up Apex or Rational Summit using apexinit or summitinit, you should make sure that your user environment is properly initialized. Normally, your Apex or Summit system administrator will have set up your user environment for you to use Rational Summit/TM without any extra effort on your part. If not, then you should at least verify that either (1) the APEX_TASK_ENABLED environment variable is set to True or (2) that you provide apexinit or summitinit with the -task option. In addition, you may want to look at the User Environment section for more details on the proper settings for Rational Summit/TM specific environment variables.

After starting Apex or Summit and bringing up a directory window on your own private working directory (not within a subsystem or view yet), let's call it "$DIR", verify that you can perform the Tasks > Set Domains command. If not, then something is probably wrong with your user environment. Either try to figure out what the problem is or go ask some more knowledgeable person for help.

If this command is present and succeeds in bringing up its dialog, then see if it lists any task domain pathnames in the Domains field. These are the "standard" task domains for which your version of Summit/TM is currently configured. The first name in this list, if any, is the default task domain which is where the tasks you create or reference are usually located. If there are no task domains listed, don't worry, but it might be prudent to verify with your system administrator that it's not supposed to list anything. In either case, just click on the Cancel button and proceed to the next subsection.

Setting Up a Task Domain for Testing

At this point, you have a small decision to make. You need a task domain in which to create a new task. If you saw one or more "standard" task domains when you ran the Tasks > Set Domains command in the previous subsection, then you can choose one of them. However, you should check with the rest of your development team to make sure it is all right to create temporary tasks there for testing purposes. If you choose this alternative, then you may proceed to the next subsection.

If your system has no "standard" task domains, or you don't want to use them, then you can create a task domain of your very own as follows.

From your directory window select the File > New > New Task Domain menu item to display the New Task Domain dialog in the context of your $DIR directory. This dialog will create a new task domain subsystem and view where your new tasks will be stored. Enter the new domain view name in the Name window, task_domain.ss/all.wrk. The domain will be set up to use the predefined task kinds that are delivered with Rational Summit/TM. If you wish to use some other task kinds, then you will need to specify them in the Kind Path field. Press OK to create the domain. See File > New > New Task Domain for more details.

After the task domain is created, run the File > Redisplay command in your directory window and you should see the new task domain subsystem, task_domain.ss, listed there. Now "visit" task_domain.ss and you should see the task domain view, all.wrk. From this point on, any reference to the "task domain" will refer to this view. In fact, unless explicitly stated otherwise, throughout this document, a task domain refers to some Summit/CM view.

Setting Default Task Domain

After choosing (or creating) the task domain that you want to use, you should make it your default task domain as follows. From a directory window, either deselect all objects with the Edit > Deselect Window command, or select the desired task domain view that you want to be your only "standard" task domain. Then, run the Tasks > Set Domains command.

In the Set Task Domains dialog, one or more task domains should now appear in the Domains field. To choose your default task domain, just select the one from the Domains field that you want and click on the Set Default button. The default should now appear in the Default Domain field. Press the OK button to accept the new default task domain.

The Set Task Domains dialog sets the default domain in all Apex or Summit windows except existing shell windows. However, new shell windows are initialized with the new default.

If you are using the command line interface, either in batch mode or in an existing Apex or Summit shell window, then you will have to use the setenv command to change the APEX_TASK_DOMAIN_PATH environment variable to the task domain you want to use as the default domain.

The advantage of a default task domain is that you can refer to its tasks with their simple task names instead of having to deal with full pathnames.

Creating Tasks

You should now be ready to create your first task. Run the File > New > New Task command. This should bring up the New Task dialog. Your default task domain should appear in the Domain field, the Parent and Name fields should be blank and default values for the Kind and Template fields should be filled in (such as "defect" and "initial"). If any of this information is incorrect or missing, then you have a problem that may require some help to resolve. Note that the Alternatives icons next to these fields can be pressed to find out what other values are supported by your system.

Assuming that the information is correct, press the OK button to create your task and "visit" it since the "Visit it" check box is selected by default. Please continue on to the next subsection.

Examining Tasks

Note: Make a mental note of the name of your new task (such as B00001) as you will need to use it later.

Visiting a task causes its task editor to be invoked displaying its various fields. When the task editor dialog appears, take some time to examine the information. The fields at the top normally identify fundamental characteristics of a task, such as its name, domain, and kind, which cannot be directly modified.

Note: Make a mental note of the name and value of one of the fields in the area described immediately below. (Such as Priority and Unassigned.) You will need it later too.

The dialog area just below the top contains miscellaneous task fields that are commonly examined and have relatively short values. You should notice a small Edit check box here which indicates, when selected, that you have changed some of the task's fields. It can also be selected explicitly to reserve the right to edit the task. This area also often contains the state Transition field with an associated drop-down list box. Click on this box to see what state transitions (if any) you can perform on this task. Do not make any changes at this time unless you want to skip the subsection on modifying tasks. You can also press any Alternatives icons you see to find out the legal values for a task field with an enumerated type.

The largest area of a task editor dialog contains several "pages" of information which can be selected via the Pages field's drop-down list box. Click on the drop-down list box and then select one of the entries listed. This operation does not modify a task, it just shows you more of a task's fields since there are too many fields to display them all at once. This area is also good for showing task fields with values that can be many lines long.

The bottom area of a task editor simply contains the standard dialog action buttons. Press the Cancel button when you are finished looking around. This will not cancel (or destroy) the new task you have created, it will just throw away any field modifications you may have made within the task editor.

Finding Tasks

Now that you have created a task and dismissed the task editor dialog that you used to look at the task's data, how do you find it again? One way it is to run the Tasks > Query command. Try it and you should see the Task Query dialog appear. Using the field name and value you remembered from the previous subsection (such as Priority and Unassigned), formulate a simple query as follows.

1 . Using the Alternatives icon next to the Field field, select the task field name.

2 . Using the Alternatives icon next to the Value field (or bentering the value manually if you did not choose a task field with an enumerated type), select the task field value.

3 . Press the Add Comparison > Field-Op-Value button. A field comparison expression should appear in the Query Text field at the top, prefixed by the keyword where. Ignore it for now.

4 . Press the OK button to perform the search (or use the Apply button if you want an easy way to try again.)

Assuming everything worked as planned, a Task Query summary window should appear containing at least the new task that you created and maybe others that were already in the task domain that you are using. Note that summary windows containing tasks show the values of some fields as well the task Ids (by default the State, Priority, Assigned, and Summary fields are also displayed for each task.)

Modifying Tasks

Using the Task Query summary window from the previous subsection, select the new task that you created and "visit" it, popping up its task editor again. Now you can have some real fun modifying the task's fields. Try changing one of its enumerated type fields first, using the Alternatives icon to select the new value. Note that the Edit check box changes to its selected (or "on") state indicating that the task's data has been modified. It is important to understand that this indication only refers to the task editor's copy of the task's data and not to the permanently recorded information about the task. To illustrate this, now press the Reset button at the bottom of the dialog. This action reverts the field you changed back to its original value and deselects (turns "off") the Edit check box. The changes you make are only permanently saved after you press the OK or Apply buttons. Another important point is that while you are editing a task (that is, while the Edit check box is on), a lock is set so that no other user can edit the same task.

Now, make the same field modification you made before and try changing some other fields (other than any state transitions) such as the Summary or Description fields. You may notice that some fields, such as the Parent field cannot be changed, they are non-editable fields. Now press the Apply button to make these changes permanent. The Edit check box should now be off and the changes should still be there.

Finally, you can attempt your first state transition. Press the Transition field's drop-down list box and select one of the legal state transitions (such as New -> Duplicate). As is probably obvious, this indicates that you wish to move the task from its current state (New) to a successor state (Duplicate). If you change your mind you can reselect a different state transition or choose the current state. Hopefully, you have chosen to transition to another state. Now, press the Apply button again to actually attempt the state transition. Why just an "attempt"? Because, depending on how your task's state machine is defined, some state transitions may be carried out only if certain (possibly complex) preconditions are satisfied. These preconditions are tested when you press the OK or Apply buttons. If the preconditions are satisfied, then your state transition will take effect, permanently.

When you are done modifying your task, press the OK or Cancel button.

Using Rational Summit/TM with Rational Summit/CM

This subsection is for those users who want to use Rational Summit/CM change control capabilities with Summit/TM.

To perform this exercise, you need to create a development subsystem with two views in it. From your $DIR directory window, use the File > New > New Subsystem command to create a subsystem called test.ss. Then, from within the $DIR/test.ss directory window, use the File > New > New View command twice (use the Apply button the first time) to create the views v1.wrk and v2.wrk.

Next, you need an object to control and change. From your $DIR/test.ss/v1.wrk directory window, run the File > New > New File command to activate the New File dialog. Type in the name of your new file (how about read.me). Press the Make it Controlled check box and a new field called Associate Tasks should appear. You'll find this type of field in many Summit/CM dialogs when used with Rational Summit/TM. For now, however, make sure that this field is empty. Then, hit the OK button to create the file. Put whatever text you wish into your new file and save the result. The file should now be controlled and checked out.

We could have done this earlier, but let's take a moment here to define your current task. This task is the one you will most often want to access during your development activities. If you find yourself in situations where you are switching from one task to another frequently, you should leave your current task undefined. From any directory window, first make sure that no objects are selected (use the Edit > Deselect Window command, to deselect them). Then, run the Tasks > Set Current command. The Tasks field of this dialog should be empty. If it is not, then select the entries listed and press the Remove button. To add your new task to this list, enter the task's name in the Task Id field and press the Add button. (But read the next paragraph first.)

There are several ways to enter a task's name into a dialog field. First, you can type it in (such as B00001). Second, you can click on the Navigate icon which brings up the Select Tasks dialog. This dialog should display the list of tasks in the default task domain (that you selected in the Set Domains dialog) from which you may select the desired task. Third, you can select a task using the Alternatives icon which displays the simple names of tasks in your "to do" task list (if any). Finally, using the right mouse button, you can press the Completion icon which will immediately list the contents of the selected task domain from which you may choose a task. Having defined your current task, press the OK button.

It is now time to check in your source file. Select the file and run the Control > Check In command. On the Check In dialog, your file should be listed in the Check In field, and your current task should appear in the Associate Tasks field. This means that you want to associate this task with the current version of this file that you are about to check in. If everything looks as expected, press the OK button.

To verify that the task has been associated with the file's current version, select the file again and run the Tasks > Show command. The task should appear directly below and indented from the file in the directory window. You can select the task here and visit it if you want to activate its task editor. If you do, examine its Version History Information page and you should see the reference to the file version that you just checked in.

You are now ready to use Rational Summit/TM to accept source changes from one view to another. Simply select your $DIR/test.ss/v2.wrk view from some directory window and run the Control > Update Objects command. The v2.wrk view should appear in the Objects field. Now press the Accept newer versions associated with tasks below radio button. Your current task should have been enabled in the Tasks field. This arrangement indicates that you want to accept all the source versions associated with the current task into the supplied destination views. If everything seems normal, hit the OK button. You should notice that your new file has been accepted into the v2.wrk view.

Of course, this might seem like a lot of work just to accept one file, but remember that your task could have been associated with many different file versions in many different views of many different subsystems.

This completes the introductory exercise on getting started with Rational Summit/TM. Now all you have to do is clean up after yourself and start applying Rational Summit/TM to some real work!


User Environment

This section describes the environment variables that are specific to Rational Summit/TM and affect its operation. Normally, when you start up Apex or Rational Summit, these variables are automatically set to their appropriate values and you do not need to concern yourself with them. If not, then you should discuss the matter with your Apex or Summit system administrator.

APEX_TASK_ENABLED

In order to use the Rational Summit/TM features at all, the APEX_TASK_ENABLED variable must be set to True. If it is set to False (or not defined), then you will not see Rational Summit/TM's dialogs, editors nor its new menu commands (such as Tasks > Show). In addition, the Rational Summit/TM specific enhancements to Summit/CM will be disabled.

To enable Rational Summit/TM, you can either set this variable before running apexinit or summitinit as follows:

or, you can invoke apexinit or summitinit with the -task option like this

or this

APEX_TASK_DOMAIN_PATH

The APEX_TASK_DOMAIN_PATH environment variable identifies the task domains that a user commonly wishes to access. It does not have to be set, but Rational Summit/TM is easier to use if it is set.

If the APEX_TASK_DOMAIN_PATH is not already set when apexinit or summitinit is invoked, then by default it will include any existing task domains listed in the configuration file called rational_dir/config/task_domain_path, followed by the task domain $APEX_BASE/task/tasks.ss/all.wrk, if it exists (rational_dir is the parent directory of $APEX_HOME).

The first domain identified by APEX_TASK_DOMAIN_PATH is called the default domain which is accessed when no particular domain is specified.

The task domains in this variable are separated by colons (":") as shown in this stylized example in which /task_domain1 is designated as the default domain:

APEX_REQUIRE_TASK

The APEX_REQUIRE_TASK environment variable determines whether tasks are required to be associated with Rational Summit/CM versions. If this variable is set to True, then any operation which creates a new version of a controlled object will fail unless at least one task is associated with the new version. For example, any operation, which checks out or deletes a controlled object or controls an existing uncontrolled object, creates a new version and will require an associated task.

Similarly, a Summit/CM check in operation will fail unless a task has been either previously associated with the checked out version, or a task is associated with it at the time of check in.

Whether APEX_REQUIRE_TASK should be set to True or False is a policy question that project management should decide. Rational Summit/TM will work well in either case. However, setting this variable to True, as follows:

can serve as a handy reminder to make sure that all source changes can be properly tracked by Rational Summit/TM.


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