Input to CGI Programs

CGI programs can get input from these sources:

• Command line: The only type of input that go to the command line of a CGI program are values typed into an <ISINDEX> field and query strings that do not contain an "=" sign (from a direct link). Forms cannot send variables to the command line.

• Environment variables: A number of standard environment variables are always available to the CGI program (see page 108). You can specify additional environment variables in the AOLserver configuration file (see page 105). And, if the METHOD for a form is GET, the field names and values are stored in the QUERY_STRING environment variable (see page 111).

• Standard input: If the METHOD for a form is POST, the field names and values are sent to standard input (see page 114).

Accessing Environment Variables

Different languages allow you to access environment variables in different ways. Here are some examples:

C or C++	#include <stdlib.h> char *browser = getenv("HTTP_USER_AGENT");
Perl	$browser = $ENV{`HTTP_USER_AGENT'};
Bourne shell	BROWSER=$HTTP_USER_AGENT
C shell	set BROWSER = $HTTP_USER_AGENT

Standard Environment Variables

These standard environment variables are defined for all CGI programs by the AOLserver:

AUTH_TYPE:

If the server supports user authentication, and the script is protected, this is the protocol-specific authentication method used to validate the user. For CGI programs run by AOLserver, this is always "Basic".

Example: Basic

CONTENT_LENGTH:

If the CGI program is run by a form with the POST method, this variable contains the length of the contents of standard input in bytes. There is no null or EOF character at the end of standard input, so in some languages (such as C and Perl) you should check this variable to find out how many bytes to read from standard input. (See page 111 for details about the format of the contents of standard input and page 114 for examples that read from standard input.)

Example: 442

CONTENT_TYPE:

If the CGI program is run by a form with the POST method, this variable contains the MIME type of the information sent by the browser. Currently, all browsers should send the information as application/x-www-form-urlencoded. Other types may be added in the future.

GATEWAY_INTERFACE:

The version number of the CGI specification this server supports.

Example: CGI/1.1

HTTP_ACCEPT:

A comma-separated list of the MIME types the browser will accept, as specified in the HTTP header the browser sends. Many browsers do not send complete lists, and the list does not include external viewers the user has installed. If you want to send browser-specific output, you may also want to check the browser name, which is specified by the HTTP_USER_AGENT variable.

Examples: */*, application/x-navidoc

    		*/*, image/gif, image/x-xbitmap, image/jpeg

HTTP_FROM:

This variable may contain the email address of the reader who caused the CGI program to run. However, some browsers do not send the email address for privacy reasons. And, users may enter false email addresses in their preferences settings.

Example: itsme@mydomain.com

HTTP_IF_MODIFIED_SINCE:

This variable contains a date and time if the browser wants a response only if the data has been modified since the specified date and time. The date is in GMT standard time. Many browsers do not send this information.

Example: Thursday, 23-Nov-95 17:00:00 GMT

HTTP_REFERER:

This variable contains the URL of the page or other location from which the reader sent the request to run the CGI program. For example, if the reader runs the program from a form, this variable contains the URL of that form.

Example: http://www.mydomain.com/mydir/feedback.htm

HTTP_USER_AGENT:

This variable tells which browser the reader is using to send the request. Normally, the format is "browser name/version".

Example: Mozilla/1.2N (Windows; I; 16bit)

PATH_INFO:

This variable contains any extra path information included in the URL sent by the browser. Commonly, this type of URL is used to pass a relative directory location to your program. For example, the following URL runs the listdir program and passes it /misc/mydir as extra path information:

    
    http://www.mysite.com/cgi-bin/listdir/misc/mydir

Another use for this type of URL is to pass information to the program without using a form or to pass form-specific variables in addition to the user-specified variables. For example:

    
    http://www.mysite.com/cgi-bin/search/keyword=navigate
    

Examples: /misc/mydir

    		/keyword=navigate

PATH_TRANSLATED:

This variable translates the relative path from PATH_INFO into the absolute path by prepending the server's root directory for Web documents. This is useful because PATH_INFO, which the reader can view, need not reveal the physical location of your files on the server.

Example: /AOLserver/pages/misc/mydir

QUERY_STRING:

This variable contains information passed by a form or link to the program. The QUERY_STRING contains information in the following situations:

• The reader submitted a form that uses the GET method.

• The reader submitted a query in a page with the <ISINDEX> tag. (The text the user types is also decoded and sent to the program's command line in this situation. The QUERY_STRING provides the non-decoded information.)

• A direct link included information after a "?" in the URL.

The QUERY_STRING is encoded in a format like this:

    
    Field1=Value1&Field2=Value2&Field3=Value3

Your CGI program should decode the QUERY_STRING. Functions that decode this string are publicly available functions for most languages. (See page 118 for a list of Web sites containing such functions.) The string encoding follows these rules:

• Field name/value pairs are separated by an "&" sign.

• A field's name and its value are separated by an "=" sign. Field names are specified by the NAME attribute. Field values depend on the type of field:

  Text field and text area: The value is the text typed into the field. Multiline text is sent as one line with the return character encoded as described below.

  Radio Buttons: The value is the value of the button that is selected.

  Checkbox: The name and value usually appear in the list only if the box is checked. Some browsers may send the name of the checkbox only.

  Selection List: The value of a selection list is the text of the item that is selected. If multiple items can be selected, there is a name/value pair with the same name for each item that is selected.

  Image Field: Two name value pairs are sent. ".x" and ".y" are added to the field name and the values are the x and y coordinates (measured in pixels from an origin at the upper-left corner of the image). For example:

    Figfield.x=185&Figfield.y=37

Hidden Fields: You can use hidden fields with fixed values (or values set when a CGI program generated the page). The value is set with the VALUE attribute. Some older browsers make hidden fields visible.

Range Fields: The value is the numeric value of the field (sent as a string). Some browsers do not support range fields.

Named Submit Buttons: You can place multiple Submit buttons in a form. If you add a NAME attribute to the Submit button, that name will be sent, along with the label of the button as the value. All the Submit buttons in a form run the same CGI program, but the CGI program can perform different actions based on which button was clicked. Some browsers do not support named submit buttons.

• Spaces are replaced by "+" signs.

• Special characters are replaced by a "%" sign followed by the hexadecimal value of the character. Here are some common characters and their hex values:

  # -- %23	= -- %3D	/ -- %2F
  % -- %25	: -- %3A	\ -- %5C
  & -- %26	; -- %3B	tab -- %0A
  + -- %2B	? -- %3F	return -- %09

REMOTE_ADDR:

The IP address of the machine from which or through which the browser is making the request. This information is always available.

Example: 199.221.53.76

REMOTE_HOST:

The full domain name of the machine from which or through which the browser is making the request. If this variable is blank because the browser did not send the information, use the REMOTE_ADDR variable instead.

Example: mybox.company.com

REMOTE_USER:

If the server prompted the reader for a username and password because the script is protected by the AOLserver's access control, this variable contains the username the reader provided.

Example: nsadmin

REQUEST_METHOD:

The method used to send the request to the server. For direct links, the method is "GET". For requests from forms, the method may be "GET" or "POST". Another method is "HEAD", which CGI programs can treat like "GET" or can provide header information without page contents.

SCRIPT_NAME:

The virtual path to the CGI script or program being executed from the URL used to execute the script. You may want to use this variable if the program generates a page that contains a form that can be used to run the program again -- for example, to search for another string.

Example: /cgi-bin/search

SERVER_NAME:

The full hostname, domain name alias, or IP address of the server that ran the CGI program.

Example: www.mysite.com

    		128.111.115.9

SERVER_PORT:

The server port number to which the request was sent. This may be any number between 1 and 65,535 (that is not already a well-known port). The default is 80.

Example: 80

SERVER_PROTOCOL:

The name and version number of the information protocol used to pass this request from the client to the server.

Example: HTTP/1.0

SERVER_SOFTWARE:

The name and version number of the server software running the CGI program.

Example: AOLserver/3.0

Other Environment Variables:

In addition to the preceding environment variables, the HTTP header lines received from the client, if any, are placed into the environment with the prefix HTTP_ followed by the header name. Any spaces in the header name are changed to underscores (_). The server may exclude any headers it has already processed, such as Content-type, and Content-length.

Also, you can specify environment variables to be passed to a CGI program in the AOLserver configuration file (see page 105).

Accessing Standard Input

If a form uses the POST method to send a request, the field names and values are sent to standard input and the length of this string is provided in the CONTENT_LENGTH environment variable. The format of the standard input string is the same as the format of the QUERY_STRING environment variable when the GET method is used (see page 111).

Different languages allow you to access the standard input in different ways. Here are some simplified examples. Your programs should also do some error checking.

C or C++	#include <stdio.h> #include <stdlib.h> #define MAX_CONTENT_LENGTH 10000 char *inputlenstr; int inputlen; int status; char inputtext[MAX_INPUT_LENGTH+1]; inputlenstr = getenv("CONTENT_LENGTH"); inputlen = atoi(inputlenstr); status = fread(inputtext, 1, inputlen, stdin);
Bourne shell	read input (reads contents to $input variable)