TweetFollow Us on Twitter

Apple Event CGIs

Volume Number: 15 (1999)
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.

 
AAPL
$119.00
Apple Inc.
+1.40
MSFT
$47.75
Microsoft Corpora
+0.28
GOOG
$540.37
Google Inc.
-0.71

MacTech Search:
Community Search:

Software Updates via MacUpdate

Skype 7.2.0.412 - Voice-over-internet ph...
Skype allows you to talk to friends, family and co-workers across the Internet without the inconvenience of long distance telephone charges. Using peer-to-peer data transmission technology, Skype... Read more
HoudahSpot 3.9.6 - Advanced file search...
HoudahSpot is a powerful file search tool built upon MacOS X Spotlight. Spotlight unleashed Create detailed queries to locate the exact file you need Narrow down searches. Zero in on files Save... Read more
RapidWeaver 6.0.3 - Create template-base...
RapidWeaver is a next-generation Web design application to help you easily create professional-looking Web sites in minutes. No knowledge of complex code is required, RapidWeaver will take care of... Read more
iPhoto Library Manager 4.1.10 - Manage m...
iPhoto Library Manager lets you organize your photos into multiple iPhoto libraries. Separate your high school and college photos from your latest summer vacation pictures. Or keep some photo... Read more
iExplorer 3.5.1.9 - View and transfer al...
iExplorer is an iPhone browser for Mac lets you view the files on your iOS device. By using a drag and drop interface, you can quickly copy files and folders between your Mac and your iPhone or... Read more
MacUpdate Desktop 6.0.3 - Discover and i...
MacUpdate Desktop 6 brings seamless 1-click installs and version updates to your Mac. With a free MacUpdate account and MacUpdate Desktop 6, Mac users can now install almost any Mac app on macupdate.... Read more
SteerMouse 4.2.2 - Powerful third-party...
SteerMouse is an advanced driver for USB and Bluetooth mice. It also supports Apple Mighty Mouse very well. SteerMouse can assign various functions to buttons that Apple's software does not allow,... Read more
iMazing 1.1 - Complete iOS device manage...
iMazing (was DiskAid) is the ultimate iOS device manager with capabilities far beyond what iTunes offers. With iMazing and your iOS device (iPhone, iPad, or iPod), you can: Copy music to and from... Read more
PopChar X 7.0 - Floating window shows av...
PopChar X helps you get the most out of your font collection. With its crystal-clear interface, PopChar X provides a frustration-free way to access any font's special characters. Expanded... Read more
OneNote 15.4 - Free digital notebook fro...
OneNote is your very own digital notebook. With OneNote, you can capture that flash of genius, that moment of inspiration, or that list of errands that's too important to forget. Whether you're at... Read more

Latest Forum Discussions

See All

Raby (Games)
Raby 1.0.3 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0.3 (iTunes) Description: ***WARNING - Raby runs on: iPhone 5, iPhone 5C, iPhone 5S, iPhone 6, iPhone 6 Plus, iPad Mini Retina, iPad Mini 3, iPad 4, iPad Air,... | Read more »
Oddworld: Stranger's Wrath (Games)
Oddworld: Stranger's Wrath 1.0 Device: iOS Universal Category: Games Price: $5.99, Version: 1.0 (iTunes) Description: ** PLEASE NOTE: Oddworld Stranger's Wrath requires at least an iPhone 4S, iPad 2, iPad Mini or iPod Touch 5th gen... | Read more »
Bounce On Back (Games)
Bounce On Back 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: | Read more »
Dwelp (Games)
Dwelp 1.0 Device: iOS Universal Category: Games Price: $.99, Version: 1.0 (iTunes) Description: === 50% off for a limited time, to celebrate release === Dwelp is an elegant little puzzler with a brand new game mechanic. To complete a... | Read more »
Make Way for Fat Chicken, from the Maker...
Make Way for Fat Chicken, from the Makers of Scrap Squad Posted by Jessica Fisher on November 26th, 2014 [ permalink ] Relevant Games has announced they will be releasing their reverse tower defense game, | Read more »
Tripnary Review
Tripnary Review By Jennifer Allen on November 26th, 2014 Our Rating: :: TRAVEL BUCKET LISTiPhone App - Designed for the iPhone, compatible with the iPad Want to create a travel bucket list? Tripnary is a fun way to do exactly that... | Read more »
Ossian Studios’ RPG, The Shadow Sun, is...
Ossian Studios’ RPG, The Shadow Sun, is Now Available for $4.99 Posted by Jessica Fisher on November 26th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Mmmm, Tasty – Having the Angry Birds for...
The very first Angry Birds debuted on iOS back in 2009. When you sit back and tally up the number of Angry Birds games out there and the impact they’ve had on pop culture as a whole, you just need to ask yourself: “How would the birds taste... | Read more »
Rescue Quest Review
Rescue Quest Review By Jennifer Allen on November 26th, 2014 Our Rating: :: PATH BASED MATCH-3Universal App - Designed for iPhone and iPad Guide a wizard to safety by matching gems. Rescue Quest might not be an entirely original... | Read more »
You Can Play the Final Chapter of Lone W...
You Can Play the Final Chapter of Lone Wolf: Dawn Over V’taag Right Now Posted by Jessica Fisher on November 26th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »

Price Scanner via MacPrices.net

BEVL Releases Dock Tailored for iPhone 6 and...
Seattle based BEVL has released their first product: an iPhone dock that is divergent in build quality, rock-solid function and visual simplicity to complement the iPhone. BEVL is now accepting... Read more
Black Friday: $150 off 13-inch Retina MacBook...
 Best Buy has 13-inch 2.6GHz Retina MacBook Pros on sale for $150 off MSRP on their online store as part of their Black Friday sale. Choose free shipping or free local store pickup (if available).... Read more
Black Friday: $300 off 15-inch Retina MacBook...
 B&H Photo has the new 2014 15″ Retina MacBook Pros on sale for $300 off MSRP as part of their Black Friday sale. Shipping is free, and B&H charges NY sales tax only: - 15″ 2.2GHz Retina... Read more
Black Friday: Up to $140 off MacBook Airs, fr...
 B&H Photo has 2014 MacBook Airs on sale for up to $140 off MSRP as part of their Black Friday sale. Shipping is free, and B&H charges NY sales tax only: - 11″ 128GB MacBook Air: $799 $100... Read more
Black Friday: 13-inch 2.5GHz MacBook Pro on s...
 Best Buy has the 13″ 2.5GHz MacBook Pro on sale for $899.99 on their online store as part of their Black Friday sale. Choose free shipping or free instant local store pickup (if available). Their... Read more
2014 1.4GHz Mac mini on sale for $449, save $...
 B&H Photo has the new 1.4GHz Mac mini on sale for $449.99 including free shipping plus NY tax only. Their price is $50 off MSRP, and it’s the lowest price available for this new model. Adorama... Read more
Early Black Friday pricing on 27-inch 5K iMac...
 B&H Photo continues to offer Black Friday sale prices on the 27″ 3.5GHz 5K iMac, in stock today and on sale for $2299 including free shipping plus NY sales tax only. Their price is $200 off MSRP... Read more
Early Black Friday sale prices on iPad Air 2,...
 MacMall is discounting iPad Air 2s by up to $75 off MSRP as part of their Black Friday sale. Shipping is free: - 16GB iPad Air WiFi: $459 $40 off - 64GB iPad Air WiFi: $559 $40 off - 128GB iPad Air... Read more
Early Black Friday MacBook Air sale prices, $...
 MacMall has posted early Black Friday MacBook Air sale prices. Save $101 on all models for a limited time: - 11″ 1.4GHz/128GB MacBook Air: $798 - 11″ 1.4GHz/256GB MacBook Air: $998 - 13″ 1.4GHz/... Read more
Why iPhone 6 Tablet/Laptop Cannibalization Is...
247wallst.com blogger Douglas A. McIntyre noted last week that according to research posted on the Applovin blog site the iPhone 6 is outselling the iPhone 6 Plus by a wide margin . Hardly a surprise... Read more

Jobs Board

*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
Senior Event Manager, *Apple* Retail Market...
…This senior level position is responsible for leading and imagining the Apple Retail Team's global event strategy. Delivering an overarching brand story; in-store, Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.