Analyzing Data Impacts

Exploring, Documenting, and Measuring

Chapter 9: Associating Code with Annotations

Annotations are effective ways to document your project. You can use them to make notes to yourself about project components or you can use them in multiple user projects to alert other users of specific situations or to assign coding tasks.

You need to have read the chapter Start Here for the Tutorials! and worked through the first session, Creating and Loading Projects, before you do this session. In this session, we assume that you have created Sample.prj.

9.1 Overview

This session shows you how to take information from a Revolve analysis and add it to an annotation. Then you will use the Annotation tool to modify the annotation.

9.1.1 Annotations

Annotations are useful in helping analysts track enhancements and to help programmers share code for research. The Annotation tool is dynamic and flexible , enabling you to use information contained in an annotation as a starting point for analysis.

9.2 Preparation

You will apply the procedures in this session to the sample project created in Creating and Loading Projects. If Revolve and sample.prj are closed, open them like before.

9.3 Sample Session

In this session you:

• Create an annotation
• View the annotation
• Edit the annotation

9.3.1 Creating an Annotation

To do this:

1. From the Browsers menu, select Variables.

   The Variables browser is displayed..

2. Type WS01-XCTL-PROGRAM into the Match edit box.
3. Click Options.

   When the Variables dialog is opened for the first time, it will display, by default, the direct modifications, references, and redefines of the specified variable(s). The displayed information can be changed by adjusting the options in the Variable Information Options dialog.

4. For our example, check the Modifications check boxes in the Direct Usage area, Indirect Usage (Lower Levels) area, and the Indirect Usage (Group Levels).
5. Uncheck the References andRedefines check boxes in Direct Usage area. Notice Figure Figure 9-1. This selective process is called Information Screening.

   
   Figure 9-1: Information Screening

6. Click OK.

7. Select the WS01-XCTL-PROGRAM folder in the information window.

8. Click Expand Completely.

   A group of information has been isolated and can be used to create a coding task.

9. Starting from ONLINE4.CBL, select all displayed information. Notice Figure 9-2.

   
   Figure 9-2: Selecting information for an annotation

10. Click Capture Results.

    The Capture Results interface is displayed. This enables you to add information to annotations, subprojects, Pop files, and Tag files.

11. Click Add to Annotation.

12. Click Ok.

13. Click New annotation.

    The Required Field dialog is displayed, prompting you to, "Please Enter a Title for this Annotation:."

14. Type:

    Locations modifying WS01-XCTL-PROGRAM

    in the open field.

15. Click OK .

16. Select the new annotation.

17. Click Add.

    A Revolve dialog informs you how many elements were added to the annotation.

18. Click OK.

The annotation is created and ready to be applied in coding tasks. Information can be added to the annotation and it can be edited. We'll elaborate on this in the next session.

9.3.2 Viewing the Annotation

To view the annotation:

1. From the Tools menu, select Annotation.

2. Select Title from the pull-down list box.

3. Type:

   LOCATIONS*

   in the Match edit field.

   Be sure to include the wild card character (*) or the match will look for an annotation named LOCATIONS.

4. Click Match.

   The Annotation tool searches an annotation that begins with LOCATIONS. The annotation we created in the previous procedure is displayed.

5. Select the folder for LOCATIONS MODIFYING WS01-XCTL-PROGRAMS.

6. Click Expand Completely.

   The information about the annotation as well as the information that we capture from variable WS01-XCTL-PROGRAM is displayed.

9.3.3 Editing Annotations

To edit the annotation LOCATIONS MODIFYING WS01-XCTL-PROGRAM:

1. Select the folder LOCATIONS MODIFYING WS01-XCTL-PROGRAM.

2. Click Edit Annotation.

   The Edit Annotation dialog is displayed. It contains current information about the annotation, including its title, creator, intended recipients, status, and a descriptions about the contents. In this interface you can modify any aspect of the annotation according to your analysis needs. See Figure 9-3.

   
   Figure 9-3: Edit Annotations

3. In the Description field, enter the text:

   Enhancement Request for all locations modifying WS01-XCTL-PROGRAM

4. Click Ok.

5. In the Annotation tool, double click the Description folder.

   Notice this is where programmers will check to see why this annotation was created.

6. Double click the Connected to... folder.

7. Select any component that is contained in the Connected to... folder.

8. Click View Source Code.

   Notice that the source code is available for the contents of the annotation. You can implement modifications in the Annotation tool and link to other tools and browsers to extend analysis. This concludes this exercise.

9. From the Window menu, select the Close All Windows menu option.

9.3.4 Before Continuing

You can close Revolve, if you want to stop for now. The project that you have created and loaded is automatically saved.

You can continue with the next tutorial later, by simply reopening the project.

Analyzing Data Impacts

Exploring, Documenting, and Measuring