Russell Owen's FileMaker CGI

Version 3.0, 9/1/95
By Russell Owen

Warning: if you are upgrading, please follow the upgrade instructions carefully. Please save your old forms and scripting additions, in case you decide to revert!

Contents

Introduction
Set Up
Installation
Upgrading
Use
Serving Your Own Database
Parameter Fields
Tips and Known Limitations
Troubleshooting
Security
Support
Misc
Source Code
History
Disclaimer
Acknowledgements
Legal Stuff

Introduction

ROFM CGI is an application that allows you to serve FileMaker Pro databases to the World Wide Web (WWW). It is easy to set up and use. It runs on Macintosh computers (only), and requires WebSTAR or MacHTTP, Filemaker Pro 2.1v3 and AppleScript 1.1 (which comes with system 7.5). To email notification of new records, you will also need Eudora 1.5 (free) or 2.1 (commercial).

The home site of ROFM CGI is http://rowen.astro.washington.edu/. The full package includes:

Installation

  1. Install the following Scripting Addition files, then reboot: To install, drag the specified files (not their folders) into the Scripting Additions folder (in the Extensions folder in your System Folder) and then reboot.

    "ACME parse args" and "ACME Script Widgets 2.5" are files in Wayne Walrath's ACME Script Widgets 2.5 package (also available via ftp from gaea). This package is shareware. When you register (with the author, Wayne Walrath, not with me!), please mention that you are using ROFM CGI. I twisted his arm pretty hard to make the parser public (so I could use it in this CGI), and I'd like him to think it was a good decision.

  2. Put "ROFM Databases" in the Preferences folder (in your System Folder).
  3. Upgrade your FileMaker Pro to 2.1v3. An updater that works on both 2.0 and 2.1 versions is available from my site. Older versions will probably fail mysteriously.
  4. Run ROFM.acgi. It should always be running before you try to serve data because it is slow to start up and may miss the first request if it is not already running.

    The first time you run the CGI it may ask you to locate "FileMaker Pro 2.1v3" and/or "Eudora". Your applications need not have exactly the same names, and Eudora can be version 1.5.x or version 2.x (regardless of what the CGI actually asks for). If you don't have Eudora and you are sure you do not wish to email newly added records, then you can supply any application instead of Eudora. (If you later change your mind, install a fresh copy of the CGI).

    Note that ROFM.acgi tests the scripting extensions (except ROFMUtil) when it starts up, and will report an error if any are broken or corrupted. Fix any problems before you go on!

  5. If ROFM.acgi asked you where applications are, you should now quit it, so it remembers the information for next time. You will need some patience because it takes about 15 seconds to quit. Then run it again.
  6. Organize your files. The forms and CGI should stay together in the same folder -- one that WebSTAR can access. The database "bb.db" can go anywhere. (If you want more flexibility in placing the CGI, you may include directory information in the form when you specify "ROFM.acgi", or use an alias to the CGI.)
  7. Open the sample database "bb.db" by double-clicking it. Your database(s) must always be open before you can serve them.
  8. Try it out! Run a WWW browser and open one of the supplied forms, such as "bbFindLinks.html", using an http:// style URL (so that WebSTAR serves them). Don't open forms as text files in your browser! WebSTAR must serve forms for them to do anything useful.

Upgrading

If you are upgrading from any pre-release version of ROFM CGI, you may need to make the following changes:

If you are upgrading from FileMaker Pro CGI version 2.4.1 or earlier, please follow these instructions carefully. For each form, make the following changes:

Serving Your Own Database

Figure out what you want to do

The CGI supports the following actions: For more information about these, read about the parameter _action.

Prepare Your Database

Every field you want to access via the CGI must obey certain rules:

Create calculation fields to format the returned data. These can include HTML tags, including pointers to images, pointers to other documents, even URLs that access this (or any other) CGI.

Edit "ROFM Databases"

You must add the name of your database to the file "ROFM Databases". This is a text file in the Preferences folder in your System Folder. It lists every database that this CGI is allowed to serve, and whether or not the user is allowed to add records. Type the name of your database on a new line, and append "=A" if you wish users to be able to add records (instead of just retrieve data). For example:
bb.db=A
aReadOnlyDatabase.fm
aWritableDatabase.fm=A

Note that "ROFM Databases" is only read when the CGI starts up. If you edit the file you must restart ROFM CGI to load the changes.

Create The Forms

Set up at least one form per action, using the samples as templates. The form is a standard HTML document that also contains various fields, including:

If you mis-spell the name of a database field, or include one that does not exist in the database, you will get erratic behavior. Blank fields are ignored by the CGI, so you will only trigger the problem when the mis-named field is actually filled in. And although ADD detects and reports such errors, FIND and FINDLINKS just find zero records, with no explanation (due to poor error handling in FileMaker Pro).

Such problems can be very frustrating and hard to detect. So please always test your forms carefully, filling in every single field. If you can ADD without error or FIND at least one record, with all fields filled in, only then can you be sure that the database field names on the form are spelled correctly.

If you wish to use URLs instead of forms to implement actions, you can easily do this. Format the URL as follows:

    <a href= "/ROFM.acgi?fieldName1=data1&fieldName2=data2...">text of link here</a>
Use this format to supply data for every field (except "Submit" and "Reset") that would be on the corresponding form, including both database and parameter fields. For an example, examine the links returned by FINDLINKS.

Parameter Fields

Parameter fields are special fields in a form used to pass data to the CGI, rather than to the database. Every parameter field's name starts with underscore (_), and in fact any field whose name starts with underscore is assumed to be a parameter field. Many of these fields are optional, and some are relevant only for certain kinds of forms (and are ignored if present on other forms). The parameter fields are as follows:

Hex Encoding of Special Characters.

Data that the user enters into a form is automatically encoded, so you don't need to worry about it. But data that is an intrinsic part of the form (such as the values of hidden fields) and URLs both require hex encoding of special characters. A hex code is a % sign followed by the character's hex value. Common codes include: less-than (<) = %3C, greater-than (>) = %3E, space = %20, return = %OD, double-quote (") = %22. If less-than and greater-than are to be displayed as text (rather than part of an HTML command) then you must encode the leading & in the HTML special symbols for them: &lt; = %26lt; and &gt; = %26gt;

This is mainly an issue for _header, _recPrefix and _footer because other fields are usually set by the user or don't tend to contain special characters.

Tips and Known Limitations

Troubleshooting

If you are getting mysterious failures, please check the following:

If FIND or FINDLINKS consistently fail to find any records, odds are you have a field in your form that doesn't exist in your database (FileMaker unfortunately can't distinguish between this and finding zero records). Check your spelling! You can localize the error by filling in different fields until you find the one that fails.

Security

Serving a database puts it at great risk. A user can write and submit their own forms, so they can do anything the CGI physically allows them to do.

ROFM Databases tells the CGI which databases it should allow access to, and whether or not it should allow users to ADD records. Once you allow access, users can read any field in the database. If you also allow add access, any user can add a record to the database.

WebSTAR/MacHTTP allow you to restrict access to the CGI (restricting access to your forms is not good enough; users can generate their own forms.) Read the WebSTAR/MacHTTP documentation or contact StarNine technical support for help with this.

FileMaker Pro allows you to password-protect various elements of a database, including adding records and reading specific fields. But once a database is opened using a secure username and password it becomes vulnerable to access by the CGI, so this mechanism must be used with great care. Also note that a protected database will ask for a username and password when it is first opened; so automatic startup you will probably require a special script to open your databases. For help setting up usernames and passwords, please read the FileMaker Pro documentation or contact Claris technical support.

That's about all I am willing to say about security. It is a complex topic and I am no expert. Think about what you are doing, test your setup. Please inspect the CGI source code before relying on ROFM Databases. If you are in doubt don't serve your database!

Support

If you have questions or comments about this CGI, or wish to be notified of new versions, please subscribe to the fmpro-cgi mailing list. Instructions for subscribing are available from my site. I do not usually have time to respond to personal email about this CGI. Please do not try to contact me by phone regarding this CGI; I have a day job and would like to keep it.

If you improve the script, please let me know, and if possible email me a copy of the improved script. I would be especially interested in hearing of a translation to a faster language.

Source Code

ROFM.acgi is written in AppleScript and includes commented source code. To view or edit the source code first make sure ROFM.acgi is not running, then drag and drop it onto Script Editor. If this fails, try increasing the memory partition of Script Editor! For your protection, please only edit a copy.

ROFMUtil is also written in AppleScript. It is a "compiled script" that contains the code that communicates with FileMaker Pro. This code may prove useful for other FileMaker scripts, as well. There is, at present, no documentation aside from the comments in the source code. To read the source code, simply double-click the file to open it in 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 incredibly weird and tricky, and Claris' own documentation is dead wrong in a number of places. Don't even think about changing things unless you are willing to do a lot of experimentation or already have a lot of experience. Some warnings for bold coders:

History

Acknowledgements

Chuck Shotton wrote and David Poteet had modified the original CGI on which I based mine. Eric Bickford supplied a lot of useful information on getting the best out of FileMaker Pro. Some of Jon Pugh's excellent tips (posted to the MacScrpt mailing list) have been incorporated. John Baxter gave me a huge amount of help in an attempted conversion of this script to Frontier (which I may yet finish if Frontier gets faster). Thanks finally to the many users who have suggested improvements, reported bugs, and been generally supportive; you have made working on this CGI very rewarding.

Legal Stuff

This software is not guranteed 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 by Russell E Owen. All rights reserved, except that you may use ROFM CGI without charge. 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.


Russell E. Owen
http://rowen.astro.washington.edu/
owen@astro.washington.edu