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

•  Don’t assume your environment—For example, just because the temp directory was C:\Temp on your development system, don’t assume that it will be the same wherever your script runs. Never hard code directories or filenames. This goes double for Perl scripts, where this travesty of proper programming happens most often. If your Perl script to tally hits needs to exclude a range of IP addresses from the total, don’t hard code the addresses into the program and say, “Change this line” in the comments. Use a configuration file.

•  Don’t assume privileges—On a UNIX machine, the server (and therefore your script) may run as the user nobody, as root, or as any privilege level in between. On a Windows NT machine, too, CGI programs usually inherit the server’s security attributes. Check for access rights and examine return codes carefully so you can present intelligible error information to the user in case your script fails because it can’t access a resource. Some NT servers enable you to specify a user account for CGI programs that’s separate from the user account for the Web server. Microsoft’s IIS does this and goes one step beyond: For CGI programs with authentication, the CGI runs in the security context of the authenticated user.

•  Don’t assume consistency of CGI variables—Some servers pass regular environment variables (for instance, PATH and LIB variables) along with CGI environment variables; however, the ones they pass depend on the runtime environment. Server configuration can also affect the number and the format of CGI variables. Be prepared for environment-dependent input and have your program act accordingly.

•  Don’t assume version-specific information—Test for it and include workarounds or sensible error messages telling the user what to upgrade and why. Both server version and operating system version can affect your script’s environment.

•  Don’t assume LAN or WAN configurations—In the Windows NT world, the server can be Windows NT Workstation or Windows NT Server; it may be standalone, part of a workgroup, or part of a domain. DNS (Domain Name Services) may or may not be available; lookups may be limited to a static hosts file. In the UNIX world, don’t assume anything about the configurations of daemons, such as inetd, sendmail, or the system environment, and don’t assume directory names. Use a configuration file for the items that you can’t discover with system calls, and give the script maintainer instructions for editing it.

•  Don’t assume the availability of system objects—As with privilege level, check for the existence of such objects as databases, messaging queues, and hardware drivers, and output explicit messages when something can’t be found or is misconfigured. Nothing is more irritating than downloading a new script, installing it, and getting only Runtime error #203 for the output.

CGI Libraries

When you talk about CGI libraries, two possibilities exist: libraries of code you develop and want to reuse in other projects and publicly available libraries of programs, routines, and information.

Personal Libraries

If you follow the advice given earlier in this chapter in the “Planning Your Script” section about writing your code in a black box fashion, you’ll soon discover that you’re building a library of routines that you’ll use over and over. After you puzzle out how to parse out URL-encoded data, for instance, you don’t need to do it again. And when you have a basic main() function written, it will probably serve for every CGI program you ever write. This is also true for generic routines, such as querying a database, parsing input, and reporting runtime errors.

•  How you manage your personal library depends on the programming language you use. With C and assembler, you can precompile code into actual .Lib files, with which you can then link your programs. Although possible, this likely is overkill for CGI, and it doesn’t work for interpreted languages, such as Perl and Visual Basic. (Although Perl and VB can call compiled libraries, you can’t link with them in a static fashion the way you can with C.) The advantage of using compiled libraries is that you don’t have to recompile all your programs when you make a change to code in the library. If the library is loaded at runtime (a DLL), you don’t need to change anything. If the library is linked statically, all you need do is relink.

•  Another solution is to maintain separate source files and include them with each project. You might have a single, fairly large file that contains the most common routines, but put seldom used routines in files of their own. Keeping the files in source format adds a little overhead at compile time but not enough to worry about, especially when compared to the time savings you gain by writing the code only once. The disadvantage of this approach is that when you change your library code, you must recompile all your programs to take advantage of the change.

•  Nothing can keep you from incorporating public-domain routines into your personal library, either. As long as you make sure that the copyright and license allow you to use and modify the source code without royalties or other stipulations, then you should strip out the interesting bits and toss them into your library.

•  Well-designed and well-documented programs provide the basis for new programs. If you’re careful to isolate the program-specific parts into subroutines, you can cannibalize an entire program’s structure for your next project.

•  You can also develop platform-specific versions of certain subroutines and, if your compiler will allow it, automatically include the correct ones for each type of build. At the worst, you’ll have to manually specify which subroutines you want.

---

NOTE:  The key to making your code reusable is to make it as generic as possible. Don’t make it so generic that, for instance, a currency printing routine needs to handle both yen and dollars, but make it generic enough that any program that needs to print out dollar amounts can call that subroutine. As you upgrade, swat bugs, and add capabilities, keep each function’s inputs and outputs the same, even when you change what happens inside the subroutine. This is the black box approach in action. By keeping the calling convention and the parameters the same, you’re free to upgrade any piece of code without fear of breaking older programs that call your function.

---