Reporting on the Worksheet

Setting Up Projects

Chapter 11: Using Revolve

To effectively use Revolve for analysis, you should understand the following fundamental features and concepts:

• Projects
  • Project Menu
  • Project Manager
  • Modifying At Component Level
  • Subprojects
  • Shareable Projects
• Revolve's Interface
  • Button Bar
  • Match Edit Bar
  • Information Window
  • Information Screening
• Viewing Source Code
• Printing
• Highlighting
• Adding Information to Annotations

Other Useful Features

• Long Filenames
• Modification Driver
• Capturing Results

11.1 Projects

The typical Revolve user is interested in a small number of files; however a large application can consist of hundreds, even thousands of source files. Because organization becomes so critical, Revolve structures source files as projects. A single Revolve project can contain up to 32,000 components. This figure represents the number of source members (COBOL, JCL, etc.), it does not include copybooks, includes, procs, or control-cards. Once created, projects exist until they are explicitly deleted by an administrator.

See also For more information about creating and maintaining projects see the chapter Setting Up Projects.

11.1.1 Project Menu

The following table provides a complete list and description of the options that are available from the Project menu:

Note: Icons in the following table are found on the Project Manager's button bar and access the described functionality.

Menu Option:	Definition:
New...	Prompts for the name and creates a new project.
Open...	Prompts for the name and opens an existing project.
Save	Saves the project. Save automatically happens when you close a project or exit Revolve, but periodically saving your project is a good practice.
Save As...	Prompts for the name and saves the project with a new name. It also updates the name of the active project.
Make User	Converts the database that is being accessed from Administrator the administrator's to the user's and vice versa.
Make Shareable...	Prompts for the path and name of a shadow project for making a shareable project (see Shareable Project for more information).
Close	Closes the active project. The changes to the project are automatically saved.
Delete Project...	Deletes the active project and any related files.
Import Project...	Loads the definition of a project from a file.
Export Project...	Saves the definition for the active project to user specified format.
Manager...	Opens the Project Manager to permit project administration.
Complete...	Opens the Complete Project dialog box, which guides the user through a process of identifying and classifying all the missing pieces and unknown information in a project.
Load Selected...	Parses (or re-parses) and loads all highlighted components in the Project Manager. Also located on the Project Manager button bar .
Make...	Parses (or re-parses) components which are "Out of Date", "Not Loaded", or "Error", and loads successfully parsed components. Also located on the Project Manager button bar .
Status...	Compares database times against source-code time stamps and updates the status in the Program Manager accordingly. Also located on the Project Manager button bar .
Add Components...	Activates the Add Components dialog box, which is used to add new components to the project. Also located on the Project Manager button bar .
Delete Components...	Removes all highlighted components in the Project Manager. Also located on the Project Manager button bar .
Exit	Shuts down the Revolve system, saving all changes to the current project.

See also For information about the administrator's options see Administrator Options in Utilities.

11.1.2 The Project Manager

Revolve projects are controlled primarily from the Project Manager. The Project Manager window displays the list of component files which have been added to the project. It also provides the user with the ability to make modifications to the project's configuration--if the user has the appropriate rights. Certain buttons in the Project Manager may be disabled depending on the rights of the user. For example, if the project is shared, the Add Components and Delete Components buttons will be grayed and unusable to the user but will be focussed and accessible to the administrator.

The Project Manager is activated by creating a new project, by selecting the Manager menu item from the Project menu, or by clicking the Project Manager button at the bottom of the Revolve desktop.

When existing projects are opened by choosing the Open option from the Project menu, the Project Manager will not appear.

See also For more information about administrative rights refer to Administrator Options in Utilities and Administrative Mode in Shareable Projects.

Columns

The Project Manager has six columns:

• File name: File name of the component.
• File type: The type of the component. Indicates which parser will be invoked when the file is parsed.
• Status: The status of the component. See next section.
• Type: The storage method for the component (DOS, PVCS, etc.).
• File path: The file path to the component.
• Time stamp: The last time the file was changed.

Component Status

Each component of a project has an associated status.

• Not Loaded: Component has not been loaded into the database.
• Parsed: Component has been partially loaded and needs to be reloaded to be fully integrated into the database. It will be fully integrated into the database with the next project make. An asterisk following this status indicates that the component encountered an error while loading.
• Loaded Component is fully loaded and all queries will be valid based on the source code.
• Not Found Source code for this component is not located on the file system where it was initially specified or it could not be located with the Automatic Component Locator.
• Out Of Date Source code for this component or related copybooks/includes has been changed since it was last loaded into the database.
• Old Version Indicates that database file(s) for the component were located, however, they were created with an older version of Revolve. This component must be reloaded before analysis can be performed on its contents.
• Error An error in the code was encountered during loading and caused an incomplete load of the database.

11.1.3 Modifying At Component Level

It is sometimes necessary to modify the parameters of a component after it has been added to a project. Revolve provides the COBOL Parameters feature to facilitate component level parameter definition. This is different from the Component Parameters functionality available through the Administrator Options dialog (Utilities/Options/Admin...) in that these parameters are applied to existing, selected components (component level), as opposed to effecting all components, new and existing, across the project (project level).

To set component parameters on the component level:

1. Select a component or series of components in the Project Manager.
2. Click . The Parameters dialog is displayed specific to the type of the component you selected. If you selected many components, then the first type that appears in descending order in the Project Manager is the first parameter dialog that is displayed.

4. Click to expand the list.
5. Select the new type from the list.
6. Check and uncheck appropriate options.
7. To establish a new search directory for the selected component(s), click Search Directories.
8. Check "Use the project's default directories" to use the directories defined in Utilities/Options/Admin.../Search Directories. Or uncheck to set up a new path.

Note: Setting up search directories at the component level overrides the default directory settings for the selected components in the Project Manager. This can be useful for import files that have the status Not Found.

9. Click Add.
10. Select directory type from the pull down list.
11. Enter the directory name or click Browse to navigate to the desired location.
12. Click Ok in the mini Search Directory dialog.
13. Click Ok in the main Search Directory window.
14. Click Ok in the Component Parameters dialog.

The parameters you select and check will be applied to the selected components when you click Ok. If the selected components are of different types, then a corresponding parameter dialog is displayed.

See also Component Parameters or Search Directories, in Utilities for more details on these dialogs.

11.1.4 Subprojects

Querying against an entire project can be inconvenient when you only need to access an isolated or small amount of data. To remedy this problem Revolve incorporates the use of subprojects in its tools and information browsers A subproject is a collection of individually specified items that are taken from a Revolve project to be analyzed and modified in specific ways. The Add to Subproject button allows the Revolve administrator to compile selected components into a Revolve subproject. To create a new subproject from the Project Manager:

1. In the Project Manager, select the elements that should be added to the subproject by left-clicking with the mouse. To select elements that are listed consecutively, click and drag with the mouse. To select elements that are not listed consecutively, use the control key and the left mouse button simultaneously.
2. Click Add to Subproject from the Project Manager button bar.
3. In the Add to Subproject dialog that appears, select the New Subproject button.
4. Enter the name of the new subproject into the Subproject Name field and click OK.
5. Select the new subproject in the Add to Subproject dialog and click Add.

The new subproject has been created. To view the subproject:

1. Open the Complete Project dialog by selecting Complete... from the Project menu.
2. Open the Subprojects dialog by clicking the Subprojects button The Subprojects dialog is invoked.

Click this:	To do this:
	Invokes the Print dialog, allowing for the subproject to be printed.
	Deletes the selected subproject.
	Invokes the New Subproject dialog where a new subproject is named and created.
	Deletes selected subproject components.
	Invokes the Find dialog where you can select project components and add them to the subproject.

Subproject Example

Subprojects are designed to limit the information pool that is to be analyzed. As an example, let's create a subproject with the sample code included with Revolve and use it in analysis.

1. In the Project Manager, invoked from the Project Menu or with the Project Manager button at the bottom of the Revolve window.
2. Double-click on the cobol files entry.
3. Left click and drag the mouse downward to select BATCH1.CBL, BATCH2.CBL, ONLINE1.CBL, and ONLINE2.CBL. This is the information that we will use to compose the subproject.
4. Press the Add to Subproject button.
5. In the Add to Subproject dialog that appears click the New Subproject button.
6. Enter SP1 as the name of the subproject and click OK.
7. In the Add to Subproject dialog select SP1 and click the Add button.
8. A dialog will appear to inform you that the elements were added to one subproject. Click OK.
9. Select Data Files from the Browsers menu.
10. Click the Match button. This will cause the window to fill with all data files in the loaded sample project.
11. Double-click the folder for PROD.DEFAULT.MASTER. Notice that ONLINE1.CBL, which is in our subproject, is included under this entry, along with other programs.
12. Now, press the Assign Scope button on the button bar.
13. In the Choose dialog select the subproject SP1 and click the OK button.
14. Go back to the folder for PROD.DEFAULT.MASTER and expand it. There's ONLINE1.CBL. Other programs are not displayed because the analysis was limited to the subproject SP1. This is a very effective way to limit information and perform streamlined analyses.

11.1.5 Shareable Projects

Revolve projects can be configured so they are accessible by one user at a time (Single User Projects) or by many users simultaneously (Shared Projects).

The configuration of Shareable Projects is different from a network version of Revolve in which multiple users are able to use the same copy of Revolve simultaneously. Just because Revolve is accessed from a network does not necessarily mean that the projects are shareable. The ability to share Revolve projects depends primarily on the configuration chosen by the administrator.

Both single user and shared projects can be password protected to prevent unwanted changes to the project's configuration.

See also the chapter about Shareable Projects.

Single User Projects

A project which is not shareable, known as a single user project, gives any user the ability to perform both analysis and administrative tasks. However, only one user at a time is permitted to open the project.

For these projects, a password can be specified which must be entered each time the project is opened. This is accessible through the Administrator Options dialog box located under the Utilities/Options menu.

Shared Projects

Revolve projects can be configured to give certain users access to administrative functionality while others are limited to performing analysis tasks. Users are those individuals with access only to analysis tasks. The Administrator has access to options which affect the analysis done by Users.

See also the chapter about Shareable Projects.

Rights specific to an administrator include:

• Adding components to Projects
• Removing components from Projects
• Deleting Projects
• Loading components
• Making a database shareable
• Updating a shared database
• Complete Project
• Global Indices

11.2 Revolve's Interface

Revolve provides tools and information browsers for the analysis of source code. The interface of each tool is designed around a series of common features that make using Revolve both flexible and consistent. This section describes the common features that you will see across Revolve.

11.2.1 The Button Bar

A button bar appears in virtually every window within Revolve. Each button is used to manipulate the window's data or perform a function. Buttons are provided for tasks such as:

• Printing
• Saving to a text file
• Adding elements to annotations
• Viewing Source Code
• Viewing Graphics
• Expanding/Contracting elements in an information window.
• Highlighting
• Information Screening (certain information browsers and views)
• Loading (Project Manager only)
• Fixing source inconsistencies (Complete Project only)

While several buttons are common across all windows, many differ depending on the window's function. For definitions of specific buttons, refer to Appendix B.

11.2.2 The Match Edit Bar

The Match edit bar appears in most windows within Revolve which contain an information window. It's primary function is to enable you to quickly view pertinent information about a specific items. The information displayed depends on the browser or tool that is being used.

The Match edit box is a field where an item's name is entered. The pull-down list box specifies how the information in the information window will be organized. After these parameters have been established the Match button initiates the search and fills the information window with results.

The wildcard character (*) appears by default in the Match edit box in most Revolve interfaces. This character is used to find all items with similar names. For example, if "WS*" is entered into the Match edit box in the Variables browser, the information window will display all the variables with names that begin with "WS." In most cases, if the wildcard character is used alone as a match criteria, the information window will fill with all items in the project as they pertain to the specific browser or tool. The (?) character is used to construct a pattern where "?" stands for a single arbitrary character. For example, "WS?" would match all names consisting of "WS" and another character, like WS1 or WSA.

The Information Window

An Information Window is a special type of listbox which presents data in a clear hierarchical format and permits modification of the amount of information which is displayed at any one time.

A format is used in which all information starting in the same vertical column on the screen is at the same hierarchy level. When a parent line is expanded the child information for that line appears beneath and indented from the current line's position. Folders are expanded by double-clicking. Also use , , to expand and collapse folders.

- a parent line which has not been expanded. The "+" indicates that Revolve has retrieved database information for this item that will appear as subsequent or children folders when double-clicked.

- a parent line which has already been expanded and contains children folders.

- a line which has been expanded and whose children are currently displayed.

- a line which is not expandable. Commonly known as a leaf.

11.2.3 Information Screening

Certain tools, views, and information browsers within Revolve are able to limit the information displayed by both the criteria specified in the Match edit bar as well as by a process called Information Screening. Options dialogs, accessible with Options buttons , allow the user to specify additional parameters for the lookup of data in the information window. Often these options do not even require the use of the Match button.

11.3 Viewing Source Code

When the View Source Code button is pressed, the Split Screen Editor is displayed and can be used to modify source code. The Split Screen Editor will display the source code for any element selected in the information window. While the Split Screen Editor is displayed, the thin, black, horizontal line dividing the sections of the window can be dragged with the mouse to adjust the size of the editing window.

The Split Screen Editor is closed by clicking the View Source Code button again.

See also For more information about the Split Screen Editor, see the section on the Integrated Editor

11.4 Printing

Printing the contents of an open window is performed by pressing the Print button .

The generated report will contain either a graphical or textual representation of the information displayed in the open window. Any information which has not been expanded (as with collapsed hierarchy levels in information windows) will not be printed. The following options are available in the Printdialog:

• Print to File When this checkbox is selected and the Print button is clicked, a Print to File dialog is displayed allowing the user to save the Revolve window as a .prn file into a specified directory.
• Color Output Revolve prints to grey scale unless this option is selected. Color Output allows for highlighted or selected items to appear in the print as they appear in the Revolve window.
• Legend This option prints out a legend for the View that is being printed. Legends define symbols and specifications for the specific, invoked View. To print legends for views that are invoked in the Split Screen Editor press the Print button in the editor and use that Print dialog to print the legend.
• Collate Copies Specifies for print to be collated.
• End with FF Specifies form feed. This is generally not needed and will allocate a blank page at the end of the print job.

11.5 Highlighting

Highlighting marks source code elements in selected colors. The Color menu, located at the bottom of the Revolve desktop, allows you to specify a highlighting color. When you click the Highlight button in a browser, the source code for all leaves () will be highlighted in the specified color. The Source View is invoked to display the line of code that was highlighted.

You can also highlight by right-clicking on an item and selecting the Highlight option. To view the highlighted code, right-click again on the item and select Go To, or click to view the source code in the Split Screen Editor.

See also Color Menu.

11.6 Adding Information To Annotations

Annotations provide a mechanism for creating and manipulating persistent documents or notes containing user-defined information about specific elements of source code. The Add to Annotation button , displays an Add to Annotation dialog. To create a new annotation:

1. With the mouse select an item or a series of items in a Revolve information window (ie. information browser).
2. Click .
3. Click New Annotation.
4. Enter the title of the new annotation in the Required Field dialog.
5. Click OK.

After an annotation has been defined, items can be added by selecting the annotation title in the Add to Annotation dialog and clicking Add.

See also For more details on annotations, see Annotations.

11.7 Long Filenames in Revolve

Revolve 16-bit does not accept filenames longer than 8 characters. The 32-bit version of Revolve allows long filenames as operating systems permit. For example, Revolve 32-bit running under Windows '95/NT allows components to have long filenames.

Long filenames within source code files will cause parsing problems in the 16-bit version. In these instances the filenames must be translated to an accommodating length of 8 or less characters. It is also important to remember that projects should contain 8 character filenames if they are shared between 16-bit and 32-bit versions of Revolve.

See also the section describing the Import Translations dialog.

11.8 Modification Driver

To support the transition from source code analysis to the implementation of modifications Revolve provides the Modification Driver. The Modification Driver allows the user to automatically insert user-defined text, comments, and/or code into the source code of selected items. This feature facilitates the implementation of source code changes in Revolve and allows for Revolve analysis results to marked for follow-up modifications in other development environments. Identified changes can be tagged or commented in the source code with the Modification Driver and easily located in Micro Focus Workbench® or other editing environments.

To insert user-defined text:

1. Select applicable item(s) in the information window. Multiple items can be selected. The Control key used with the left mouse button allows you to select multiple items that do not occur sequentially.
2. Press the Modification Driver button . The Modification Driver dialog will be displayed.
3. To tag columns, activate the Tag columns check box.
4. Specify the column numbers in the respective fields. The column tag parameters should be set from 1 to 6 for COBOL code
5. In the adjoining field, enter the text that should be inserted into the tagged column.
6. To insert comments or code before selected source code, activate the Insert before check box and enter text into the adjoining field. To insert COBOL comments, space over six positions in order to preserve proper column alignment. Also preface comments with an asterisk (*).
7. To insert text after selected code, activate the Insert after check box and enter text into the adjoining field. To insert COBOL comments, space over six positions in order to preserve proper column alignment. Also preface comments with an asterisk (*)

To insert text into the source code of multiple items in one step, set the parameters discussed above and click Execute all . The Execute button inserts text into the code of the current item. To skip a selected item's source code and continue insertions in the next item's code, click Skip. All insertions can be viewed in the Split Screen Editor.

Upon closing the browser or tool in which changes have been made, you will be prompted by a Save File dialog to save modifications. Yes to All saves all modifications that have been made. No to All cancels all changes. Yes saves the modification of the displayed item and No cancels it.

11.9 Capturing Results

When the Early Release Option is selected in the User Options dialog (Utilities/Options/User), the Capture Results dialog can be invoked by clicking . Capturing Results allows selected items to be included in annotations, subprojects, POP files, and TAG files.

• Add to Annotation: displays an Add to Annotation dialog where selected items can be added to an existing annotation or a new annotation can be created.
• Add to Subproject: displays an Add to Subproject dialog where selected items can be added to an existing subproject or a new subproject can be created.
• Export to POP file: displays a Create POP File dialog. POP files can be used to define projects in Micro Focus COBOL Workbench. Give the file a name, navigate through the directories to the location where it should be saved, and click OK.
• Export to Tag file: adds a tag to the source code of the selected items. Tag files mark source code for easy future identification in Revolve and other applications.
• Options: allow you to set the Tag file extensions and Tag values that are inserted in the selected element(s).

Reporting on the Worksheet

Setting Up Projects