CGI Information

HTTP Basics

To understand CGI, it is important to understand HTTP. There are six phases of HTTP: 3 by the browser (request), 3 by the server (response).

1. Request method. Usually GET or POST. This line also inlcudes the URL to retrieve, and the version of HTTP being used.
2. Request header. Information that the browser sends to the server with each request. Includes fields such as acceptable mime types, acceptable languages, type of browser.
3. Request data. If the request is a POST, then additional data can be transmitted from the browser. This could be form data, possibly including a file to be uploaded.
4. Response status. The server indicates if the file could be found, if there was an access violation, if the file has moved.
5. Response header. The server sends information about the request back to the browser. Fields include content-type, pragma, cookies, etc.
6. Response data. The file that was requested.

CGI Basics

After studying calculus, it doesn't take long to see that 5% of any problem is calculus. The remaining 95% is algebra. CGI programming is the same way: 5% is CGI, 95% is programming. There are only a few assumptions that are being made:

• The information from the request header is placed into environment variables on the server. These variables can be accessed by CGI scripts.
• The server places information about itself into environment variables, too. Fields such as server administrator, server name, server port, etc.
• All data from the request data phase is sent to STDIN of a CGI script.
• The CGI script is responsible for all phases of the reponse. All output is sent to the browser via STDOUT.
  • If the script does not provide a response status, then the server will automatically return a status of OK.
  • The minimum response header contains the content-type and ends with a blank line. Other fields can also be supplied, but it is important that the blank line is after all the header fields.
    Pragma: no-cache
Content-type: text/html
 
  • The response data contains all the information to be displayed in the browser.
  • There is one exception to this. If the header is a relocation header, then that is all that is allowed in the repsonse (pluse a blank line):
    Location: /some/new/page.html
 
• All parameters to a CGI script must come from environment variables or be read from STDIN.
• Everything that is to be displayed in the browser must be sent via STDOUT.

CGILib

I have added a library name CGILib that contains useful functions for doing CGI scripts. These are the functions that are in it. I have indicated the parameters that are expected, and the return type of the function.

# File: CGILib.pm
# hash get_query()
#    Return a hash array of all the name value pairs in the QUERY_STRING variable, or from STDIN
# hash get_cookie()
#    Return a hash array of all the name value pairs in the HTTP_COOKIE variable
# string time_gmt(seconds)
#    Return a GMT formatted string from the current time pluse seconds
# string url_encode(string)
#    Return a string that has special characters translated to %xx
# string url_decode(string)
#    Return a string that translates %xx back to special characters
# string html_encode(string)
#    Return a string that translates & < > to &amp; &lt; &gt;
# void print_head(title, bgcolor)
#    Print the standard HTML codes, setting the title and background color
# void print_HTTP_header(mime_type)
#    Print the Content-type header for the given mime type, text/html is the default
# void print_tail()
#    Print the standard ending tags for an HTML page.
# void display_file(system_path, mime_type, mode)
#    Print a file to standard out with the given content-type
#    Use a non-zero mode to indicate text mode instead of the default binary mode.
# void redirect(url)
#    Print the relocation header for the given URL

Using CGILib

To use CGILib, add these statements to any Perl script
use lib '/home/scsfac/downeyt/public/scripts';
use CGILib;

There are two ways to generate output for the browser

1. Redirect to a different URL. Use the redirect function for this.
2. Generate the complete response.
   • Use the print_HTTP_header, print_head, and print_tail functions to generate an HTML page. Supply the rest of the content using print statements.
   • Use the display_file function to send a complete file to the browser. This works very well for image files.

Use the get_query and get_cookie methods to parse the appropriate environment variable into a hash array.
my %query = get_query();
if ($query{fullname} eq "") {
    print "You must fill in your full name";
}

Use the url_encode and url_decode to parse any information that you are sending in the repsonse header.

Use the time_gmt function to create a string that corresponds to a time. This can be used when settin the expiration time for a cookie or for a cached document.

Use html_encode to encode special characters that are being sent to the browser.

Testing for syntax errors

Syntax errors will generate 500 Internal Server Errors when the script is run from the web. The first syntax error will be placed into the error log of your server. However, syntax errors rarely travel alone. It is better to see a lot of them at once. You can test your script for syntax errors from the shell prompt.

• Change to the directory that contains your script, for example cgi-bin
  cd ~/COP3832/server/cgi-bin
• Execute the script, for example image.cgi
  ./image.cgi
  It is important to include the ./so that the operating system knows to look in the current directory for the script.