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.
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.
- MacHTTP 2.0 or later
- AppleScript 1.1 or later
- ScriptTools 1.3.1 OSAX
- Tokenize OSAX
- Decode URL OSAX
- DePlus OSAX
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:
- 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.
- 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.
This tutorial is intended to be completed in the order below, as each script
builds on the one before.
- 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.
- Self-Quitting
- This lesson shows how to make a CGI quit after a specified period without
receiving an AppleEvent.
- Error Handling
- This lesson demonstrates a CGI that will return an informative page describing
any errors that are encountered during execution.
- 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.
- 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