Platinum Edition Using HTML 4, XML, and Java 1.2
(Publisher: Macmillan Computer Publishing)
Author(s): Eric Ladd
ISBN: 078971759x
Publication Date: 11/01/98

•  Try to encapsulate private data and processing. Your routines should have a defined input and output: one door in, one door out, and you know who’s going through the door. How your routines accomplish their tasks isn’t any of the calling routine’s business. This is called the black box approach. What happens inside the box can’t be seen from the outside and has no effect on it. A properly encapsulated lookup routine that uses flat file tables, for example, can be swapped for one that talks to a relational back end database without changing any of the rest of your program.

•  Document your program as you go along. Self-documenting code is the best approach, with generous use of comments and extra blank lines to break up the code. If you use sensible, descriptive names for your variables and functions, half your work is already done. But good documentation doesn’t just tell what a piece of code does; it tells why. “Assign value of REQUESTMETHOD to pRequestMethod,” for example, tells what your code does. “Determine if you were invoked by GET or POST” tells why you wrote that bit of code and, ideally, leads directly to the next bit of code and documentation: “If invoked via GET, do this,” or “If invoked via POST, do this.”

•  Define your output beforehand as carefully as you plan the input. Your messages to the user should be standardized. For instance, don’t report a file-locking problem as Couldn’t obtain lock. Please try again later, and report a stack overflow error as ERR4332. Your success messages should be consistent as well. Don’t return You are the first visitor to this site since 1/1/96 one time and You are visitor number 2 since 01-01-96 the next.
If you chart your data flow and group your functions logically, each type of message will be produced by the appropriate routine for that type. If you hack the code with error messages and early-out success messages sandwiched into your program’s logic flow, you’ll end up with something that looks inconsistent to the end user and looks like a mess to anyone who has to maintain your code.

Standard CGI Environment Variables

The following is a brief overview of the standard environment variables you’re likely to encounter. Each server implements the majority of them consistently, but variations, exceptions, and additions exist. In general, you’re more likely to find a new, otherwise undocumented variable omitted rather than a documented variable. The only way to be sure, though, is to check your server’s documentation.

This section is taken from the NCSA specifications and is the closest thing to “standard” as you’ll find. The following environment variables are set each time the server launches an instance of your script and are private and specific to that instance:

•  AUTH_TYPE—If the server supports basic authentication and if the script is protected, this variable will provide the authentication type. The information is protocol and server-specific. An example of AUTH_TYPE is BASIC.

•  CONTENT_LENGTH—If the request includes data using the POST method, this variable will be set to the length of valid data supplied in bytes through STDIN; for example, 72.

•  CONTENT_TYPE—If the request includes data, this variable will specify the type of data as a MIME header; for example, application/x-www-form-urlencoded.

•  GATEWAY_INTERFACE—Provides the version number of the CGI interface supported by the server in the format CGI/version-number; for example, CGI/1.1.

•  HTTP_ACCEPT—Provides a comma-delimited list of MIME types that are acceptable to the client browser; for example, image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, and */*. This list actually comes from the browser itself; the server just passes it on to the CGI script.

•  HTTP_USER_AGENT—Supplies the name, possibly including a version number or other proprietary data, of the client’s browser, such as Mozilla/2.0b3 (WinNT; I).

•  PATH_INFO—Shows any extra path information supplied by the client, tacked onto the end of the virtual path. This is often used as a parameter to the script. For example, with the URL http://www.yourcompany.com/cgi-bin/myscript.pl/dir1/dir2, the script is myscript.pl and the PATH_INFO is /dir1/dir2.

•  PATH_TRANSLATED—Supported by only some servers, this variable contains the translation of the virtual path to the script being executed (that is, the virtual path mapped to a physical path). If, for example, the absolute path to your Web server root is /usr/local/etc/httpd/htdocs and your cgi-bin folder is in the root level of your Web server (that is,
http://www.mycorp.com/cgi-bin), a script with the URL
http://www.mycorp.com/cgi-bin/search.cgi would have the PATH_TRANSLATED variable set to /usr/local/etc/httpd/htdocs/cgi-bin/search.cgi.

•  QUERY_STRING—Shows any extra information supplied by the client, tacked onto the end of a URL and separated from the script name with a question mark; for example, http://www.yourcompany.com/hello.html?name=joe&id=45 yields a QUERY_STRING of name=joe&id=45.

•  REMOTE_ADDR—Provides the IP address of the client making the request. This information is always available; for example, 199.1.166.171.

•  REMOTE_HOST—Furnishes the resolved host name of the client making the request; for example, dial-up102.abc.def.com. Often, this information is unavailable for one of two reasons: Either the caller’s IP is not properly mapped to a host name via DNS, or the Webmaster at your site has disabled IP lookups. Webmasters often turn off lookups because they mean an extra step for the server to perform after each connect, and this slows down the server.