Lessons by Jon

CGI Applications in AppleScript

MacHTTP uses AppleEvents to communicate with external applications. This is nice for non-programmers because it means that you can use AppleScript to write CGI applications. In the following lessons I'll walk you through the design of a CGI script, showing several useful additions like delayed quitting and informative error messages. The final lesson is an AppleScript that can easily be modified for almost any task you can think of.

Required Software

Before you run off trying to make a CGI application, you will want to gather the basic materials. The items below are required to complete all of the lessons and will be useful in any future scripts you write. If you don't know where to obtain or how to install this software, check out my handy-dandy instructions.

Notes about the Lessons

Terminology
Let's get a few terms straight.
CGI Application
This is the actual application, compiled from an AppleScript. I will often refer to this as just a "CGI" due to lazy typing.
CGI Script
This is the AppleScript text that will be compiled.
argument
This is one item of information that is passed from MacHTTP to the CGI application. Username, password, and post_args are all arguments.
I don't know if these are correct, but they're what I use so at least we'll all be on the same page.

Using Forms
It is nearly impossible to demonstrate how to develop CGI applications without also talking about forms. After all, you need something for the application to process and online forms are the most interactive use of CGI applications. If you have no idea what I mean when I talk about forms, you might want to take a look at this sample form page. You will also need to make sure you are using a forms-capable client so you can interact with the lessons.

POST vs. GET
There are currently two ways of passing information from MacHTTP to a CGI application; they are the GET and POST methods. I'm not familiar with the historical differences of the two, but in practical terms the difference amounts to two things:

  1. POST arguments can contain much more data - You can pass up to 24K of information using POST arguments, where GET arguments are limited to 4K of information.
  2. The POST method passes more arguments to the CGI application - there is quite a bit of information passed to a CGI application by MacHTTP (eventually this will be covered below). This information includes the machine address for the client, username and password (if needed) and the referer. When MacHTTP is sending an AppleEvent using the POST method, it sends even more information, and this will likely improve even more in the future.
In my opinion there is no reason to use the GET method anymore, so all of my lessons will be using the POST method. I may (eventually) write a short description of how to convert a script to use GET instead of POST. Its very easy to do.

Return Codes
When MacHTTP sends an AppleEvent to a CGI application, it waits for another AppleEvent in return. The AppleEvent returned by the CGI application must contain instructions for MacHTTP on what to tell the client. There are pretty much only two things the CGI should send back, either a block of text to be treated like a page (Code 200 OK) or the URL for another page that already exists (Code 302 FOUND). In the first case, the CGI application is responsible for building an entire page, including the HTTP header (more on this later). This is the type of return that is generally used with forms, so we'll be using it in the lessons. There are many codes that can be returned, most of them error codes which a CGI application usually shouldn't be returning. CERN provides a summary of these codes, although new ones have been proposed recently that aren't in that document.

Actual Tutorial Files

This tutorial walks you through a number of scripts, adding a new feature in each one (if you go in order). I have provided the actual scripts as text files in a separate folder. View these scripts in the Script Editor and use them to work from as you follow the lessons. Whatever you do, don't try to copy the scripts out of your WWW client! This will not work. I've tried to make them presentable in HTML, but you can't copy that into the Script Editor - none of the special characters or line breaks will work so you'll just end up with another headache.

When you are ready to try some of your own scripts, or if you want to install any of these examples, you will need to save the script as a CGI application. Follow these directions if you're not sure how. You might also want to take a look at these instructions on installing forms to see where to put everything on your own site.

Lesson Index

This tutorial is intended to be completed in the order below, as each script builds on the one before.
  1. The Basics - This lesson shows how to make a CGI that returns an HTML page with all of the information that was passed to it. No processing is done on the data.
  2. Self-Quitting - This lesson shows how to make a CGI quit after a specified period without receiving an AppleEvent.
  3. Error Handling - This lesson demonstrates a CGI that will return an informative page describing any errors that are encountered during execution.
  4. Parsing the Form Data - This lesson covers parsing the information passed from a form into variables for processing. It also covers how to use an OSAX to speed up processing of data, in this case using the Tokenize OSAX.
  5. Decoding the Form Data - This lesson covers decoding the special character encodings used by client applications to send data to MacHTTP. Uses the Decode URL and DePlus OSAXen.
[Return to Extending MacHTTP]

Jon Wiederspan
Last Edited: December 11, 1994