CGI Scripting in Frontier

CGI stands for Common Gateway Interface. It's an Internet term for scripts and applications that run behind web server software.

Examples of CGI applications include search engines, guestbooks, bulletin-boards and page counters. Most dynamic website features can be implemented using CGIs.

A framework for CGI scripting

It's always been relatively easy to write CGI scripts in Frontier because Frontier implements a framework that hides a lot of the complexity of CGI scripting. In Frontier 4.1 it gets simpler, so that any reasonably experienced Frontier script writer can build web-based applications.

Hello World

As long has been the tradition when documenting programming languages, we start our introduction to CGI scripting with a simple Hello World example. This script will greet anyone who visits the web page with the current date and time at the server.

Launch Frontier. Choose the New Script command from The Main Menu. Set the dialog up as shown below:

A script window opens. The shell of a CGI script is automatically created, as shown below:

Finish the script by adding the text as shown below. Use the Return key to make a new line, Tab to indent, Shift-Tab to outdent:

If you don't want to enter the script by hand, you can download the finished script.

After entering the script, press Command-S to save the new script to disk. Click on the Compile button to be sure there are no syntax errors in the script. If there are, click on the Go To button in the Error Info to jump to the location of the error.

The script is created in the suites.webServerScripts table. All CGI scripts must run from this table. This is a security precaution, it shields all other scripts in Frontier.root from execution over the net. However, your scripts can call scripts in other tables, so it's up to you how much of your world you want to open up to other net users.

Now let's examine the script to see how it works.

Parameters

CGI scripts in Frontier always take a single parameter, the address of a table containing all the parameters to the script.

This table contains the parameters passed by the web server software to Frontier, information such as the address of the client, the kind of browser that's running on the client, the name and IP address of the server, a sub-table containing all the parameters for processing forms.

There is a standards body that defines the format of this table, so all Mac web servers basically send the same information. This means that your Frontier-based CGI scripts can run behind WebStar, NetPresenz, Boulevard, WebCenter or any new compatible web server software that might appear on the Macintosh.

The second line of the script is a comment that's collapsed. If you expand it by double-clicking on the « to the left of the line, the comment will expand to reveal a list of all the parameters that are available.

The helloWorld script uses one of the parameters, serverName. You'd could refer to this variable as adrParams^.serverName, but since it's nested underneath a "with" statement, we can just refer to it as serverName. Any code that's nested underneath the "with adrParams^" line can directly reference (or change) any of the information in the parameters table.

The goal of the CGI

The goal of any CGI script is to do some processing and then return some HTML text that's displayed on the client machine. Recognizing this, the framework automatically creates and initializes a variable called "htmltext" and defines a local subroutine for adding text to htmltext.

Usually the last line in a CGI script is:

return (htmltext)

And this CGI script is no exception!

Setting up your server

Now that we've written the CGI script, set up your web server to call Frontier when a call comes in over the network.

By convention, calls to Frontier-based CGI scripts end with ".fcgi". The first part of the call looks just like normal web URL, beginning with http://, followed by the name of your server machine. The middle part of the URL is the name of the script, in this case, helloWorld.

Putting it all together, to call the CGI script we just built, we could say:

http://206.204.24.2/helloWorld.fcgi

In fact, that script is running on the server listed above, so if you want to try it out, just click on the link.

So, the goal is to teach your web server software how to pass thru a ".fcgi" call to Frontier. We have detailed instructions for setting up Quarterdeck's WebSTAR to do this. They're at WebSTAR Setup for Frontier CGI Scripting.

Now try out the URL listed above, substituting the name of your server for 206.204.24.2.

Pointers

The Guestbook CGI Application maintains a simple guestbook for your web server. It's an example of a more sophisticated CGI application. Full source is provided.

The NetFrontier suite is very useful when working with CGI scripts that are running on another machine. It allows you to easily move bits of the object database from one machine to another, either via Program Sharing for local area networks, or via TCP for machines that are not accessible locally.

Mason Hale wrote an excellent article about CGI scripting. His article goes deeper than we can on this page. Mason also was responsible for the development and evolution of the CGI Framework, and in many ways was the catalyst for the renewal of Frontier in the last couple of years. Thanks Mason!

Extending WebStar: Jon Stevens and Jon Wiederspan team up with this tutorial of CGI scripting for WebStar using Frontier.

---

© Copyright 1996-97 UserLand Software. This page was last built on 5/7/97; 1:16:23 PM. It was originally posted on 10/12/96; 7:51:01 AM. Internet service provided by Conxion.