Threaded ACGIs
Volume Number: 15
Issue Number: 7
Column Tag: Explain It(TM)
Threaded ACGI's in PowerPlant
By Aaron Montgomery, Valparaiso, IN
The Monsterworks' Framework
This article describes the Monsterworks' CGI Framework. The framework arose out of
work I did implementing a distance-learning course at Purdue University North
Central. I had written Java applets to allow students to take quizzes over the Internet
and there was a need for a CGI application to collect the student responses. While other
frameworks for CGI applications are available (see the references at the end of this
article), the Monsterworks' Framework provides the following advantages:
• It is written in C++ (instead of C).
• It builds on the PowerPlant framework with which you may already be
familiar.
• It provides threaded request handling with little effort by the user.
This article assumes that the reader has some familiarity with the C++ language and
the PowerPlant application framework. Some background with CGI applications, the
C++ container classes and threading might also be helpful since the framework uses
these, but you might be able to get what you need from examining the sample projects.
I provide references that cover these topics at the end of the article. You will need to
have a Macintosh Web server to use the applications produced by the framework. If
you have a Macintosh computer with a permanent IP address, then there are a number
of free Web server software packages (e.g., Quid Pro Quo).
Download the source and project files of the Monsterworks' Framework
athttp://faculty.purduenc.edu/agm/web/cgi.html. The two projects described below
and the project for building Server Proxy (described in the debugging section) are
there now. Currently, work is underway to provide a Web interface to the SQL database
provided by dtF. You will be able to download that project at the same location when it
is complete. This framework requires Apple's Universal Headers (version 3.2), the
PowerPlant framework (version 1.9.3) and the C++ standard library (MSL version
4.1.05).
The next section, The Setting: CGI Basics, will provide a brief introduction to CGI
programming which should be sufficient to allow you to understand the remainder of
the article. Following this, the article presents some facilities the framework offers
in The Characters of Monsterworks' Framework. Once you have been introduced to the
basics of the framework the section Act One: CGI Base presents a simple CGI program
that I built using the framework. Following this is an Intermission: Debugging and
Error Handling where the article discusses some issues in building CGI programs with
the framework. The next section, Act Two: CGI Mailer, presents a more complicated
example of a CGI program. The last section, Behind the Scenes, then describes some of
the code which implements the framework. The article concludes with a number of
references on the topic of CGI programming and PowerPlant.
The Setting: CGI Basics
This section provides a quick survey of CGI programming as well as some of the details
of CGI programming on the Macintosh. If you are already familiar with CGI
programming, you can skip to the next section. You can find a complete discussion of
this subject in the references provided at the end of this article.
The primary task of a Web server is to retrieve files for a Web browser. However,
Web servers treat some types of documents differently. When a Web browser requests
a CGI application, the server does not just return the contents of the file. Instead, it
launches the application and passes it information about the request. The application
executes and returns a response to the Web server and the server passes the response
back to the Web browser as if it were the contents of the file. To perform as a CGI
application, an application must accomplish three tasks: decode the data from the
server; perform application specific processing; return data to the server.
The actual data transfer between the Web server and the CGI application is platform
dependent and Macintosh machines use AppleEvents. The Web server will break the
data down into a number of different CGI variables and the enumeration ECGIKeys
(found in UtCGIKeys.h) lists the names of the variables available to CGI applications
working with a WebSTAR style server. The three most commonly used CGI variables
are ECGIKey_POST, ECGIKey_SEARCH and ECGIKey_PATH. The descriptions of these
variables will use the following
URL:http://www.server.com/app.cgi$path%20data?keyword+another
• ECGIKey_POST: A Web browser generates this variable in response to an
HTML
this variable. This variable can be up to 32K in length (longer than any other
CGI variable).
• ECGIKey_SEARCH: A Web browser generates this variable in response to
an HTML tag or in response to an HTML
action. Alternatively, the HTML author can include it in the URL following a
question mark. In the sample URL, the ECGIKey_SEARCH variable would
contain the string "keyword+another".
• ECGIKey_PATH: The HTML author can include this variable in the URL
following a dollar sign. In the sample URL, the ECGIKey_PATH variable would
contain the string "path%20data".
The ECGIKey_POST, ECGIKey_SEARCH and ECGIKey_PATH variables will arrive at the
CGI application as www-url-encoded strings. The following is a loose (and slightly
inaccurate) description that will suffice for this article, please see the references for
a complete (and accurate) description. The encoding specifies that most
non-alphanumeric characters should be converted to three-character codes of the
form "%XX" where the XX is the hexadecimal ASCII value for the character. In the
example above, "path%20data" is the encoded form of "path data". For data,
the data will be a sequence of encoded keywords separated by unencoded '+' characters.
In the example above, the ECGIKey_SEARCH variable has two keywords: "keyword" and
"another". For
unencoded '=' characters separate the keys from the values and unencoded '&'
characters separate the pairs. For example, the string
"Thatcher=5%20years&Conor=2%20months" has two pairs: "Thatcher" associated
with "5 years" and "Conor" associated with "2 months".
You can find descriptions of the remaining CGI variables in Appendix C of the WebSTAR
3 Manual. WebSTAR servers encode all of their CGI variables as strings with two
exceptions: the ECGIKey_CONNECTION variable (an SInt32); and the ECGIKey_DIRE
variable (an FSSpec).
The Characters of Monsterworks' Framework
This section will present the classes of the Monsterworks' Framework that we will use
in the following examples. If you are eager to see actual code, you can skip to the next
section, Act One: CGI Base, and deduce the roles from the uses of the classes in the code.
The descriptions below do not replace the information found in the Monsterworks' API
or the header files included with the projects, but should allow you to understand the
sample projects.
The Monsterworks' Framework will handle the first and third tasks of a CGI
application: decoding data from the server and returning data to the server. The three
classes in the CCGIThreadApp component handle most of the work: CCGIThread, CCGIApp
and CCGIFactory. The CCGIThread object is responsible for handling the CGI requests.