The A5 Doc Lister is used in conjunction with the A5 Doc program created by Bill Parker of Partec Database Systems. You must have a registered version of the A5 Doc program and your database must be documented before the Lister can be used.
Note: Until registered, the reports generated will be limited to approximately 40 lines.
What Lister does
The Lister runs a text search on existing A5 Doc output to locate references to specific layouts, scripts, functions, or any other text string that you enter and shows the output in WordPad. This sounds pretty simple but the important part is that the output can then be used as a powerful tool to help a developer debug or update an application.
Because of the type of information needed for debugging or updating, we recommend that all field rules, all layouts, and all three script types - global scripts, layout event scripts, and field rule event scripts - are documented prior to running the Lister. Printing the documentation results is not necessary in order to use the Lister.
Note: Documenting layouts only helps to locate user defined global functions (UDFs) that might be used in calculated fields, filters, or other expressions. If you don't use any UDFs in calculated fields, filters, or other expressions, this part can be skipped.
Advantages
Although text searches can already be done within A5 Doc itself, the Lister provides the following advantages:
It can locate references to ALL forms, reports, scripts, functions, etc. with one operation rather than manually running, for example, 150 different searches for 150 different report names.
It provides optional printed output. (Even some clients - those with knowledge of A5 - have found this useful.)
It automatically provides a list of all layout/script names so you don't need to remember the exact spelling in order to list a specific one.
It identifies layouts, saved operations, and scripts that are not found as: ***Not Referenced*** This makes it easier to determine which ones can be deleted. Just remember that certain things like the autoexec script, the run-on-load form, and any 'developer only' scripts/functions may not be referenced but should not be deleted.
It will warn you of duplicate layout, script, or saved operation names which could cause program errors.
The output opens in a separate window making it easier to switch back and forth while editing or debugging your application.
Using Lister
When updating an application, it is important to know where each layout, script, etc. is referenced in order to be sure that all affected areas have been appropriately handled. Without some simple means of determining where each item is referenced, there is a very good chance that something will be overlooked and the customer (internal or external) will end up frustrated and angry because something is still not working correctly. Although using the Lister can't guarantee the update will be right the first time, it can certainly improve the odds.
The Lister can also be used as a great 'cleanup' tool on new or updated databases. By running a listing on all layouts, scripts, and functions, you can quickly determine which ones are still being used and which ones can now be deleted. Just remember that certain things like the Autoexec script, the run-on-load form, and some 'used by developer only' items may not be referenced anywhere in the documentation.
Shows Layout Errors
This item is really something that A5 Doc does but it's important to mention here because of its relation to debugging applications. Running A5 Doc will locate errors on forms because running A5Doc's 'Scripts/Layout Events' documentation will open each form and a message will be displayed when any errors are found. This is generally much faster than opening each one yourself! When an error message is displayed, the layout name will appear in the status bar at the lower left corner of your screen. (Of course, the status bar must be turned on in order to see it.)
Shows Duplicate Names
Duplicate names can cause program errors because A5 will try to open/run the first one it finds even though the programmer may have intended to use the second 'copy'. Form names and Saved Operation names can be duplicated by using the same name in a different table or set. Scripts can be duplicated if there is an attached library file. Running the lister will show duplicate layout, script, and saved operation names.
There is no check for duplicate index names because (a) indexes are only listed one table at a time and A5 does not allow duplicate index names in one table, and (b) using the same index name for two different tables will not cause any program errors.
Naming Issues
After using the A5 Doc Lister awhile you will begin to understand the need for a good naming convention so your searches will be more precise. Searches for layout names like Rep, Show, About, Users, Input, Menu, etc. usually result in more invalid hits than valid hits. Your searches will be much more accurate if you follow these primary rules:
Always use at least 2 words in every object name because it makes them more unique.
Never use spaces in object names - use underscores instead because it makes them more unique.
(I hope you're beginning to notice a pattern here.)
Example: 'User_List' instead of 'Users'
In addition, making names of fields, indexes, and variables unique will also improve the search accuracy. This means that a field and an index or variable should not have the same name. One easy way to accomplish this is to end all field names with 'f', all indexes with an underscore, and matching variable names with a 'v'. Using this method, the same basic name can be used for fields, indexes, and variables while still keeping them unique. For example, the index for the 'Last_Namef' field would be 'Last_Name_' and 'Last_Namev' would be used for a matching variable name.
Of course, this system isn't perfect and some duplication is inevitable but using this system or something like it will significantly improve the accuracy of your searches and result in a time savings when debugging or cleaning up an application.
Please note that these naming recommendations are to improve search accuracy and have nothing to do with what is allowed in A5.
For more information and explanation about naming conventions, see A5 Naming Practices
AIMS DataCom, Inc. - Custom Database Applications
This site created and maintained by Cal Locklin, CALocklin@chartermi.net, using 1st Page 2000.
Last update: 07-Dec-03
This site may be freely linked to but not duplicated in any fashion without prior written consent.