Review
	Reviewed by Carson Cooman

  I really love Clarion for Windows! I sing its praises to anyone who will listen. However, one issue that I always avoided was Clarion’s ability to add to or modify existing databases. When my friends were using other products that were able to add fields "on the fly" to already existing databases, I hated to tell them that Clarion suggested one of two very unsatisfactory solutions:

1. Force each end-user to purchase a copy of Clarion and each time a database changed, run the built-in Clarion function to compare dictionaries with databases and make the conversion. This is expensive and extremely unrealistic especially for low-cost or shareware applications.
2. For each change to each file, create a special Clarion compiled application using the provided function and then distribute the plethora of EXEs to all end-users. Of course, these all need to be run in the proper order on the datafiles.

In the days of Clarion for DOS, the Filer (CFIL) utility existed which allowed developers to distribute new file definitions to end-users and then run the Filer to upgrade the data. This was easier but it still was not automatic. I wanted a tool that would automatically sense the changes and would upgrade the files accordingly. I wanted a tool that would upgrade my user to the most current version whether they were running a copy that was five versions old or only one version old.

CapeSoft’s File Manager 2 (FM2) is a tool which fit this bill.

File Manager 2 Features

FM2 provides automatic file upgrading and data conversion for datafiles. The product supports TopSpeed, Clarion [file downgrading supported as well as upgrading], and Btrieve datafiles. FM2 does not currently support BLOBs or dimensioned/groups. FM2 automatically upgrades user datafiles to match the file definitions in the compiled Clarion application. This feature is called AutoUP. As part of this conversion process, it will:

• Add, change, or delete fields
• Rename fields and have the data moved from the old field to the new field
• Add, change, or delete keys and indexes
• Add a password/owner to a file (or change an already existing password/owner)
• For new fields, set an initial default value
• Add auto-increment fields and fill them with the proper values accordingly
• Change the file driver among the supported types

FM2 also provides other helpful features such as:

• AutoFIX (a function that automatically detects errors in TopSpeed datafiles and uses TPSFIX to automatically fix them)
• AutoNET (a function that automatically upgrades programs and DLLs on local drives of computers connected to a network server)
• AutoBUILD (a function that adds a procedure to your application that allows an end-user or technical support representative to view file statistics and perform functions such as lock releasing and index rebuilding.)
• C-SCAN (a Windows version of the old Clarion or DOS Scanner (CSCN) utility. It allows browsing and direct modifications of datafiles in applications that use FM2 using a clean browser interface. This utility can be distributed to end-users royalty-free with your application.)
• International Language Support (ability to change all messages and prompts within FM2 into whatever language you choose.)
• VLDS [Very Large Dictionary Support] (ability to overcome ISL errors when compiling applications with very large dictionaries; also works with DET’s VBD function.)
• DLL Support (ability to include FM2 into an application with multiple DLLs.)
• DET Support (support for The Moseley Group’s DET product with a checkbox option; all other known Clarion add-ons work without any additional features)

Installing File Manager 2

Installation of FM2 was very smooth. The product is shipped as a single EXE file that is an automatic installation program. The installation program installed the necessary program files, placing templates, DLLs, and LIBs in their proper directories and created Start Menu/Program Manager icons for the documentation. Both 16-bit and 32-bit DLLs and LIBs were installed for Clarion 2.x.

Like most Clarion add-on products, it did not provide a function to automatically register the template in the Clarion template registry. However, there is only a single template chain to register (FM2.TPL) and thus it is simple enough to manually register it.

Implementing File Manager 2

FM2 was wonderfully easy to implement. I decided that I would implement FM2 in the sample school management application (SCHOOL.APP) that shipped with Clarion for Windows.

First, I added the global extension template, "ActivateFileManager" to the application. This is the only necessary template in the entire product. Because the application uses TopSpeed files, I check the box for TPS. I also decided to use AutoFIX which will automatically use TPSFIX when necessary on damaged TopSpeed files.

Figure 1: The ActivateFileManager extension template

After adding the extension template to my application, the only other thing that I needed to do was add a version identifier to each file in my dictionary. To do this, you simply add "Version(1)" to the options tab on the file properties in the dictionary editor.

[Review Editors Note: According to CapeSoft, FM2 automatically defaults to a "Version(0)" so all that is required initially is to add the Global Extension. Version identifiers are only needed after a file definition is changed.]

Figure 2: Options Tab on File Properties Screen

This version identifier tells FM2 which version the definition in the dictionary is. When you make a change to the dictionary definition, you simply increment the version number for the affected file. For example, you change it from "Version(1)" to "Version(2)" when the file changes. [Note: For ALIASes, there is no need to set a version identifier; they use the version identifier from the main file.]

This is all that needs to be done to implement the automatic file upgrading features in FM2. I then compiled the application to see how it would run.

Using (or Watching) File Manager 2

The first time I ran the application, nothing unusual happened because the files had not changed. However, I decided that I would add a field to the database. I went to the dictionary and added a field for "FavoriteColor" to the "Student" database table. I then changed the version identifier for the "Student" table to be "Version(2)" and then added the field to the "UpdateStudents" screen in the application itself.

When I compiled and ran the application, the first time in the application that the "Student" table was opened, a small progress dialog appeared and moved a progress bar showing me the status as the file upgrade operation. When it had completed, the file now had the additional field added to it and it was as if it had always been there!

I then tried deleting the field and the field was removed from the database in the subsequent run of the program. I also tried adding the field back and changing the datatype of the field from STRING to ULONG. It did its best to convert between datatypes with some success. Those that were numbers converted as numbers and going the other way was much better as all numbers can be converted into strings.

The AutoFIX function worked very well. I manually damaged the file with a hex editor and AutoFIX detected it and ran TPSFIX to repair the file.

I also tested the AutoNET feature that automatically upgrades local program files (EXE and DLL) from a single network application. I placed my application EXE on the network server and used the INI file settings as described in the documentation to tell it where the local program was stored. When I placed a new EXE up on the network with new file definitions, AutoNET automatically upgraded the local program.

The AutoBUILD feature is also a very useful function. I simply added a procedure template, "RuntimeFileManager," to my application and then called it from my main application frame. No coding was needed to add automatic index building, file packing, and lock releasing.

FM2 also does an excellent job upgrading files that are older than one version. I saved a set of "Version(1)" datafiles and then restored them to a directory that contained a "Version(4)" EXE. FM2 handled this perfectly and made sure that the old datafiles were upgraded completely to "Version(4)." [AutoNET also supports local datafiles that are from different application versions.]

The C-SCAN utility is also a long-awaited tool that is very useful. I was able to use C-SCAN to browse the data in the datafiles for the school application. It allows me to view file statistics, perform file operations [release, lock, rebuild indices], and add/delete/change records. This is a wonderful utility for technical support representatives to have available on site for the client.

Distributing an Application

After you have added FM2 to your application, distribution is very easy. FM2 only requires that one small DLL (for either 16 or 32-bit) be distributed with your application EXE.

Also, FM2 performs its wizardry through the use of a file called UPG.TPS that it creates in the directory with the datafiles on the end-user’s machine. This file is an encrypted TopSpeed file that FM2 uses to store information about your datafiles. FM2 cannot work without this file. FM2 provides means, by either INI files or an internal function, to tell FM2 where this file is located in the event that you wish to place it in a different location.

FM2 also has a feature that allows you to add upgrading to your application even if the original version did not have FM2 included. For example, if you have already released Version 1.0 of your application and you are now getting ready to release Version 1.1, you are able to include FM2 in Version 1.1 and, by following a procedure outlined carefully in the documentation, you will be able to automatically upgrade the datafiles of the Version 1.0 users.

Documentation

FM2 ships its documentation as a single HTML file. The installation program installs an icon for it and it can be viewed easily using either Netscape Navigator or Microsoft Internet Explorer. It does not use any fancy HTML elements and is very clean in both browsers. Because it is provided as an HTML file and not as a Windows help file, it is very easy to print, and create a nice looking printed manual.

The documentation is very well written and describes all functions in the program clearly. Because the software was so easy to use, I rarely needed to refer to the documentation after initially reading through the sections on implementation.

The documentation includes a table of contents that provides HTML links to the various sections. The sections include information about each feature in the program as well as topics such as contacting technical support.

Technical Support

CapeSoft provided excellent technical support for FM2 by e-mail. When I had some initial trouble obtaining the product, they were quick to respond, and provided a satisfactory solution to problems. They offer phone and fax support but I found that e-mail support was more than adequate, especially because of how easy it was to implement and use the product.

Conclusion

Overall, FM2 is an excellent product. It provides a very easy-to-use solution to a major Clarion problem and even includes some welcome unexpected extras such as C-SCAN. The product does its job very well and it is very hard to find shortcomings in the product.

The only shortcoming that I can find about the product is its price tag. At $199 US, it is a major purchase for any small developer. However, the product saves any developer an incredible amount of time and headaches so, for many developers, it may be considered well worth it.

Currently, CapeSoft has available a version for Clarion 2.x as well as a version for the 2003 template set of Clarion 4. CapeSoft states that once Clarion 4 has been officially released, they will release a version for the ABC/OOP templates.

One of the best things about CapeSoft’s products is that they provide a complete 16-bit trial version of the product for free. A complete, fully functional (limited to 15 fields) 16-bit trial version of FM2 is available from CapeSoft’s website at http://www.capesoft.com. The full product is fully compatible with this trial version and is available from CapeSoft directly or through TopSpeed Accessories.