On-the-Spot Information
`
`on the World Wide Web
`
`A NUTSHELL®
`
`[g
`
`HANDBOOK
`
`Shishir Gundavaram
`O'Reilly & Associates, Inc.
`
`AHBLT-2007.001
`
`

`
`CGI Programming
`on the World Wide Web
`
`AHBLT-2007.002
`
`

`
`CGI Programming
`on the World Wide Web
`
`Shishir Gundavaram
`
`Bonn
`
`• Cambridge
`
`O'Reilly & Associates, Inc.
`• Paris
`• Sebastopol
`• Tokyo
`
`AHBLT-2007.003
`
`

`
`CG/ Programming on the World Wide Web
`by Shishir Gundavaram
`
`Copyright© 1996 O'Reilly & Associates, Inc. All rights reserved.
`Printed in the United States of America.
`
`Published by O'Reilly & Associates, Inc., 103 Morris Street, Suite A, Sebastopol, CA 95472.
`
`Editors: Andy Oram and Linda Mui
`
`Production Editor: Jane Ellin
`
`Printing History:
`
`March 1996:
`
`First Edition
`
`Nutshell Handbook and the Nutshell Handbook logo are registered trademarks of O'Reilly &
`Associates, Inc.
`
`Many of the designations used by manufacturers and sellers to distinguish their products are
`claimed as trademarks. Where those designations appear in this book, and O'Reilly &
`Associates, Inc. was aware of a trademark claim, the designations have been printed in caps
`or initial caps.
`
`While every precaution has been taken in the preparation of this book, the publisher assumes
`no responsibility for errors or omissions, or for damages resulting from the use of the
`information contained herein.
`
`This book is printed on acid-free paper with 85% recycled content, 15% post-consumer waste.
`O'Reilly & Associates is committed to using paper with the highest recycled content available
`consistent with high quality.
`
`ISBN: 1-56592-168-2
`
`AHBLT-2007.004
`
`

`
`Table of Contents
`
`Preface ................................................................................................. ix
`
`1: The Common Gateway Inteiface (CG/) .................................... 1
`What Is CGI? ......................................................................................................... 1
`CGI Applications .................................................................................................. 2
`Some Working CGI Applications ........................................................................ 5
`Internal Workings of CGI .................................................................................... 6
`Configuring the Server ......................................................................................... 8
`Programming in CGI ............................................................................................ 9
`CGI Considerations ............................................................................................ 13
`Overview of the Book ....................................................................................... 13
`
`2: Input to the Common Gateway Interface ............................... 15
`Introduction ........................................................................................................ 15
`Using Environment Variables ............................................................................ 16
`Accessing Form Input ........................................................................................ 23
`Extra Path Information ....................................................................................... 30
`Other Languages Under UNIX .......................................................................... 31
`Other Languages Under Microsoft Windows .................................................... 35
`Other Languages on Macintosh Servers ................ , ........................................... 36
`Examining Environment Variables .................................................................... 37
`
`v
`
`AHBLT-2007.005
`
`

`
`vi
`
`Table of Contents
`
`3: Output from the Common Gateway Interface ...................... 39
`Overview ............................................................................................................ 39
`CGI and Response Headers ............................................................................... 40
`Accept Types and Content Types ..................................................................... 41
`The Content-length Header ............................................................................... 42
`Server Redirection .............................................................................................. 44
`The "Expires" and "Pragma" Headers ............................................................... 46
`Status Codes ....................................................................................................... 47
`Complete (Non-Parsed) Headers ...................................................................... 49
`
`4: Forms and CGL ................................................................................ 51
`HTML Tags ......................................................................................................... 52
`Sending Data to the Server ................................................................................ 59
`Designing Applications Using Forms in Perl .................................................... 63
`Decoding Forms in Other Languages ............................................................... 69
`
`5: Server Side Includes ....................................................................... 87
`Introduction ........................................................................................................ 87
`Configuration ...................................................................................................... 89
`Environment Variables ....................................................................................... 90
`Including Boilerplates ........................................................................................ 91
`File Statistics ....................................................................................................... 92
`Executing External Programs ............................................................................. 93
`Executing CGI Programs .................................................................................... 94
`Tailoring SSI Output .................. · ........................................................................ 99
`Common Errors ................................................................................................ 100
`
`6: Hypermedia Documents ............................................................ 101
`Creating Dynamic Home Pages ....................................................................... 101
`CGI Examples with Postscript ......................................................................... 104
`The gd Graphics Library .................................................................................. 116
`CGI Examples with gnuplot ............................................................................ 127
`CGI Examples with pgperl .............................................................................. 131
`Animation ......................................................................................................... 136
`
`AHBLT-2007.006
`
`

`
`Table of Contents
`
`vii
`
`7: Advanced Form Applications ................................................... 143
`Guestbook ........................................................................................................ 143
`Survey/Poll and Pie Graphs ............................................................................ 151
`Quiz/Test Form Application ............................................................................ 163
`Security ............................................................................................................. 180
`
`8: Multiple Form Interaction ........................................................ 183
`Hidden Fields ................................................................................................... 184
`CGI Side Includes ............................................................................................ 190
`Netscape Persistent Cookies ............................................................................ 202
`
`9: Gateways, Databases, and Search/Index Utilities ............ 205
`UNIX Manual Page Gateway ........................................................................... 205
`Mail Gateway ............................................................................. '. ...................... 215
`Relational Databases ........................................................................................ 223
`Search/Index Gateway ..................................................................................... 255
`
`10: Gateways to Internet Information Servers .......................... 263
`Overview .......................................................................................................... 263
`What Are Sockets? ............................................................................................ 264
`Socket I/0 in Perl ............................................................................................ 264
`Socket Library ................................................................................................... 268
`Checking Hypertext (HTTP) Links .................................................................. 269
`Archie ................................................................................................................ 271
`Network News on the Web ............................................................................. 279
`Magic Cookies .................................................................................................. 290
`Maintaining State with a Server ....................................................................... 293
`Forking/Spawning Child Processes ................................................................. 308
`
`11: Advanced and Creative CG/ Applications ........................... 311
`Animated Clock ................................................................................................ 311
`Game of Concentration .................................................................................... 314
`Introduction to Imagemaps ............................................................................. 326
`Calendar Manager ............................................................................................ 327
`
`12: Debugging and Testing CG/ Applications ............................ 367
`Common Errors ................................................................................................ 367
`Programming/System Errors ............................................................................ 370
`
`AHBLT-2007.007
`
`

`
`viii
`
`Table of Contents
`
`Environment Variables ..................................................................................... 372
`Logging and Simulation ................................................................................... 373
`CGI Lint-A Debugging/Testing Tool ............................................................ 375
`Set UID/GID Wrapper ..................................................................................... 380
`
`A: Perl CG! Programming FAQ ..................................................... 383
`
`B: Summary of Regular Expressions .......................................... 401
`
`C: CG! Modules for Perl 5 ............................................................... 405
`
`D: CG! Lite ............................................................................................ 413
`
`E: Applications, Modules, Utilities, and Documentation ..... 417
`
`Index ................................................................................................ 423
`
`AHBLT-2007.008
`
`

`
`46
`
`Chapter 3: Output from the Common Gateway Interj ace
`
`This program checks the load average of the host system with the uptime
`command (see Chapter 1
`for an explanation of the
`regular expression).
`Depending on the load average, one of two documents is returned; a rich, compli(cid:173)
`cated HTML document with graphics if the system is not "busy," or a simple text(cid:173)
`only document otherwise.
`
`And the last thing to note is that you are not limited to returning documents on
`your own server. You can also return a document (static or virtual) located else(cid:173)
`where on the Internet, so long as it has a valid URL:
`
`print "Location: http://www.ora.com", "\n\n";
`
`For example, this statement will return the home page for O'Reilly and Associates.
`
`The "Expires" and "Pragma" Headers
`Most browsers cache (or store internally) the documents you access. This is a ve1y
`positive feature that saves a lot of resources; the browser doesn't have to retrieve
`the document everytime you look at it. However, it can be a slight problem when
`you are dealing with virtual documents created by CGI programs. Once the
`browser accesses a virtual document produced by a CGI program, it will cache it.
`The next time you try to access the same document, the browser will not make a
`request to the server, but will reload the document from its cache. To see the
`effects of caching, try running the following program:
`
`#!/usr/local/bin/perl
`
`'/bin/date');
`chop ($current_date =
`$script_name = $ENV{'SCRIPT_NAME'};
`
`print "Content-type: text/html", "\n\n";
`print "<HTML>", "\n";
`print "<HEAD><TITLE>Effects of Browser Caching</TITLE></HEAD>", "\n";
`print "<BODY><Hl>", $current_date, "</Hl>", "\n";
`print "<P>", qql<A HREF="$script_name">Click here to run again!</A>I,
`II \nll;
`print "</BODY></HTML>", "\n";
`
`exit (0);
`
`This program displays the current time, as well as a hypertext link to itself. If you
`click on the link to run the program again, the date and time that is displayed
`should change, but it does not, because the browser is retrieving the cached docu(cid:173)
`ment. You need to explicitly tell the browser to reload the document if you want
`to run the CGI program again.
`
`AHBLT-2007.009
`
`

`
`Status Codes
`
`47
`
`Fortunately, there is a solution to this problem. If you don't want a virtual docu(cid:173)
`ment to be cached, you can use the Expires and/or Pragma headers to instruct
`the client not to cache the document.
`
`#!/usr/local/bin/perl
`
`print •cont ent-type : text/html•, •\n";
`print "Pragma : no-cache", • \n\n• ;
`
`or
`
`#!/usr/local/bin/perl
`
`print "Content-type: text/html", '\n" ;
`print "Expires : Wednesday, 27-Dec-95 05:29 : 10 GMT" , "\n\n";
`
`However, some browsers don't handle these headers correctly, so don't rely on
`them.
`
`Status Codes
`Status codes are used by the HTIP protocol to communicate the status of a
`request. For example, if a document does not exist, the server retums a "404"
`status code to the browser. If a document has been moved, a "301" status code is
`returned.
`
`CGJ programs can send status information as part of a virtual document. Here's an
`arbitrary example that returns success if the remote host name is bu.edu, and
`failure otheiwise:
`
`#!/usr/local/bin/perl
`
`$remote_host = $ENV (' REMOTE_ HOST ' };
`
`print "Content- type : text/pl ain•, "\n";
`
`if ( $remote_hos t eq "bu. edu • l
`(
`print •status : 200 OK" , •\n\n";
`print •Great ! You are from Boston Uni versi ty ! ", "\n";
`else (
`print "Status: 400 Bad Request •, •\n\n";
`print ' Sorry! You need to access this from Boston University ! ",
`• \n" ;
`
`exit (Ol ;
`
`AHBLT-2007.010