ROFM CGI Miscellaneous

ROFM CGI Miscellaneous Topics

Contents
Introduction
Set Up
Use
Special Characters
Misc: History; Source Code; Acknowledgements; Legal Stuff

History

4.3B No changes to the CGI. Documentation was changed to reflect new home site link. The scripts ROFMCGIMain and ROFMUtil were updated to reflect the new location of scripting additions in Mac OS 8.1 (a change only of interest to people messing with the source code or using these scripts for their own purposes). August 12, 1998. Also a few minor corrections to the documentation 10/1/98 with no change in version number.
4.3 Extensive changes to email that require modifying all existing forms that send email: (1) added _emailSubject; (2) renamed _emailToPtr to _emailTo; (3) eliminated the old _emailTo functionality (email addresses now must be stored in the database); (4) renamed _emailField to _emailBody; (5) you may now email records retrieved via Get. Added limited support for relational data using the new parameter _layout. Added a menu item to open the log window. August 17, 1997.
4.2 Modified to support modern Mac WWW servers such as WebSTAR 2.0 (thanks to François Matte for the fix). Added compatibility with the Lynx text-based browser. Added the ability to run different copies of ROFM CGI, each with its own preferences file. Please read the Security section of the manual for information on how to use this feature. The package now includes GTQLib, for the convenience of those messing with source code (this version also uses a few new OSAXen from GTQLib). Moved SearchInstr.html up one level so it is easier to access from your own forms. All operations now have a default footer (previous GET and MODIFY did not). Fixed a few places where & was being used to separate arguments (instead of &). March 10, 1997.
4.1-B The manual was updated to say that System 7.5 is required to run ROFM CGI 4.1. Also an error in the sample form "bbFindToEdit.html" was fixed; it was a bogus hybrid between FIND and FINDLINKS. (Thanks to Robert at the UT Career Development and Resource Center for spotting the bbFindToEdit.html error). July 8, 1996
4.1 Preferences are now saved in a preferences file (thanks to François Matte for showing me how). Added ISO Latin 1 translation for special characters (directly copying François Matte's work in his French adaptation ROFMfr). Note that ISO Latin 1 does not handle all characters, and not all browsers support it well, but it is much better than nothing. The user interface has been refined (much of this courtesy of François). Graphics for the new splash screen are by François. Added the GetVersion action. Corrected a documentation error that suggested using & as an argument separator after the "?"; & should always be encoded as &. Added introductory text to the "Use" section, based on a tutorial by Nancy J. Kelly. I now ask that users include mention of ROFM CGI somewhere appropriate on their site. May 13, 1996
4.0 New actions for modifying and deleting records. Search results are now returned on multiple pages if too many records are found for one page; as a result, the special strings for custom headers and footers have changed significantly. The reserved field names _username and _password are now set from the Add form (not automatically as in 3.4), and are read for Modify and Delete. Fields whose names begin with underscore (_) cannot be read, i.e. for _field, _emailField, etc. (yes this is finally for real). Added the parameter _skipRecords. FindLinks bogs down less when many records are found (but further improvement is possible). Now uses $ instead of ? for URL-based commands, so it is not fully compatible with MacHTTP. Thanks to Mark S. Strom and Espen S. Ore for help debugging and François Matte for the French version with ISO-latin translation. Mar 7, 1996
3.4 The first version to support (and require) FileMaker Pro 3.0. Allows default setting of values while adding, and Add works with databases containing sounds and images (though these cannot be added). Thanks to Davide Monge (and somebody else whose name I've lost) for reporting the sound/image problem. Many enhancements to sorting: reverse-order sorting is supported, sorting works on numeric fields (I forget who first reported that problem) and the entire found set is sorted before data is returned. Fixed a lie in the documentation claiming that a "_" prefix prevented a field from being read (but that feature will come in a later version). Jan 18, 1996.
3.3-B Fixed an error in the documentation that claimed that certain fields in your database can be hidden from access by ROFM CGI. This was false; the only built-in security is that discussed under Security. Jan 18, 1996
3.3 Now has reserved database fields "client_address", "referer", "_username" and "_password", which are automatically set (if present) during Add. Added the parameter _emailToPtr, which sends email to addresses listed in the database. Now handles multi-select lists correctly, at the cost that multiple iterations of a repeating field can no longer be set. Added import of settings from recent older versions. Changed "Read" security item to "Find" so that newly added records may be read. Rearranged menus. (Thanks to Kevin Chval for help with referer.) 12/26/95
3.2 ROFM.acgi is now a FaceSpan project. As a result, multiple requests are now properly queued (thanks to Eric Bickford for noticing this capability). Security and custom headers and footers are now defined within ROFM.acgi. Record prefixes are now ignored by Find and only work with FindLinks. There were no code changes from 3.2b3 and 3.2b3.2. 11/7/95
3.1 Adding records is much faster. The trade-off is that defaults are handled much more poorly (read about Add for more info). Sorting is faster and now works with FindLinks as well as Find; also, sorting does not bring FileMaker to the front. R.O. 9/20/95
3.0 Added sorting via _sortField (it's slow, and only works with Find, but it's a start). Add the security file "ROFM Databases" (thanks to Jeff Clough and Don Napoli for getting me to think about a better security system). Now sends email as well as queuing it. Many speed-ups. Renamed the CGI from FileMaker.acgi to ROFM.acgi. Modified to use ACME Script Widgets 2.5 and ACME parse args. Parameter name parsing is no longer case sensitive. Modified to handle the CERN proxy problem. Almost all of the parameter fields have changed. R.O. 9/1/95
2.4.1 Only the documentation changed! "Join List" was missing from the list of extensions in the installation instructions (thanks to Jim Fowler for the report). R.O. 7/6/95
2.4 Added parameters: _header, _footer and _recSeparator, prompted in part by Ken Tidwell's demonstration of the use of tables. Includes a new form "bbFindTableOfLinks.html" and a new version of the sample database "bb.db" that show a different use of tables. Modified the syntax for the action Get. Now all actions can be implemented using the POST method (forms) or Get method (encoding the parameters in the URL). (Thanks to Jeff Clough for prompting me to finally do this). Now reports the amount of time spent parsing the input (in addition to other timings). Added the parameter "_recID". Modified to use the extension "Replace" (from the first release of ACME Script Widgets), instead of "DePlus osax". 7/5/95
2.3.1 fixed a nasty bug (reported by Marco Pagliano) in Add that could result in writing data to the wrong database, corrupting existing records. R.O. 5/25/95
2.3 changed Add email to send a formatted record rather than a URL, and so added the _emailLayoutName field. Changed Add to only set fields that aren't left blank. R.O. 5/24/95
2.2 Add forms can email a link to the new record (see field _emailTo). The search instructions are much more comprehensive and are now on a separate page (which you are welcome to use or modify). Some code clean-ups -- getting lists from FMPro is nicer. R.O. 5/22/95
2.1.1 Only the documentation changed. The documentation included some bad links and incorrectly listed _linkLayoutName as _ptrLayoutName (thanks to Sam DeVore for pointing this out). R.O. 5/12/95
2.1 Removed auto-loading of database files (and hence the need to configure the CGI!). Make sure the databases are open before serving them. Removed excess restrictions on database and layout names added in 2.0. Better documented some genuine restrictions in field names. Major bug fixes to error handling (it was pretty broken), which also simplified the code. Added performance feedback to help you optimize your forms and databases. Removed the use of clientAddress by Add forms. R.O. 5/11/95
2.0 Finally added FindLinks and Get support. As a result, the CGI now requires a new scripting addition: Encode URL. Also, the CGI now quits to save changes after being configured (fixing a problem reported by Douglas Wyatt). R.O. 5/8/95
1.4 Added special handling of layouts with only one field in them: returns the data "raw", allowing custom formatting (you'll also get higher performance). Smarter handling of searches; if a user only fills one data field on a Find form the search should go significantly faster (for large databases). Searches with only a few fields filled in may also go more quickly. Also fixed a bug discovered by Gerry Paille that could cause the wrong database to be searched (I still wasn't referencing the database by name while retrieving records during a search). Finally, I had not removed "Show All Records" in 1.3.1, despite claims to the contrary, but have done so now in this version. R.O. 5/95
1.3.1 Minor change: removed Show All Records, which one user (whose name I've lost) claims speeds it up a bit on large databases. I've tested this change extensively but still worry I've missed something. If your searches start missing some records, please let me know. R.O. 3/23/95
1.3 Fixed a bug discovered by Lee Riggs: if a layout had only one record the returned page was screwed up. Also, the configuration application handles errors better and does most of the configuration work itself; this should make it less confusing to use, though still not wonderful. R.O. 3/11/95
1.2.2 Documentation changed to an HTML file. R.O. 3/3/95
1.2.1 Added code to check for the required scripting extensions. R.O. 3/3/95
1.2 Added user-settable limit on # of records returned; handles large #s of records much better. Fixed a bug involving multiple databases (I forgot the "of document databaseName" in two places). R.O. 3/2/95
1.1 Added named layout support, for limiting which fields are shown in replies. R.O. 3/1/95
1.0.4 Made a separate application to configure the CGI, so there is no need to edit the script to configure it. Removed the maintainer's name and email address from the CGI's error feedback page, making the CGI easier to configure. R.O. 3/1/95
1.0.3 Removed the auto-quit code; I could not see how to make it reliable. R.O. 3/1/95
1.0.2 Moved the documentation into a separate file. Now supports returns in text areas (the problem was display, not data entry). Now Add reads and returns the record added, giving more info and greater assurance the add worked. Increased the application size to fix an annoyance added in 1.0.1: a complaint when quitting. R.O. 2/28/95
1.0.1 Fixed a bug in the sample database (clientAddress was of type Number, preventing searches on it). R.O. 2/27/95
1.0 Released. Russell Owen, 2/27/95

Source Code

ROFM.acgi is a FaceSpan project written in AppleScript. You must have FaceSpan 2.1 (a commercial scripting development environment) to edit ROFM.acgi. To edit ROFM.acgi simply drag and drop it onto FaceSpan. FaceSpan is available from Digital Technology International. A free demo version is available that may be sufficient for personal modifications to ROFM CGI; the primary limitation to the demo is that you may not distribute software created using it.

Before changing ROFM.acgi you must first install various items in ROFM CGI's "Scripting Additions" folder, including several from the GTQ archive. Read the file " Read Me (Scripting Additions)" in that folder for details. These items must be installed to compile ROFM.acgi, ROFMUtil or ROFMCGIMain, but are not required after compilation.

ROFMUtil is a "compiled script" that contains all the code that ROFM CGI uses to communicate with FileMaker Pro. These routines are intended to be quite general and reusable. Hence you may find them useful for your own scripts. Also, the routines are optimized and work around many of the quirks in FileMaker's Apple Event support. The primary documentation for ROFMUtil is the comments in the source code (each subroutine includes an explanatory header).

To read the ROFMUtil source code, simply double-click the file to open it in Script Editor. If the file fails to open, no matter what the error message is, please try increasing the memory partition for Script Editor. For your protection, please only edit a copy.

Please do not modify ROFMUtil unless you know what you are doing. FileMaker Pro Apple Event support is rather weird and tricky (though much less so in FileMaker Pro 3 than in 2.1v3). Don't change anything unless you are willing to verify that it works, and don't use modified code with ROFM.acgi unless you are fully understand the interface. Some warnings for bold coders:

ROFMUtil will not recompile unless you delete the word "transaction" wherever "end transaction" appears. This is an idiocy in Script Editor, and is commented in the source code. The compiler will jump to the offending line(s) if you explicitly recompile (but not if you just try to save, which automatically recompiles but gives no useful feedback if the compilation fails).
ROFM.acgi loads ROFMUtil when ROFM.acgi is compiled. So if you change ROFMUtil you must then recompile ROFM.acgi to use the changes. Similarly, to compile ROFM.acgi you must have ROFMUtil in the Scripting Additions folder.

ROFMCGIMain is a "compiled script" that contains the CGI-level subroutines which perform the various actions, once ROFM.acgi has received and parsed the event. It may be of interest to CGI scripters, but probably nobody else. The procedure for reading and modifying the code are the same as those for ROFMUtil (see above).

Acknowledgements

François Matte has made major contributions to ROFM CGI by implementing ISO-Latin translation, developing the initial preferences file code, many other user interface enhancements, supplying the graphics for the about box, and creating ROFMfr, a French adaptation, available from the ROFM CGI home site.

Many people wrote scripting additions that are used by ROFM CGI. These handy software components add capabilities, greatly increase speed, or simplify code. Except for ACME Script Widgets, these utilities are all included with ROFM CGI in the Scripting Additions folder.

Wayne Walrath wrote ACME Script Widgets 2.5. These perform a host of useful tasks, and ROFM CGI owes its good performance to them.
Motoyuki Tanaka wrote the ISO-Latin translation code, part of a set of scripting additions, which also include Japanese character translators, available free from his server and from ScriptWeb. (If anyone wishes to develop a Japanese version of ROFM CGI, these scripting additions may be just what you need.)
Gregory T. Quinn wrote several osaxen used for handling the preferences file. These are part of his fine GTQ Script Library, included with this package (in Scripting Additions).
Chuck Shotton wrote Encode URL, a free osax that performs basic hex encoding. Chuck also wrote a basic FileMaker Pro CGI which was the starting point for ROFM CGI.

Thanks to Jon Weiderspan for writing the fine CGI shell and tutorials that helped get me started, to Eric Bickford for early help with scripting FileMaker Pro, to Jon Pugh for many excellent tips posted to the MacScrpt mailing list, to John Baxter for lots of help in an attempted conversion of this script to Frontier, and to Claris for greatly improving its apple event support in 3.0 (though it still has a ways to go). Last but not least, thanks to the many users who have suggested improvements, reported problems, and generally been supportive. You have made working on this CGI very rewarding.

Legal Stuff

This software is not guaranteed in any way. I have attempted to make it robust and useful, but make no promises as to the results. You use this software entirely at your own risk.

Copyright © 1995, 1996, 1997 by Russell E Owen. All rights reserved, except that you may use ROFM CGI without charge. All I ask is that if you use ROFM CGI, please include mention of it on your server.

If you wish to distribute this software, please make arrangements with me. At the minimum I will ask for assurances that you will keep your distribution current and will not charge for distribution.