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.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

calibre 2.69.0 - Complete e-book library...
Calibre is a complete e-book library manager. Organize your collection, convert your books to multiple formats, and sync with all of your devices. Let Calibre be your multi-tasking digital librarian... Read more
Evernote 6.9.1 - Create searchable notes...
Evernote allows you to easily capture information in any environment using whatever device or platform you find most convenient, and makes this information accessible and searchable at anytime, from... Read more
jAlbum Pro 13.5 - Organize your digital...
jAlbum Pro has all the features you love in jAlbum, but comes with a commercial license. You can create gorgeous custom photo galleries for the Web without writing a line of code! Beginner-friendly... Read more
jAlbum 13.5 - Create custom photo galler...
With jAlbum, you can create gorgeous custom photo galleries for the Web without writing a line of code! Beginner-friendly, with pro results - Simply drag and drop photos into groups, choose a design... Read more
Google Chrome 53.0.2785.143 - Modern and...
Google Chrome is a Web browser by Google, created to be a modern platform for Web pages and applications. It utilizes very fast loading of Web pages and has a V8 engine, which is a custom built... Read more
Chromium 53.0.2785.143 - Fast and stable...
Chromium is an open-source browser project that aims to build a safer, faster, and more stable way for all Internet users to experience the web. Version 53.0.2785.143: [Security Fix] High CVE-2016-... Read more
QuickBooks 2015 16.1.7.1524 R8 - Financi...
Save 20% on QuickBooks Pro for Mac today through this special discount link QuickBooks 2015 helps you manage your business easily and efficiently. Organize your finances all in one place, track... Read more
Sierra Cache Cleaner 11.0.1 - Clear cach...
Sierra Cache Cleaner is an award-winning general purpose tool for macOS X. SCC makes system maintenance simple with an easy point-and-click interface to many macOS X functions. Novice and expert... Read more
Default Folder X 5.0.7 - Enhances Open a...
Default Folder X attaches a toolbar to the right side of the Open and Save dialogs in any OS X-native application. The toolbar gives you fast access to various folders and commands. You just click on... Read more
Safari Technology Preview 10.1 - The new...
Safari Technology Preview contains the most recent additions and improvements to WebKit and the latest advances in Safari web technologies. And once installed, you will receive notifications of... Read more

Pumped BMX 3: Beginner tips and tricks
There’s a whole lot more to Pumped BMX 3 than meets the eye. Your goal is to perform a wide array of sweet flips and tricks, but that’s easier said than done. It takes well practiced timing and coordination, and the game doesn’t really explain that... | Read more »
Cybird’s latest release - BFB Champions...
Launched in the UK in early September, BFB Champions’ newest update is loaded with great new features, and looks set to outshine the original version by taking it out of soft launch and giving it a new lease of life. | Read more »
3 apps to boost your focus
As someone who works from home, my workspace is a minefield of distraction. Cats, tasty snacks, the wind blowing past my window, that cleaning that I suddenly can’t put off any longer. If I let distraction takes its course, I find that soon half... | Read more »
Pumped BMX 3 (Games)
Pumped BMX 3 1.0 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0 (iTunes) Description: The final instalment of the smash hit #1 rated BMX game is here! Following on from the insane success of Pumped BMX 2, Pumped 3... | Read more »
4 games like Burly Men at Sea to inspire...
Burly Men at Sea is out today and it looks a treat. It tells the tale of three Scandinavian fishermen who leave the humdrum of their daily lives to go exploring. It’s a beautiful folksy story that unfurls as you interact with the environment... | Read more »
3 reasons you need to play Kingdom: New...
Developed by a tag team of indie developers - Thomas "Noio" van den Berg and Marco "Licorice" Bancale - Kingdom is a vibrant medieval fantasy adventure that casts players as a king or queen who must expand their empire by exploring the vasts lands... | Read more »
JoyCity have launched a brand new King o...
Great news for all of you Game of Dice fans out there - JoyCity have just released a brand new limited edition pack with a really cool twist. The premise of Game of Dice is fairly straightforward, asking you to roll dice to navigate your way around... | Read more »
Burly Men at Sea (Games)
Burly Men at Sea 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Burly Men at Sea is a folktale about a trio of large, bearded fishermen who step away from the ordinary to seek adventure. | Read more »
3 tips for catching the gnarliest waves...
Like a wave breaking on the shore, Tidal Rider swept its way onto the App Store charts this week settling firmly in the top 10. It’s a one-touch high score-chaser in which you pull surfing stunts while dodging seagulls and collecting coins. The... | Read more »
The beginner's guide to destroying...
Age of Heroes: Conquest is 5th Planet Games’ all new turn-based multiplayer RPG, full of fantasy exploration, guild building, and treasure hunting. It’s pretty user-friendly as far as these games go, but when you really get down to it, you’ll find... | Read more »

Price Scanner via MacPrices.net

CAZE Annouces New Zero 5 Case for Jet Black i...
Hong Kong basd CAZE has announced Zero 5 case for iPhone 7/ 7 Plus, one of the world’s thinnest clear hard cases, measuring just 0.5 millimeters. CAZE has been producing and improving the Zero 5... Read more
Nest Egg Inventory App for iOS Offers Conven...
Campbell, California based Winprogger LLC has announced the release and immediate availability of Nest Egg – Inventory 4.1.22, an important update to their easy-to-use, yet comprehensive inventory... Read more
Factor4, LLC Launches Apple iOS and Android G...
Factor4, LLC, which offers gift and loyalty services to the SMB marketplace, has released free mobile applications that enable merchants to process via all Apple and Android devices. The Apple and... Read more
15-inch Retina MacBook Pros on sale for $200...
B&H Photo has 15″ Retina Apple MacBook Pros on sale for $200 off MSRP. Shipping is free, and B&H charges NY tax only: - 15″ 2.2GHz Retina MacBook Pro: $1799 $200 off MSRP - 15″ 2.5GHz Retina... Read more
Apple refurbished iMacs available for up to $...
Apple has Certified Refurbished 2015 21″ & 27″ iMacs available for up to $350 off MSRP. Apple’s one-year warranty is standard, and shipping is free. The following models are available: - 21″ 3.... Read more
Check Apple prices on any device with the iTr...
MacPrices is proud to offer readers a free iOS app (iPhones, iPads, & iPod touch) and Android app (Google Play and Amazon App Store) called iTracx, which allows you to glance at today’s lowest... Read more
Apple price trackers, updated continuously
Scan our Apple Price Trackers for the latest information on sales, bundles, and availability on systems from Apple’s authorized internet/catalog resellers. We update the trackers continuously: - 15″... Read more
Apple refurbished 2016 13-inch MacBook Airs a...
Apple has Certified Refurbished 2016 13″ MacBook Airs available starting at $849. An Apple one-year warranty is included with each MacBook, and shipping is free: - 2016 13″ 1.6GHz/8GB/128GB MacBook... Read more
1.4GHz Mac mini on sale for $449, save $50
Adorama has the 1.4GHz Mac mini on sale for $50 off MSRP including free shipping plus NY & NJ sales tax only: - 1.4GHz Mac mini (Apple sku# MGEM2LL/A): $449 $50 off MSRP To purchase a mini at... Read more
Apple refurbished 2015 13-inch MacBook Airs a...
Apple has Certified Refurbished 2015 13″ MacBook Airs available starting at $759. An Apple one-year warranty is included with each MacBook, and shipping is free: - 2015 13″ 1.6GHz/4GB/128GB MacBook... Read more

Jobs Board

Systems Architecture Prototyping - *Apple*...
Changing the world is all in a day's work at Apple . If you love innovation, here's your chance to make a career of it. You'll work hard. But the job comes with more Read more
*Apple* Retail - Multiple Positions- Akron,...
Job Description:SalesSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
Hardware Design Validation Engineer - *Apple...
Changing the world is all in a day's work at Apple . If you love innovation, here's your chance to make a career of it. You'll work hard. But the job comes with more Read more
Systems Architecture Prototyping - *Apple*...
Changing the world is all in a day's work at Apple . If you love innovation, here's your chance to make a career of it. You'll work hard. But the job comes with more Read more
*Apple* Retail - Multiple Positions- South B...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.