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

Fantastical 2.3.6 - Create calendar even...
Fantastical 2 is the Mac calendar you'll actually enjoy using. Creating an event with Fantastical is quick, easy, and fun: Open Fantastical with a single click or keystroke Type in your event... Read more
Creative Kit 1.1 - $149.99
Creative Kit 2016--made exclusively for Mac users--is your ticket to the most amazing images you've ever created. With a variety of powerful tools at your fingertips, you'll not only repair and fine-... Read more
iMazing 2.2.3 - Complete iOS device mana...
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
Apple Configurator 2.4 - Configure and d...
Apple Configurator makes it easy to deploy iPad, iPhone, iPod touch, and Apple TV devices in your school or business. Use Apple Configurator to quickly configure large numbers of devices connected to... Read more
WhatRoute 2.0.18 - Geographically trace...
WhatRoute is designed to find the names of all the routers an IP packet passes through on its way from your Mac to a destination host. It also measures the round-trip time from your Mac to the router... Read more
Posterino 3.3.5 - Create posters, collag...
Posterino offers enhanced customization and flexibility including a variety of new, stylish templates featuring grids of identical or odd-sized image boxes. You can customize the size and shape of... Read more
Skim 1.4.28 - PDF reader and note-taker...
Skim is a PDF reader and note-taker for OS X. It is designed to help you read and annotate scientific papers in PDF, but is also great for viewing any PDF file. Skim includes many features and has a... Read more
Apple macOS Sierra 10.12.4 - The latest...
With Apple macOS Sierra, Siri makes its debut on Mac, with new features designed just for the desktop. Your Mac works with iCloud and your Apple devices in smart new ways, and intelligent... Read more
Apple Numbers 4.1 - Apple's spreads...
With Apple Numbers, sophisticated spreadsheets are just the start. The whole sheet is your canvas. Just add dramatic interactive charts, tables, and images that paint a revealing picture of your data... Read more
Xcode 8.3 - Integrated development envir...
Xcode includes everything developers need to create great applications for Mac, iPhone, iPad, and Apple Watch. Xcode provides developers a unified workflow for user interface design, coding, testing... Read more

Power Rangers: Legacy Wars beginner...
Rita Repulsa is back, but this time she's invading your mobile phone in Power Rangers: Legacy Wars. What looks to be a straightforward beat 'em up is actually a tough-as-nails multiplayer strategy game that requires some deft tactical maneuvering.... | Read more »
Hearthstone celebrates the upcoming Jour...
Hearthstone gets a new expansion, Journey to Un'Goro, in a little over a week, and they'll be welcoming the Year of the Mammoth, the next season, at the same time. There's a lot to be excited about, so Blizzard is celebrating in kind. Players will... | Read more »
4 smart and stylish puzzle games like Ty...
TypeShift launched a little over a week ago, offering some puzzling new challenges for word nerds equipped with an iOS device. Created by Zach Gage, the mind behind Spelltower, TypeShift boasts, like its predecessor, a sleak design and some very... | Read more »
The best deals on the App Store this wee...
Deals, deals, deals. We're all about a good bargain here on 148Apps, and luckily this was another fine week in App Store discounts. There's a big board game sale happening right now, and a few fine indies are still discounted through the weekend.... | Read more »
The best new games we played this week
It's been quite the week, but now that all of that business is out of the way, it's time to hunker down with some of the excellent games that were released over the past few days. There's a fair few to help you relax in your down time or if you're... | Read more »
Orphan Black: The Game (Games)
Orphan Black: The Game 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Dive into a dark and twisted puzzle-adventure that retells the pivotal events of Orphan Black. | Read more »
The Elder Scrolls: Legends is now availa...
| Read more »
Ticket to Earth beginner's guide: H...
Robot Circus launched Ticket to Earth as part of the App Store's indie games event last week. If you're not quite digging the space operatics Mass Effect: Andromeda is serving up, you'll be pleased to know that there's a surprising alternative on... | Read more »
Leap to victory in Nexx Studios new plat...
You’re always a hop, skip, and a jump away from a fiery death in Temple Jump, a new platformer-cum-endless runner from Nexx Studio. It’s out now on both iOS and Android if you’re an adventurer seeking treasure in a crumbling, pixel-laden temple. | Read more »
Failbetter Games details changes coming...
Sunless Sea, Failbetter Games' dark and gloomy sea explorer, sets sail for the iPad tomorrow. Ahead of the game's launch, Failbetter took to Twitter to discuss what will be different in the mobile version of the game. Many of the changes make... | Read more »

Price Scanner via MacPrices.net

Is A New 10.5-inch iPad Still Coming In April...
There was no sign or mention of a long-rumored and much anticipated 10.5-inch iPad Pro in Apple’s product announcements last week. The exciting iPad news was release of an upgraded iPad Air with a... Read more
T-Mobile’s Premium Device Protection Now Incl...
Good news for T-Mobile customers who love their iPhones and iPads. The “Un-carrier” has become the first national wireless company to give customers AppleCare Services at zero additional cost as part... Read more
FileWave Ensures Support for Latest Apple OS...
FileWave multi-platform device management providers announced support for Apple’s release yesterday of iOS 10.3, macOS Sierra 10.12.4, and tvOS 11.2. FileWave has a history of providing zero-day... Read more
Use Apple’s Education discount to save up to...
Purchase a new Mac or iPad using Apple’s Education Store and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free: -... Read more
Apple refurbished Apple Watches available sta...
Apple is now offering Certified Refurbished Series 1 and Series 2 Apple Watches for 14-16% off MSRP, starting at $229. An Apple one-year warranty is included with each watch. Shipping is free: Series... Read more
9-inch 32GB Space Gray iPad Pro on sale for $...
B&H Photo has the 9.7″ 32GB Space Gray Apple iPad Pro on sale for $549 for a limited time. Shipping is free, and B&H charges NY sales tax only. Their price is $50 off MSRP. Read more
13-inch MacBook Airs on sale for $100-$150 of...
B&H Photo has 13″ MacBook Airs on sale for up to $150 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 13″ 1.6GHz/128GB MacBook Air (MMGF2LL/A): $899 $100 off MSRP - 13″ 1.... Read more
13-inch MacBook Airs, Apple refurbished, in s...
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: - 13″ 1.6GHz/8GB/128GB MacBook Air: $... Read more
12-inch Retina MacBooks on sale for $1199, sa...
B&H has 12″ 1.1GHz Retina MacBooks on sale for $100 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 12″ 1.1GHz Space Gray Retina MacBook: $1199 $100 off MSRP - 12″ 1.1GHz... Read more
Save up to $260 with Apple refurbished 12-inc...
Apple has Certified Refurbished 2016 12″ Retina MacBooks available for $200-$260 off MSRP. Apple will include a standard one-year warranty with each MacBook, and shipping is free. The following... Read more

Jobs Board

Fulltime aan de slag als shopmanager in een h...
Ben jij helemaal gek van Apple -producten en vind je het helemaal super om fulltime shopmanager te zijn in een jonge en hippe elektronicazaak? Wil jij werken in Read more
Desktop Analyst - *Apple* Products - Montef...
…technology to improve patient care. JOB RESPONSIBILITIES: Provide day-to-day support for Apple Hardware and Software in the environment based on the team's support Read more
*Apple* Mobile Master - Best Buy (United Sta...
**493168BR** **Job Title:** Apple Mobile Master **Location Number:** 000827-Denton-Store **Job Description:** **What does a Best Buy Apple Mobile Master do?** At Read more
Fulltime aan de slag als shopmanager in een h...
Ben jij helemaal gek van Apple -producten en vind je het helemaal super om fulltime shopmanager te zijn in een jonge en hippe elektronicazaak? Wil jij werken in Read more
*Apple* Mobile Master - Best Buy (United Sta...
**492889BR** **Job Title:** Apple Mobile Master **Location Number:** 000886-Norwalk-Store **Job Description:** **What does a Best Buy Apple Mobile Master do?** Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.