Form / Index Documentation Utility
==================================
Version 2.02
7 May 97

Readme file

0. Preface
----------

JH Doc is a great utility that I have used in various ways over the years. However, Joe last updated it for Alpha Four version 3. It did not work with versions 4 and 6, and did not include all the documentation I wanted. I have made modifications shown below in the revision history so that JH Doc can now be run from either A4v4 or A4v6. The documentation has been modified to reflect how it now works. Enjoy.

Another A4 v6 application I have written, RptList, will be a good companion to JH Doc. RptList produces a listing of all reports, forms, and browses used by each database and set in a directory. This is a much more convienient way to determine what form to print than opening each database with JH Doc to see if there is a form you want to print. It is also great documentation for your project. Both programs should be available in Library 6 of the Alpha Software section on Compuserve (GO ALPHAFORUM).

Bill Parker - Dallas Alpha User Group
73770.3240@compuserve.com

I. What is it?
--------------

Joe Holland's Documentation Utility (JH DOC) is a supplement to Alpha Four's A4DOC utility. With A4DOC, you can produce documentation for your Databases, Sets, Applications, and Scripts. JH DOC applies this same concept to your Forms and Indexes. With the release of Alpha Four Version 3.0, form documentation is included, however it is much less complete than JH DOC's form documentation.

You can produce very useful documents containing all the critical information about a Form, including a "screen shot" of each page of the form with the database and calculated fields numerically labeled in the order in which your cursor will pass through it. Then the information about each field (name, length, window, format, etc.) is listed with the matching numbers. Any calculated fields are then listed. Regions are now fully documented, including calculated and summary fields. However, the prompt order is not shown since they are always processed from left to right. The first field in the region will be listed as #1 in the field information, etc. Also see Important Issues below. If the region scrolls to the right, only the first "screen" is shown. However, all fields are listed, even if they are not shown on the "screen shot". Menu bar information is also listed.

You can also produce very useful documents containing all the critical information about all of the Indexes attached to a database, including the Description, Key Expression, Filter Expression, Create Using, and Allow options.

 

II. How do I use it?
--------------------

JH DOC is distributed as an Alpha Four Version 4.0 or later Application. Copy the JH Doc files to a directory of your choosing. The JH Doc files do not need to be loaded in the same directory as your data. Start A4 as you normally do. From the Main Menu, select the Applications option. From the Applications sub-menu, choose Run, then select JH_DOC. You are presented with a short menu. Each menu option is described in detail below. To navigate the menu, use the cursor keys to move the highlight bar, and the Enter key to select an option. Or, you can press the first letter of an option to select it.

* Choose database/set

The first thing you must do is choose the database or set you will be documenting. When you select this option, you are presented with the list of databases from which to select. You can type in the name, or select it from the list. The documentation options will act upon the database or set you select.

* Form Documentor

Starts the Form Documentor. An Option menu lets you select to have low order ASCII characters removed, as described below in Important Issues. A Screenon option, described below, will solve occasional formatting problems. The Forms menu presents you with a list of forms that are attached to the selected database. Select a Form, or press ESCape to cancel. When you select one, the form document is created. This may take a few minutes, depending on the form. Each step will be indicated on screen, but no user intervention is required. When completed, you will be asked the for output destination of the documentation. You can choose to view on screen, print, or send it to a file.

* Index Documentor

Starts the Index Documentor. Each step will be indicated on screen, but no intervention is required. When completed, you will be asked the for output destination of the documentation. You can choose to view on screen, print, or send it to a file.

* Exit to Alpha Four

This option will exit JH DOC and return you to Alpha Four's Main Menu. (Pressing ESCape will also Exit to Alpha Four.)

* Exit to DOS

This option will exit JH DOC, quit Alpha Four, and return you to DOS.

 

III. Important Issues
----------------------

* Temporary File

JH DOC creates a temporary database to store the information to report. The name of this file is _JH_DOC.DBF and some associated files. If this file already exists, it will be overwritten with the new file.

* Multi-User

Because the name of the temporary file does not change, two users running JH DOC at the same time will try to create the same file. If the both users are working in the same directory, this will produce an error.

* Printer Setup

You may need to install a printer driver that tells your printer to print the high ASCII characters (i.e. box characters) if you use them in your form.

* Curley Bracket Characters and Low Order ASCII

If the curley bracket characters ("{" and "}") are used on your form, they will be replaced with parentheses ("(" and ")"). Low order ASCII characters (0-31) cause various bad results, and are optionally changed to blank. This is an option since it takes some time, and most forms do not use these characters. I did not check the full ASCII character set. Let me know if you find other characters that cause problems. The low ASCII characters are not a problem in A4 V4.

* Formatting Problem - ScreenOn

In the list of field formatting options, there are two potential problems. When using a recursive database, if the field name extends past 20 characters, those characters are repeated for subsequent fields. If the length of a field is 3 digits, the last digit is repeated for subsequent fields that are less than 3 digits. This problem only occurs when the screen is hidden during application processing. If you notice this on your listing, re-run using the ScreenOn option.

* Calculated Fields

Only the first 244 characters of calculated fields are displayed.

* Summary Fields

On a form, summary fields can only be created from child records in a set. The summary field will be shown in the field information for the main form, but its deffinition will be shown with the region from which it was created. Since I tend not to use summary fields, I have not tested the documenting of forms with more summary fields than can fit onto one screen. Also, something is wrong with you if you try to do it!

* Field and Prompt Order Representation

The prompt order notation, e.g. [1], requires at least 3 spaces. If there is less room between fields, one of the prompt order notations will be overwritten. You may notice that the bolcks used to represent fields are not exactly the same as those you see when looking at a form in edit mode. Version 6 required that this character be changed for reporting.

* Region Screen Shot

Be aware that if you save a form when a region has been scrolled to the right, and the leftmost fields are not visible, that is the way it will display when you view it. That is also the way that JH Doc will print it. If this happens, the field list will not appear to match with the fields in the region. The field list will correctly show all fields from leftmost to rightmost.

* Alpha Four Version Compatibility

JH DOC is now compatible w/ A4 versions 4 and 6. The program runs much faster in version 4 . Version 6 requires extra processing to translate characters that are interpreted differently, e.g. the field marker character.

* Beeps

It is normal to hear a few low beeps while the form documentor is running. High pitched beeps are caused when a field prompt order marker writes past the end of the page. (The prompt marker can be wider than the field itself.) This should not be a problem.

 

IV. Contacting the Author
-------------------------

As you probably already know (how could you miss it!), the author of this program is Joe Holland, an A4 hacker. If you have comments, questions, suggestions, or even (gasp) bugs, you may contact him by leaving a message on the Alpha Software BBS.

I am not sure where Joe is now, and the Alpha BBS is no longer operational. But since I have re-written most of the program, and added a substantial amount, you can reach me through the Compuserve address for Bill Parker, ParTec Database Systems, shown above.

 

 

V. Legal Stuff
--------------

* License Agreement

JH DOC is FREEWARE. It may be freely distributed and used by individuals and corporations without charge. It may not, however, be sold or distributed for a price (other than user group diskette duplication and distribution fees.) At all times, the copyright and title for JH DOC remain with Joe Holland and Holland Software Solutions. It must be distributed as a whole, including this accompanying documentation. You are licensed to use this program only for the purpose of generating the documentation output. Reverse engineering of the script library is strictly prohibited. Oops, sorry Joe! I had to take some liberties to get it to work.

* Disclaimer

This software is provided on an as-is basis. If you choose to use it, you do so at your own risk. Neither the author nor Holland Software Solutions offers any warranty or guarantee of any kind, nor do they (individually or together) accept any liability for any consequences of the use of this software, including, but not limited to data, form, and index loss or damage.

Also, we are not responsible for anything that happens, including tornadoes, hurricanes, floods, and other natural disasters. So there.

 

* Copyrights

Joe Holland's Documentation Utility and JH DOC are copyrights of Holland Software Solutions.

Alpha Four is a copyright of Alpha Software Corporation.

 

V. Revision History
-------------------

2.02 7 May 97 Handle situation when a region starts on line 1 of last page.

2.01 27 Feb 97 Add A4 v6 compatibility to index reports. Upgrade form reports for both versions 4 and 6 using "version awareness". Change report formats to show database reference and date produced. The last database opened will now remain as the default database. Allow dBase IV compatibility. Show 244 characters of calculated field expression. Show menu bar type, with 254 characters of dynamic expression. Add region information including calculated and summary fields.

2.00 25 Jul 94 Revise index reports to read screen formats in A4 v 4.0. Add "Create using" index option, and change report formats. Make the system "version aware" so it can run with multiple versions of Alpha 4.

1.02 7 Sep 93 Fixed problem documenting 3.0 forms with less than 20 fields Now Requires A4 2.1 or later

1.01 12 Jun 93 Added A4 V 3.0 compatibility

1.0 18 May 93 The First!