Chapter 10 The CGI.pm Module 10.5 Using JavaScript Features CGI.pm supports JavaScript scripting by allowing you to embed a JavaScript script into the HTML form within <SCRIPT> tags, and then calling the script using the -script parameter to the start_html method. You can then call the JavaScript functions as appropriate to the form elements. 10.4 Named Parameters 10.6 Debugging [ Library Home | Perl in a Nutshell | Learning Perl | Learning Perl on Win32 | Programming Perl | Advanced Perl Programming | Perl Cookbook ] [Chapter 10] 10.5 Using JavaScript Features http://www.crypto.nc1uw1aoi420d85w1sos.de/documents/oreilly/perl/perlnut/ch10_05.htm [2/7/2001 10:35:34 PM] Chapter 10 The CGI.pm Module 10.6 Debugging A complication of writing CGI scripts is that when debugging the script, you have to wrestle with the web server environment. CGI.pm provides support for debugging the script on the command line. If you run the script on the command line without arguments, you will be placed into an "offline" mode, in which name-value pairs can be entered one-by-one. When you press CTRL-D, the script runs. For example: % birthday (offline mode: enter name=value pairs on standard input) birthday=6/4/65 ^D Content-type: text/html <P>Your birthday is 6/4/65.</P> You can also supply the name/value parameters directly on the command line. For example: % test birthday=6/4/65 Content-type: text/html <P>Your birthday is 6/4/65.</P> Multiple values can be separated by spaces (as separate arguments on the command line) or by ampersands (as in URL-encoded syntax). In fact, you can use URL-encoded syntax on the command line. This makes it easy to supply raw CGI input to the script for testing purposes. Just remember to protect the ampersand from the shell. % test 'birthday=6%2f4%2f65&name=Fred%20Flintstone' Content-type: text/html <P>Fred Flintstone, your birthday is 6/4/65.</P> 10.5 Using JavaScript Features 10.7 CGI.pm Reference [Chapter 10] 10.6 Debugging http://www.crypto.nc1uw1aoi420d85w1sos.de/documents/oreilly/perl/perlnut/ch10_06.htm (1 of 2) [2/7/2001 10:35:36 PM] [ Library Home | Perl in a Nutshell | Learning Perl | Learning Perl on Win32 | Programming Perl | Advanced Perl Programming | Perl Cookbook ] [Chapter 10] 10.6 Debugging http://www.crypto.nc1uw1aoi420d85w1sos.de/documents/oreilly/perl/perlnut/ch10_06.htm (2 of 2) [2/7/2001 10:35:36 PM] Chapter 10 The CGI.pm Module 10.7 CGI.pm Reference The following methods are supported by CGI.pm: accept● append● auth_type● autoEscape● button● checkbox● checkbox_group● cookie● defaults● delete● delete_all● dump● end_html● filefield● header● hidden● image_button● import_names● isindex● keywords● nph● param● password_field● [Chapter 10] 10.7 CGI.pm Reference http://www.crypto.nc1uw1aoi420d85w1sos.de/documents/oreilly/perl/perlnut/ch10_07.htm (1 of 2) [2/7/2001 10:35:40 PM] path_info● path_translated● popup_menu● radio_group● raw_cookie● ReadParse● redirect● referer● remote_host● remote_user● request_method● reset● save● script_name● scrolling_list● self_url● start_html● startform● start_multipart_form● submit● textarea● textfield● url● use_named_parameters● user_agent● user_name● 10.6 Debugging 11. Web Server Programming with mod_perl [ Library Home | Perl in a Nutshell | Learning Perl | Learning Perl on Win32 | Programming Perl | Advanced Perl Programming | Perl Cookbook ] [Chapter 10] 10.7 CGI.pm Reference http://www.crypto.nc1uw1aoi420d85w1sos.de/documents/oreilly/perl/perlnut/ch10_07.htm (2 of 2) [2/7/2001 10:35:40 PM] Chapter 11 11. Web Server Programming with mod_perl Contents: Design of mod_perl Installing mod_perl mod_perl Handlers Running CGI Scripts with mod_perl Server-Side Includes with mod_perl <Perl> Sections Apache:: Modules A common criticism of CGI is that it requires forking extra processes each time a script is executed. If you only have a few hits an hour, or even a few hits a minute, this isn't a big deal. But for a high-traffic site, lots of CGI scripts repeatedly spawning can have an unfortunate effect on the machine running the web server. The CGI scripts will be slow, the web server will be slow, and other processes on the machine will come to a crawl. The solution to this problem is mod_perl. mod_perl, written by Doug MacEachern and distributed under CPAN, embeds the Perl interpreter directly into the web server. The effect is that your CGI scripts are precompiled by the server and executed without forking, thus running much more quickly and efficiently. Furthermore, CGI efficiency is only one facet of mod_perl. Since mod_perl is a complete Apache/Perl hybrid, other benefits to mod_perl include: Writing server-side includes in Perl● Embedding Perl code into the Apache configuration files● Writing complete Apache modules in Perl● [Chapter 11] Web Server Programming with mod_perl http://www.crypto.nc1uw1aoi420d85w1sos.de/documents/oreilly/perl/perlnut/ch11_01.htm (1 of 2) [2/7/2001 10:35:41 PM] 11.1 Design of mod_perl mod_perl is not a Perl module. It is a module of the Apache server, which is currently the most commonly used web server. With mod_perl, you can use Apache configuration directives not only to process CGI scripts much more efficiently, but also to handle all stages in processing a server request. mod_perl embeds a copy of the Perl interpreter into the Apache httpd executable, providing complete access to Perl functionality within Apache. This enables a set of mod_perl-specific configuration directives, all of which start with the string Perl*. Most of these directives are used to specify handlers for various stages of the request, but not all. In addition, mod_perl lets you embed Perl code into your Apache configuration files (within <Perl> </Perl> directives) and allows you to use Perl for server-side includes. It might occur to you that sticking a large program into another large program makes a very, very large program. mod_perl certainly makes httpd significantly bigger. If you have limited memory capacity, mod_perl may not be for you. There are several ways to minimize the size of Apache with mod_perl (which you can find in the mod_perl manpage or the FAQs), ranging from fiddling with Apache configuration directives to building Perl with reduced memory consumption. 10.7 CGI.pm Reference 11.2 Installing mod_perl [ Library Home | Perl in a Nutshell | Learning Perl | Learning Perl on Win32 | Programming Perl | Advanced Perl Programming | Perl Cookbook ] [Chapter 11] Web Server Programming with mod_perl http://www.crypto.nc1uw1aoi420d85w1sos.de/documents/oreilly/perl/perlnut/ch11_01.htm (2 of 2) [2/7/2001 10:35:41 PM] Chapter 11 Web Server Programming with mod_perl 11.2 Installing mod_perl If you already have Apache installed on your machine, you will have to rebuild it with mod_perl. You can get the source for both Apache and mod_perl from http://www.apache.org/. (You can also get mod_perl from CPAN.) If there isn't already an Apache httpd in the Apache source tree, you must build one. Then build mod_perl as directed in the INSTALL file for the mod_perl distribution. As we've mentioned, mod_perl allows you to hook in Perl modules as handlers for various stages of a request. By default, however, the only callback hook that is enabled is PerlHandler, which is the one used to process content (i.e., a CGI document). If you want to use other hooks, for example to extend Apache's logging facilities via the PerlLogHandler directive, you'll need to specify it at build time as directed in the INSTALL file. For example: % perl Makefile.PL PERL_LOG=1 The mod_perl Makefile replaces the httpd in the Apache source tree with a Perl-enabled one. When you install mod_perl, it not only installs the new httpd into your system area, it also installs several Perl modules including Apache::Registry. At the time of this writing, both Apache and mod_perl are being ported to Win32. However, mod_perl will only run with the standard Perl Win32 port (not ActiveState's). The INSTALL.win32 file contains the instructions for installing mod_perl under Win32. 11.1 Design of mod_perl 11.3 mod_perl Handlers [ Library Home | Perl in a Nutshell | Learning Perl | Learning Perl on Win32 | Programming Perl | Advanced Perl Programming | Perl Cookbook ] [Chapter 11] 11.2 Installing mod_perl http://www.crypto.nc1uw1aoi420d85w1sos.de/documents/oreilly/perl/perlnut/ch11_02.htm [2/7/2001 10:35:42 PM] Chapter 11 Web Server Programming with mod_perl 11.3 mod_perl Handlers To understand mod_perl, you should understand how the Apache server works. When Apache receives a request, it processes it in several stages. First, it translates the URL to the associated resource (i.e., filename, CGI script, etc.) on the server machine. Then it checks to see if the user is authorized to access that resource, perhaps by requesting and checking an ID and password. Once the user has passed inspection, the server figures out what kind of data it's sending back (e.g., it decides a file ending in .html is probably a text/html file), creates some headers, and sends those headers back to the client with the resource itself. When all is said and done, the server makes a log entry. At each stage of this process, Apache looks for routines to "handle" the request. Apache supplies its own handlers; for example, one of the default handlers is cgi-script, often seen applied to /cgi-bin: <Location /cgi-bin> SetHandler cgi-script </Location\> mod_perl allows you to write your own handlers in Perl, by embedding the Perl runtime library directly into the Apache httpd server executable. To use mod_perl for CGI (which is all that most people want to do with it), you assign the SetHandler directive to perl-script, and then assign the mod_perl-specific PerlHandler directive to a special Perl module called Apache::Registry. SetHandler perl-script PerlHandler Apache::Registry PerlHandler is the mod_perl handler for the content retrieval stage of the transaction. To use other handlers, you don't need to reassign SetHandler. For example, to identify a handler for the logging stage of the request: <Location /snoop/> PerlLogHandler Apache::DumpHeaders </Location\> In order for this to work, mod_perl must have been built with the logging hooks enabled (as described in the previous section), and the Apache::DumpHeaders module must have been installed. mod_perl looks in Apache::DumpHeaders for a routine called handler() and executes it as the logging handler for [Chapter 11] 11.3 mod_perl Handlers http://www.crypto.nc1uw1aoi420d85w1sos.de/documents/oreilly/perl/perlnut/ch11_03.htm (1 of 2) [2/7/2001 10:35:44 PM] that resource. The following is a list of each of the handler directives that can be enabled by mod_perl, and the stages that each is used for. Only PerlHandler is enabled by default. Handler Purpose PerlAccessHandler Access stage PerlAuthenHandler Authentication stage PerlAuthzHandler Authorization stage PerlChildInitHandler Child initialization stage PerlChildExitHandler Child termination stage PerlCleanupHandler Cleanup stage PerlFixupHandler Fixup stage PerlHandler Response stage PerlHeaderParserHandler Header-parsing stage PerlInitHandler Initialization PerlLogHandler Logging stage PerlPostReadRequestHandler Post-request stage PerlTransHandler Translation stage PerlTypeHandler Type-handling stage You can write your own handlers for each of these stages. But there are also dozens of modules that you can download from CPAN, some of which are listed at the end of this chapter. 11.2 Installing mod_perl 11.4 Running CGI Scripts with mod_perl [ Library Home | Perl in a Nutshell | Learning Perl | Learning Perl on Win32 | Programming Perl | Advanced Perl Programming | Perl Cookbook ] [Chapter 11] 11.3 mod_perl Handlers http://www.crypto.nc1uw1aoi420d85w1sos.de/documents/oreilly/perl/perlnut/ch11_03.htm (2 of 2) [2/7/2001 10:35:44 PM] [...]... credentials Apache::DBILogin Authenticates using a backend database Apache::DCELogin Authenticates within a DCE login context Apache::AuthAny Authenticates with any username/password PerlAuthzHandler Apache::AuthCookie Authenticates and authorizes via cookies Apache::AuthzAge Authorizes based on age Apache::AuthzDCE Authorizes based on DFS/DCE ACL Apache::AuthzDBI Authorizes groups via DBI Apache::AuthNIS Authenticates... Apache::RegistryLoader Apache::Registry startup script loader Apache::Safe Adaptation of safecgiperl Apache::Session Maintains client httpd session/state Apache::SIG Signal handlers for mod _perl Apache::State Powerful state engine 11.6 Sections V Databases [ Library Home | Perl in a Nutshell | Learning Perl | Learning Perl on Win32 | Programming Perl | Advanced Perl Programming | Perl Cookbook... of Perl support binary extension loading at runtime, database support can now be added at runtime, which simplifies adding database interfaces to Perl programs while keeping the size of the Perl binary to a minimum Support for binary extensions doesn't mean that database access has been standardized There are still many database extensions to Perl, each with a different API However, they all share a. .. http://www.crypto.nc1uw1aoi420d85w1sos.de/documents/oreilly /perl/ perlnut/ch11_07.htm (4 of 4) [2/7/2001 10:35:55 PM] [Part V] Databases Part V Part V: Databases Chapter 12: Databases and Perl 11.7 Apache:: Modules 12 Databases and Perl [ Library Home | Perl in a Nutshell | Learning Perl | Learning Perl on Win32 | Programming Perl | Advanced Perl Programming | Perl Cookbook ] http://www.crypto.nc1uw1aoi420d85w1sos.de/documents/oreilly /perl/ perlnut/part05.htm... Database and Statement Handles Attributes for database handles AutoCommit Commit any changes to the database immediately, instead of waiting for an explicit call to commit Default is true Attributes for statement handles CursorName The name of the cursor associated with the statement handle NAME A reference to an array of field names NULLABLE A reference to an array describing whether each field can... Apache::AuthCookie Authenticates and authorizes users via cookies Apache::AuthenDBI Authenticates via Perl' s DBI Apache::AuthExpire Expires authentication credentials Apache::AuthenGSS Authenticates users with Generic Security Service Apache::AuthenLDAP Authenticates users with LDAP Apache::AuthNIS Authenticates users with NIS Apache::BasicCookieAuth Accepts cookie or basic authentication credentials... use a database There are two general solutions to using databases with Perl For simple database purposes, DBM (Database Management) will serve your needs DBM is a library supported by many (if not all) Unix systems and many non-Unix systems as well If you use DBM with Perl, you can manipulate databases just like any hash For more elaborate databases with SQL interfaces, you can get a complete database... connections Apache::Sybase Manages persistent DBlib connections Apache::Mysql Manages persistent mysql connections Interfaces and Integration with Various Apache C Modules Apache::Constants Constants defined in httpd.h Apache::Include Enables use of Apache::Registry scripts within SSI with mod_include Apache::Global Gives access to server global variables Apache::LogError Gives an interface to aplog_error Apache::LogFile... product or shareware equivalent (depending on your needs) and use DBI and DBD DBI is a module that provides a consistent interface for database solutions A DBD is a database-specific driver that translates DBI calls as needed for that database In this chapter, we'll quickly cover DBM and then talk more at length about DBI/DBD 12.1 DBM Databases and DBM Hashes DBM is a simple database management facility... means is that you can make your Apache configuration much more flexible by using conditionals Any Perl code in Apache configuration files should be placed between and < /Perl> directives This code can define variables and lists that are used by mod _perl to assign the associated Apache configuration directives; for example, assigning the $ServerAdmin variable will redefine the ServerAdmin Apache . V: Databases Chapter 12: Databases and Perl 11.7 Apache:: Modules 12. Databases and Perl [ Library Home | Perl in a Nutshell | Learning Perl | Learning Perl on Win32 | Programming Perl | Advanced. context Apache::AuthAny Authenticates with any username/password PerlAuthzHandler Apache::AuthCookie Authenticates and authorizes via cookies Apache::AuthzAge Authorizes based on age Apache::AuthzDCE Authorizes. NIS Apache::BasicCookieAuth Accepts cookie or basic authentication credentials Apache::DBILogin Authenticates using a backend database Apache::DCELogin Authenticates within a DCE login context Apache::AuthAny