REBOL
Docs Blog Get-it

Quick and Easy CGI - A Beginner's Tutorial and Guide

By Carl Sassenrath
Revised: 12-Mar-2024
Original: 20-Jan-2005

Contents

Introduction
Other Articles
Why CGI?
Benefits of REBOL CGI
Just Dive In
Step 1: Write and Test the Script Locally
Step 2: Add REBOL to The Server
Step 3: Upload the Script
Step 4: Test the Script from Your Web Server
Problems? Fixing Your CGI Script
How to Put REBOL on Your Server
What Version You Need
If You Have Shell Access
If You Only Have FTP Access

Introduction

This is the first in a series of articles that describes how to write, install, and debug Common Gateway Interface (CGI) scripts in order to create your own custom web applications that run on a variety of web servers. These articles will include CGI tutorials, guides to CGI resources, and advanced CGI techniques.

Other Articles

Once you've read this article, you can move on to the second article in this series, Creating and Processing Web Forms in CGI.

Why CGI?

Even with the arrival of more advanced network technologies such as the X-Internet, CGI still powers many of the interactive elements found on web sites. CGI scripts are frequently used to generate special purpose web output, process input forms, handle user feedback, search web sites and types of other databases, run web chat rooms, add guestbook services, score online exams, and much more.

There many possible approaches to solving a particular CGI problem. CGI solutions are often written in Perl, PHP, Basic, Java, C and other languages; however, after writing more than 100 CGI scripts in recent years, I've found that REBOL offers a clean, quick, and easy approach to CGI. Of course, the fact that you are free to pick your favorite CGI approach is the true beauty of the CGI design. CGI is totally independent of whatever scripting language you use. So, you get to choose!

Unfortunately, CGI itself is not free from a number of pitfalls. Most of the problems and frustrations that CGI programmers encounter have nothing to do with their CGI scripts, but are more often a result of some "little detail" that was missed in the web server CGI environment. CGI scripts will fail for simple reasons, like forgetting to set the correct permissions on a script or data file. But, don't worry. These CGI articles will cover all the common pitfalls and give you enough information to avoid them in your CGI development projects.

Benefits of REBOL CGI

Over the years, I've found REBOL to be an excellent tool for writing and processing CGI scripts. It offers several pleasant advantages:

Just Dive In

There is nothing like diving-in to get started learning how to use CGI.

Whenever I sit down to write a new CGI application, I've found it very helpful to start small, then build from there.

Try to get a simple script working first. This approach lets you work out all the common CGI gotchas when the script is still small. It will also give you the satisfaction of getting something running within a few minutes, then let you improve on the script at your own pace.

When writing a CGI script, here are the steps I follow regardless of the operating system or web server being used:

  1. Write and test the CGI script locally.
  2. Add REBOL to the server.
  3. Upload the CGI script.
  4. Test the CGI script from the web server.

Each of these steps is described in detail below.

Step 1: Write and Test the Script Locally

To write a REBOL CGI script, all you need is a plain text editor. If you run on Windows, you can use an editor like Notepad, although there are many better choices (see what other REBOL developers recommend in the Editor Survey.)

Here is a simple little script to start. It only prints the current date, time, and time zone found on your web server. That's not very useful, but it makes a good first step. Type the lines below into your text editor:

REBOL [Title: "Server Time"]
print "content-type: text/html^/"
print [<HTML><BODY>]
print ["Date/time is:" now]
print [</BODY></HTML>]

I'll explain the details of this script and why I wrote it this way in the next article. For now, just save the script to a text file called now.cgi. Be sure that you save the file as plain text. If you are using a word processor (like MS Word) rather than a text editor, then you will need select a special save option to save the file as text.

Now, run your script with REBOL to test it. To do so, you'll need to download REBOL/Core. This is a very quick download and requires no installation. Put REBOL in the same directory as your new CGI script.

Now, click on the REBOL program icon (or run it from the shell). You will see REBOL startup with a few lines such as:

REBOL/Core 2.5.5.3.1
Copyright 1997-2003 REBOL Technologies
REBOL is a Trademark of REBOL Technologies
...
>>

To run your script, type:

do %now.cgi

Note that the percent is required for all file names in REBOL. If you forget it, you will see an error:

** Script Error: now.cgi has no value
** Near: do now.cgi

You can also run your script from a shell (console), or by creating an icon shortcut. The command line looks like this:

REBOL now.cgi

When your script runs, you will see this text output:

content-type: text/html

<HTML><BODY>
Date/time is: 11-Mar-2003/10:09:42-8:00
</BODY></HTML>

This text, when sent to a web browser via CGI, will generate a very simple web page that shows the date and time.

Testing your CGI script on your local computer is a big time saver. It lets you get your script working properly before you upload it to a server. It is much easier to debug and improve a script locally than remotely on a web server.

This technique will be used for all the scripts created in these CGI articles.

Step 2: Add REBOL to The Server

Just as you used REBOL on your local machine to test your CGI script, you now need to put REBOL on your server to run your CGI script. This is easy to do, but the approach may depend on what type of account you have on your server.

To summarize the process: you will need to download REBOL/Core either directly to your server (if you have a shell account), or download it first to your local machine then upload to your server (if you only have an FTP account).

The process is very similar to how you upload graphics to your web site. The main trick is to be sure to upload the correct version of REBOL for your type of server. If you need help, see the section below for step-by-step instructions.

Make a note of where you put the REBOL program. You will need this information later.

Once you have REBOL on your server, you will need to set the execute permissions to allow the REBOL program to run. For non-windows servers, if you have a shell account on the web server, you can type the command:

chmod +x rebol

If you have an FTP account, you must use the file permissions (CHMOD) command on your FTP program to set the read and execute permissions for all users.

Some web service providers may also provide a web site control panel to let you control these permissions. See their support pages for more info.

Step 3: Upload the Script

Before you upload the script, you need to tell the web server where to find the REBOL program that you just added.

To do that, add a line to the top of your now.cgi script file. It looks something like:

#!/home/your-account/rebol -c

This line tells the server the correct path to the REBOL program. The full path must be provided for the script to run. See the section below. Don't forget the "-c" option that tells REBOL to run in CGI mode.

Your now.cgi file should look like this:

#!/home/user/rebol -c
REBOL [Title: "Server Time"]
print "content-type: text/html^/"
print [<HTML><BODY>]
print ["Date/time is:" now]
print [</BODY></HTML>]

Note that you can still run the program locally with REBOL as you did before. REBOL ignores all lines before the word REBOL.

Upload the script to your web server's cgi-bin directory using FTP. Later, we will show you how to write a handy REBOL script that will upload the file for you.

There are several different approaches to cgi-bin on web servers. The method described here is just one possibility. If that does not match your system, don't worry. We'll describe the other cgi-bin methods in articles that follow.

You will now need to make your CGI script executable following the same approach you used for the REBOL program earlier. You can either use the chmod command from the server's shell:

chmod +x now.cgi

or set it using your FTP program.

Step 4: Test the Script from Your Web Server

You are now ready to test the script on your server. To do so, open a web browser and type the URL for your web site, followed by the correct cgi-bin path and script file name. The most common format for the URL is:

http://www.example.com/cgi-bin/now.cgi

There are, however, a few variations on this used by different web service providers. If you're not sure, check the support pages for your server provider. They will usually provide an example. Also, there are other example URL formats below.

If you are lucky, you'll see a date and time appear on your web browser. Wow! Good job. Your CGI script ran. It is showing the date and time on your web server (so it may not match your local time zone).

But, if it does not work, don't feel bad. CGI never works the first time. The chances are good that your script did not work. Now you get to figure out why. You missed a step or provided a wrong path. That's why we provide this next section.

Problems? Fixing Your CGI Script

The good news is that you your script is ready to run. The bad news is that there are many reasons why a CGI script will fail.

Here is a checklist of things that can go wrong.

1. Your CGI script does not have execute permission.

Check that you set the execute permission for the now.cgi file.

This is required on all Unix/Linux servers for a script to run. If you use a service provider, check their support pages for how to do this. There is way to do it! Otherwise, a lot of other CGI scripts would not work, not just yours. If you have a shell account, you can type "ls -l" on Linux/Unix systems to see a list of files and their permissions.

2. REBOL does not have execute permission.

Follow the same steps as above, but for the REBOL program.

3. You did not provide the correct program path.

Make sure that your script starts with the #! line that gives the correct path to the REBOL program.

Some service providers use special "file links" (ie. symbolic links and NFS) to locate files and directories, and the path to specific files may not be obvious.

If you have a shell account, you can change to the directory where you put REBOL and type "pwd" to print the full directory path. If you do not have a shell account, check the instructions provided by your web service.

4. Other permissions need to be set.

The script file and the REBOL program must be readable and executable by "all users". This is normally the default, but not always. It depends on your OS settings.

In Unix/Linux terms, the REBOL and script files must have 755 permission (read and execute by all, but only change by you).

If you have a shell account, you can set these permissions with:

chmod 755 rebol

chmod 755 now.cgi

If you only have FTP, then use its file permission settings to set READ and EXECUTE options for all users.

5. There is a problem with line terminators.

Unfortunately, different operating systems use different line terminators. Windows uses the CR and LF characters at the end of each line, whereas Linux/Unix uses only the LF character and Macintosh uses only the CR character.

The REBOL program does not care about line terminators, but some CGI shell environment do care.

The best way to prevent this problem is to upload your CGI script using the FTP text mode transfer, not the binary mode (which may be the default on your FTP client).

If you have a shell account on the server, you can also convert scripts using REBOL. First run REBOL then type the line:

write %now.cgi read %now.cgi

REBOL will rewrite the now.cgi file with the correct line terminators for your system. This is a handy trick to remember.

6. You may need a special URL for your CGI.

Sometimes the URL for CGI needs additional information. For example, some servers require that you provide an account name in the URL or a special "cgiwrap" path. Here are some examples:

http://data.rebol.com/cgi-bin/test-cgi.cgi

http://www.rebol.org/cgi-bin/cgiwrap/rebol/index.r

To find out if you need this type of URL, check your web service provider's support pages.

7. You may need a specific CGI file suffix.

Some web servers are configured to only recognize CGI files that end in a specific suffix. I used .cgi (rather than .r) for the above example because it is usually accepted by web servers.

If you run your own web server, check your server configuration file (or control panel) to see or change the suffixes it allows. If you use a service provider, you will need to check their help pages for the suffixes they allow.

8. You used the wrong REBOL.

There are different versions of REBOL for different operating systems. For example, if your server is Red Hat Linux, then you need to use the REBOL 042 program.

If you don't know what operating system your server is using, check your service provider's help pages.

If you have a shell account, you can verify that you have the correct version of REBOL by running REBOL at the command line.

9. You mistyped the example.

It is also possible that you made a mistake when you typed in the script. Of course, you tested the script locally first, so that should not be the case. Right?

10. You cannot execute program files.

Some web service provider may require that you to put the program in a special directory. Or, in rare cases, they may not permit you to run programs from CGI. (But there are plenty of other service providers that will, if you want to switch to a good one.)

If you still cannot get your script working, then you need to contact your service provider and get some ideas. You can also ask for help on the REBOL email list. REBOL users run on a wide variety of systems and configurations, so chances are good that someone knows the answer.

When you figure it out, please let us know what you discovered so we can add it to our CGI articles.

How to Put REBOL on Your Server

Here are the detailed steps that you can follow to put REBOL on your web server. The steps are:

  1. Determine what version of REBOL you need.
  2. Transfer the REBOL program to the server.
  3. Set the permissions for REBOL.

The details of these steps depend on what operating system your server uses and what type of account you have to access it. I will cover the common cases.

What Version You Need

Web servers run on many different operating systems. REBOL supports most of them.

If you run your own server, then you already know what OS it uses. If you use a web service provider, then you need to find out from your service provider what OS they use.

Find the correct OS version of REBOL on the REBOL/Core download page.

For the CGI script examples provided in these articles, it is best to use the most up-to-date version of REBOL. We suggest version 2.5.5 or better, although most scripts will run fine with older versions.

If You Have Shell Access

If you have shell access, you can use any FTP client to download REBOL directly from ftp://ftp.rebol.com/pub/downloads/core/. Or, you can also download the compressed archive from our web site.

Once downloaded, set the execute permissions for REBOL with a line such as:

chmod 755 rebol

You can now test REBOL by typing:

rebol

It should start and give you a prompt. Type:

print "hello world"

It should echo the text back. To quit, type:

quit

Make a note of where you put REBOL. If you are not sure where to put it, a good spot is in the directory just above your cgi-bin directory.

To find the full path to a directory, on Linux/Unix you can type:

pwd

If You Only Have FTP Access

If you only have FTP, you will need to download REBOL first to your local computer, then upload it to your web server.

To do this, you need to download the executable REBOL program, not the archive (zipped) version. Note that the REBOL download page provides the exe files for that reason. (Note that they are FTP links. Most browsers will handle that, but you can also use an FTP client to download them from ftp://ftp.rebol.com/pub/downloads/core/.)

Once you have downloaded REBOL to your local machine, you can upload it to your web server using FTP. Make sure that you use binary mode in FTP, just as you would for a graphics file. If you transfer the program in text mode, it will not run (or it will bomb out with a strange error).

Make a note of the directory where you put REBOL and add that path to the top of the CGI script as shown above.

Now, you need to set the execute permission for REBOL. Most modern FTP clients have a command option to do this (often called the CHMOD command). Make sure that you make REBOL both readable and executable by all users.

If you cannot set the permissions for a file from FTP, your web service provider may provide a control panel that lets you set it. Check their support pages for details.

To test REBOL, you will need to use your CGI script. Just make sure that you set the execute permission on the REBOL program and on the script, otherwise you will get a server error.

When you figure it out and get it running, you may want to make a few notes to tell other users how to do the same. Send them to us, and we will add them to our CGI articles.

About | Contact | PrivacyREBOL Technologies 2024