Apple Event CGIs
Volume Number: 15
Issue Number: 8
Column Tag: Web Development
Apple Event Terminology for CGIs
by Chuck Shotton, BIAP Systems
Edited by Cal Simone, Technical Edit by Grant Neufeld
What changed in Mac OS 8.5?
A Little History
In 1993, MacHTTP was one of only 3 Web server products in existence. The other 2
were Unix-based servers from CERN in Switzerland and NCSA at the University of
Illinois Urbana-Champaign. When they first appeared on the scene, all these servers
could do is send back files of data. It quickly became apparent that to do really useful
stuff, Web servers had to be able to interact with applications on the local machine.
Initially, the only external interface provided by URLs, HTTP, and HTML was an
ability to specify search terms to some external program by putting those terms after
a "?" in a URL. While it is rarely used today, many features besides free text searches
were implemented with this mechanism. In order to implement search functions on the
Mac, MacHTTP implemented a simple mechanism for invoking an AppleScript and
passing some arguments to it.
In its first incarnation, the AppleScript source was loaded from disk, compiled by
MacHTTP, and then executed each time a request for the "search engine" was received
by the server. In order to pass arguments to the script, variable assignment
statements were actually prepended to the AppleScript source read from disk, and
compiled into the program. The output from this script was then returned to the HTTP
client. Since this was in the days of HTTP 0.9, no HTTP header was required and most
scripts just returned plain text or simple HTML documents that were generated on the
fly.
As it turns out, this was one of the first applications that actually used AppleScript on
the Mac in any significant way, but MacHTTP's performance when compiling and
running AppleScripts for each request was painfully slow. It quickly became apparent
that there had to be a better way to quickly load and execute external AppleScripts as
well as stand-alone programs written in other languages. So a new AppleEvent was
defined so that MacHTTP could launch external programs and pass the necessary
parameters to the external application.
This was the genesis of the WWWOmegaSRCH, or "search" AppleEvent. It passed a
single argument string (the data appearing after a "?" in a URL) to an external
application and received a text response. While it increased performance by removing
the overhead of recompiling an AppleScript each time a request was made, there was
still the overhead of launching the application or script each time a request came in. In
addition, it was about this time that the NCSA server implemented the first version of
the CGI (Common Gateway Interface) standard.
In typical Unix fashion, CGIs were passed all of their arguments in Unix shell
environment variables. Since the Mac OS had no similar function, implementing the
CGI standard on a Mac required a different approach. Since MacHTTP already had a way
to pass arguments to external applications, it made sense to simply extend the existing
AppleEvent to pass all the parameters necessary to implement the CGI standard. Since
older scripts and applications depended on the "search" event, a new event was created
called "search document", or WWWOmegaSDOC.
Because AppleScript doesn't provide a convenient user-level mechanism for specifying
your own English-like terminology for events that you create in AppleScripts, the
familiar but totally unfriendly syntax of:
on “event WWWOmegaSDOC” ...
sprang into being. In order to list all the parameters passed to a script, an AppleScript
CGI author had to carefully craft the event handler syntax, using the chevron syntax
for the event and all of its parameters. While functional, it was not very readable and
greatly complicated the learning curve for new users.
As the Mac CGI standard matured, the parameters passed to CGI applications from
MacHTTP were extended to include approximately 15 different arguments. In order to
make some sense out of the parameter list, Wayne Walrath of Acme Technologies
created an Apple event terminology file that AppleScript CGI authors could install on
their Macs that made the cryptic chevron syntax into something more human readable.
While not widely distributed, this terminology file greatly improved the readability of
AppleScripts.
With the advent of Mac OS 8, Apple began including a basic HTTP server for
performing personal Web sharing. This server had the ability to send the same sorts of
AppleEvents to external CGI applications provided by MacHTTP providedand other Mac
servers like WebSTAR, Quid Pro Quo, and NetPresenz. However, it wasn't until the
release of Mac OS 8.5 that the very widely used "SDOC" AppleEvent finally got
officially-supported Apple event terminology as part of the core operating system.
What this means is that now AppleScript CGI authors can write CGI event handlers
using simple English-like syntax without having to revert to the cryptic chevron
syntax. In Mac OS 8.5, Apple included its version of the AppleEvent terminology as
part of the "Standard Additions" file in the "Scripting Additions" folder in the OS 8.5
System Folder. In order to see the new syntax, users should use the Script Editor
application to open the AppleEvent dictionary of the "Standard Additions" file.
The Handle CGI Event Syntax
• handle CGI request: Sent to a script to process a Common Gateway
Interface request
• handle CGI request string - the path of the URL
• [searching for string] - the data for the GET method or data after the '?'
in a POST method
• [with posted data string] - the POST arguments
• [of content type string] - the MIME content type of POST arguments
• [using access method string] - either 'GET' or 'POST'
• [from address string] - the IP address of the entity making the request
• [from user string] - the user name associated with the request
• [using password string] - the password sent with the request
• [with user info string] - additional information about the user, usually
the email address
• [from server string] - the name of the server application sending this
request
• [via port string] - the IP port number of the server
• [executing by string] - the path to the script executing this CGI, in URL
form
• [referred by string] - the URL of the page the client used to link to the
CGI
• [from browser string] - the name of the client software
• [using action string] - the path to the file or CGI
• [of action type string] - either PREPROCESSOR, POSTPROCESSOR, CGI,
or ACGI
• [from client IP address string] - the Internet address of the client
• [with full request string] - the full request as sent to the server
• [with connection ID integer] - the ID of the connection from the server to
the client
• Result: web page - An HTML page resulting from the CGI execution
Format upgrade drawbacks
There are some drawbacks to Apple's addition of this AppleEvent terminology in Mac OS
8.5 that users need to be aware of. First, it can prevent existing, correctly written
CGIs from being compiled. I found that every single one of my CGIs (based on the old
MacHTTP CGI template scripts) failed to compile under the Mac OS 8.5 terminology,
even though they compiled and ran fine under OS 8.1. This is because Apple chose to
use relatively verbose and somewhat nonstandard terminology for their version of this
event, causing several commonly used variable names to conflict with the Apple event
keywords in the new terminology.
In order to correct this problem, you need to find all of the parameters in your old
version of the SDOC event handler that have name conflicts with Apple's new
terminology and rename those parameters. In my case, Apple had chosen to use the
term "action" as a part of one of their keywords and I had used it as the name of one of
my event's parameters. In order to clearly see which event parameters are causing
problems, you may need to disable Apple's new terminology so you can easily examine
your old script in the Script Editor. To do this:
1. Quit the Script Editor
2. Move the "Standard Additions" file out of the Scripting Additions folder
temporarily, and reopen your old CGI in the Script Editor.
You'll then see the old chevron syntax for the SDOC event, and can easily compare your
parameter names to the keywords found in Apple's dictionary entry for the CGI event.
Once you've changed your parameter names:
1. Quit the editor, saving your script
2. Reinstall the "Standard Additions" file,
3. Reopen your CGI.
You should now have a script that compiles correctly and uses the new terminology.
One other problem that you should note stems from the fact that Apple implemented
terminology for the SDOC event that is slightly out of date from the event commonly
supported by the recent versions of Mac Web servers. Specifically, the "DIRE
parameter, which typically contains a string representing the Web server's current
working directory, is not present in Apple's version of the SDOC event terminology. If
your existing CGI script uses the DIRE parameter, it will still be available but it will
revert to the old chevron syntax for that one parameter. If you need to write a new CGI
that uses the DIRE parameter, you'll have to append a parameter to the end of Apple's
parameter list that looks like:
given “class DIRE”: dir_path
An example script that uses the URL path, search arguments and server directory
might look like:
Sample AppleScript using URL path, search args, and server directory
on handle CGI request inURLPath
searching for inSearchArgs given “class DIRE”:dir_path
- build your HTTP header and response data, and return them...
end handle CGI request
Conclusion
For the most part, the addition of a standard terminology for the SDOC AppleEvent for
AppleScript authors is a great benefit. If you have existing AppleScript CGIs, you'll
have to be careful about the potential impact this new terminology can have on your
CGIs. But with a small amount of modifications as described above, you can quickly take
advantage of this new feature of Mac OS 8.5 and start writing much more readable,
maintainable AppleScript CGIs.
Debugging an AppleScript CGI
Writing a CGI can be rewarding - and for a simple task, you can write the CGI in the
Script Editor and, after a couple of tries, you should be able to get it to work.
The simple (limited) method:
1. Write your CGI and save it as a stay-open script application ("CGI
applet").
2. Go to your browser and submit requests. Your web server software will
send Apple event messages to your CGI applet.
3. If the CGI doesn't work properly, you can examine the script in the Script
Editor (or your favorite editor), searching for the problem command or
commands, correcting the script, and saving again.
If you get stuck, you can insert dialog boxes, beeps, and writing stuff out to a text file.
Any of these involves modifying your CGI, which means you aren't debugging the same
CGI that you'll use for real - and you must take care to remove anything you placed in
your script purely for debugging purposes.
While this method is straightforward, because of the indirect method of invoking the
CGI handler in your script, it will be effective only if your CGI is short and simple.
But suppose something goes wrong? Or suppose your CGI is complex, involving several
applications? How can you perfect it?
The deeper (cooler) method
If you have Main Event Software's Scripter, you have several tools available to debug
your CGI "live". Getting a scripting environment beyond Apple's free Script Editor may
cost a little bit, but how much is your time worth?
• Drag the CGI applet onto the Live Edit application, which can be found in
the Scripter Extras folder. The applet will quit if it's running. After several
seconds, a dialog box will appear indicating that the CGI is ready for editing in
Scripter.
• Choose Observe in the Windows menu to open the Observe window. If you
triple-click the first line of your CGI handler declaration (the line that starts
with "on handle CGI request") and command-drag the line from your CGI's
editing window to the Observe window, all your parameter values will appear
in the Observe window whenever your CGI is called. You can also drag variable
names from your script into the Observe window, useful to see their values
change as you single step through your CGI.
• If you want to see every line that executes in your script and every
result, choose Log in the Windows menu to open the Log window.
• Now you can go to your browser and submit requests. Your web server
software will send Apple event messages to your CGI, but they will be diverted
to Scripter. Each CGI request will appear in the Call Box window, where you
can examine and modify it before calling the script and single-stepping
through the handler. The handler's result will be displayed in the Call Box's
result area, and will also be sent back to the web server.
• The Live Edit application leaves behind another application called
Reinstate xxxx, where xxxx is part or all of the name of your CGI applet (note
that you can have several CGIs open for editing and debugging at the same
time). When you're finished debugging, double-click the Reinstate
application, and your revised CGI applet will be started and again made
available directly to your web server.
______________________________
Chuck Shotton (cshotton@biap.com) is the creator of MacHTTP, the first Mac
webserver, which later evolved into WebSTAR.