App-Ref 1.01 - from Sable Software

by Tom Hebenstreit, Review Editor

Published 1999-05-01    Printer-friendly version

Recently, I was faced with a project where I needed to document and change a large application that I did not write. In other words, I was going into a large code base blind. In this type of situation, it is imperative that you know exactly what the ramifications of any changes you make will be, and to do that you need to know exactly how and where all of the files, fields and other variables that are declared are used throughout the application. To accomplish this, one needs some kind of cross-referencing tool, something that can take an entire application, chew it up, and then spit out the details on all of those component bits.

App-Ref 1.01, a brand new product from Sable Software, aims to fill that need. Let’s take a look.

Major Features

Here are the highlights of App-Ref, as described by Sable Software:

1. App-Ref shows you all templates used and where they are used. You can see all the templates used in a Project or all of the templates a Procedure uses.
2. App-Ref will show you where each file, key, field and global variable is used, and displays all unused files, keys, fields, globals and local variables. This will allow you to clean out unused items.
3. Will show you all calls to and from a procedure, also the files, fields and templates used by a procedure.
4. Shows you where each file/field is used in an APP procedure. Files and fields shown in RED were not found to be used. You should be able to delete them if not needed.
5. Shows Where Global Variable are used in the App files. Globals shown in RED were not found to be used
6. Displays Unused Files/Keys/Fields, Clean up your app and remove unused Files/Fields/Keys, etc.
7. Displays unused Local variables so you can remove them.
8. Summary of your app, Procedure Count, Line Count, File Count, Field Count etc, Useful to impress your client how much work you have done.

Installation

I downloaded App-Ref from the Sable Software App-Ref page (http://www.clarion.org.au/app-ref/). It is provided as a ZIP file containing six files, one of which is a readme that contains the instructions for installing the product. As instructed, I created a new folder, extracted the six files to it using WinZip, and then copied the App-Ref.tpl file to my \Clarion5\Template folder.

Now, none of this was terribly difficult, but I am of the opinion that all commercial products really should be provided as a self-installing EXE. It shouldn’t be left up to the user to have to copy files around, create menu items, create shortcuts, etc.

Implementation

Once I had the files copied to the desired locations, I registered the App-Ref templates and loaded up a medium sized C5 ABC application that is nearing completion. I chose this particular app because it uses a mixture of large SQL and TPS files, has gone through a fair number of design changes, and still has a number of ‘dead’ procedures and variables in it (old code still in the application, but not called or used). It seemed that this would be a good test of App-Ref’s ability to sniff out unused files, fields, variables and so on. (For the sake of completeness, I also tested App-Ref with a Clarion templates app.)

Continuing to follow the instructions in the readme file, I compiled the app to ensure that the CLW (Clarion source files) were all up to date. I then ran the App-Ref utility template, which created a comma delimited (CSV or Basic format) file of information about the app. To automate the process further, App-Ref also includes an optional global template that refreshes the CSV file each time you compile your app.

The last step was to close the app, open the dictionary for it and use the ‘Export Text’ option to create a TXD file.

Now that I had all of the required files (fresh CLW, TXD and the App-Ref template generated CSV file), I was finally ready to actually fire up App-Ref itself.

Performance

Still following the instructions in the readme, I started App-Ref and then clicked on the toolbar button for the ‘Project Setup, Import, Select Wizard’. This walked me through the process of assigning a name to my new App-Ref ‘project’ and specifying the locations of the CLW, TXD and CSV files that I had created earlier. Once all the information was entered, App-Ref began digesting, analyzing and cross referencing the source files. The program gave good feedback on its progress, indicating at each step what it was doing and how it was coming along. All told, I guessed it took 2-3 minutes to process my test application.

Ok, I now had my first official project loaded up into App-Ref (a ‘project’ is Sable’s term for a group of related apps and files). Using my mouse to hover over each of the toolbar buttons so that I could find out what they did, I chose to click on the last button (‘Project Summary Details’). Oops. I got an error that App-Ref was unable to open a file ("App-Ctl, Access Denied"), and was then dumped out of the program. Ah, well. Started it up again, clicked on the same button and could now view the project summary. (By the way, it informed me that it had taken exactly 3 minutes, 14 seconds to import my 18 files, 51 keys, 1,965 fields, 84 global variables, 24 procedures and so on and so forth.)

Figure 1: The App-Ref main menu and button bar

The options on the App-Ref button bar are, from left to right: "Project Setup, Select, Import Wizard", "Templates (view where templates are used)", "Procedures (view Files, Fields, Templates and Procedure Calls)", "Files (view where Files, Fields, and Keys are used)", "Keys Fields (view where Key Fields are used)", "Global Variables (view where Global variables are used)", "Local Variables (view where local variables are used)", "Button Controls (view Icons, Text, etc., on buttons)", "Reports (view Report header details)", "Windows (view Window details)", "Source View (view where File, Field and Globals are used in source)", "App Tree (view inter-app procedure calls)" and finally, "Project Summary Details". Even more options are available through the menus.

So, I proceeded to click my way across the App-Ref button bar, checking out each individual option. There was a lot of good information presented here, allowing me to view the application from almost any angle I desired. For example, it was easy to go down the list of procedures and see both who called them and who they called. Similarly, I could view where files were used, which fields where used, the line of code where the usage occurred and more. Ditto for global variables, local variables, button controls, windows and more. At most steps, I could also print out reports, with the reports offering basic filter options such as printing all, only used, only unused, etc.

For example, let’s take a look at the option to list where file fields are used, as shown below in Figure 2.

Figure 2: Viewing where file fields are used.

If you take a close look at it, you can see how much good information is shown just on this one screen. By selecting the file from the first list, then the field in the second list, I can see everywhere it was used listed on the far right. By scrolling up and down in that box, I can see the actual line of code that it was used in (displayed below the list boxes). Way cool, as the saying goes.

All in all, I must say I was impressed with the number of options and the depth which App-Ref covers.

A work in progress…

There were a number of areas where App-Ref could be improved, though, both in usability and in accuracy. A few examples:

1. My application uses a number of global queues to manipulate data as it is being processed. App-Ref didn’t seem to recognize the queue component fields as being part of the queue. To illustrate, I have a queue called SOD_Q, and one of its members is a field called ITEM_NBR that is derived from a field of the same name in a sales activity file. Within the listing of global variables, ITEM_NBR was listed as if that was the entire identifier rather than the correct, full name of SOD_Q.ITEM_NBR. The confusion manifested itself in the listing of where it thought ITEM_NBR was used, as it listed both occurrences of the actual file field (e.g., "PROJECT(SA:ITEM_NBR)") as well as the proper occurrences of the global SOD_Q.ITEM_NBR. This was not a major problem when browsing the list, as App-Ref displays the context of each use. In the reports, on the other hand, the context is not shown. This could lead to erroneous documentation of where the queue fields are actually used.
2. App-Ref did not seem to pick up local variables declared in the local data embed of a procedure. Only variables declared via the procedure properties DATA button were listed.
3. In the same manner, files which were used outside of the FILES button (e.g., were opened, used and closed in embed code) were not shown as being used. You see that in Figure 2 where it listed the files beginning with ‘x’ as not used. In actuality, they are export files that are opened, filled and closed within a ‘Source’ procedure of that application.
4. In the ABC app I tested with, the ‘used in’ procedure that was displayed was usually listed as ‘ValidateRecord’ when the item in question was actually used in a routine within the parent procedure. This was not so much of a problem in a Clarion templates application, as there aren’t all those other little procedures (the ABC methods) generated within the ‘actual’ procedure. For ABC, App-Ref seemed to just pickup the name of the last declared method (usually ValidateRecord). In any case, I’d like to see App-Ref go down to the routine level.
5. On the usability front, if you take another look at Figure 2 above, you’ll see that there are two columns in each of the first two list boxes. When I opened that window the first few times, I didn’t even know those columns were there (they were hidden off to the right, outside of the visible portion). It was only by accident that I found them, and then I had to maximize both App-Ref and the window in order to reach their column size adjusters so that I could resize them to be visible. Unfortunately, App-Ref does not store those adjustments, so I had to do the same thing each time I re-entered the procedure. It would be great if App-Ref retained column sizes between sessions (there are even freeware templates which handle this).

Documentation

Three files provide the documentation for App-Ref: The readme file mentioned above, a windows Help file, and an RTF (Rich Text Format) document which can be loaded and printed from any standard word processor.

Like App-ref itself, the docs are still pretty rough around the edges. The readme does a good job of walking you through the process of installing and creating your first App-Ref project. It also contains a few other tips for combining apps, etc. Both the RTF and help file pretty much just give rather cursory explanations of what each menu item does, with the RTF file being the more useful of the two.

The help file also contains information about how to order App-Ref, getting support and on installing App-Ref. Other than that, the help file is really sparse. For example, the help for the ‘BrowseIcons’ option in the help contents menu is, and I quote it in full: "Browse the IconName File".

The product could really benefit from an expansion of the documentation, along with the addition of a new section on the overall purpose and function of App-Ref.

Technical Support

Sable offers free email based support for App-Ref. If you are in Australia (where Sable is located), they also offer phone support, with calls being billed at $Aus3.50 per minute (I’ll take the email support, thank you very much). Response time to my email was very fast considering the time difference, and they seem dedicated to improving App-Ref as a product.

Once you get the hang of using App-Ref, my guess is that you won’t find yourself needing much support. Better docs would really help in this area as well, though.

Summary

App-Ref fills a definite need in the Clarion world, one that has been sorely lacking since the days of the old DOS Clarion Professional Developer.

When it comes to recommending App-Ref, though, I must confess to being pretty ambivalent. It shows tremendous potential, and is already very useful. On the other hand, it shows a definite lack of polish in its supporting materials such as the installation and documentation, and really needs some more work on its detection of variables and files declared and used outside of the IDE buttons, i.e., in embed code.

Bottom line, I guess, is that I would definitely recommend that you download it and try it out for yourself. When installed in its unregistered ‘demo’ mode, App-Ref will function for a full 30 days, giving you a more than adequate period of time to see if it covers your own particular needs.

I would also recommend that if you do try it, you get in touch with Sable and feed them as many problem reports, feature requests, etc., as you can. Their documentation calls App-Ref a work in progress, and, while it certainly is that, we will all benefit from helping them bring the product to its full potential.

Category	Product Score
Ability to do the task	Fair
Ease of use	Very Good
Ease of Installation	Fair
Documentation	Fair
Technical Support	Very Good
Modifies Shipping Templates	No
Black-Box DLLs/LIBs	N/A

App-Ref is available directly from Sable Software. It is priced at $Aus 185.00, with the U.S. price depending on current exchange rates (according to their web page, approximately $US 115.00). Full ordering information is available at the App-Ref web page and in the help file.

To download App-Ref or to obtain more information, visit: http://www.clarion.org.au/app-ref/

Vendor Comments from Sable Software:

App-Ref is very much a "work in progress", and is driven by user requests. We have added many features due to end user requests and will continue adding new features to allow developers to analyze and standardize their apps. Coming in the next release will be a cross project listing to show you where in ALL your projects you have used a template. App-Ref version 1.02 will be available within the next week. It will correct a number of gremlins and add a couple of new features. We are working on improving the documentation for App-Ref. SPECIAL OFFER to Clarion Online Readers When you order App-Ref and "mention in the ordering email you are a Clarion Online Reader and you read this review", we will give you a $Aus 35.00 discount of the App-Ref price. You only pay $Aus 150.00 (Approx $US 98.00) for App-Ref. This offer expires on the 30th June 1999

Printer-friendly version

Copyright © 1999-2008 by CoveComm Inc. All Rights Reserved. Reproduction in any form without the express written consent of CoveComm Inc., except as described in the subscription agreement, is prohibited.

Clarion Magazine ISSN 1718-9942