Metering Lines of Code

Using Worksheets

Chapter 4: Using Enterprise Analysis Tools and Sets

This chapter describes using the analysis tools to produce sets, and how you work with the sets.

4.1 Introduction

The analysis tools search for points of interest that match the criteria that you specify. Typically, each analysis tool searches for points of interest based on one specific attribute, such as the names of data items, their type and size, their values, their usage and so on. Many tools accept an input set, usually containing data items or statements, on which to work. Most tools create an output set containing the points of interest that match the specified criteria, and some tools move the resulting set into the worksheet.

Figure 4-1 shows an example view of a set. The points of interest in the set are listed in the left-hand pane. The right-hand pane shows a history of how the set reached its current state. You can also optionally show the source program containing a POI, or view relevant source code.

Figure 4-1: Example Set View

4.2 The Analysis Tools

There are single-step tools that search for one type of point of interest, and composite tools that are a combination of other tools. Some composite tools are supplied, but you can also create your own. You can also create batch processes, which specify a series of tools (either single-step or composite) to be run one after another.

By default, only some analysis tools are listed in the Analysis Tools palette. You can show or hide whichever tools you want, so that you see only those tools that you need. To show or hide tools, click Options in the Analysis Tools palette and go to the Tool Palette Editor tab.

When you run an analysis tool, you can specify the points of interest to search for in various ways:

You can specify the project components for the tool to search by using the Scope option. You can also provide the tool with an input set so that it applies only to the points of interest in that set.
You can change the tool's settings temporarily (that is, for only the current session) by typing the settings you want. Some tools enable you to import a text file containing a pre-defined set of search patterns.
You can use the default settings or swap to another group of settings that have been previously set up and saved with the Configuration wizard. The settings group currently in use is shown at the bottom of the Analysis Tools palette.

4.2.1 Scope of the Analysis Tools

When you run an analysis tool, it searches only the specified scope of code. You can choose universal scope, in which case the tools search the whole project, but alternatively you might want to specify the programs that you want to search. This makes each search quicker, but the search is not comprehensive.

To define the scope of the search click Options in the Analysis Tools palette, go to the Scope tab, and specify the scope you want.

By default, the single-step tools search the whole project. The supplied composite tools vary in the scope of their searches. See the help on each tool for details.

You can also run a tool by dragging a set onto it, thus further reducing the scope to just the points of interest in that set.

4.2.2 Changing Tool Settings for this Session

The tools search for points of interest matching the criteria that you specify. The criteria are known as the tool's settings. So, before running a tool, you might need to change the settings.

With some tools you change the settings by selecting options, and with other tools you enter your own settings or import a text file of settings. Importing a text file of settings can be quicker than entering the settings in a dialog. Using a text file of settings also enables several people to share an imported file, saving everyone time and ensuring consistency. Look up Settings in the help index for details on how to edit settings and how to prepare a text file for importing.

The new settings remain in force for this session or until you change them again. If you want to preserve the settings, use the Configuration Wizard and save them in a group of settings. Note that the worksheet channel will use the new settings when it is run from the Analysis Tools window, but will use the default settings if it is implicitly run by using an Add to worksheet option from a hover menu or a menu button.

Tip: By default, tools run without asking you to specify the settings. To change this, click Options in the Analysis Tools palette, go to the Analysis Tools Options tab and check Edit settings before running a tool.

4.2.3 Configuring and Saving New Settings

Customize the settings for groups of tools using the Configuration wizard. These settings remain in place even if you close the current session. The Configuration wizard takes a copy of the default settings (or whichever previously configured settings you select) and then you make changes. For details on how to do this, look up Configuration Wizard in the help.

Tip: You can swap between groups of settings or return to the default settings at any time by selecting Enterprise>Settings. The group of settings currently in use is shown at the bottom of the Analysis Tools palette.

4.3 Composite Tools

A composite tool contains a sequence of tools each with their own settings and can also contain steps that combine sets in various ways. Some composite tools are supplied, but you can create your own too.

4.3.1 Creating a Composite Tool

You can create a composite tool by hand, by adding whichever tools you want to the composite tool. To do this, you right-click in the Analysis Tools palette and use New Composite Tool. For full details, look up Composite tool in the index of the help.

Alternatively, you can create a composite tool from an existing set, so that the new tool can reproduce the process you used to create the original set. This is very useful if the analysis process you use to find a set points of interest is complicated and you want to be able to repeat that process consistently. You can then use the composite tool for other projects and in group projects, and thereby save effort and ensure consistency. To create a composite tool this way, you right-click on the audit trail of the existing set and click Create Tool.

You can also create a new composite tool by copying an existing one. This is useful if the current tool already does a lot of the things you want, but you just need to change a few settings. To copy a composite tool, right-click on it in the Analysis Tools palette, click Copy and save the tool with a new name. You can then edit it as required.

When you create a composite tool, the current settings of the included tools are captured as the default settings of the new composite tool. If you later change the settings of the stand-alone version of a tool you included, only the stand-alone version changes and not the copy that you included in the composite tool.

4.3.2 Editing a Composite Tool and its Settings

You can edit a composite tool to change the tools included in it or to change the settings of those included tools.

To change the included tools, double-click the tool, or right-click it and select Properties, to use the Composite Tool Editor, which displays the sequence of tools and operations within the composite tool. You can then add or delete tools as required.

To change the settings of the tools included in the composite tool, double-click the composite tool first and then double-click the included tool. You can then change the included tool's settings. For details, look up Composite tool in the index of the help.

4.4 Batch Processes

A batch process contains a series of tools that is run in sequence on the current project scope. The main differences between composite tools and batch processes are:

The settings for each tool in the batch process are those that are current for the tool; you cannot edit them specifically for use in the batch process.
You can suppress the display of a tool's output set that might be created by the tools in the batch process, which you cannot do with a composite tool.

You create and maintain your batch processes using the Batch Process Editor; to find this, right-click on the Batch Processes page and select New Process. You can:

Create a new process, by adding whichever tools you want to it, either simple or composite ones. When the process is run the tools are executed in the order in which they are listed in the Batch Selection list box.
Edit an existing process

When you are creating or editing a process, you can:

Add and remove tools
Move them up or down in the Batch Selection list box, thereby changing the order in which they are executed.
Specify that you do not want the set output by a tool to be displayed. You would normally do this only for intermediate sets.

After you have finished defining a new process, and you click Save, you can specify a name for the new batch process, the name of the file where you want it to be stored, and its scope.

There are also facilites to delete a batch process, copy a batch process and view and change the details that you specified when you originally saved it.

For full details of how to create and maintain batch processes, look up Batch process in the index of the help.

4.5 Working with Sets

Each time you run a tool, a fresh set is produced. This means that you can always rethink and start again if you run a tool and the resulting set is not what you expected.

4.5.1 Creating Sets

You can create sets from a number of starting points:

The whole project. You create a set based on one or more specified attributes, by using the appropriate analysis tool. For example, you can create a set of all the data items with certain types and sizes, by double-clicking Type and size of data items and specifying the types and sizes.
Selected programs in the project. To do this, use Options in Analysis Tools, select the Scope tab and specify the programs to search.
An existing set (typically a set of statements or data items). For example, you can create a set of the data items that are used in a set of statements, by dragging the statement set onto Data items from statements. Conversely, you can create a set of statements from a set of data items by dragging the data item set onto Type of statements and specifying the types of usages you are interested in.
A subset of candidates in a set. You select the candidates individually using Ctrl+click within a Set View, and drag them onto one of the analysis tools, such as Copy or create set or Worksheet channel.
Selected candidates in the worksheet. You select the candidates and drag them onto one of the analysis tools, such as Copy or create set.

You can also expose a set to further refining by an analysis tool, by dragging the set onto the tool and specifying the required criteria. The contents of the resulting set depends on the tool.

4.5.2 Manipulating Sets

You can manipulate sets in the following ways:

Combine sets: make a union of them, intersect them or subtract one from another. Intersecting two sets finds the candidates that are common to both sets. Making a union of two sets combines the contents of both sets and subtracting removes the contents of one set from another. For example, you can subtract a set of MOVE statements from a set of all statements.
Filter existing sets with the analysis tools to remove any candidates that don't meet that tool's criteria. You can use a number of tools in sequence, feeding the output from one tool as input to another.
Move sets to and from the worksheet via Worksheet channel. You can add sets to the worksheet or remove sets from it. You can also create a set from selected worksheet entries.

The history of the set is maintained in the right-hand pane, so that you can see how you arrived at the current set. The history states how you first generated the set, the analysis tools you subsequently used on the set, and the other sets or subsets you combined with this set. To see the criteria that you specified for an analysis tool, double-click the name of the analysis tool in the right-hand pane.

4.5.3 Combining Sets

You can combine a whole set with another set, using the following set operations:

Set operation:	Result:
Intersect	Removes from the target set any candidates that are not also in the dragged set. The resulting target set contains only the candidates that are common to both sets.
Union	Adds the contents of one set to another or to the worksheet.
Subtract	Removes the contents of one set from another or from the worksheet.

To combine a whole set with another set, pick up the whole set by pointing to in the Set View, and dragging it to the target set. If you hover over the target set before dropping the dragged set onto the target set, a menu pops up for specifying how to combine the sets.

Alternatively, instead of hovering and waiting for the menu to appear you can use a key in conjunction with dragging with the mouse, as follows:

Cursor:	Set operation:	Mouse + key:
	Intersect	Drag
	Union	Drag
	Subtract	Alt + drag

4.5.4 Combining a Subset with a Set

You can combine a subset with another set using the same set operations as for combining a whole set: intersect, union or subtract.

To combine a subset, you select just the set entries you want and drag those to the target set. You can hover over the target set and choose the required set operation. Alternatively, you can use a key combination with the mouse.

Note: Set operations on an arbitrarily selected subset destroy the integrity of the resulting set. The resulting set is no longer considered pure. It is no longer a product of manipulating complete sets using known criteria, and this step cannot be precisely recorded in the history of the set in the right-hand pane of the Set view. This means that you cannot reproduce the set automatically, but you have to repeat the manual step if you want this set again.

4.5.5 Naming, Saving and Deleting Sets

We recommend keeping sets only temporarily, because once you have identified some genuine points of interest, they need to be in the worksheet. Sets are temporary, whereas the worksheet is the permanent record of the points of interest. Sets are partial information, whereas the worksheet is a complete persistent database that is immediately updated whenever you make any changes. Also, only the group worksheet enables you to share information, and you cannot share sets.

Although sets are temporary, you can keep them from one session to another if need be. You can:

Name a set, which automatically saves it. You can then open the set from the Named Sets window. Use named sets for sets that you will want to refer to and use while analyzing the project.
Save a set without naming it. You can then reload the set, but it does not appear in the Named Sets window. Use saved sets when you need to keep a set between sessions but don't need to keep it for the life of the project.
Go to an open set, whether or not it is named or saved, by selecting it from the Window menu.

4.5.5.1 Named Sets

Use named sets for sets that you will want to refer to and use while analyzing the project.

When you name a set, the set is stored to disk with the name you specify and the suffix .set. It is stored in the project directory. You can then:

Go to the set or re-open it by double-clicking it in the Named Sets window
Save changes to the named set by closing the Set View and confirming that you want the changes saved
Delete the set, by deleting its name and then closing the Set View without saving

For details on how to name a set and how to delete a named set, look up Named set in the index of the help.

4.5.5.2 Saved Sets

Use saved sets when you need to keep a set between sessions but don't need to keep it for the life of the project.

When you save a set, it is stored by default in the project directory.

When you reload a saved set, the saved set is loaded into the current Set View. This means that the name of the saved set does not appear in the window title, but the name of the previous set remains. If the previous set was a named or saved set, you can redisplay or reload it later.

To delete a saved set, close the Set View and delete the file in Windows.

4.5.6 Moving Sets to and from the Worksheet

You can add a set or subset to the worksheet in the same way as you combine other sets and subsets. You can also take selected worksheet entries and make them into a set or combine them with an existing set.

You use the Worksheet channel tool to move sets to and from the worksheet. You can:

Add a whole set or selected items in the set as candidates using Add candidates. If you do this, you can allocate categories and write notes for the entries you are adding, otherwise the entries are just added to the worksheet.
Add a whole set or items in the set as non-candidates using Add non-candidates. You can allocate categories, write notes and provide a reason why these are non-candidates. Any candidates in the set or subset that are moved to the worksheet are marked as non-candidates, just as if you had used Remove from list.
Create a set from the whole worksheet or items in the worksheet using Extract from worksheet. You can specify what to extract by applying filters, selecting POI types, data types and categories, and choosing between all candidates and only non-candidates.

You can also:

Drop worksheet entries onto a set, either adding, removing or intersecting them with that set
Drop worksheet entries on one of the analysis tools and specify the required criteria for that tool. For example, you can produce a specific set of statements, by selecting some statements in the worksheet and dragging them onto Copy or create set or Type of statements.

When you move items to the worksheet the result is by default a union of the set or subset and what was in the worksheet. Alternatively you can choose to move only the intersecting items or only the non-intersecting items. You are told how many candidates or non-candidates are added. Any candidates in the set or subset that are already non-candidates in the worksheet, remain non-candidates. They do not get reinstated.

When you use the worksheet channel, the default worksheet is created if no worksheet exists for this project. If only the default worksheet exists, then it is opened. If you have enabled multiple worksheets, the most recently used worksheet is opened. If there is no last used worksheet, the default worksheet based on the project name is opened. For further information about multiple worksheets, see the section Multiple Worksheets in the chapter Using Worksheets.

You can also highlight the candidates in the set that are already in the worksheet. To do this, use Options in the Analysis Tools and check Colorize items that exist in the worksheet on the Set Viewer Options tab.

Metering Lines of Code

Using Worksheets