HTML 4.0 Sourcebook
(Publisher: John Wiley & Sons, Inc.)
Author(s): Ian S. Graham
ISBN: 0471257249
Publication Date: 04/01/98

Client Sends to Server (HTTP)

There are three ways data can be sent from a client to a server. These are:

As a URL query string. An example URL is:

<http://some.site.edu/cgi-bin/ex_prog?query_info>

This passes the query string query_info to the server. The server, in turn, places the query string within an environment variable and then launches the gateway program ex_prog, which, in turn, obtains the query string from the environment variable.

As extra path information in the URL. Extra path information is placed in the URL by adding directory-like information to the URL, just after the name of the gateway program. An example is (extra path in boldface):

<http://some.site.edu/cgi-bin/ex_prog/dir/file?query_info>

If the server knows that /cgi-bin/ex_prog references a gateway program, then the string /dir/file is interpreted by the server as extra path information, while query_info is again the query string. When the server launches the gateway program ex_prog, it passes both the query string query_info and the extra path string /dir/file to ex_prog. In both cases, these data are passed to the gateway program within environment variables.

As data sent to the server in a message body. This is possible with the HTTP POST method and is commonly used with HTML FORMs. When a server receives a POST method message from a FORM, it sends the POSTed data to the designated gateway program. The gateway program reads the data from its standard input.

Server Sends to Gateway (CGI)

The CGI specifications define the mechanisms by which data are forwarded by a server to a gateway program. There are three mechanisms:

Command-line arguments. The server launches the gateway program and passes data to the program as command-line arguments. This occurs only with a GET method request arising from an ISINDEX query.

Environment variables. The server puts information in environment variables before starting the gateway program—the gateway program can then access these variables and obtain their contents. Everything contained in the HTTP headers sent by a client is placed in these environment variables. Thus, environment variables contain the query string and the extra path information discussed previously, as well as the content of every request header field sent by the browser. There are also environment variables containing information about the server, such as the home directory for the documents, the type of server, and the server’s domain name.

Standard input. The gateway program reads data from standard input. This is how message data, sent by a browser using the POST method, are passed to the gateway program.

The mechanisms relevant during a particular transaction depend on the HTTP method used (GET or POST) and on the nature of the query string appended to the URL (ISINDEX versus non-ISINDEX queries). Examples illustrating typical cases are given later in this chapter.

Gateway Sends to Server (CGI)

There are two mechanisms by which a CGI program sends information back to the server:

By writing to standard output. A gateway program passes results back to the server by writing to standard output—this is the only way a gateway program can return data. In general, the returned data are in two parts. The first part is a collection of server directives, which are parsed by the server and are used by the server to compose the response header that the server sends ahead of the returned data. The second part is the actual data being returned by the gateway program. The two parts are separated by a blank line containing only a CRLF (carriage return linefeed) pair.

By the name of the gateway program. Gateway programs with names beginning with the string nph- are called non-parsed header programs and are treated specially by the server. As just mentioned, the server usually parses the output of a gateway program and uses the server directives to create the HTTP response header that is sent to the client ahead of the returned data. If a gateway program name begins with nph-, the server sends the gateway program output directly to the client without this extra processing, which means the server does not add any header information. In this case, a gateway program must itself provide all required HTTP response header fields.

These methods are illustrated in the following five examples. Example 20 looks at an HTML ISINDEX document request. Example 21 demonstrates non-parsed header gateway programs, which send data directly back to the client, bypassing any server processing. Example 22 shows how environment variables are passed to the gateway program and explains the contents of these variables. Examples 23 and 24 show how data from HTML FORMs—using the GET and POST methods, respectively—are passed to a gateway program. These examples also explain how these data are decoded by a gateway program.

Example 20: ISINDEX Searches

ISINDEX is the only query method that passes data to a gateway program as command-line arguments. It is a simple technique, and a useful starting point for understanding client-server-gateway interactions.

This example accesses the gateway program srch-example listed in Figure 10.2, which is a Bourne-shell script designed to search a phone-number database via the search program grep. The script searches for names in a phone-number database and uses the ISINDEX element to prompt for the search string. In this example, the search string is just the list of names you want to search for. When the script receives these data, it searches the database for the indicated names and returns the names and phone numbers of any matches. The script is designed both to prompt for search strings and return the results of the search.