Creating Projects

Implementing Analysis Tools

Chapter 4: Managing Projects

This chapter describes the features designed to help you manage your projects.

4.1 Using the Project Manager

The Project Manager, as the name suggests, is the interface designed to be used in project administration. It enables you to access your project on the component level according to file type. For example, all components that have been added to a project as COBOL files are displayed in the Project Manager under the cobol folder. Likewise, other folders that are displayed contain corresponding file types. From this vantage point you are able to access individual project files and control their status in the project.

The Project Manager is activated in three ways: by creating a new project, by selecting the Manager menu item from the Project menu, or by clicking Project Manager at the bottom of the Desktop.

Figure 4-1: Project Manager

The Project Manager's interface is designed around hierarchical folders, where the top level folder indicates file type. When expanded, corresponding project files are displayed. The following information is displayed in columns for each component:

• File name: identifies the file name of the component.

• File type: indicates component type.

• Status: displays the status of the component.

• File path: shows the path of the component when it was selected to be added to the project.

• Date: The last date the file was modified.

• Time stamp: The last time the file was changed.

Every component in a project has an associated status. Each possible status is described below:

• 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 current source code.

• Not Found: Source code for this component cannot be 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.

• Invalid: Indicates that either a designated preprocessor .dll is not available or the designated preprocessor failed due to source code error. To alleviate this status, first ensure that the preprocessor is configured correctly. To do this, check that the appropriate .dll is specified in the Options dialog, invoked by selecting the invalid component in the Project Manager and clicking Options. The name that appears in the bottom text box should match the preprocessor .dll file name as it appears in the \revolve\bin\ directory. If the appropriate preprocessor is available and the Invalid status still appears, examine the source code for possible errors.

In addition to viewing component status, the Project Manager enables you to add or delete components in the open project. The Add function displays the Add Components dialog box, where you locate system files and add them to the project. The Delete function deletes the selected component from the project.

After modifications, like adding or deleting components, and editing source code, are made to a project, check the status of the modified files by selecting them in the Project Manager and clicking Status. The Status function examines the file's time stamp to see when it was modified in comparison to the project. If time stamps differ, the modified files will have a status of Out of Date. To load the selected components, click Load Selected. To update the entire project click Make. The Make function examines all project files and updates all unloaded or out of date components.

4.1.1 Configuring at the Component Level

Every system file that you add to a project is assigned specific settings based on its file type. These settings indicate how the file will be handled in your project. There are two classifications of these settings.

• Component Level settings are applied to specific components.

• Project Level settings are applied to all components, based on type, as they are added to a project.

Project Level settings are applied to every file as it is added to the project. These settings are accessed on the Utilities > Options... dialog. The Project Manager enables you to make changes on the Component Level to Component Parameters and Search Directories. To do this, select component files in the Project Manager and click Options.... The changes you make affect only the selected components.

For more information on setting Project Level Component Parameters and on specific functionality, see Component Parameters and Search Directories.

4.1.2 Using Preprocessors

Preprocessors are useful for preparing some source files for parsing into a project. The Component Parameters tab invoked from the Project Manager, enables you to specify a preprocessor that selected components are directed through prior to parsing. When your project is parsed, components with preprocessor configuration are preprocessed with the module name specified in the Preprocessor field. After preprocessing is complete, the files are parsed into the project.

It is recommended that you store preprocessors in the \revolve\bin directory where Revolve is installed. If the preprocessor is not configured correctly, it will produce errors and cause relative source components to have incomplete information. Be aware that parser error messages may result from preprocessor problems. If you do use a preprocessor on a file and it doesn't parse correctly, try removing the prepocessor settings and allowing the Revolve parser to process the file. The parser may be able to handle the file on its own.

4.1.3 Subprojects

Querying against an entire project can be inconvenient when you need to access an isolated or small amount of data. To remedy this problem, you can create subprojects and use them in tools and browsers to streamline your analysis tasks. The Capture Results... button is available on most tools and browsers and enables you to load selected components into an existing subproject or to a new one. When you click Subprojects... on the Project Manager's tool bar you invoke the Subprojects window. From this interface you are able to organize and control your project's subprojects.

The Subprojects window enables you to use the following functions:

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.

4.1.4 Project Menu

The Project menu provides some general and specific functions that may or may not be available in the Project Manager. The following table provides a complete list and description of the options that are available from the Project menu. Icons indicate that the described function is available on the Project Manager's tool bar.

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	Changes access to the project from ADMIN to USER.
Make Shareable...	Prompts for the path and name of a shadow project.
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...	Imports .pop files and old projects created in previous versions.
Manager...	Opens the Project Manager to permit project administration.
Complete...	Opens the Complete Project, an interface that guides you 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 selected 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 time stamps to source-code time stamps and updates the status in the Project 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 selected components in the Project Manager. Also located on the Project Manager button bar .
Exit	Closes everything, saving all changes to the current project.

4.2 Shareable Projects

To make projects available to more than one user, you can create Shareable Projects. When a project is made shareable a duplicate copy of the project is created, given an extension of .SHA, and stored in a different directory than the initial project. The copy is referred to as the Shadow Project.

Using a shareable project is not the same as using a network version of Revolve, where multiple users can use the same copy of Revolve at the same time. A shareable project can be accessed simultaneously by several users across a network. However, access to shareable projects is controlled. There are two levels assigned to shareable project operators:

• USERS

• Administrators

USERS have analysis specific privileges in the shareable project. They perform analysis tasks and edit source code. But USERS cannot make changes to project loading and component options, like Search Directories or Component Parameters. They also cannot add or delete components. The modifications that a USER makes are implemented in the Shadow Project. It is the Administrator's responsibility to apply those modifications to the actual project.

The rights specific to an administrator include:

• Adding components to projects.

• Removing components from projects.

• Deleting Projects.

• Loading components.

• Making a project shareable.

• Updating a shared project.

• Completing the project.

4.2.1 Making Your Project Shareable

The first step in making your project shareable is to create a subdirectory that will contain the Shadow Project and its associated databases. This subdirectory does not have to be on a network drive but must be accessible to any operator who needs administrative rights to the project. The second step is to open the project that will be shared. From the Project menu choose the Make Shareable... option. This will prompt you for the directory and name of the Shadow Project. Shadow projects have a .SHA extension so as not to confuse them with the .PRJ of single-user projects. For the path name, choose the newly created subdirectory from the first step.

Figure 4-2: Making a Project Shareable

After clicking OK, the shadow project is built in the specified directory. Once this is completed, Revolve reopens the project in ADMIN mode.

4.2.2 Administrative Mode

Once a project is shareable, only an administrator has the ability to change the project through adding/removing components, parsing, etc. Functions exclusive to an administrator are listed below.

• Project > Save

• Project > Delete Project...

• Project > Complete...

• Project > Add Components...

• Project > Delete Components...

• Project > Load Selected...

• Project > Make...

• Project > Status...

To gain administrative access to a project, open the project and choose Project > Make Administrator. Another way to access the project as an administrator is to use the -A command-line option when opening Revolve.

For more information, see the appendix, Command Line Parameters.

When you are in the project as an administrator, Revolve includes the indicator "(Admin)" in its title bar. Also, certain buttons in the Project Manager are disabled. For example, the Add Components and Delete Components buttons will be grayed and unusable to someone with USER access but will be focussed and accessible to the administrator.

As a project administrator, you have ADMIN access to options not available to other USERS. It is also the administrator's responsibility to maintain the project and assure the integrity of the work that is being performed.

4.2.3 Password Protection

The administrator can protect administrative access to a project with a password. To add or change a project administrator's password. To access password settings, select the Utilities menu, click Options..., and click the Project tab. When you click the Password... button it displays a prompt where you enter the project's password.

4.2.4 Maintaining Shareable Projects

When modifying a project as an administrator by adding/deleting, making, or completing the project, you are modifying the Shadow Project not the main shareable project which all USERS share over the network. So, while a project is being updated by the ADMIN, USERS can continue analysis without interruption. As administrator, if you are satisfied the Shadow Project is completely up to date, you will need to update the shareable project using the Project > Update Shareable menu item or through the updateShared() function. This function requires that all USERS close the shareable project. Once the update operation is completed, both the shareable project and shadow projects will be up to date and in sync. If the administrator tries to update the shareable project while the project is still open to USERS, a project update message displays, stating that other someone still has the project open. The messaging system automatically logs off any USERS. This operation normally takes two to three minutes. Anyone with the shareable project open receives a message stating that the project is being closed down.

When you are updating a shareable project Revolve creates a .LCK file in the directory containing the project to prevent other users from accessing it. If the Update Shareable process is interrupted, this .LCK file should be removed to gain access to the shareable project.

4.2.5 Setting Up Messaging System

If projects are going to be shared by many people, the messaging system should be properly configured to enable network communication between the administrator and USERS. The \revolve\post\ directory is used by default to post messages. All operators should be able to read and write at the post\ directory.

A different post directory may be designated by creating GLOBAL.DEF in the revolve\bin\ directory. Format the file as follows, where "directory name" is the complete path to the new message post directory:

[Messages]

MessagePath=<directory/file name >

If a specified message directory/file is terminated with a back slash then the message file will be named Revolve.mes. For example, the message file specified with the path J:\Jim\ will be J:\Jim\Revolve.mes.

4.2.6 Making a Project Non-Shareable

To restore a shareable project to a single-user project:

1. Verify that the shared project is up to date.

2. Exit Revolve and make sure no other USERS are logged into the project.

3. Delete all the project files and database files from the Shadow Project directory.

4. Open the shareable project and select the Make Admin... option. You are asked if the project should be made non-shareable.

5. Click Yes to make the project non-shareable (single user).

4.2.7 Teamwork

When Revolve is used on a Local Area Network (LAN), it can support development teams through partitioned projects and databases. In a typical LAN-based project a copy of all system source files is loaded onto the central file server and parsed to create a master database. When programmers modify parts of the system, they make copies of files on their own PC and re-parse them into local databases. Revolve can be configured to treat the resulting partitioned database as a single entity with queries operating transparently across both parts. When both local and remote copies of a database exist, the local version takes precedence.

When system changes are complete, local files may be integrated with those on the master file server and reloaded into the master database. No specialized server software is required for work group operation. Revolve requires only that the LAN provide shared disk space and standard DOS file locking services.

4.2.8 Modifying Code on a Workstation

When you want to modify portions of the code and see those changes reflected in Revolve without interfering with other USERS, you need to create your own individual project.

The following procedure describes how a USER at typical workstation can configure his/her own personal project from a shared project.

1. Open up the shareable project.

2. From the Project menu, select Save As....

   This option is only available if the Project Manager is open.

3. Locate the directory where the new working project is to be stored.

   Save this project in its own directory.

4. Make sure the All Components and the Link to Existing Files options are set, and click Ok.

For any files set to be modified locally, first remove these files from the project using Project > Delete Components.... Then, add the new source code using Project > Add Components.... Finally, use Project > Make to bring the project up to date. By configuring the project in this way, the USER shares common files on the server and modifies files locally within the same project. If a file is modified locally, it can be reloaded to ensure that future queries against the file are correct. To reload, click Make.

Once the USER has completed making modifications, the modified file can be integrated into the file server and the Shareable Project updated by the administrator. This step should typically be performed overnight or during a period of low activity to prevent disruption to other USERS.

4.2.9 Moving a Shareable Project

Ordinarily, moving a project is a case of moving project files and databases from one path to another. With Shareable Projects, however, special considerations must be made. After physically moving the Shareable/Shadow project files, the Shareable Project path must be changed to point to the new location of the project.

1. Select Utilities > Options....

2. Click the Project tab.

3. Enter the new path to the project in the Shareable Project Path field.

4. Click OK.

5. Click Update Shareable on the Project menu.

Your project has been successfully moved and updated.

4.3 Automating Project Management

The Scripts tool provides project management scripts for you to use as templates for automating your administrative tasks. These scripts implement REQL functions and constructs for batch project management procedures and operations. Pronounced REE-QUAL, REQL is an acronym for Revolve Query Language. It is used to manage the Revolve database. REQL, used in conjunction with the provided scripts, facilitates batch, command line, project management, where an administrator maintains numerous projects at one time by running customized scripts.

When you use REQL in project management you should be familiar with some general functions and parameters. These correspond with features that are also available in the Graphical User Interface (GUI). For example, the projectOpen function corresponds to the Open option on the Project menu. Where the Open option displays a dialog box that you use to open a project, the projectOpen function requires that you enter the path to the project. For more specifics on REQL, see the chapter Introduction to the REQL Language.

4.3.1 General Project Functions

The following functions correspond to features accessible on Revolve's Project menu:

4.3.2 Project Load Functions

Use the following functions when loading system components into a project The square brackets [] indicate optional parameters.

These functions correspond to those available on the Project Manager.

REQL Function	GUI Equivalent
addComponent(strPath, [type]);	Add Components
projectAddDirectory(strPath, strFileSpec, indIncludeSubDirs [, type]);	Add Components
addComponent(strPath, [type]);	Add Components
projectAddDirectory(strPath, strFileSpec, indIncludeSubDirs [, type]);	Add Components
projectRemoveComps(setUid, [, indDeleteDatabase [, indDeleteSearchPath]]);	Delete Components
make();	Make
makeSelected();	Load Selected
parse();	Make
status();	Status
addPathSource(strPath, type, [, indScan [, parent]]);	Search Directories (Project Level)
addExtSource(strExt, type);	Extensions

4.3.3 Component Type Functions

REQL supports a wide variety of component types. Use the following type parameters when you add components to a project with REQL. These correspond to options available in Add Components.

File Types

• system_component_assembler

• system_component_bms

• system_component_cics-table_dct

• system_component_cics-table_fct

• system_component_cics-table_pct

• system_component_cics-table_ppt

• system_component_cics-table_rct

• system_component_cobol

• system_component_ecl

• system_component_ims_dbd

• system_component_ims_mfs

• system_component_ims_psb

• system_component_ims_gen

• system_component_pli

• system_component_jcl

• system_component_text

• system_component_tp-formal

• system_component_linkdeck

Import Types

• system_code_import_copybook:

• system_code_import_include:

• system_code_import_proclib:

• system_code_import_control-card:

• system_code_import_macro:

• system_code_import_library:

4.3.4 Component Parameters

This section describes functionality that corresponds to the Component Parameters feature that is accessed from the Utilities menu. All parameters are project level, in the sense that settings encompass components according to their type. The syntax for setting a component parameter is:

retCode :=addRel(sourceUid, relation="attribute-name", value);

A return code of 1 indicates success, 0 indicates failure. To set values for default project values with new components, use the project as the sourceUid parameter. To set values for existing components, use the component as the sourceUid parameter.

The following integer attributes are modified with the corresponding relationships.

• attr_reql_comp-param-i_align-offset

• attr_reql_comp-param-i_end-column

• attr_reql_comp-param-i_jcl-schid

• attr_reql_comp-param-i_start-column

The following string attributes are modified with the corresponding relationships.

• attr_reql_comp-param-d_comment-chars

• attr_reql_comp-param-d_flavor-name

• attr_reql_comp-param-d_preproc-name

The following flag attributes are modified with the corresponding relationships:

• attr_reql_comp-param-f_align-fields

• attr_reql_comp-param-f_comment-first-col

• attr_reql_comp-param-f_endcol-no-comment

• attr_reql_comp-param-f_extended-ascii

• attr_reql_comp-param-f_jcl-slash-ends

• attr_reql_comp-param-f_proccard-optional

• attr_reql_comp-param-f_import-type

• attr_reql_comp-param-f_librarian-replace

• attr_reql_comp-param-f_partial-replace

• attr_reql_comp-param-f_pli-keywords

• attr_reql_comp-param-f_pli-inernal-progs

• attr_reql_comp-param-f_pli-functions

• attr_reql_comp-param-f_pli-skip-preprocs

• attr_reql_comp-param-f_use-compname

• attr_reql_comp-param-f_word-storage

To set values for existing components, use the component as the sourceUid parameter:

• retCode :=addRel(project, relation="attr_reql_comp-param-i_start-column", 7);

• retCode :=addRel(project, relation="attr_reql_comp-param-d_flavor-name", "General");

• retCode :=addRel(project, relation="attr_reql_comp-param-f_extended-ascii", 1);

• uid :=system_component_cobol="BATCH1.CBL";

• retCode :=addRel(uid, relation="attr_reql_comp-param-i_start-column", 7);

• retCode :=addRel(uid, relation="attr_reql_comp-param-d_flavor-name", "General");

• retCode :=addRel(uid, relation="attr_reql_comp-param-f_extended-ascii", 1);

The syntax for getting an existing setting is:

retVal :=sourceUid:>attribute-name;

For example:

retVal :=project:>attr_reql_comp-param-i_start-column;

uid :=system_component_cobol="BATCH1.CBL";

retVal :=uid:>attr_reql_comp-param-i_start-column;

The following project options are set and returned with the setOption() and getOption() functions.

• "EnableACL" 0|1

• "PublicAnnotationDir" string

• "PostProcessingScript" string

4.3.4.1 Search Paths and Extensions

The following functions enable you to add search paths, and extension-type mappings. These correspond with functionality available in Search Directories.

• addPathSource(strPath, type, [, indScan [, parent]]);

• addExtSource(strExt, type);

For additional descriptions and examples of functions associated with REQL, refer to the Functions chapter.

Creating Projects

Implementing Analysis Tools