Internet

Beginning CGI Programming with Perl

After reading Tutorial 1 you now can install your own programs, and you know your way around your server. In this Tutorial, you will learn how the server and the browser (client) talk to each other. Understanding how the server and the client communicate will help you build and debug your CGI programs.

In particular, you will learn about these topics:

  • Using the uniform resource identifier (URI)
  • Understanding how the browser requests your Web page
  • Using the TCP/IP protocol
  • Using status codes in response headers
  • Using HTTP request headers
  • Using HTTP response headers
  • Returning a Web page based on the User-Agent header

Using the Uniform Resource Identifier

First let’s get some terminology straight. Requests to the server are in the form of a URI. A URI is a uniform resource indicator.

You might be familiar with the term URL, or maybe you use URN (uniform resource name). Quite honestly, there are a number of valid names for this term. The ncSA gurus who wrote the HTTP specifications use both the term URI and URL. They started out using URI, and I’m going to try to follow their convention. I will use URI throughout these tutorials. You can substitute whatever name you are familiar with in its place.

A URI is made up of basically three fields. You probably are familiar with at least the first two parts of a URI, and all parts are discussed in detail in the following sections. A URI has this format:

protocol://<domain name>/<requested file>

The Protocol

The first field of a URI is the Protocol field. The Protocol field specifies the Internet protocol that will be used to transfer the data between the client and the server. There are many valid Internet protocol schemes: FTP, WAIS, Gopher, Telnet, HTTP, and more. For the purposes of these tutorials, the only protocol you will be interested in is HyperText Transport Protocol (HTTP). And, by the way, that’s why the messages passed between the client and the server are called HTTP headers. HTTP is used to designate files, programs, and directories on a remote or local server.

The Domain Name

Immediately following the protocol is a :// and then the domain name. The domain name is the machine address of your server on the Internet. This name or address is between the :// and the next forward slash (/).

Following the domain name and before the trailing forward slash is an optional :port number. If no port number is given, the default port of 80 is assumed. The port number as it relates to HTTP and CGI is explained in Tutorial 3 “Using Server Side Include Commands.” Briefly, the UNIX server handles different services by sending messages received at different port addresses to programs registered for those ports. The default port for the HTTP daemon is 80. Other programs, such as FTP and Telnet, have different default port addresses. These system default port addresses are set in a file named services under the system directory /etc.

The Directory, File, or CGI Program

The path the server uses to find your program follows the first single forward slash (/). The server checks each element of this path to determine whether a file, a program, or a directory is being requested.

An element is a section of the path, target directory, program, or filename. Each element is separated by a beginning and ending forward slash. In the following example, you can see that element 1 is cgibook, element 2 is chap2, and element 3 is test.html:

/cgibook/chap2/test.html

If the last element is a directory and no further elements follow, the server does one of three things:

  • If there is an index.html file in the directory, that file is returned. index.html is the default home page name. (You can set the default home page name in the srm.conf file.)
  • If there is not an index.html file and Directory Listing is turned on, a Gopher-like directory listing is returned. (Directory Listing is an OPTION argument enabled in the access.conf file. This server configuration issue is discussed, along with other configuration issues, in Tutorial 12, “Guarding Your Server Against Unwanted Guests.”)
  • If Directory Listing is turned off, error status code 404, NOT FOUND, is returned.

If the element is a directory and more elements follow, the next element is checked.

Because PATH_INFO and QUERY_STRING data can be added to the URI after the target filename or program, the execution of the program or returning of the file does not occur until the entire URI is parsed. Each element of the URI is parsed until the target filename, program, or directory is found. If the next element is a file, the file is returned to the client.

If the next element is a program, the program is executed and the data it generates is returned to the client. (As long as valid response headers are generated.)

After the target URI (file, program, or directory) is identified, the server continues looking for PATH_INFO and QUERY_STRING data. PATH_INFO is added after the target URI. Any valid text data can be added after the target URI. The PATH_INFO data is terminated by a question mark (?), as shown here, where PATH_INFO is more-information:

/cgibook/chap2/test.html/more-information?

Before the target URI is invoked, the environment variable’s PATH_INFO and QUERY_STRING data are set. So if there are any additional elements after the target URI, then any data after the file and before a trailing question mark (?) is converted to path information and made available as environment variables.

Additional data can be appended to the URI by adding a question mark to the last element instead of a forward slash. This data then is called the QUERY_STRING and also is made available as an environment variable.

QUERY_STRING data also can be any valid text data. It begins after the PATH_INFO data, as shown in the following line of code, and is limited only by the size of the input buffer-usually, 1,024 bytes:

/cgibook/chap2/test.html/more-information?Query-name= Query-value&Q2=Joe&last=Smith

QUERY_STRING data normally follows a predefined format, which is explained in Tutorial 5 “Decoding Data Sent to Your CGI Program.” Environment variables are covered in Tutorial 6 “Using Environment Variables in Your Programs.”

Requesting Your Web Page with the Browser

So what happens when someone clicks on your URI? Figure 2.1 shows the sequence of events that occur when the browser requests and the server returns a Web page. Your CGI program and the Web page calling it are closely linked (pun intended).

Figure 2.1 : The client/server connection.

When a link to your CGI program is activated, the browser or client generates request headers. The server receives the request headers, which include the address to your CGI program on the server. The server translates the headers into environment variables and executes your CGI program. Your CGI program must generate the required response headers and HTML for the server to return to the browser.

When is my browser my client?

I switch between the terms browser and client frequently throughout these tutorials. Strictly speaking, your browser-Netscape, Mosaic, or whatever-acts as both a client and a server. The browser is a client when the user requests Web services (URIs) by clicking something on a Web page. The browser can be a server when the URI requests that the browser launch an application.

The basics of client/server are very simple. The client requests something, and the server satisfies the request.

Try this example. You are at a restaurant.

  1. You are the client. Your waiter, the server, takes your order.
  2. The waiter goes to the kitchen and gives the cook your order. The waiter is the client to the cook, and the cook is the server.
  3. Your order is completed. The cook (still the server) gives your order to the waiter, the client.
  4. The waiter, again the server, brings you-now the client-your order.

Client/server in a nutshell! For the most part, I will refer to the browser as a client and the machine that has the URI as the server.

The basics of client/server are very simple. The client requests something, and the server satisfies the request.

First, the browser/client makes a connection to the receiving program/server. The browser uses the domain name address as the phone number or address to reach the server.

Note

Remember that the server is just a computer connected somewhere at the other end of a wire. As far as the Internet is concerned, it makes no difference whether the server is in the same room or halfway across the world. There is, of course, some time delay difference between talking across the room and across the world. But think of it as similar to talking on the phone. Whether you are talking locally or across the country, you don’t expect there to be any time lag in the conversation.

The browser looks up the domain name address-the information after the http:// and before the next forward slash (/). In

http://www.practical-inet.com/

for example,

www.practical-inet.com

is the domain name address.

Next, the browser sends the following request headers to the identified domain:

  • A request header identifying the file or service (URI) being requested
  • Request header fields identifying the browser
  • Additional specialized information about the request
  • Any data that goes with the request

These are all called HTTP request headers. They identify to the server the basic information the client is requesting and what type of response can be accepted by the client. The server also takes all the headers sent by the client and makes them available to your CGI program in a format called environment variables (Tutorial 6goes into more detail about these).

If the calling Web page is an HTML form that is sending data to your CGI program, that data also is included in the initial transaction.

The server looks at the first incoming header-the method request header-and tries to find the URI. It does this by starting at its top-level server root directory and searching for a file that matches the URI listing. The server looks at each pathname after the domain name looking for a valid filename.

Take a look at this example of an HTTP request. You’ll use it to cement all of this theory with a concrete example of how the server finds the correct file from the incoming request header:

http://www.practical-inet.com/cgibook/chap2/test.html/more-information

First, the server checks the element name cgibook. Then, because this is a directory, the server continues to chap2, another directory.

Next, the server finds that test.html is a filename. So the server examines the file extension. Because the file extension identifies this as a valid text type, the server begins the job of sending the requested URI back to the client.

One more thing before leaving the URI in the example-more-information is after test.html. This information is called extra path information and is saved and made available to the requested URI as an environment variable.

Now the server must respond with the response headers. The first response header is a status line, which tells the client the result of the search for the requested URI. This response can range from Success to Authorization Required or even Location Moved. If the status is Success, the contents of the requested URI usually are returned to the client/browser and displayed on the client’s computer screen.

The next section discusses in further detail what the request and response headers look like and when and how they are sent.