CGI Interface -- How Web Pages Run CGI Programs

How Web Pages Run CGI Programs

There are several ways a Web page can run a CGI program:

Direct Link: A link in your page can reference a CGI program directly. Normally, such links are used when you do not need to send any variables to the program.
<ISINDEX> Tag: This tag can be included in the <HEAD> section of the page. For example, you could add this tag:
```
    <ISINDEX HREF="/cgi-bin/search.pl" PROMPT="Search for:"> 
```
Normally, the <ISINDEX> tag is used to run search programs, but this is not a requirement. You can use this tag to run CGI programs if you don't care where the field is located in your page and your program accepts a single variable.
When you use this tag, the browser adds a field to the Web page. Readers can type a string in this field. The server decodes the text the reader typed and sends it to your CGI program as separate command-line arguments. The advantage is you don't need to decode the input.
Form: You can create a form with multiple fields. Use forms to run CGI programs when your readers can choose or type values for one or more variables.The METHOD attribute of the <FORM> can be either "GET" or "POST".
- The "GET" method causes the field names and values to be passed to the program in the QUERY_STRING environment variable.
- The "POST" method causes the field names and values to be passed to the program through standard input. If the input from your form may be long, it is best to use the POST method because long strings can be truncated when they are assigned to an environment variable.

URLs that Run CGI Programs

For each method of running a CGI program described in the previous section, the browser software sends a URL to the server. (In addition, the HTTP header sent with the URL includes some environment variables, which are described on page 108.)

Generally the URL to run a CGI program can have these parts:

CGI path[/extra path information ][?query string]

The CGI path is the location of the CGI program to run. The path can be a relative or absolute reference to the program file.
The optional extra path information can be included in the URL to provide either a directory location the CGI program should use or some extra information for the CGI program. The path is relative to the root directory for Web pages. The extra path information is available to the CGI program in the PATH_INFO environment variable.
The optional query string is preceded by a question mark (?) and contains either a single variable or a set of field names and variables for the CGI program to use. The query string is available to the CGI program in either the QUERY_STRING environment variable or the standard input location (if the form method is POST).

For example, the query string from a form with 3 fields could be:

Field1=Value1&Field2=Value2&Field3=Value3

Spaces in the query string are replaced with plus signs (+). Any special characters (such as ?, =, &, +) are replaced with %xx, where xx is the hexadecimal value for that character. (See page 111 for more on how the query string is encoded.)

Here are some examples of URLs that could run a CGI program:

http://www.mysite.com/cgi-bin/gettime

This URL runs the gettime program, which could return a page with the current time. There are no variables, so you might use this as a direct link.
http://www.mysite.com/cgi-bin/listdir/misc/mydir

This URL runs the listdir program and passes it /misc/mydir as extra path information. This might be a direct link in a page.
http://www.mysite.com/cgi-bin/search?navigate

This URL runs the search program and passes it the word "navigate" as input. This URL doesn't include any field names, so it might be passed by pages with an <ISINDEX> tag.
http://www.webcrawler.com/cgi-bin/WebQuery?searchText=word

This is a real URL that runs the WebCrawler search program and passes a value for the searchText field of "word". Normally, CGI programs that accept field values like these are run from a form.

If your programs are not executed, make sure the program file allows read and execute access.

Top of Page
Copyright © 1998-99 America Online, Inc.