Chapter 8: Administering Group Working

The information in this chapter is intended for the system administrator and describes:

• The features that enable programmers or analysts to work together in a group on the same project, with the work divided between them.
• The responsibilities of an administrator involved in running group projects with particular emphasis on the use of group worksheets.

  It is assumed that you are familiar with worksheets and have read the chapter Using Worksheets.

Group Working Features

Revolve provides the following features that help you, the system administrator, to facilitate and manage group working:

• Shareable projects. You can make a project available to a group of users, who can all work on different components of the project at the same time. When a project is shared, many project management tasks, such as adding components and deleting projects, become your exclusive preserve.
• The REQL language and script templates. These enable you to automate project management, easing the task of looking after large shared projects.

Making Projects Shareable

You have the ability to make projects available to more than one user at a time. 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 from 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.

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.

General Project Functions

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

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
integer rebuildProjectManagerData()	Rebuild Project Manager data for all views
addPathSource(strPath, type, [, indScan [, parent]]);	Search Directories (Project Level)
addExtSource(strExt, type);	Extensions

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:

Component Parameters

This section describes functionality that corresponds to the Component Parameters tab on 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

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.

Administrator Responsibilities

Group working requires a consistent approach to policy and standards, especially where you have several projects in one enterprise.

Projects may be independent of each other, or may be related, for instance, if a very large project has to be divided into subprojects. Each subproject is treated as a separate project.

There are a range of tasks including setting up, customizing and maintenance which are best coordinated by one person, the administrator. To enable a group to work together, the administrator needs to define a strategy and the process for group working. It is worth taking time to develop a system that applies to your specific project for everyone to use consistently: this can save a great deal of investigative time and effort.

Administration Tasks to Set Up and Run Group Working

Having decided on your group working policies, there are three possible ways that group working can be established. These are discussed in the section Group Working in the chapter Using Worksheets.

The method described here is that of sharing a project for which the administrator needs to do the following:

• Create a project
• Load the source code for the project into the Revolve database
• Make the project shareable

  When you make a project shareable you automatically create a duplicate copy of the project with an .sha extension. This is stored in a separate directory from the initial project and is referred to as the Shadow Project: it is used by the administrator to perform updates to the project without interfering with other users.

• Make the project accessible to the users

  All users need access to the shared project and require its name and location. Users cannot update the source files directly but pass changes to the administrator to be loaded into the project. For further details, see the section Making Projects Shareable earlier in this chapter.

• Meter code

  If your application code is metered on a line-of-code basis, the code has to be metered before you can process it. However, only one person needs to meter the code and then everyone can process the code without further cost. Authorizing a user includes enabling a usage counter for that user and giving write access to the metering control file. See the chapter Metering Lines of Code.

• Customize tools and other group settings

  Customize and make shareable the analysis tool settings and default categories. Create new composite tools where appropriate. See the sections Customizing Group Settings, Sharing Worksheet Classifications and the chapter Using Analysis Tools and Sets.

• Create and maintain a group worksheet

  For everyone to be able to view the current state of the group's analysis information, this involves merging users' changes into the group worksheet, and backing up and restoring the group worksheet. See the section Sharing Worksheets.

• Set and allocate work to the group members

  See the section Sharing Worksheets.

• Produce reports

  The administrator needs to merge all the local worksheet information into the group worksheet before running the reports to ensure accurate information is produced. See the chapter Worksheet Reports for further details.

Customizing Group Settings

Revolve enables you to share custom analysis tool settings, composite tools and batch processes so that results are consistent and meaningful.

Items to be customized for the group are:

• Settings for the analysis tools

  Users can specify different settings for each analysis tool every time they run it, but if they do, each user would identify different points of interest for the same problem and the worksheet would end up with conflicting points of interest and misleading information. To ensure consistency, you need to create one group of settings for everyone to use. See the section Sharing Analysis Tools Settings.

• Composite tools

  Users can create composite tools to address their specific analysis requirements. To find out how to share these composite tools, see the section Sharing Composite Tools.

• Batch processes

  Users can use any analysis tools in any sequence, but to ensure consistency they need to use the same sequences of tools. To enable this, you can create batch processes, which contain sequences of other tools. See the section Sharing Batch Processes.

Sharing Analysis Tools Settings

The default settings for the analysis tools are stored in a group called defaults in the Config\Settings directory.

To share customized individual tool settings, copy the tool settings file (.dts) onto each user's computer. The .dts files are created by the Configuration Wizard.

You can define new tool settings each time you run a tool, although this does not guarantee a consistent method of locating POIs when working on a group project.

For full details on how to customize and share settings, look up Settings in the index of the online help. See also the chapter Using Analysis Tools and Sets for for details on configuring settings.

Sharing Composite Tools

As an administrator, you create and share composite tools to avoid users using tools in different ways and so finding different points of interest. Composite tools have the filename you specify with the file extension .ct.

You can make a composite tool (.ct) available to only the current project, to all the projects for the current user or to all projects by anyone whose computer has access rights. Composite tools are stored as follows:

If tools with the same names exist in the shared directory, the users' project directory and also in the users' Enterprise > Analysis Tools directory, the shared tool is used. The tools are searched for in the following order:

1. Shared
2. User
3. Project

For full details of sharing composite tools, look up Composite tools in the index of the help. See also the chapter Using Analysis Tools and Sets for details on creating and editing composite tools.

Sharing Batch Processes

Batch processes provide a means of running a sequence of composite tools one after the other in a defined order. If it is important that all users run the same set of tools in the same order, then you should create a batch process to share between the users. Sharing batch processes works in the same way as sharing composite tools.

You can make a batch process available to only the current project, to all the projects for the current user or to all projects by anyone.

See the section Batch Processes in the chapter Using Analysis Tools and Sets.

Sharing Worksheet Classifications

Group users need to use the same classifications in the same ways so that, for example, final reports contain accurate information for each type of classification. You can customize the default settings for classifications for everyone to use.

Taking the time to develop a shared system of classification can save a great deal of investigative effort. If you decide to do this and want to avoid unnecessary work later, we recommend that you plan your classification strategy with care.

Types of Classifications

There are four types of classifications that can be assigned to points of interest:

• Categories

  These are assigned to points of interest and can indicate, for example, how the points of interest were found or the type of work required to overcome the problems.

  The administrator can choose whether an individual user can define his own local categories: individual users can never change group categories.

  See the section Categories in the chapter Using Worksheets for more information.

• Notes

  When you add points of interest to the worksheet, you can add a note to describe, for example, the origin of the items or why they are being added. Reasons for ascribing notes will differ according to the individual organization and project requirements.

  Revolve can remember recently used notes. The precise number of notes to remember can be adjusted. See Notes in the help index for further details.

• Removal reasons

  Removal reasons are notes that you add to explain why you are removing points of interest.

• Data types

  Data types show how data items of a particular type are handled, such as data items used to store dates of different formats and monetary values used in different contexts, for example, an account balance and an item price.

  See the section Data Types and Assignment Rules in the chapter Using Worksheets for more information.

Methods of Sharing Classifications, Filters, User-defined Tabs and Assignment Rules

The way in which users share classifications, filters, user-defined tabs and assignment rules depends on whether projects are stand-alone or group working. Within group working the sharing of classifications differs depending on which worksheet is involved, group or local.

Notes:

In a group working environment with local worksheets, you need to be aware that different conditions apply when users want to change classifications, filters or assignment rules:

• Categories and data types:
  • Individual users cannot change these types of classifications within the group worksheet
  • The administrator can decide at the time of creating local worksheets whether or not to enable local users to create new categories and data types. If this facility is enabled, any new categories or data types that users create can only be used in their local worksheets.
  • If you merge any items containing user-defined classifications into the group worksheet, this is treated as a conflict and you are asked if you want to add the relevant user-defined classifications to the group worksheet
• Notes, removal reasons and filters

  Individual users can always change or add to these types of classifications within their local worksheet but these changes are never merged into the group worksheet.

• Assignment rules
  • Individual users cannot change assignment rules within the group worksheet
  • The administrator can decide at the time of creating local worksheets whether or not to enable local users to create new assignment rules. If this facility is enabled, any new assignment rules that users create can only be used in their local worksheets.
  • Any new assignment rules created by users are never copied into the group worksheet

Sharing Worksheets

A group worksheet is useful for everyone to see the current state of the group's analysis information. The main areas of responsibility for the administrator are:

• Setting up the group and local worksheets and allocating the work to the group members.
• Backing up and restoring the group worksheet.
• Merging users' changes into the group worksheet.
• Resolving conflicts between entries being merged and the entries already in the group worksheet. An alert is issued if a conflict arises. You are given options to resolve the conflict.
• Producing reports on the group worksheet

Setting Up the Project and the Group Worksheet

As administrator, you are responsible for creating the project and the group worksheet. We suggest splitting up the work by source file, although you can split it up in any way that suits you.

There are two approaches to populating the group worksheet with the candidate points of interest (POIs):

• Populate the worksheet at the outset with POIs found by using the analysis tools or other integrated tools and then assign the POIs to users.

  After you have populated a worksheet with all the initial points of interest, this worksheet is still a local worksheet. You then must promote the local worksheet to a group worksheet and assign it a password.

  The group worksheet password is required for read-write access to the information stored in the group worksheet. It is also needed to change some properties of local worksheets created from the group worksheet. Group users without the group worksheet password have read-only access to the group worksheet. Local worksheets do not require a password. See the online help for further details.

  Or

• You can split up the work by program, as described above and allow the individual users to do all of the analysis. In this case, you create an empty local worksheet and then immediately promote it to a group worksheet.

For more information about group and local worksheets, see the chapter Using Worksheets.

Backing Up and Restoring the Group Worksheet

We recommend that you backup the group worksheet before making any changes.

You might need to restore a previous version of the worksheet if, for example, the new worksheet has some incorrect information or if there are many conflicts when merging. For further information look up Worksheet in the online help index.

Merging Local Worksheets into the Group Worksheet

The administrator is responsible for merging users' local worksheets into the group worksheet. Depending on the procedures in your organization, you can do this:

• At a set time
• When the users request changes and pass their saved worksheets to you for merging

Before merging in users' changes, you must backup the group worksheet in case you decide to restore the previous version. You should also ensure that you have backup copies of the local worksheets that you are about to merge into the group worksheet. If you decide to restore the group worksheet after merging items from the local worksheets, you should also restore the backup copies of the local worksheets. Otherwise you may lose some of the information that was in the local worksheets before you merged them. See the section Backing Up and Restoring the Group Worksheet for details.

You use the Merge wizard to merge in the information from the users' local worksheets and to resolve any conflicts between the new entries and the existing ones. When you merge the worksheets:

• You can merge only one or all of the information types. We recommend that you merge just data items at first. When you are confident that you have all the data items correctly assigned, the users can start investigating the other information types which you can subsequently merge.
• Any entries that are successfully merged into the group worksheet are deleted from the user's local worksheet. This means that if all the user's entries are successfully merged, the user's worksheet is empty.
• Any entries that are in a user's removed list are treated as conflicts if they exist in the group worksheet (but not its removed list). You can accept the user's entries, so that the corresponding entries in the group worksheet are removed and put in the group worksheet's removed list. There is an option to override this if the user who removed the item is marked as its owner.
• Any merges or changes you make are immediately saved in the group worksheet, and are immediately available to users when they refresh their worksheets.

Copyright © 2006 Micro Focus (IP) Ltd. All rights reserved.