CS10100 First Perl CGI Script

How to write your first CGI script

Perl CGI scripts follow the same rules as other Perl scripts and are not more difficult to write. However, a CGI script is (usually) invoked from a browser and runs in the web server, which makes it difficult to track errors. The browser will simply report an "internal error", but you don't get the warnings and an error message you usually get when running Perl scripts. (Actually, a CGI script generates the same error messages as any other Perl script. But since error messages are printed to STDERR and the CGI script runs within a web server, the messages end up in the server's error log, to which you don't have access. The Perl CGI::carp module traps (not all) server errors and let's you print a message to the browser.)

CGI scripts are executable scripts that run within a web server. The server starts the execution when it receives an HTTP request for the CGI script. This has two important consequences. First, your scripts need a running server; you can't test them like HTML pages or Perl scripts on your computer. Second, the server must be configured to allow CGI scripts to be executed. (Not all CS machines allow CGI scripts. The domain of your scripts must be 'http://www.people.cs.uchicago'. If you want to run scripts on other servers outside of the CS network, you have to check with the service provider if and how CGI scripting is allowed.)

When starting to write a CGI script, your first step should be to establish contact between the web page that invokes the script and starts its execution. Take small steps! The more code you write, the more possibilities for mistakes you introduce.

A CGI script is invoked by giving its URL as a hypertext reference (href). Hence, you invoke a CGI script by clicking on a link (if the link points to a CGI script), by submitting a form (if the form-action attribute points to a CGI script), etc.

First CGI Step-by-Step

Create a directory for CGI scripts in your HTML directory on the server. By convention, this directory is usually called 'cgi-bin'.
Create a file for your CGI script. This file may be empty at this point.
Set permissions for the file to 755 (read and execute for group and everyone).
Now start editing the file.
Save your file containing only these three lines:
```
#!/usr/local/bin/perl -w

print "Content-type: text/html\n\n";
print "Hello, world!\n";
```
Call your CGI script from a test HTML page, either by setting a simple link that points to CGI script, or by writing a simple form and setting the action attribute to the script. As a shortcut, you can also simply type the URL of the script into the browser's UTL window:

http://people.cs.uchicago.edu/~YOUR_USER_ID/CGI_DIR/SCRIPT_NAME

If you can connect and see 'Hello, world!' on the screen, and receive no server error messages, your script works. If you get "not found" message, your link or action attribute points to the wrong URL. If you get a "forbidden" message, you haven't set permissions to the file or the directory containing the file. If you get an "internal server error" message, there's an error in your script. (Check your script; you probably left out a semicolon or quotation mark). Otherwise, proceed to the next step.
Now load the CGI Perl module and create a CGI object. (You may delete the 'Hello, world!' message now.)
Add the following lines before the print statement:
```
use CGI;

$q = new CGI;
```
The variable $q now contains the CGI object, and you can call the CGI functions from the variable with object access operator, ->. If you want to see if everything worked fine up to this point, safe the script and call it from your browser. If you still get no error message of an "internal server error", everything is working fine.

Now we will let the CGI object print the HTTP header for us. Delete the
```
print "Content-type: text/html\n\n";
```
line from your page and replace it with
```
print $q->header();
```
Save the script and run it to see that you don't get an error message. If you do, check your syntax.
So far we have only created a script that prints an HTTP header. Now we will add a body to the page:
Expand your header print statements as follows:
```
print $q->header(),
      $q->start_html(-title=>"First CGI Script",
                     -bgcolor=>'#FFFFFF'),
      $q->end_html();
```
Note that you can group the printing functions like a list; each function is separated by a comma from the next. If you put a semicolon after a function call, you must start the next printing function again with a print statement. Also, some functions, like start_html( ), can take more than one argument, which are also separated by a comma.
If you don't get an error message, change the bgcolor--just to make sure it has an effect.
Expand your script and add more tags and content.