Introduction to Revolution CGIs - A Tutorial

Simple CGIs

Revolution CGIs require certain information to be present and that the script follow a particular structure. This structure is:

• The first line of the script must begin with a pound sign and exclamation mark (#!) followed by the path to the engine. Do not leave any blank lines at the top of the script.

  Important: If you are using a Revolution engine from version 2.7 or higher, you must also add the flags -ui to the declaration. This tells Revolution not to load its graphical interface. If you do not add these flags, the CGI will fail. The correct declaration for any script used with Revolution 2.7 or higher is: #!revolution -ui

  All scripts in this tutorial use the newer convention. It won't hurt to add the -ui flag if you are using an older version of Revolution, though it isn't strictly necessary.

  The path may be either relative or absolute. If the engine is in the same folder as the script (as it will be in our tutorial,) then the path may be as simple as #!revolution. Or you can use a full path, such as #!/home/httpd/cgi-bin/revolution. If this is your first experience with CGIs, it is easier to place the engine inside the cgi folder so that you don't have to worry about the relative path.

• Do not include any leading spaces, carriage returns, or other characters before the path declaration.

• Always include an on startup handler in the script. This is the first message the engine sends, and your script will not run without it. The on startup message is what activates the CGI.

• Remember to include a blank line (two carriage returns in a row) between the headers and the content being returned.

Things to keep in mind when writing a CGI script

The scripts you write will contain regular Revolution statements and syntax. Virtually anything you can do in a stack, you can do in a CGI script. There are a few things to keep in mind, however.

• The put command writes to standard output (stdout) and is what will be returned to the user's browser.

• Remember to include at least a minimal header i.e., "content-type:" when you are returning data to the browser.

• It is crucial that line endings are appropriate for your server. If you are running a Linux server then your line endings must be saved with Unix line endings (linefeeds.) If you are running Mac OS X, you must also use Unix line endings. If you are running a Windows server, use DOS line endings (linefeed-carriage return.) Incorrect line endings will cause a server error and the script will fail.

• Once the script is written, upload or copy it to the server, and place it in the cgi folder. Using either an FTP program or a terminal program, set the script's file permissions to 755; i.e. chmod 755 myscript.cgi.

• If your script needs to access the server environment variables, they are all available automatically and can be used without any declarations. Server variables are set by the server when your cgi is run; they all begin with "$". For example, $SERVER_ADDR will contain the IP of the host server.

  Not all servers provide all variables. You can get a list of the variables your server supports by running the echo.mt script. Unzip this file, place this script into your cgi folder, set permissions to 755, and call it from your browser. It loops over all the environmental variables and lists their values. This script is also useful as a test script when you want to see if your Revolution cgi setup is working.

Our first CGI: "Hello World"

In keeping with programming tradition, our first CGI script will be a "hello world" example. It simply returns the text "Hello World!" to the user's browser.

Open any text editor and paste the following script into it. Remember to set the line endings appropriately for the server's OS.

#!revolution -ui

on startup
  put "Content-Type: text/plain" & cr & cr
  put "Hello World!"
end startup

Save the text file as "hello.cgi" and copy it to the cgi folder on the server. Set its file permissions to 755.

Now open your web browser and type the URL to this script into the location bar. If you are testing on the same machine, the path will be something like this:

http://localhost/cgi-bin/hello.cgi

or alternately

http://127.0.0.1/cgi-bin/hello.cgi

If you are testing on a remote server, substitute the URL of the web site for localhost in the URL.

When you hit the return key in the browser location bar, you should see the text "Hello World!" returned. You've just written your first CGI.

Troubleshooting Tips

Most errors fall into one of these common categories:

1. Incorrect line endings. Make sure line endings in scripts are correct for the server platform. DOS line endings are carriage return and linefeed. Unix line endings are a single linefeed. Macintosh line endings are a single carriage return (but note that scripts run by Apache in OS X require Unix line endings.)

2. Incorrect permissions. Most files are usually CHMOD 755. Files that must have both read and write permissions can be set to either 766 or 666.

   Set permissions on both the Revolution engine and the script. Note that on Mac OS X you pretty much have to use Terminal or an FTP program for this. Changing permissions in OS X's Get Info box doesn't work.

   Some modes that may be useful in a typical CGI context are:

   • CGI programs, 755
   • data files to be readable by CGI, 644
   • directories for data used by CGI, 755
   • data files to be writable by CGI, 666 (data has no security)
   • directories for data used by CGI with write access, 777 (no security)

3. Incorrect relative file paths. Script paths must be relative to the cgi folder. This is the path that appears at the top of every CGI script file you write.

4. Incorrect file extensions. In some cases you may need to use a particular script naming extension. Technically this isn't required, but extensions are generally included in the file name, though they can usually be arbitrary. (For historical reasons, ".mt" is a traditional extension for Revolution CGIs.) Some ISPs restrict CGIs from running unless the extension is of a predefined type such as .pl, .cgi, or .sh, for example. If so, try renaming the script with the extension ".cgi".

5. Any Revolution commands, functions, and syntax can be used as long as they don't require the graphical user interface. Remember that your script will run without the Revolution GUI and commands that address the GUI will error or do nothing.

Some native Revolution commands that don't work (and may hang your script) are:

• go - requires a GUI window redraw
• toplevel - GUI-based
• modeless (or any other stack modes) - GUI-based
• create stack (or any file creation) - CGI permissions restriction
• save stack (errors with "can't open stack backup file") - permissions restriction
• beep - GUI-based

There is more discussion on debugging CGI scripts in Appendix: Debugging CGIs

A note about creating files on the server

Because the cgi folder has special restrictions, scripts won't be able to create new files within that folder. One way around this is to just create or upload a blank file via FTP and have your scripts store and retrieve data there. If your scripts really do need to create new files, then you can sometimes create a subfolder within the cgi folder and set its permissions to accept new files. Or you can save the files to another folder on the server that does not have restricted permissions.

An expanded "Hello World" example

The following script shows how you can use a server variable and a native Revolution function to add the user's IP address and the time to our Hello World script.

Since you already have hello.cgi installed on the server, you only need to edit that file. This will save you the trouble of re-uploading the file and resetting file permissions. Change the text file to this:

#!revolution -ui

on startup
  put "Content-Type: text/plain" & cr & cr
  put "Hello World!" && $REMOTE_ADDR && "The time is:" && the time
end startup

When you open hello.cgi in your browser, you should see the remote address of your browser and the current time after the "Hello World" statement.

 

Up to top | Introduction to Revolution CGIs - TOC | Next Page