Table of Contents

Introduction

What's a CGI?
How they work
Revolution advantages
Security
Two ways to do Rev CGIs
Installing the engine
Setting permissions

Structure of a CGI script
Things to keep in mind
"Hello World"
Troubleshooting Tips
Creating files
Expanded "Hello World"

Example: Visitor counter
Example: Random content

Example: Addresses stack
Setting up files
Environment variables
Parsing parameters
Putting a stack in use
Creating scripted HTML

The library command
Advantages
Example: Addresses 2
LibCGI library

Quick Checklist
Other techniques
Environment variables
Other online references

Debugging CGIs

Debugging text-based CGIs can be a challenge because very little error information is available. All you see in the browser is a generic "Server Error" message when something goes wrong. Here are some tips for more easily debugging text-based CGIs.

Quick Checklist

Some errors are so common that it is helpful to run through this checklist first before trying other debugging techniques. Check for these common errors:

1. Make sure the first line of the CGI script has the correct path to the engine, and make sure there are no blank lines or other characters before that line.

2. Make sure that the CGI text file, any stacks in use, and the Revolution engine all have their permissions set to executable. In most cases, this is chmod 755.

3. Make sure that line endings in all text files are correct for the server the file is running on.

4. If you are using OS X, make sure Personal Web Sharing is turned on in System Preferences.

5. All data returned by the CGI must be preceded by the correct headers. At a minimum, this must be a "content-type:" declaration. You can add other headers if your script requires it.

6. Make sure that all the correct Apache libraries are installed (see list below.)

Other Debugging Techniques

Write and debug the script in Revolution as much as possible

Debugging in the Revolution script editor makes it easier to catch syntax and logic errors. If possible, write as much of the script as you can within the Revolution IDE and then, after testing, move it to a text file.

Check the server log

The server log is one of your most valuable resources. If any error information is available, it will be listed in the server log. These errors can tell you about missing libraries, the line number where an error occurred, permissions errors, and "file not found" errors, among others. On OS X and the various UNIX platforms, the server log is in /private/var/log/httpd/, and you can open it in any text editor. If you are using a remote ISP, ask them how to access your server logs.

In addition to server errors, the server log will also list errors from the Revolution engine. If the first word of the error message is "revolution" then you know the problem is related to your script, rather than to the server or its setup.

Write scripts in short sections

To debug while interacting with the server, write the CGI script one line or one section at a time, and add temporary lines of code that return data to the browser at various points so you can see what the data is. This also one way to isolate the location in a script where a failure is occuring (although the server log can often tell you the same thing.)

If the script runs without errors but the end results are unexpected, try returning a list of variables and their values at end of the content output so you can see them for reference.

Put the result

Include put the result after lines of script that aren't working, or use try/catch structures to identify problems. Any data that is "put" will be displayed in the browser.

Server 500 Errors are usually script errors...

Server error 500, "Internal Server Error", or "Server error: premature end of header" are almost always script errors. If possible, move the script into a stack and test it in the Revolution IDE for syntax errors. Otherwise use one of the above techniques to locate the problem.

...unless they are library errors

There is one occasion where a Server 500 Error may not be a script error, and that can occur if your server does not have the correct library files installed. In this case, the error in the server log will reference the libraries that are missing, and you'll see something similar to this:

Premature end of script headers: /usr/local/apache/cgi-bin/echo.cgi
revolution: error in loading shared libraries: libXext.so.6: 
cannot open shared object file: No such file or directory

libXext.so.6
libX11.so.6
libm.so.6
libc.so.6
ld-linux.so.2

Use shell

Run a shell session in a terminal program. First cd to the cgi-bin folder and then type ./engineName scriptName. For example, type ./revolution hello.cgi to run the "hello.cgi" script.

Determining Environment Variables

Servers are all configured differently, and not all of them support every possible environment variable. The best way to determine which ones your server can work with is to run a CGI script that reports them.

You can download the echo.mt script for this purpose. Place the script into your cgi folder, set its permissions to 755, and call it from your browser like this:

http://localhost/cgi-bin/echo.mt

Other online references

Here are some other sites that discuss using Revolution as a CGI:

http://forums.runrev.com/phpBB2/viewforum.php?f=15 The Runtime Revolution forum which discusses Revolution CGIs.

http://www.navaching.com/pagem.html Nelson Zink discusses setting up a website to do e-commerce using MetaCard or Revolution as a CGI

http://www.andregarzia.com/index.html Andre Garcia, the expert in Revolution CGIs, offers additional tools and libraries.