Chapter 8

Using Existing CGI Libraries

• Using the cgi-lib.plLibrary
  • Determining the Requesting Method
  • Decoding Incoming CGI Data
  • Printing the Magic HTTP Content Header
  • Printing the Variables Passed to Your CGI Program
  • Printing the Variables Passed to Your CGI Program in a Compact Format
• Using CGI.pmfor Creating and Reading Web Forms
  • Installing CGI.pm
  • Reading Input Data
  • Saving Your Incoming Data
  • Saving the Current State of a Form
  • Creating the HTTP Headers
  • Creating an HTML Header
  • Ending an HTML Document
  • Creating Forms
  • Creating a Submit Button
  • Creating a Reset Button
  • Creating a Defaults Button
  • Creating a Hidden Field
  • Creating a Clickable Image Button
  • Controlling HTML Autoescaping
• Using the CGI Library for C Programmers: cgic
  • Writing a cgic Application
    
  • Using String Functions
  • Using Numeric Functions
  • Using Header Output Functions
  • A cgic Variable Reference
• Summary
• Q&A

Welcome to Hump Day in the afternoon. It really is a lovely day outside, and every lesson series should have an early day off. You should be able to read through this chapter relatively quickly and catch your breath today. Expect to return to this chapter on a regular basis, however, because it contains reference material to what I think are some of the best CGI library resources available.

The Internet is a vast sea of resources. You can find almost anything within the Internet Information sea, but how do you find the real pearls in all those vast waters? Well, that's what you do in this chapter-you examine a couple of Perl gems and one C library. They will save you vast amounts of programming time. Make good use of these libraries and don't be like the average programmer and reinvent the wheel each time you build a new cart. Read through the libraries to be sure you understand what they do and, with cgi-lib.pl, how they do it. Decide which library or libraries best suit your needs and then download them from the resources identified. Usually, you will want to install them in your cgi-bin directory. Make sure that you check with your Webmaster to see whether these libraries already are installed on your server.

Be lazy like me, and make good use of these libraries so that you can concentrate on whatever is today's real problem. And that's what this afternoon's lesson is about. In this chapter, you will learn about several existing libraries on the Net.

In particular, you will learn about the following:

• cgi-lib.pl: A nice, compact library for performing simple CGI operations.
• CGI.pm: A robust Perl 5 library for reading CGI data, saving the state of your program, generating HTML Web fill-out forms, and generating other basic HTML tags.
• cgic: An ANSI C CGI library for decoding incoming CGI data.

Using the cgi-lib.pl Library

The cgi-lib.pl version 1.14 library is the smallest library you will learn about in this chapter. Don't discard it from your toolbox just because it is small, though. Many of your CGI programs will be small applications that don't require a large library with a large amount of code to interpret. Some of the advantages of a small library are ease of understanding, ease of use, and improved efficiency. The smaller cgi-lib.pl library also takes less time to load than the other, larger libraries. I particularly like the cgi-lib.pl library because of its simplicity. For lots of small applications, it's just perfect. The cgi-lib.pl library is written and copyrighted by Steven E. Brenner ([email protected]) and is included here with his permission. You can find the latest copy of this library at

http://www.bio.cam.ac.uk/web/form.html

As you look through this library, take a close look at the first few lines of the PrintVariables function. Steve uses the special Perl global variable $*. The $* variable enables multiple-line pattern matching. But in addition to that, Steve illustrates good programming practice by saving the value of the $* variable before his subroutine changes it for its own use. This way, before his subroutine exits, it can restore the original value of the $* variable. Saving the values of any variables you need to use inside your subroutines and then restoring them before you exit the subroutine saves you many hours hunting for strange and hard-to-find bugs. This means that you can go out and party at night instead of having an all-night affair with your computer.

Determining the Requesting Method

The MethGet function determines which HTTP request method was used to call your CGI program. The function returns True if the request method was Get. The complete function is only one statement long. Sometimes it seems silly or not worth the effort to create a function that is only a couple of lines long. If you are going to use the same code several times, however, it makes sense to make that code into a subroutine. I like to use the three-or-greater rule: If the same code is going to be used in three or more places, it should be made into a subroutine. Listing 8.1 shows the MethGet function in its entirety.

Listing 8.1. The MethGet function.

1: sub MethGet {
2:   return ($ENV{'REQUEST_METHOD'} eq "GET");
3: }

Decoding Incoming CGI Data

The ReadParse() function reads in Get or Post data, converts it to unescaped text, and puts one key=value in each member of the list @in. The ReadParse function also creates key/value pairs in %in, using '\0' to separate multiple selections. If a parameter (*cgi_input, for example) is passed to ReadParse, the parsed data is stored there, rather than in $in, @in, and %in. Listing 8.2 shows the ReadParse function.

Listing 8.2. The ReadParse function.

01: sub ReadParse {
02:     local (*in) = @_ if @_;
03:   local ($i, $loc, $key, $val);
04:   # Read in text
05:   if ($ENV{'REQUEST_METHOD'} eq "GET") {
06:     $in = $ENV{'QUERY_STRING'};
07:   } elsif ($ENV{'REQUEST_METHOD'} eq "POST") {
08:     read(STDIN,$in,$ENV{'CONTENT_LENGTH'});
09:   }
10:   @in = split(/&/,$in);
11:
12:   foreach $i (0 .. $#in) {
13:     # Convert pluses to spaces
14:     $in[$i] =~ s/\+/ /g;
15:     # Split into key and value.
16:     ($key, $val) = split(/=/,$in[$i],2); # splits on the first =.
17:     # Convert %XX from HEX numbers to alphanumeric
18:     $key =~ s/%(..)/pack("c",hex($1))/ge;
19:     $val =~ s/%(..)/pack("c",hex($1))/ge;
20:     # Associate key and value
21:     $in{$key} .= "\0" if (defined($in{$key}));
 # \0 is the multiple separator
22:     $in{$key} .= $val;
23:   }
24:   return 1; # just for fun
25: }

Printing the Magic HTTP Content Header

The function PrintHeader returns the content-type: text/html HTTP response header for HTML documents with the correct number of newline characters (\n\n). Listing 8.3 shows the PrintHeader function.

Listing 8.3. The PrintHeader function.

1: sub PrintHeader {
2:   return "content-type: text/html\n\n";
3: }

Printing the Variables Passed to Your CGI Program

The function PrintVariables, shown in Listing 8.4, formats an input variable list that is an associative array and returns an HTML string formatted as a definition list (<DL>) made up of the keyword represented as a definition term (<DT>) and the keyword value as a definition description (<DD>).

Listing 8.4. The PrintVariables function.

01: sub PrintVariables {
02:   local (%in) = @_;
03:   local ($old, $out, $output);
04:   $old = $*;  $* =1;
05:   $output .=  "<DL COMPACT>";
06:   foreach $key (sort keys(%in)) {
07:     foreach (split("\0", $in{$key})) {
08:       ($out = $_) =~ s/\n/<BR>/g;
09:       $output .=  "<DT><B>$key</B><DD><I>$out</I><BR>";
10:     }
11:   }
12:   $output .=  "</DL>";
13:   $* = $old;
14:   return $output;
15: }

Printing the Variables Passed to Your CGI Program in a Compact Format

The function PrintVariablesShort, shown in Listing 8.5, formats an input variable list
that is an associative array and returns an HTML string formatted as one line per keyword/value pair.

Listing 8.5. The PrintVariablesShort function.

01: sub PrintVariablesShort {
02:   local (%in) = @_;
03:   local ($old, $out, $output);
04:   $old = $*;  $* =1;
05:   foreach $key (sort keys(%in)) {
06:     foreach (split("\0", $in{$key})) {
07:       ($out = $_) =~ s/\n/<BR>/g;
08:       $output .= "<B>$key</B> is <I>$out</I><BR>";
09:     }
10:   }
11:   $* = $old;
12:   return $output;
13: }

Using CGI.pm for Creating and Reading Web Forms

The Perl 5 library CGI.pm uses objects to create Web forms on-the-fly and to parse their contents. It is similar to cgi-lib.pl in some respects. Perl 5 is an object-oriented version of the standard Perl language. It provides a simple interface for parsing and interpreting query strings passed to CGI scripts. It also offers a rich set of functions for creating fill-out forms, however. Instead of remembering the syntax for HTML form elements, you just make a series of Perl function calls. An important fringe benefit of this is that the value of the previous query is used to initialize the form, so the state of the form is preserved from invocation to invocation. The CGI.pm library is included in this chapter with the permission of Mr. Lincoln Stein, MD, Ph.D. and is available at

http://www-genome.wi.mit.edu/WWW/tools/scripting/CGIperl

Everything is done through a CGI object. When you create one of these objects, it examines the environment for a query string, parses it, and stores the results. You then can ask the CGI object to return or modify the query values. CGI objects handle Post and Get methods and distinguish between scripts called from Isindex documents and form-based documents. In fact, you can debug your script from the command line without worrying about setting up environment variables.

A script to create a fill-out form that remembers its state each time it's invoked is very easy to write with CGI.pm. Listing 8.6 shows an example of such a script.

Listing 8.6. Creating a fill-out form using CGI.pm.

01: use CGI;
02: $query = new CGI;
03: print $query->header;
04:
05: print $query->startform;
06: print "What's your name? ",$query->textfield('name');
07: print "<P>What's the combination? ",
08:         $query->checkbox_group('words',['eenie','meenie','minie','moe']);
09: print "<P>What's your favorite color? ",
10:         $query->popup_menu('color',['red','green','blue','chartreuse']);
11: print "<P>",$query->submit;
12: print $query->endform;
13:
14: print "<HR>\n";
15: if ($query->param) {
16:     print "Your name is <EM>",$query->param('name'),"</EM>\n";
17:     print "<P>The keywords are: <EM>",join(", ",$query->param('words')),
 "</EM>\n";
18:     print "<P>Your favorite color is <EM>",$query->param('color'),"</EM>\n";
19: }

Installing CGI.pm

To use this package, install it in your Perl library path. On most systems, this will be /usr/local/lib/perl5, but check with your System Administrator to be sure. Then place the following statement at the top of your Perl CGI scripts:

Use CGI;

If you do not have sufficient privileges to install into /usr/local/lib/perl5, you still can use CGI.pm. Place it in a convenient place-for example, in /usr/local/etc/httpd/cgi-bin-and preface your CGI scripts with a preamble something like this:

BEGIN {
     push(@Inc,'/usr/local/etc/httpd/cgi-bin');
}
Use CGI;

Be sure to replace /usr/local/etc/httpd/cgi-bin with the location of CGI.pm on your server.

Reading Input Data

You can use two methods in the CGI.pm library to read data passed to your CGI program:

• $query = new CGI;
  This method parses the input (from both Post and Get methods) and stores it in a Perl 5 object called $query.
• $query = new CGI(FILEHANDLE);
  This method enables you to read the contents of the form from a previously opened filehandle.
  The filehandle can contain a URL-encoded query string, or it can be a series of newline delimited tag=value pairs. This method is compatible with the save() method, which enables you to save the state of a form to a file and reload it later.

Saving Your Incoming Data

Your incoming data should be saved to an object such as the $query object. The following methods are available for decoding and modifying the object data; these methods assume that you have named that object $query.

Getting a List of Keywords from the Query Object

If your CGI program was invoked as the result of an Isindex search, the parsed keywords of the Isindex input search string can be obtained with the keywords() method. This method returns the keywords as a Perl array. Use this code:

@keywords = $query->keywords

Getting the Names of All Parameters Passed to Your Script

If your CGI program was invoked with a parameter list such as

name1=value1&name2=value2&name3=value3"

the param() method returns the parameter names as a list. For backward compatibility, this method works even if the script was invoked as an Isindex script; in this case, a single parameter name is returned named 'keywords'. Use this code:

@names = $query->param

Getting the Value(s) of a Named Parameter

You pass the param('NAME') method a single argument to fetch the value of the named parameter. If the parameter is multivalued (from multiple selections in a scrolling list, for example), you can ask to receive an array. Otherwise, the method returns a single value. Use this code:

@values = $query->param('foo');

or

$value = $query->param('foo');

As of version 1.50 of this library, the array of parameter names returned is in the same order in which the browser sent them. Although this is not guaranteed to be identical to the order in which the parameters were defined in the fill-out form, this is usually the case.

Setting the Value(s) of a Named Parameter

The method

param('NAME' 'NEW-VALUES')

sets the value for the named parameter 'foo' to one or more values. These values are used to initialize form elements, if you so desire. Note that this is the correct way to change the value of a form field from its current setting. Use this code:

$query->param('foo','an','array','of','values');

Deleting a Named Parameter

The method

delete('NAME')

deletes a named parameter entirely. This is useful when you want to reset the value of the parameter so that it isn't passed down between invocations of the script. Use this code:

$query->delete('foo');

Importing Parameters into a Namespace

The method

import_names('NAME_SPACE')

imports all parameters into the given namespace. If there were parameters named 'foo1', 'foo2', and 'foo3', for example, after executing $query->import('R'), the variables @R::foo1, $R::foo1, @R::foo2, $R::foo2, and so on would conveniently spring into existence. Because CGI has no way of knowing whether you expect a multi- or single-valued parameter, it creates two variables for each parameter. One variable is an array and contains all the values, and the other is a scalar containing the first member of the array. Use whichever variable is appropriate. For keyword (a+b+c+d) lists, the variable @R::keywords is created. Use this code:

$query->import_names('R')

If you don't specify a namespace, this method assumes namespace "Q". Use this code:

$query->import_names('R');
print "Your name is $R::name\n"
print "Your favorite colors are @R::colors\n";

Saving the Current State of a Form

As you have seen throughout this book, saving the state of your CGI program is one of the harder things to do in the CGI environment. The CGI.pm library addresses that need with the following two methods. These two methods enable you to save object state information so that you can use it the next time your CGI program is called.

Saving the State to a File

The method

save(FILEHANDLE)

writes the current query object out to the filehandle of your choice. The filehandle already must be open and writable but, other than that, it can point to a file, a socket, a pipe, or whatever. The contents of the form are written out as tag=value pairs, which can be reloaded with the new() method later. Use this code:

$query->save(FILEHANDLE)

Saving the State in a Self-Referencing URL

The method

self_url()

returns a URL that, when selected, reinvokes your CGI program with all its state information intact. This is most useful when you want to jump around within a script-generated document using internal anchors but don't want to disrupt the current contents of the form(s). Use this code:

$my_url=$query->self_url;

Creating the HTTP Headers

Every CGI program needs to print the correct HTTP headers. The following methods perform this task for you with a minimum amount of programming effort.

Creating the Standard Header for a Virtual Document

The header('CONTENT-TYPE/SUBTYPE') method prints the required HTTP content-type header and the requisite blank line below it. If no parameter is specified, it defaults to 'text/html'. Use this code:

print $query->header('image/gif');

Writing a cgic Application

Because all CGI applications must perform certain initial tasks, such as parsing form data and examining environment variables, the cgic library provides its own main() function. When you write applications that use cgic, you begin your own programs by writing a cgiMain() function, which cgic invokes when the initial CGI work has been completed successfully. Your program also must be sure to include the file cgic.h.

Using String Functions

You can use this section as a quick-and-easy reference to learn about the various string functions.

cgiFormString

The cgiFormString() function retrieves the first argument (name) from the Web fill-out form and places the retrieved value into the result. Use this code:

cgiFormResultType cgiFormString(char *name, char *result, int max)

Table 8.14 explains the parameters of the cgiFormString function.

Regardless of the newline format submitted by the browser, cgiFormString() always encodes each newline as a single line feed (ASCII decimal 10). As a result, the final string may be slightly shorter than indicated by a call to cgiFormStringSpaceNeeded but will never be longer.

cgiFormString() returns one of these status codes:

• cgiFormEmpty: The string was retrieved but was empty.
• cgiFormLong: The string was retrieved but was truncated to fit the buffer.
• cgiFormNotFound: No such input field was submitted. In this case, an empty string is copied to result.
• cgiFormSuccess: The string was retrieved successfully.
• cgiFormTruncated: The string was retrieved but was truncated to fit the buffer.

cgiFormStringMultiple

The cgiFormStringMultiple() function is useful in the unusual case in which several input elements in the form have the same name and, for whatever reason, the programmer does not want to use the checkbox, radio button, and selection menu functions. This is needed occasionally if the programmer cannot know in advance what values might appear in a multiple-selection list or group of checkboxes on a form. The value pointed to by the result is set to a pointer to an array of strings; the last entry in the array is a null pointer. This array is allocated by the CGI library. Use this code:

cgiFormResultType cgiFormStringMultiple(char *name, char ***ptrToStringArray)

Table 8.15 explains the parameters of the cgiFormStringMultiple() function.

cgiFormStringMultiple() returns one of these status codes:

• cgiFormMemory: Not enough memory is available to allocate the array to be
  returned.
• cgiFormNotFound: No occurrences were found.
• cgiFormSuccess: At least one occurrence of the name was found.

cgiFormStringNoNewlines

The cgiFormStringNoNewlines() function is equivalent to cgiFormString(), except that any carriage returns or line feeds that occur in the input are stripped out. This function is recommended for single-line text input fields, because some browsers submit carriage returns and line feeds when they should not. See the section "cgiFormString," earlier in this chapter, for further information.

Use this code:

cgiFormResultType cgiFormStringNoNewlines(char *name, char *result, int max)

cgiFormStringSpaceNeeded

The cgiFormStringSpaceNeeded() function determines the length of the input text buffer needed to receive the contents of the specified input field. This is useful if the programmer wants to allocate sufficient memory for input of arbitrary length. The actual length of the string retrieved by a subsequent call to cgiFormString() may be slightly shorter but will never be longer than the returned *result parameter. Use this code:

cgiFormResultType cgiFormStringSpaceNeeded(char *name, int *length)

Table 8.16 explains the parameters of the cgiFormStringSpaceNeeded function.

cgiFormStringSpaceNeeded() returns one of these status codes:

• On success, cgiFormStringSpaceNeeded() sets the value pointed to by the parameter *length to the number of bytes of data, including the terminating null character, and returns cgiFormSuccess.
• If the specified field name cannot be retrieved, cgiFormStringSpaceNeeded() sets the value pointed to by length to 1 and returns cgiFormNotFound. The 1 is set to ensure space for an empty string (a single null character) if cgiFormString() is called despite the return value.

cgiStringArrayFree

The cgiStringArrayFree() function frees the memory associated with a string array created by cgiFormStringMultiple(). Use this code:

void cgiStringArrayFree(char **stringArray)

Using Numeric Functions

This section lists the various numeric functions. They are arranged in alphabetical order for easy reference.

cgiFormCheckboxMultiple

The cgiFormCheckboxMultiple() function determines which checkboxes among a group of checkboxes with the same name are checked. This is distinct from radio buttons (see the section "cgiFormRadio," later in this chapter). Use this code:

cgiFormResultType cgiFormCheckboxMultiple(char *name, char **valuesText,
  int valuesTotal, int *result, int *invalid)

Table 8.17 explains the parameters of the cgiFormCheckboxMultiple() function.

cgiFormCheckboxMultiple() returns one of these status codes:

• cgiFormNotFound: No valid checkboxes were checked.
• cgiFormSuccess: At least one valid checkbox was checked.

cgiFormCheckboxSingle

The cgiFormCheckboxSingle() function determines whether the checkbox with the specified name is checked. cgiFormCheckboxSingle() is intended for single checkboxes with a unique name. Use this code:

cgiFormResultType cgiFormCheckboxSingle(char *name)

cgiFormCheckboxSingle() returns one of these status codes:

• cgiFormNotFound: The checkbox is not checked.
• cgiFormSuccess: The button is checked.

cgiFormDouble

The cgiFormDouble() function attempts to retrieve the floating-point value sent for the specified input field. Use this code:

cgiFormResultType cgiFormDouble(char *name, double *result, double defaultV)

The value pointed to by result is set to the value submitted.

Table 8.18 explains the parameters of the cgiFormDouble() function.

cgiFormDouble() returns one of these status codes:

• cgiFormBadType: The value submitted is not a number.
• cgiFormEmpty: The value submitted is an empty string.
• cgiFormNotFound: No such input field was submitted.
• cgiFormSuccess: The value was retrieved successfully.

cgiFormDoubleBounded

The cgiFormDoubleBounded() function attempts to retrieve the number sent for the specified input field and constrains the result to be within the specified bounds. Use this code:

cgiFormResultType cgiFormDoubleBounded(char *name, double *result, double min,
  double max, double defaultV)

Table 8.19 lists the parameters of the cgiFormDoubleBounded() function.

cgiFormDoubleBounded() returns one of these status codes:

• cgiFormBadType: The value submitted is not an integer.
• cgiFormConstrained: The value was out of bounds and result was adjusted accordingly.
• cgiFormEmpty: The value submitted is an empty string.
• cgiFormNotFound: No such input field was submitted.
• cgiFormSuccess: The value was retrieved successfully.

cgiFormInteger

The cgiFormInteger() function attempts to retrieve the integer sent for the specified input field. The value pointed to by the result is set to the value submitted. Use this code:

cgiFormResultType cgiFormInteger(char *name, int *result, int defaultV)

Table 8.20 explains the parameters of the cgiFormInteger() function.

cgiFormInteger() returns one of these status codes:

• cgiFormBadType: The value submitted is not an integer.
• cgiFormEmpty: The value submitted is an empty string.
• cgiFormNotFound: No such input field was submitted.
• cgiFormSuccess: The value was retrieved successfully.

cgiFormIntegerBounded

The cgiFormIntegerBounded() function attempts to retrieve the integer sent for the specified input field and constrains the result to be within the specified bounds. Use this code:

cgiFormResultType cgiFormIntegerBounded(char *name, int *result, int min,
  int max, int defaultV)

Table 8.21 explains the parameters of the cgiFormIntegerBounded() function.

cgiFormIntegerBounded() returns one of these status codes:

• cgiFormBadType: The value submitted is not an integer.
• cgiFormConstrained: The value was out of bounds and result was adjusted accordingly.
• cgiFormEmpty: The value submitted is an empty string.
• cgiFormNotFound: No such input field was submitted.
• cgiFormSuccess: The value was retrieved successfully.

cgiFormRadio

The cgiFormRadio() function determines which, if any, of a group of radio buttons with the same name was selected. Use this code:

cgiFormResultType cgiFormRadio(char *name, char **valuesText, int valuesTotal,
  int *result, int defaultV)

Table 8.22 explains the parameters of the cgiFormRadio() function.

cgiFormRadio() returns one of these status codes:

• cgiFormNoSuchChoice: The radio box submitted does not match any of the possibilities in the valuesText array.
• cgiFormNotFound: No box was checked.
• cgiFormSuccess: A checked radio box was found in the group.

cgiFormSelectMultiple

The cgiFormSelectMultiple() function retrieves the selection numbers associated with a Select element that allows multiple selections. Use this code:

cgiFormResultType cgiFormSelectMultiple(char *name, char **choicesText,
  int choicesTotal, int *result, int *invalid)

Table 8.23 explains the parameters of the cgiFormSelectMultiple() function.

cgiFormSelectMultiple() returns one of these status codes:

• cgiFormNotFound: No valid selections were submitted.
• cgiFormSuccess: At least one valid selection was retrieved successfully.

cgiFormSelectSingle

The function cgiFormSelectSingle() retrieves the selection number associated with a Select element that does not allow multiple selections. Use this code:

cgiFormResultType cgiFormSelectSingle(char *name, char **choicesText,
  int choicesTotal, int *result, int defaultV)

Table 8.24 explains the parameters of the cgiFormSelectSingle() function.

cgiFormSelectSingle() returns one of these status codes:

• cgiFormNoSuchChoice: The selection does not match any of the possibilities in the choicesText array.
• cgiFormNotFound: No selection was submitted.
• cgiFormSuccess: The value was retrieved successfully.

Using Header Output Functions

Only one of the CGI Header functions-cgiHeaderLocation(), cgiHeaderStatus(), or cgiHeaderContentType()-should be invoked for each CGI transaction.

You call cgiHeaderLocation() to specify a new URI if the document request should be redirected. You call cgiHeaderStatus() if you want to respond to a request with an HTTP error status code and message; see the HTTP documentation for the legal codes. You usually call cgiHeaderContentType(), however, to specify the MIME type of the document (such as text/html); you then can output the actual document directly to cgiOut.

cgiHeaderContentType

The cgiHeaderContentType() function should be called if the programmer wants to output a new document in response to the user's request. This is the normal case. The single argument is the MIME document type of the response; typical values are text/html for HTML documents, text/plain for plain ASCII without HTML tags, image/gif for GIF images, and audio/basic for .au-format audio.

Use this code:

void cgiHeaderContentType(char *mimeType)

cgiHeaderLocation

The cgiHeaderLocation() function should be called if the programmer wants to redirect the user to a different URI. No further output is needed in this case. Use this code:

void cgiHeaderLocation(char *redirectUrl)

cgiHeaderStatus

The cgiHeaderStatus() function should be called if the programmer wants to output an HTTP error status message instead of a document. The status code is the first argument; the second argument is the status message to be displayed to the user. Use this code:

void cgiHeaderStatus(int status, char *statusMessage)

cgiMain

The programmer must write this function, which performs the unique task of the program and is invoked by the true main() function, found in the cgic library itself. The return value from cgiMain will be the return value of the program. It is expected that the user will make numerous calls to the cgiForm functions from within this function. See "Writing a cgic Application," earlier in this chapter, for details.

Use this code:

int cgiMain()

cgiSaferSystem

The cgiSaferSystem() function is a convenience function used to invoke the system() function less dangerously. That is, cgiSaferSystem() escapes the shell metacharacters ; and |, which can otherwise cause other programs to be invoked beyond the one intended by the programmer. However, understanding the shell commands you invoke and ensuring that you do not invoke the shell in ways that permit the Web user to run arbitrary programs is your responsibility. Use this code:

int cgiSaferSystem(char *command)

cgiWriteEnvironment and cgiReadEnvironment

These two functions are designed to work together:

• The function cgiWriteEnvironment() can be used to write the entire CGI environment, including form data, to the specified output file. Use this code:
  cgiEnvironmentResultType cgiWriteEnvironment(char *filename)
• The function cgiReadEnvironment() restores a CGI environment saved to the specified file by cgiWriteEnvironment(). Use this code:
  cgiEnvironmentResultType cgiReadEnvironment(char *filename)

The function cgiReadEnvironment() can be used to restore environments saved by the cgiWriteEnvironment() from the specified input file. Of course, these will work as expected only if you use the cgic copies of the CGI environment variables and cgiIn and cgiOut rather than STDIN and STDOUT. These functions are useful in order to capture real CGI situations while the Web server is running, and then to re-create them in a debugging environment.

Both functions return one of these status codes:

• cgiEnvironmentIO: Indicates an I/O error.
• cgiEnvironmentMemoryOn: Indicates an out-of-memory error.
• cgiEnvironmentSuccess: Indicates success.

A cgic Variable Reference

This section provides a reference guide to the various global variables provided by cgic for the programmer to use. These variables always should be used in preference to STDIN, STDOUT, and calls to getenv() in order to ensure compatibility with the cgic CGI debugging features.

Most of these variables are equivalent to various CGI environment variables. The most important difference is that the cgic environment string variables are never null pointers. They always point to valid C strings of zero or more characters. Table 8.25 lists the environment string variables.

Summary

In this chapter, you learned about three very useful existing libraries on the Net: cgi-lib.pl, CGI.pm, and cgic. You should be able to put these libraries to regular use, saving yourself countless hours of time reinventing existing applications. I hope that you have the opportunity to return to this chapter many times in the future for use as a valuable reference tool.

Listing 8.7. Using self-referencing URLs to jump to internal links.

01: #!/usr/local/bin/perl
02:
03: use CGI;
04: $query = new CGI;
05:
06: # We generate a regular HTML file containing a very long list
07: # and a pop-up menu that does nothing except to show that we
08: # don't lose the state information.
09: print $query->header;
10: print $query->start_html("Internal Links Example");
11: print "<H1>Internal Links Example</H1>\n";
12:
13: print "<A NAME=\"start\"></A>\n"; # an anchor point at the top
14:
15: # pick a default starting value;
16: $query->param('amenu','FOO1') unless $query->param('amenu');
17:
18: print $query->startform;
19: print $query->popup_menu('amenu',[('FOO1'..'FOO9')]);
20: print $query->submit,$query->endform;
21:
22: # We create a long boring list for the purposes of illustration.
23: $myself = $query->self_url;
24: print "<OL>\n";
25: for (1..100) {
26:     print qq{<LI>List item #$_<A HREF="$myself#start">Jump to top</A>\n};
27: }
28: print "</OL>\n";

Listing 8.8. Saving state information to a file.

01: use CGI;
02: $query = new CGI;
03:
04: print $query->header;
05: print $query->start_html("Save and Restore Example");
06: print "<;H1>Save and Restore Example<;/H1>\n";
07:
08: # Here's where we take action on the previous request
09: &save_parameters($query)              if $query->param('action') eq 'save';
10: $query = &restore_parameters($query)  if $query->param('action') eq
  'restore';
11:
12: # Here's where we create the form
13: print $query->startform;
14: print "Popup 1: ",$query->popup_menu('popup1',
 ['eenie','meenie','minie']),"\n";
15: print "Popup 2: ",$query->popup_menu('popup2',['et','lux','perpetua']),"\n";
16: print "<;P>";
17: print "Save/restore state from file: ",$query->textfield('savefile',
 'state.sav'),"\n";
18: print "<;P>";
19: print $query->submit('action','save'),$query->submit('action','restore');
20: print $query->submit('action','usual query');
21: print $query->endform;
22:
23: # Here we print out a bit at the end
24: print $query->end_html;
25:
26: sub save_parameters {
27:     local($query) = @_;
28:     local($filename) = &clean_name($query->param('savefile'));
29:     if (open(FILE,">$filename")) {
30:      $query->save(FILE);
31:      close FILE;
32:      print "<;STRONG>State has been saved to file $filename<;/STRONG>\n";
33:     } else {
34:      print "<;STRONG>Error:<;/STRONG>
  couldn't write to file $filename: $!\n";
35:     }
36: }
37:
38: sub restore_parameters {
39:     local($query) = @_;
40:     local($filename) = &clean_name($query->param('savefile'));
41:     if (open(FILE,$filename)) {
42:      $query = new CGI(FILE);
 # Throw out the old query, replace it with a new one
43:      close FILE;
44:      print "<;STRONG>State has been restored from file
  $filename<;/STRONG>\n";
45:     } else {
46:      print "<;STRONG>Error:<;/STRONG> 
 couldn't restore file $filename: $!\n";
47:     }
48:     return $query;
49: }
50:
51:
52: # Very important subroutine - get rid of all the naughty
53: # metacharacters from the file name. If there are, we
54: # complain bitterly and die.
55: sub clean_name {
56:    local($name) = @_;
57:    unless ($name=~/^[\w\.-]+$/) {
58:       print "<;STRONG>$name has naughty characters.  Only ";
59:       print "alphanumerics are allowed.  You can't use absolute
  names.<;/STRONG>";
60:       die "Attempt to use naughty characters";
61:    }
62:    return $name;
63: }

Q&A