The Tutorials Start Here

Populating the Worksheet

Chapter 4: Finding Points of Interest

In this session, you use the Enterprise Edition analysis tools to identify sets of monetary data items.

Please see the Tutorials Map to check that you have been through all necessary previous sessions.

4.1 Overview

The application used in these Enterprise Edition sessions is supplied with Revolve Enterprise Edition. It is referred to as the Orderapp demo, and relates to part of an order processing application for a mail order company. In this session we suppose that the company has added some very high value items to its range, and needs to check that all its systems can handle the large numbers involved. You will need to look at every line of code that involves money, to work out whether to modify it.

Supplied are the source files - COBOL sources, copyfiles, BMS maps, and CICS resources. The analysis tools find items meeting particular search criteria, and put them into sets that you can manipulate. You use the analysis tools to find all lines of code that are of interest - those involving money, in this case. These are called points of interest (POIs). You can identify them using the following procedure:

1. Use search criteria designed to identify monetary data items by their PICTURE clauses. However, this search finds everything that could possibly be monetary, and so might include many that are actually not monetary.

2. Remove from this set all items used as counters, subscripts and other items that just help the flow of the program, since these cannot be monetary, and all items whose names imply they are not monetary.

3. Add to the set all data items that are initialized to a value and all statements that use constants with monetary data items.

This gives you your final list of POIs - lines of code that might need attention and might need decisions from business analysts.

You use the following analysis tools:

• Format of data items to find potentially monetary data items based on their PICTURE. This is the starting set and is the working set that we go on to analyze and refine.

• Use of data items to find and remove data items that are used in ways that imply the items aren't monetary. We will remove these from the working set of potential monetary items.

• Names of data items to find data items whose names imply the items aren't monetary. We will remove these from the working set of potential monetary items.

• Constants used with data items and statements to find data items and statements that are used with potentially monetary constants.

• Filter set to separate a set containing both data items and statements into one set of data items and one set of statements.

4.2 Preparation

Open Revolve Enterprise Edition from the Windows desktop, by clicking Start > Programs > MERANT Revolve TPS > Revolve Enterprise Edition.

If this session has been run before and has created a project and related files in the folder where you intend to create your project, delete them as follows:

1. Open the project, using Project > Open or the "recently used files" list at the bottom of the Project menu.

2. Click Project > Delete Project, then make sure Delete out related database files is checked and click Yes.

3. Use Windows to delete all files remaining in the project folder.

4.3 Creating and Building the Project

To create and build the project for the Order demo:

1. Click Project > New.

2. In the New Project window that appears, navigate to where you want to create your project folder for this demo, and use the button to create it. Call it Order.

   We will assume that your new folder is in the projects folder you created in the Revolve Getting Started, so that the path is \projects\order.

3. Type order in the File Name field, then click Create. (If this session has been run previously, you will be asked whether to overwrite the existing project. Click Yes.)

   So the path to this project is \projects\order\order.prj.

4. Click Yes on the Add Components message.

5. In the Drives list, select the drive where Revolve is installed. Make sure Filter is set to *.* and Type to automatic.

6. In the list of folders, navigate to \samples\Enterprise\orderapp. Double-click the icon at the top of the list to navigate to the parent directory.

   The \samples\Enterprise\orderapp contains the source files of the demo. They are in a subfolder called source.

7. Select the source folder, then click Add to add all the files in it to the project.

8. Click Yes when asked if you want to include subdirectories, then click OK on the message telling you how many files have been added.

9. Click Done, then click Yes on the New Components prompt.

   Progress indicators are shown while components are being added.

10. A message box opens to tell you that errors have been discovered in the source code. These deliberate errors illustrate different aspects of Revolve in these tutorials, so you don't need to worry about them. Click OK on the message.

11. Click OK on the message saying the project is up to date.

12. Close the Project Manager window.

4.4 Metering Code

The Enterprise Edition features are metered on a line-of-code basis, which means that the code has to have been metered before you can process it through the analysis tools. Only one person needs to meter the code and then everyone can process the code without further cost.

The demonstration programs are already metered, so all you need to do is to point to the file that confirms that the code has been metered. This file is called the metering control file.

To ensure Revolve finds the metering control file:

1. Click Enterprise > Analysis Tools.

   If the Analysis Tools window appears, you do not need to do anything about metering. You are already pointing to the correct metering control file. Skip the rest of this section.

   Otherwise, the Metering Wizard opens.

2. Follow the wizard's instructions. When asked for the metering control file, navigate to the directory \samples\enterprise\meter, which contains the relevant metering control file, factory.bdb. Continue with the wizard and click Finish at the end.

   If at any time a message appears telling you that the cache files need to be built, click Build cache files now, then click OK.

4.5 Preparing the Analysis Tools

To check that the settings of the tools are as required for this session:

1. If the Analysis tools window is not already displayed, click Enterprise > Analysis Tools.

   If a message appears telling you that the cache files need to be built, click Build cache files now, then click OK.

   The Analysis Tools window lists all the analysis tools included in Revolve Enterprise Edition.

2. Click Options on the Analysis Tools window's toolbar.

3. On the Set View Options, Analysis Tool Options and Scope tabs, make sure that the following options are checked:
   • Colorize items that exist in the worksheet
   • Display prompt before changing set contents
   • Edit settings before running tool
   • Universal scope within project

   All other chapters in this book assume that you have these settings.

4. Click OK

4.6 Searching for Data Items by Format

First, search for data items with PICTURE formats that could represent monetary values:

1. In the Analysis Tools window, click Format of data items and click to see the help describing this tool.

2. Double click Format of data items to run the tool.

3. On the dialog box that appears, click and then click any field for a popup explaining that field. Click anywhere to make the popup disappear again.

4. Make sure the settings on the Options tab are:
   • Type = Numeric
   • Maximum size = 18
   • Minimum size = 4
   • Maximum number of decimal places = 2
   • Minimum number of decimal places = 0
   • Include usage = Any

   This tool looks for data items whose definitions conform to the criteria you've set. These default settings represent items that could hold monetary values. As you can see, as a definition of a monetary data item these criteria are fairly broad.

5. Click OK.

   The tool runs, and searches all the files in the project for items that match the search criteria. Finally it displays a Set View window, showing the set of data items that it found. This window is shown in Figure 4-1.

Figure 4-1: Set View

In the Set View:

• The left-hand pane lists the data items in the set.

• The right-hand pane contains a history of the set, and shows that the set was created using the tool Format of data items. Point to the name of the tool in the right-hand pane and double-click to display the settings you used. Click Cancel to close the tool.

• The status line at the bottom shows that there are 250 data items in the set.

  If your set contains a different number of data items, check that you used exactly the settings listed in Step 4, by double-clicking the tool in the right-hand pane. If you used different settings, go back and rerun the tool with the correct settings.

• You can drag the border of the set view, to enlarge or shrink it, and you can also drag the divider between the two panes to suit. For now, enlarge the set view by dragging its top or bottom border.

4.7 Examining the Data Items in the Set

Now you start getting to know the sample source code, looking through the data items in the set and finding which data items aren't monetary and so need to be removed from the set. These items for removal are sometimes referred to as false positives.

1. In the Set View, look at the data item VAL-P-AND-P-COST.

   If you can't see it, you can scroll to it quickly. Click the Sort Ascending button to get the list into alphabetical order, then click in the left-hand pane and type V to get to the first item beginning with V.

   This item's name certainly implies it holds a monetary value. However, you might want to look at it in the context of the source code to confirm that it really is monetary.

2. Click VAL-P-AND-P-COST and then click the View Source Code button .

   This splits the Set View into two panes with the set at the top and the source file containing the data item's definition at the bottom. If necessary, drag the bottom edge of the Source View and/or the horizontal divider between the two views, so that you can see more source code.

   Notice that the definition of VAL-P-AND-P-COST sets an initial value of 17.50, which looks like a monetary value. Later we will capture a set of all such monetary constants.

3. Make sure that VAL-P-AND-P-COST is still highlighted in the Source View, and then click the Next Usage button several times to see where it's used.

   The way it's used in the Procedure Division confirms it is monetary.

4. Now click TEMP-QTY in the Set View at the top and then click several times to see how this item is used.

   From its name and the names of the data items it is used with, you can see this is not a monetary item. Later we will remove it, along with other items whose names imply that they aren't monetary items.

5. Now examine CURR-DATE-ACCEPT in the same way.

   Since this data item is used to hold the date, it is definitely not monetary and not of interest. In the following sections you search this set to find sets of data items that for various reasons are clearly not monetary, and remove them from this set.

6. Now examine the data items starting OE01 in the same way.

   These data items all correspond to BMS fields. Their data definitions are automatically generated from the BMS screen map and so have names ending in L, I, O corresponding to how the data items are used. Some of these data items might refer to monetary fields on a BMS screen, and might need modification. Once again, there is a tool to identify BMS-related data items.

7. Close the source view, by clicking again at the top of the Set View.

4.8 Naming and Saving a Set

To name and save the set you have created:

1. Click Options on the Set View.

2. In the Name field, type Initial data items and click OK.

   This saves the set in the project directory. Its filename is the name you specified, with the extension .set. Its name now appears in its title bar.

3. Click Enterprise > Named Sets, and you can see the set listed there. If the Named Sets window is not visible, you might need to scroll down to it and drag it up to just below the Analysis Tools window. If you can't see all of the name, drag the header bar divider for the Name column a little to the right.

4.9 Creating a Working Copy

To create a copy of the set so that you can work on it without affecting the original set:

1. Click in the "Initial data items" set so that the title bar is highlighted.

2. If necessary, drag the set to one side, so that you can see the whole Analysis Tools window.

3. Point to in the toolbar of the "Initial data items" set.

4. Drag the icon and point to the name Copy or Create set in the Analysis Tools window.
5. When the cursor changes to to indicate a set operation, drop the set onto Copy or Create set.

   The new set is now ready for you to use as a working set, so that you can refine it, gradually removing the unwanted non-monetary items.

6. Tidy up by closing the "Initial data items" set.

   It remains in the Named Sets window, so you can re-open it at any time.

7. Drag the working set to the top of the Revolve window, and to the right of the Analysis Tools window.

4.10 Subtracting Irrelevent Data Items

Many of the data items in the working set are irrelevant because they aren't used to process money, but rather are used to help the flow of the program. There is a tool for identifying these data items. It finds, for example, data items controlling PERFORM VARYING statements, and data items to do with dates.

To search the working set for these sorts of data items and remove them from the working set:

1. Point to in the toolbar of the working set and drag it onto Use of data items in the Analysis Tools window.

   If you run an analysis tool by double-clicking it, it searches the source files of the application as defined on the Scope tab of Analysis Tools Options. If you run the tool by dragging a set onto it, it further limits the search to just that set.

   On the dialog box, look at the check boxes to see the uses of data items that this tool searches for.

2. Make sure all the check boxes are checked and click OK.

   The resulting set contains 46 data items. Notice that these data items are genuinely unwanted, since they represent dates, lengths, error codes, and so on.

3. Now remove the data items in the new set from the working set. Start to drag from the new set, then hover over the working set without releasing the mouse button.

4. When the hover menu appears, select Subtract and drop the new set onto the working set. Click Yes on the warning message to confirm that you want to subtract the set.

   The working set now contains 204 data items (250 minus 46). Its history in the right pane, which records the tools and set operations used to create it, is now as follows:

   • The first line, Format of data items represents the first set you created when you started producing the resulting set that now exists in the left-hand pane.

   • The "Subtract" line indicates that one set was subtracted from the first set.

   • Everything in the curly braces represents the second set. This second set was subtracted from the first set. This second set was itself created in two steps: by first running Format of data items and then by running the resulting set through Use of data items.

5. Tidy up by closing the set created by Use of data items. Click No when asked whether to save the set.

4.11 Subtracting Data Items with Non-monetary Names

Another set of data items that aren't of interest are those whose names imply they are unlikely to contain monetary amounts. There is a tool to find these items. Since any application has its own naming conventions, you need to specify the kind of names to look for.

To search the working set for data items with these names and remove them from the working set:

1. Drag in the working set and drop it onto Names of data items in the Analysis Tools window.

2. Clear the existing defaults, by clicking Clear.

   We have supplied a list of names for the Order demo, so that you can import this list and run the tool quickly. In the real world you would develop your own list of names as you work on an application and get to know it. You can keep your list in a separate file and pass it to colleagues working on similar or related source files. This not only saves them time but also ensures consistency when any of you rerun the tool.

3. Click Import and specify the file Criteria.txt, which is in \samples\enterprise\orderapp\other.

   This imports a set of strings as the search criteria: *date*, *-dd*, *-id*, and so on.

4. Click OK.

   The resulting set contains 95 data items. Scan down the list of data items briefly and confirm that probably none of them is monetary.

5. Subtract this non-monetary set from the working set. This time, instead of dragging the set and waiting for the hover menu to appear, hold down Alt while you drag the non-monetary set onto the working set.

   The working set now contains 109 data items (204 minus 95). You have now finished deleting false positives from it.

6. Name and save the working set as "Potential monetary data items" using Options as before.

7. Tidy up by deleting the set created by Names of data items. As before, don't save it.

4.12 Finding Monetary Constants

You now look for monetary constants, and the statements and data items associated with them. Monetary constants might represent a fixed amount of money that is added to a customer's bill - for example, a handling or shipping charge. The value of a constant might change substantially if, for example, the company starts shipping very large, heavy items when it has never done so previously.

It is important to identify these monetary constants in the Data Division and the Procedure Division early. Although changing these amounts is easy, determining which need to be changed is typically done by the business analysts and not the IT department. Identifying these constants at an early stage will help the decision process, especially as this information might raise questions or issues that the business analysts had not previously contemplated.

1. Drag the working set - now called "Potential monetary data items" - onto Constants used with data items and statements.

2. Ensure that Exclude multiplication by -1 is checked and the one constant "ZERO" is shown in the list.

3. Click OK to run the tool.

   The resulting set contains 66 entries, including both statements and data items.

4. Examine the contents of the set in the context of the source code, to confirm that they genuinely involve constants in some form. To do this:

   Click the first entry in the set and click View Source Code. Then press down arrow to show the source for each set entry in turn.

   Notice that the entries are either data items defined with constant values, or statements that use those data items, or statements that contain constant values used with the data items in the "Potential monetary data items" set.

5. Name and save the new set as "Monetary constants".

6. For demonstration purposes, separate out the data items from the set "Monetary constants", by dragging the set ontoFilter set and selecting only the two Data items choices in the Worksheet tab column in the list. These two items are listed as "cobol_var" and "cobol_condition_c88".

   The resulting set contains 9 data items.

7. Close the set of data items without saving, since you don't need it. However, on other occasions you might need to separate a mixed set into its constituents, so that you can process the separate sets through further analysis tools.

8. Tidy up by closing the "Monetary constants" set and the "Potential monetary data items". You have already saved both of these.

4.13 Before Continuing

The Order project you created is used in many sessions in this book.

If you want to take a break before going on to the next session, you can close the project. Or you can close Revolve, with or without closing the project.

Return to the Tutorials Map and choose which session to go on to next.

Comments on the books?

Click Send Us Comments.

The Tutorials Start Here

Populating the Worksheet