/ 
nsapi_perl-0.24
River stage zero No dependents
/ Netscape::Registry

NAME

Netscape::Registry - emulate perl CGI programming under nsapi_perl

SYNOPSIS

In obj.conf

NameTrans fn="pfx2dir"
    from="/perl" dir="/full/path/to/perl" name="perl"

<Object name="perl">
ObjectType fn="force-type" type="application/perl"
Service fn="nsapi_perl_handler" module="Netscape::Registry"
</Object>

DESCRIPTION

This module allows CGI programs written in Perl to be run within the Netscape httpd server process. This provides a large performance boost by reducing overhead from the normal fork/exec/compile process for Perl CGI programs. Netscape::Registry is loaded into the server by nsapi_perl, the Perl interface to the Netscape httpd API.

For the full details of nsapi_perl, see nsapi_perl. Suffice it to say here that nsapi_perl provides a mechanism by which a Perl interpreter is embedded into a Netscape server. The NSAPI can then be programmed to in Perl rather than in C. This is achieved by placing the appropriate hooks in the server configuration files; nsapi_perl will then call whatever Perl subroutines you wish at various stages of processing a request from a client.

This module was inspired by and derived from Apache::Registry, which provides the same functionality for the Apache web server.

USAGE

Basically you need to tell your Netscape server that all files underneath a certain directory, or ending with a certain suffix, are to be handled during the Service stage of the transaction by the Perl module Netscape::Registry. This generally involves editing the file obj.conf; see nsapi_perl and your server's documentation for full details. See also "EXAMPLES".

After this initial setup, it's essentially CGI programming as per normal. However, since your scripts are actually run in the server process, it's prudent to avoid the use of global variables since they may by left around after your script has finished.

Netscape::Registry works with Lincoln Stein's CGI.pm module but you should use version 2.36 or more recent; earlier versions may not clean up global variables properly.

Compile and run-time errors from your scripts are written to the server's error log.

See "BUGS" for a summary of (some) known bugs.

INTERNALS

The first request for a given file causes the file to be compiled (by eval()) into a subroutine whose package is is unique to that file. The modification time and length of the source file are then stored in a global hash.

The subroutine is then executed by a statement like this:

eval {package->subroutine};

Each subsequent request for the file causes Netscape::Registry to check the time stamp and size of the file. If the file has changed, it is recompiled and then executed. If the file has not changed, it is executed immediately.

Standard input and output are tie()d to the Netscape::Server::Socket class. This enables your script's output to be sent to the client. It also lets your script read the content of POST-type requests on the standard input (but don't do this yourself; let CGI.pm take care of it for you).

The perl built-in exit() function is redefined to be a mutation of die() - and hence trapable by the above eval() - so that it doesn't cause grief for the server.

ENVIRONMENT

Netscape::Registry attempts to provide the same environment as for normal CGI, but at the time of writing there are some differences.

AUTH_TYPE

This variable is the same as under regular CGI. It is only defined if the program being accessed is under access control.

CONTENT_LENGTH

This variable is the same as under regular CGI.

CONTENT_TYPE

This variable is the same as under regular CGI.

GATEWAY_INTERFACE

This variable is defined as CGI/1.1; nsapi_perl/x.y where x and y are respectively the major and minor version numbers of nsapi_perl.

HTTPS

This variable is currently hardcoded to the value OFF. Let the author know if this is a problem.

HTTP_*

These variables, which represent the header lines from the client's request header, are defined the same as they would be under regular CGI.

PATH

This variable is currently not defined under nsapi_perl but it is under (at least some of) Netscape's implementations of CGI. I don't think it *should* be defined under CGI, so if you've come to rely on it, that's your problem :-)

PATH_INFO

This variable is the same as under regular CGI.

PATH_TRANSLATED

Under Netscape's implementation of CGI, this variable (if defined) is PATH_INFO appended to the server's document root. Under nsapi_perl, this variable (if defined) is PATH_INFO appended to the full path to the script. One of these implementations is probably in error.

QUERY_STRING

This variable is the same as under regular CGI.

REMOTE_ADDR

This variable is the same as under regular CGI.

REMOTE_HOST

This variable is the same as under regular CGI.

REQUEST_METHOD

This variable is the same as under regular CGI.

REMOTE_USER

This variable is the same as under regular CGI. It is only defined if the program being accessed is under access control.

SCRIPT_NAME

This variable is the same as under regular CGI.

SERVER_NAME

This variable is currently undefined under nsapi_perl. This is a bug.

SERVER_PORT

This variable is currently undefined under nsapi_perl. This is a bug.

SERVER_PROTOCOL

This variable is the same as under regular CGI.

SERVER_SOFTWARE

This variable is currently undefined under nsapi_perl. This is a bug.

SERVER_URL

This variable is currently undefined under nsapi_perl. This is a bug.

BUGS

Command-line switches on your CGI scripts are currently ignored by nsapi_perl. For example, if you dutifully put

#!/usr/bin/perl -w

at the start of your script, it will be ignored.

See "ENVIRONMENT" for some important differences in environment variables between nsapi_perl and regular CGI.

Extension modules that dynamically load a shared object may cause you grief. See the section titled DYNAMIC LOADING OF EXTENSION MODULES in nsapi_perl if you suffer problems. The good news is that such modules are reported to work "out of the box" on Win32.

use CGI::Carp('fatalsToBrowser') doesn't work as expected.

CGI programs can't - or at least shouldn't - muck with @INC.

Expect other bugs and weirdness. Please don't get mad; just report them to nsapi_perl mailing list: nsapi_perl@samurai.com.

AUTHOR

Benjamin Sugars <bsugars@canoe.ca>

SEE ALSO

perl(1), nsapi_perl, modperl, Apache::Registry