Return-Path: 
 <modperl-cvs-return-3305-apmail-perl-modperl-cvs-archive=perl.apache.org@perl.apache.org>
Delivered-To: apmail-perl-modperl-cvs-archive@perl.apache.org
Received: (qmail 92903 invoked by uid 500); 11 Apr 2003 02:24:38 -0000
Mailing-List: contact modperl-cvs-help@perl.apache.org; run by ezmlm
Precedence: bulk
list-help: <mailto:modperl-cvs-help@perl.apache.org>
list-unsubscribe: <mailto:modperl-cvs-unsubscribe@perl.apache.org>
list-post: <mailto:modperl-cvs@perl.apache.org>
Reply-To: dev@perl.apache.org
Delivered-To: mailing list modperl-cvs@perl.apache.org
Received: (qmail 92892 invoked by uid 500); 11 Apr 2003 02:24:38 -0000
Delivered-To: apmail-modperl-docs-cvs@apache.org
Date: 11 Apr 2003 02:24:37 -0000
Message-ID: <20030411022437.89538.qmail@icarus.apache.org>
From: stas@apache.org
To: modperl-docs-cvs@apache.org
Subject: cvs commit: modperl-docs/src/docs/general/os/win32 faq.pod
X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N

stas        2003/04/10 19:24:37

  Modified:    src/docs/2.0/api/Apache compat.pod
               src/docs/2.0/devel config.cfg
               src/docs/2.0/devel/porting porting.pod
               src/docs/2.0/user config.cfg
               src/docs/2.0/user/install install.pod
               src/docs/2.0/user/intro overview.pod start_fast.pod
               src/docs/general/os/win32 faq.pod
  Added:       src/docs/2.0/user/porting compat.pod
  Removed:     src/docs/2.0/user/compat compat.pod
  Log:
  moving compat/compat.pod to porting/compat.pod
  
  Revision  Changes    Path
  1.3       +1 -1      modperl-docs/src/docs/2.0/api/Apache/compat.pod
  
  Index: compat.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/compat.pod,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- compat.pod	7 Mar 2003 08:31:39 -0000	1.2
  +++ compat.pod	11 Apr 2003 02:24:36 -0000	1.3
  @@ -69,7 +69,7 @@
   documentation.
   
   Another important document to read is: L<Migrating from mod_perl 1.0
  -to mod_perl 2.0|docs::2.0::user::compat::compat> which covers all
  +to mod_perl 2.0|docs::2.0::user::porting::compat> which covers all
   mod_perl 1.0 constants, functions and methods that have changed in
   mod_perl 2.0.
   
  
  
  
  1.18      +0 -1      modperl-docs/src/docs/2.0/devel/config.cfg
  
  Index: config.cfg
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/devel/config.cfg,v
  retrieving revision 1.17
  retrieving revision 1.18
  diff -u -r1.17 -r1.18
  --- config.cfg	9 Apr 2003 04:23:19 -0000	1.17
  +++ config.cfg	11 Apr 2003 02:24:36 -0000	1.18
  @@ -46,5 +46,4 @@
           debug/code
       )],
   
  -
   );
  
  
  
  1.12      +4 -4      modperl-docs/src/docs/2.0/devel/porting/porting.pod
  
  Index: porting.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/devel/porting/porting.pod,v
  retrieving revision 1.11
  retrieving revision 1.12
  diff -u -r1.11 -r1.12
  --- porting.pod	7 Apr 2003 07:02:49 -0000	1.11
  +++ porting.pod	11 Apr 2003 02:24:36 -0000	1.12
  @@ -147,7 +147,7 @@
   =head1 Porting a Perl Module to Run under mod_perl 2.0
   
   Note: API changes are listed in L<the backwards compatibility
  -document|docs::2.0::user::compat::compat/>.
  +document|docs::2.0::user::porting::compat/>.
   
   The following sections will guide you through the steps of porting
   your modules to mod_perl 2.0.
  @@ -278,7 +278,7 @@
   prototype has changed, or it requires ditfferent arguments, etc.).
   
   In either of these cases, refer to L<the backwards compatibility
  -document|docs::2.0::user::compat::compat/> for an exhaustive list of
  +document|docs::2.0::user::porting::compat/> for an exhaustive list of
   API calls that have been modified or removed.
   
   =head3 Methods that No Longer Exist
  @@ -305,10 +305,10 @@
   
   Looks like we are calling a non-existent method! Our next step is to
   refer to L<the backwards compatibility
  -document|docs::2.0::user::compat::compat/>, wherein we find that as we
  +document|docs::2.0::user::porting::compat/>, wherein we find that as we
   suspected, the method C<log_reason()> no longer exists, and that
   L<instead we should use the other standard logging
  -functions|docs::2.0::user::compat::compat/C__r_E_gt_log_reason_>
  +functions|docs::2.0::user::porting::compat/C__r_E_gt_log_reason_>
   provided by the C<Apache::Log> module.
   
   =head3 Methods Whose Usage Has Been Modified
  
  
  
  1.21      +5 -1      modperl-docs/src/docs/2.0/user/config.cfg
  
  Index: config.cfg
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/config.cfg,v
  retrieving revision 1.20
  retrieving revision 1.21
  diff -u -r1.20 -r1.21
  --- config.cfg	12 Mar 2003 06:37:07 -0000	1.20
  +++ config.cfg	11 Apr 2003 02:24:36 -0000	1.21
  @@ -24,8 +24,12 @@
   
       group    => 'Coding',
       chapters => [qw(
  -        compat/compat.pod
           coding/coding.pod
  +    )],
  +
  +    group    => 'Porting',
  +    chapters => [qw(
  +        porting/compat.pod
       )],
   
       group    => 'mod_perl Handlers',
  
  
  
  1.38      +1 -1      modperl-docs/src/docs/2.0/user/install/install.pod
  
  Index: install.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/install/install.pod,v
  retrieving revision 1.37
  retrieving revision 1.38
  diff -u -r1.37 -r1.38
  --- install.pod	7 Apr 2003 06:26:22 -0000	1.37
  +++ install.pod	11 Apr 2003 02:24:37 -0000	1.38
  @@ -367,7 +367,7 @@
     PerlWarn
   
   Use L<their 2.0
  -equivalents|docs::2.0::user::compat::compat/Configuration_Files_Porting>
  +equivalents|docs::2.0::user::porting::compat/Configuration_Files_Porting>
   instead.
   
   =back
  
  
  
  1.4       +1 -1      modperl-docs/src/docs/2.0/user/intro/overview.pod
  
  Index: overview.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/intro/overview.pod,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- overview.pod	27 Jan 2003 04:05:13 -0000	1.3
  +++ overview.pod	11 Apr 2003 02:24:37 -0000	1.4
  @@ -586,7 +586,7 @@
   did in mod_perl 1.0, so users of the API will not notice the
   difference, other than the addition of many new methods. Where API has
   changed a special L<back compatibility
  -module|docs::2.0::user::compat::compat> can be used.
  +module|docs::2.0::user::porting::compat> can be used.
   
   In mod_perl 2.0 the APR API resides in the C<APR::> namespace, and
   obviously the C<Apache::> namespace is mapped to the Apache API.
  
  
  
  1.13      +1 -1      modperl-docs/src/docs/2.0/user/intro/start_fast.pod
  
  Index: start_fast.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/intro/start_fast.pod,v
  retrieving revision 1.12
  retrieving revision 1.13
  diff -u -r1.12 -r1.13
  --- start_fast.pod	7 Mar 2003 04:20:24 -0000	1.12
  +++ start_fast.pod	11 Apr 2003 02:24:37 -0000	1.13
  @@ -67,7 +67,7 @@
     PerlModule Apache::compat
   
   For more information see: L<Migrating from mod_perl 1.0 to mod_perl
  -2.0|docs::2.0::user::compat::compat>.
  +2.0|docs::2.0::user::porting::compat>.
   
   
   
  
  
  
  1.1                  modperl-docs/src/docs/2.0/user/porting/compat.pod
  
  Index: compat.pod
  ===================================================================
  =head1 NAME
  
  Migrating from mod_perl 1.0 to mod_perl 2.0
  
  =head1 Description
  
  This chapter explains how to port code and configuration files from
  mod_perl 1.0 to mod_perl 2.0.
  
  As will be explained in details later loading C<Apache::compat> at the
  server startup, should make the code running properly under 1.0 work
  under mod_perl 2.0. If you want to port your code to mod_perl 2.0 or
  writing from scratch and not concerned about backwards compatibility,
  this document explains what has changed compared to mod_perl 1.0.
  
  Several configuration directives were changed, renamed or
  removed. Several APIs have changed, renamed, removed, or moved to new
  packages.  Certain functions while staying exactly the same as in
  mod_perl 1.0, now reside in different packages. Before using them you
  need to find out those packages and load them.
  
  You should be able to find the destiny of the functions that you
  cannot find any more or which behave differently now under the package
  names the functions belong in mod_perl 1.0.
  
  See also L<additional porting
  notes|docs::2.0::devel::porting::porting>, mainly oriented for the 3rd
  party module and core developers.
  
  =head1 Configuration Files Porting
  
  To migrate the configuration files to the mod_perl 2.0 syntax, you may
  need to do certain adjustments. Several configuration directives are
  deprecated in 2.0, but still available for backwards compatibility
  with mod_perl 1.0 unless 2.0 was built with
  C<L<MP_COMPAT_1X=0|docs::2.0::user::install::install/MP_COMPAT_1X>>. If
  you don't need the backwards compatibility consider using the
  directives that have replaced them.
  
  =head2 C<PerlHandler>
  
  C<PerlHandler> was replaced with C<PerlResponseHandler>.
  
  =head2 C<PerlSendHeader>
  
  C<PerlSendHeader> was replaced with C<PerlOptions +/-ParseHeaders>
  directive.
  
    PerlSendHeader On  => PerlOptions +ParseHeaders
    PerlSendHeader Off => PerlOptions -ParseHeaders
  
  =head2 C<PerlSetupEnv>
  
  C<PerlSetupEnv> was replaced with C<PerlOptions +/-SetupEnv>
  directive.
  
    PerlSetupEnv On  => PerlOptions +SetupEnv
    PerlSetupEnv Off => PerlOptions -SetupEnv
  
  =head2 C<PerlTaintCheck>
  
  The taint mode now can be turned on with:
  
    PerlSwitches -T
  
  As with standard Perl, by default the taint mode is disabled and once
  enabled cannot be turned off inside the code.
  
  =head2 C<PerlWarn>
  
  Warnings now can be enabled globally with:
  
    PerlSwitches -w
  
  =head2 C<PerlFreshRestart>
  
  C<PerlFreshRestart> is a mod_perl 1.0 legacy and doesn't exist in
  mod_perl 2.0. A full teardown and startup of interpreters is done on
  restart.
  
  If you need to use the same I<httpd.conf> for 1.0 and 2.0, use:
  
    <IfDefine !MODPERL2>
        PerlFreshRestart
    </IfDefine>
  
  =head2 Apache Configuration Customization
  
  mod_perl 2.0 has slightly changed the mechanism for L<adding custom
  configuration
  directives|docs::2.0::user::config::custom> and now also makes it easy to 
  access an Apache parsed configuration tree's values.
  
  META: add L<> to the config tree access when it'll be written.
  
  
  
  
  =head1 Code Porting
  
  mod_perl 2.0 is trying hard to be back compatible with mod_perl
  1.0. However some things (mostly APIs) have been changed. In order to
  gain a complete compatibilty with 1.0 while running under 2.0, you
  should load the compatibility module as early as possible:
  
    use Apache::compat;
  
  at the server startup. And unless there are forgotten things or bugs,
  your code should work without any changes under 2.0 series.
  
  However, unless you want to keep the 1.0 compatibility, you should try
  to remove the compatibility layer and adjust your code to work under
  2.0 without it. You want to do it mainly for the performance
  improvement.
  
  This document explains what APIs have changed and what new APIs should
  be used instead.
  
  If you have mod_perl 1.0 and 2.0 installed on the same system and the
  two use the same perl libraries directory (e.g. I</usr/lib/perl5>), to
  use mod_perl 2.0 make sure to load first the C<Apache2> module which
  will perform the necessary adjustments to C<@INC>.
  
    use Apache2; # if you have 1.0 and 2.0 installed
    use Apache::compat;
  
  So if before loading C<Apache2.pm> the C<@INC> array consisted of:
  
    /home/stas/perl/ithread/lib/5.8.0/i686-linux-thread-multi
    /home/stas/perl/ithread/lib/5.8.0
    /home/stas/perl/ithread/lib/site_perl/5.8.0/i686-linux-thread-multi
    /home/stas/perl/ithread/lib/site_perl/5.8.0
    /home/stas/perl/ithread/lib/site_perl
    .
  
  It will now look as:
  
    /home/stas/perl/ithread/lib/site_perl/5.8.0/i686-linux-thread-multi/Apache2
    /home/stas/perl/ithread/lib/5.8.0/i686-linux-thread-multi
    /home/stas/perl/ithread/lib/5.8.0
    /home/stas/perl/ithread/lib/site_perl/5.8.0/i686-linux-thread-multi
    /home/stas/perl/ithread/lib/site_perl/5.8.0
    /home/stas/perl/ithread/lib/site_perl
    .
  
  Notice that a new directory was prepended to the search path, so if
  for example the code attempts to load C<Apache::RequestRec> and there
  are two versions of this module undef
  I</home/stas/perl/ithread/lib/site_perl/>:
  
            5.8.0/i686-linux-thread-multi/Apache/RequestRec.pm
    5.8.0/i686-linux-thread-multi/Apache2/Apache/RequestRec.pm
  
  The mod_perl 2.0 version will be loaded first, because the directory
  I<5.8.0/i686-linux-thread-multi/Apache2> is coming before the
  directory I<5.8.0/i686-linux-thread-multi> in C<@INC>.
  
  Finally, mod_perl 2.0 has all its methods spread across many
  modules. In order to use these methods the modules containing them
  have to be loaded first. The module
  C<L<ModPerl::MethodLookup|docs::2.0::api::ModPerl::MethodLookup>> can
  be used to find out which modules need to be used. This module also
  provides a function
  C<L<preload_all_modules()|docs::2.0::api::ModPerl::MethodLookup/preload_all_modules__>>
  that will load all mod_perl 2.0 modules, implementing their API in XS,
  which is useful when one starts to port their mod_perl 1.0 code,
  though preferrably avoided in the production environment if you want
  to save memory.
  
  =head1 C<Apache::Registry>, C<Apache::PerlRun> and Friends
  
  C<Apache::Registry>, C<Apache::PerlRun> and other modules from the
  registry family now live in the C<ModPerl::> namespace to avoid
  collisions with the versions from 1.0.
  
  To run the C<Apache::Registry> module from mod_perl 1.0 you have to
  load C<Apache::compat> at the startup:
  
    file:startup.pl:
    ----------------
    use Apache2; # if you have 1.0 and 2.0 installed
    use Apache::compat ();
    #use lib ...; # to find 1.0x Apache::Registry
  
  then in I<httpd.conf>:
  
    Alias /perl /path/to/perl/scripts
    <Location /perl>
       SetHandler perl-script
       PerlResponseHandler Apache::Registry
       Options +ExecCGI
       PerlOptions +ParseHeaders
    </Location>
  
  Notice that C<Apache::compat> has to be loaded before C<CGI.pm> if the
  latter module is used.
  
  The only reason you may want to use C<Apache::Registry> with mp2 is
  that because at this moment C<ModPerl::Registry> (and others) doesn't
  C<chdir()> into the script's dir like Apache::Registry does, because
  C<chdir()> affects the whole process under threads. This should be
  resolved by the time mod_perl 2.0 is released. But for now you can use
  C<Apache::Registry>. However you will have problems if you are using
  anything but the preforked MPM, the main reason why
  C<ModPerl::Registry> doesn't C<chdir()>.
  
  Otherwise C<ModPerl::Registry> modules are configured and used
  similarly to C<Apache::Registry> modules. Refer to one of the
  following manpages for more information:
  C<L<ModPerl::RegistryCooker|docs::2.0::api::ModPerl::RegistryCooker>>,
  C<L<ModPerl::Registry|docs::2.0::api::ModPerl::Registry>>,
  C<L<ModPerl::RegistryBB|docs::2.0::api::ModPerl::RegistryBB>>
  and
  C<L<ModPerl::PerlRun|docs::2.0::api::ModPerl::PerlRun>>.
  
  
  
  =head2 C<ModPerl::RegistryLoader>
  
  In mod_perl 1.0 it was only possible to preload scripts as
  C<Apache::Registry> handlers. In 2.0 the loader can use any of the
  registry classes to preload into. The old API works as before, but new
  options can be passed. See the
  C<L<ModPerl::RegistryLoader|docs::2.0::api::ModPerl::RegistryLoader>>
  manpage for more information.
  
  
  
  =head1 C<Apache::Constants>
  
  C<Apache::Constants> has been replaced by three classes:
  
  =over
  
  =item C<L<Apache::Const|docs::2.0::api::Apache::Const>>
  
  Apache constants
  
  =item C<L<APR::Const|docs::2.0::api::APR::Const>>
  
  Apache Portable Runtime constants
  
  =item C<L<ModPerl::Const|docs::2.0::api::ModPerl::Const>>
  
  mod_perl specific constants
  
  =back
  
  See the manpages of the respective modules to figure out which
  constants they provide. (XXX: not all manpages exist yet.)
  
  META: add the info how to perform the transition. XXX: may be write a
  script, which can tell you how to port the constants to 2.0? Currently
  C<Apache::compat> doesn't provide a complete back compatibility layer.
  
  =head2 Deprecated Constants
  
  C<REDIRECT> and similar constants have been deprecated in Apache for
  years, in favor of the C<HTTP_*> names (they no longer exist Apache
  2.0). mod_perl 2.0 API performs the following aliasing behind the
  scenes:
  
       NOT_FOUND     => 'HTTP_NOT_FOUND',
       FORBIDDEN     => 'HTTP_FORBIDDEN',
       AUTH_REQUIRED => 'HTTP_UNAUTHORIZED',
       SERVER_ERROR  => 'HTTP_INTERNAL_SERVER_ERROR',
       REDIRECT      => 'HTTP_MOVED_TEMPORARILY',
  
  but we suggest moving to use the C<HTTP_*> names. For example if
  running in 1.0 compatibility mode change:
  
    use Apache::Constants qw(REDIRECT);
  
  to:
  
    use Apache::Constants qw(HTTP_MOVED_TEMPORARILY);
  
  This will work in both mod_perl generations.
  
  
  =head2 C<SERVER_VERSION()>
  
  C<Apache::Constants::SERVER_VERSION()> has been replaced with:
  
    Apache::get_server_version();
  
  =head2 C<export()>
  
  C<Apache::Constants::export()> has no replacement in 2.0 as it's not
  needed.
  
  
  =head1 Issues with Environment Variables
  
  There are several thread-safety issues with setting environment
  variables.
  
  Environment variables set during request time won't be seen by C
  code. See the L<DBD::Oracle
  issue|docs::2.0::user::troubleshooting::troubleshooting/C_Libraries_Don_t_See_C__ENV__Entries_Set_by_Perl_Code> for possible workarounds.
  
  Forked processes (including backticks) won't see CGI emulation
  environment variables. (META: This will hopefully be resolved in the
  future, it's documented in modperl_env.c:modperl_env_magic_set_all.)
  
  =head1 Special Environment Variables
  
  =head2 C<$ENV{GATEWAY_INTERFACE}>
  
  The environment variable C<$ENV{GATEWAY_INTERFACE}> is deprecated in
  mod_perl 2.0 (See:
  C<L<MP_COMPAT_1X=0|docs::2.0::user::install::install/MP_COMPAT_1X>>). Instead
  use C<$ENV{MOD_PERL}> (available in both mod_perl generations), which
  is set to something like this:
  
    mod_perl/1.99_03-dev
  
  However to check the version it's better to use C<$mod_perl::VERSION>:
  
    use mod_perl;
    use constant MP2 => ($mod_perl::VERSION >= 1.99);
  
  
  
  =head1 C<Apache::> Methods
  
  =head2 C<Apache-E<gt>request>
  
  C<Apache-E<gt>request> is deprecated.  It's error-prone and hurts
  performance when using threaded MPMs, since it has to use thread local
  storage.
  
  For any location that uses C<Apache-E<gt>request> and uses
  C<SetHandler modperl>, you need to configure:
  
    <Location ...>
        SetHandler modperl
        PerlOptions +GlobalRequest
        ...
    </Location>
  
  It's already enabled for:
  
    <Location ...>
        SetHandler perl-script
        ...
    </Location>
  
  =head2 C<Apache-E<gt>define>
  
  C<Apache-E<gt>define> has been replaced with
  C<Apache::exists_config_define()> residing inside
  C<Apache::ServerUtil>.
  
  See the
  C<L<Apache::ServerUtil|docs::2.0::api::Apache::ServerUtil>>
  manpage.
  
  =head2 C<Apache-E<gt>untaint>
  
  C<Apache-E<gt>untaint> has moved to
  C<L<Apache::ServerUtil|docs::2.0::api::ModPerl::Util>> and now is a
  function, rather a class method. It'll will untaint all its
  arguments. You shouldn't be using this function unless you know what
  you are doing. Refer to the I<perlsec> manpage for more information.
  
  C<L<Apache::compat|docs::2.0::api::Apache::compat>> provides the
  backward compatible with mod_perl 1.0 implementation.
  
  =head2 C<Apache-E<gt>get_handlers>
  
  To get handlers for the server level, mod_perl 2.0 code should use:
  
    $s->get_handlers(...);
  
  or:
  
    Apache->server->get_handlers(...);
  
  C<Apache-E<gt>get_handlers> is avalable via
  C<L<Apache::compat|docs::2.0::api::Apache::compat>>.
  
  =head2 C<Apache-E<gt>push_handlers>
  
  To push handlers at the server level, mod_perl 2.0 code should use:
  
    $s->push_handlers(...);
  
  or:
  
    Apache->server->push_handlers(...);
  
  C<Apache-E<gt>push_handlers> is avalable via
  C<L<Apache::compat|docs::2.0::api::Apache::compat>>.
  
  =head2 C<Apache-E<gt>set_handlers>
  
  To set handlers at the server level, mod_perl 2.0 code should use:
  
    $s->set_handlers(...);
  
  or:
  
    Apache->server->set_handlers(...);
  
  C<Apache-E<gt>set_handlers> is avalable via
  C<L<Apache::compat|docs::2.0::api::Apache::compat>>.
  
  =head2 C<Apache::exit()>
  
  C<Apache::exit()> has been replaced with C<ModPerl::Util::exit()>,
  which is a function (not a method) and accepts a single optional
  argument: status, whose default is 0 (== do nothing).
  
  See the
  C<L<ModPerl::Util|docs::2.0::api::ModPerl::Util>>
  manpage.
  
  =head2 C<Apache::gensym()>
  
  Since Perl 5.6.1 filehandlers are autovivified and there is no need
  for C<Apache::gensym()> function, since now it can be done with:
  
    open my $fh, "foo" or die $!;
  
  Though the C function C<modperl_perl_gensym()> is available for XS/C
  extensions writers.
  
  =head2 C<Apache::module()>
  
  C<Apache::module()> has been replaced with the function
  C<Apache::Module::loaded()>, which now accepts a single argument: the
  module name.
  
  =head2 C<Apache::log_error()>
  
  C<Apache::log_error()> is not available in mod_perl 2.0 API. You can
  use:
  
    Apache->server->log_error
  
  instead. See the
  C<L<Apache::Log|docs::2.0::api::Apache::Log>> manpage.
  
  
  
  
  =head1 C<Apache::> Variables
  
  =head2 C<$Apache::__T>
  
  C<$Apache::__T> is deprecated in mod_perl 2.0. Use C<${^TAINT}>
  instead.
  
  
  
  
  
  =head1 C<Apache::Server::> Methods and Variables
  
  =head2 C<$Apache::Server::CWD>
  
  C<$Apache::Server::CWD> is deprecated and exists only in
  C<L<Apache::compat|docs::2.0::api::Apache::compat>>.
  
  =head2 C<$Apache::Server::AddPerlVersion>
  
  C<$Apache::Server::AddPerlVersion> is deprecated and exists only in
  C<L<Apache::compat|docs::2.0::api::Apache::compat>>.
  
  
  
  
  =head1 Server Object Methods
  
  =head2 C<$s-E<gt>register_cleanup>
  
  C<$s-E<gt>register_cleanup> has been replaced with
  C<APR::Pool::cleanup_register()> which accepts the pool object as the
  first argument instead of the server object. e.g.:
  
    sub cleanup_callback { my $data = shift; ... }
    $s->pool->cleanup_register(\&cleanup_callback, $data);
  
  where the last argument C<$data> is optional, and if supplied will be
  passed as the first argument to the callback function.
  
  See the C<L<APR::Pool|docs::2.0::api::APR::Pool>> manpage.
  
  
  
  
  
  =head1 Request Object Methods
  
  
  =head2 C<$r-E<gt>current_callback>
  
  C<$r-E<gt>current_callback> is now simply a
  C<Apache::current_callback> and can be called for any of the phases,
  including those where C<$r> simply doesn't exist.
  
  C<L<Apache::compat|docs::2.0::api::Apache::compat>> implements
  C<$r-E<gt>current_callback> for backwards compatibility.
  
  =head2 C<$r-E<gt>get_remote_host>
  
  C<get_remote_host()> is now invoked on the C<L<connection
  object|docs::2.0::api::Apache::Connection>>:
  
    use Apache::Connection;
    $r->connection->get_remote_host();
  
  C<$r-E<gt>get_remote_host> is available through
  C<L<Apache::compat|docs::2.0::api::Apache::compat>>.
  
  =head2 C<$r-E<gt>content>
  
  See the next item.
  
  =head2 C<$r-E<gt>args> in an Array Context
  
  C<$r-E<gt>args> in 2.0 returns the query string without parsing and
  splitting it into an array. You can also set the query string by
  passing a string to this method.
  
  C<$r-E<gt>content> and C<$r-E<gt>args> in an array context were
  mistakes that never should have been part of the mod_perl 1.0
  API. There multiple reason for that, among others:
  
  =over
  
  =item *
  
  does not handle multi-value keys
  
  =item *
  
  does not handle multi-part content types
  
  =item *
  
  does not handle chunked encoding
  
  =item *
  
  slurps C<$r-E<gt>headers_in-E<gt>{'content-length'}> into a single
  buffer (bad for performance, memory bloat, possible dos attack, etc.)
  
  =item *
  
  in general duplicates functionality (and does so poorly) that is done
  better in C<Apache::Request>.
  
  =item *
  
  if one wishes to simply read POST data, there is the more modern
  C<{setup,should,get}_client_block> API, and even more modern filter
  API, along with continued support for C<read(STDIN, ...)> and
  C<$r-E<gt>read($buf, $r-E<gt>headers_in-E<gt>{'content-length'}>)
  
  =back
  
  For now you can use C<CGI.pm> or the code in
  C<L<Apache::compat|docs::2.0::api::Apache::compat>> (it's slower).
  
  META: when C<Apache::Request> will be ported to mod_perl 2.0, you will
  have the fast C implementation of these functions.
  
  =head2  C<$r-E<gt>chdir_file>
  
  C<chdir()> cannot be used in the threaded environment, therefore
  C<$r-E<gt>chdir_file> is not in the mod_perl 2.0 API.
  
  For more information refer to: L<Threads Coding Issues Under
  mod_perl|docs::2.0::user::coding::coding/Threads_Coding_Issues_Under_mod_perl>.
  
  =head2 C<$r-E<gt>is_main>
  
  C<$r-E<gt>is_main> is not part of the mod_perl 2.0 API. Use
  C<!$r-E<gt>main> instead.
  
  Refer to the
  C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec/main__>>
  manpage.
  
  =head2 C<$r-E<gt>finfo>
  
  Probably won't be implemented, because Apache 2.0's finfo
  datastructure can't be mapped into the Perl finfo datastructure.
  
  C<L<Apache::compat|docs::2.0::api::Apache::compat>> handles that for
  now with:
  
    sub finfo {
        my $r = shift;
        stat $r->filename;
        \*_;
    }
  
  =head2 C<$r-E<gt>header_in>
  
  See the next item.
  
  =head2 C<$r-E<gt>header_out>
  
  See the next item.
  
  =head2 C<$r-E<gt>err_header_out>
  
  C<header_in()>, C<header_out()> and C<err_header_out()> are not
  available in 2.0. Use C<headers_in()>, C<headers_out()> and
  C<err_headers_out()> instead (which should be used in 1.0 as
  well). For example you need to replace:
  
    $r->err_header_out("Pragma" => "no-cache");
  
  with:
  
    $r->err_headers_out->{'Pragma'} = "no-cache";
  
  See the L<Apache::RequestRec> manpage.
  
  
  =head2 C<$r-E<gt>log_reason>
  
  C<$r-E<gt>log_reason> is not available in mod_perl 2.0 API. Use the
  other standard logging functions provided by the
  C<L<Apache::Log|docs::2.0::api::Apache::Log>>
  module. For example:
  
    $r->log_error("it works!");
  
  See the C<L<Apache::Log|docs::2.0::api::Apache::Log>>
  manpage.
  
  
  =head2 C<$r-E<gt>register_cleanup>
  
  C<$r-E<gt>register_cleanup> has been replaced with
  C<APR::Pool::cleanup_register()> which accepts the pool object as the
  first argument instead of the request object. e.g.:
  
    sub cleanup_callback { my $data = shift; ... }
    $r->pool->cleanup_register(\&cleanup_callback, $data);
  
  where the last argument C<$data> is optional, and if supplied will be
  passed as the first argument to the callback function.
  
  See the L<APR::Pool> manpage.
  
  =head2 C<$r-E<gt>post_connection>
  
  C<$r-E<gt>post_connection> has been replaced with:
  
    $r->connection->pool->cleanup_register();
  
  See the L<APR::Pool> manpage.
  
  
  =head2 C<$r-E<gt>request>
  
  Use C<L<Apache-E<gt>request|/__Apache___gt_request_>>.
  
  =head2 C<$r-E<gt>send_fd>
  
  See the next item.
  
  =head2 C<$r-E<gt>send_fd_length>
  
  currently available only in the 1.0 compatibility layer. The problem
  is that Apache has changed the API and its functionality. See the
  implementation in C<L<Apache::compat|docs::2.0::api::Apache::compat>>.
  
  XXX: needs a better resolution
  
  =head2 C<$r-E<gt>send_http_header>
  
  This method is not needed in 2.0, though available in
  C<L<Apache::compat|docs::2.0::api::Apache::compat>>. 2.0 handlers only
  need to set the I<Content-type> via C<$r-E<gt>content_type($type)>.
  
  =head2 C<$r-E<gt>server_root_relative>
  
  C<Apache::server_root_relative> is a function in 2.0 and its first
  argument is the I<pool> object. For example:
  
    # during request
    my $conf_dir = Apache::server_root_relative($r->pool, 'conf');
    # during startup
    my $conf_dir = Apache::server_root_relative($s->pool, 'conf');
  
  The old way:
  
    my $conf_dir = Apache::server_root_relative('Apache', 'conf');
  
  will work as well, but you shouldn't use it, because it'll internally
  use a global pool, which is a bit slower, but the worst drawback is
  that every time you use this way the allocated from this pool memory
  won't be cleaned up, till the server quits so there will be a memory
  leak. When you are inside a request and use C<$r-E<gt>pool>, this pool
  is freed at the end of each request.
  
  
  See the L<Apache::ServerUtil> manpage.
  
  
  =head2 C<$r-E<gt>hard_timeout>
  
  See the next item.
  
  =head2 C<$r-E<gt>reset_timeout>
  
  See the next item.
  
  =head2 C<$r-E<gt>soft_timeout>
  
  See the next item.
  
  =head2 C<$r-E<gt>kill_timeout>
  
  The functions C<$r-E<gt>hard_timeout>, C<$r-E<gt>reset_timeout>,
  C<$r-E<gt>soft_timeout> and C<$r-E<gt>kill_timeout> aren't needed
  in mod_perl 2.0.
  
  =head2 C<$r-E<gt>set_byterange>
  
  See the next item.
  
  =head2 C<$r-E<gt>each_byterange>
  
  The functions C<$r-E<gt>set_byterange> and C<$r-E<gt>each_byterange>
  aren't in the Apache 2.0 API, and therefore don't exist in mod_perl
  2.0. The byterange serving functionality is now implemented in the
  ap_byterange_filter, which is a part of the core http module, meaning
  that it's automatically taking care of serving the requested ranges
  off the normal complete response. There is no need to configure
  it. It's executed only if the appropriate request headers are
  set. These headers aren't listed here, since there are several
  combinations of them, including the older ones which are still
  supported. For a complete info on these see
  I<modules/http/http_protocol.c>.
  
  =head1 C<Apache::Connection>
  
  =head2 C<$connection-E<gt>auth_type>
  
  The record I<auth_type> doesn't exist in the Apache 2.0's connection
  struct. It exists only in the request record struct. The new accessor
  in 2.0 API is C<$r-E<gt>ap_auth_type>.
  
  C<L<Apache::compat|docs::2.0::api::Apache::compat>> provides a back
  compatibility method, though it relies on the availability of the
  global C<Apache-E<gt>request>, which requires the configuration to
  have:
  
    PerlOptions +GlobalRequest
  
  to set it up for earlier stages than response handler.
  
  =head2  C<$connection-E<gt>user>
  
  This method is deprecated in mod_perl 1.0 and C<$r-E<gt>user> should
  be used instead for both versions of mod_perl. C<$r-E<gt>user()>
  method is available since mod_perl version 1.24_01.
  
  =head1 C<Apache::File>
  
  The methods from mod_perl 1.0's module C<Apache::File> have been
  either moved to other packages or removed.
  
  =head2 C<open()> and C<close()>
  
  The methods C<open()> and C<close()> were removed. See the back
  compatibility implementation in the module
  C<L<Apache::compat|docs::2.0::api::Apache::compat>>.
  
  =head2 C<tmpfile()>
  
  The method C<tmpfile()> was removed since Apache 2.0 doesn't have the
  API for this method anymore.
  
  See C<File::Temp>, or the back compatibility implementation in the
  module C<L<Apache::compat|docs::2.0::api::Apache::compat>>.
  
  With Perl v5.8.0 you can create anonymous temporary files:
  
     open $fh, "+>", undef or die $!;
  
  That is a literal C<undef>, not an undefined value.
  
  
  
  
  =head1 C<Apache::Util>
  
  A few C<Apache::Util> functions have changed their interface.
  
  =head2 C<Apache::Util::size_string()>
  
  C<Apache::Util::size_string()> has been replaced with
  C<APR::String::format_size()>, which returns formatted strings of only
  4 characters long. See the
  C<L<APR::String|docs::2.0::api::APR::String>> manpage.
  
  =head2 C<Apache::Util::escape_uri()>
  
  C<Apache::Util::escape_uri()> has been replaced with
  C<Apache::Util::escape_path()> and requires a pool object as a second
  argument. For example:
  
    $escaped_path = Apache::Util::escape_path($path, $r->pool);
  
  =head2 C<Apache::Util::unescape_uri()>
  
  C<Apache::Util::unescape_uri()> has been replaced with
  C<Apache::unescape_url()>.
  
  =head2 C<Apache::Util::escape_html()>
  
  C<Apache::Util::escape_html> currently is available only via
  C<L<Apache::compat|docs::2.0::api::Apache::compat>> until
  I<ap_escape_html> is reworked to not require a pool.
  
  =head2 C<Apache::Util::parsedate()>
  
  C<Apache::Util::parsedate()> has been replaced with
  C<APR::Date::parse_http()>.
  
  =head2 C<Apache::Util::ht_time()>
  
  C<Apache::Util::ht_time()> has been replaced (temporary?) with
  C<Apache::Util::format_time()>, which requires a pool object as a
  forth argument. All four arguments are now required.
  
  For example:
  
     use Apache::Util ();
     $fmt = '%a, %d %b %Y %H:%M:%S %Z';
     $gmt = 1;
     $fmt_time = Apache::Util::format_time(time(), $fmt, $gmt, $r->pool);
  
  See the L<Apache::Util> manpage.
  
  
  =head2 C<Apache::Util::validate_password()>
  
  C<Apache::Util::validate_password()> has been replaced with
  C<APR::password_validate()>. For example:
  
     my $ok = Apache::Util::validate_password("stas", "ZeO.RAc3iYvpA");
  
  
  
  
  
  
  =head1 C<Apache::URI>
  
  =head2 C<Apache::URI-E<gt>parse($r, [$uri])>
  
  C<parse()> and its associate methods have moved into the C<APR::URI>
  package. For example:
  
    my $curl = $r->construct_url;
    APR::URI->parse($r->pool, $curl);
  
  See the C<L<APR::URI|docs::2.0::api::APR::URI>> manpage.
  
  =head2 C<unparse()>
  
  Other than moving to the C<APR::URI> package, C<unparse> is now
  protocol-agnostic. Apache won't use I<http> as the default protocol if
  I<hostname> was set, but I<scheme> wasn't not. So the following code:
  
    # request http://localhost.localdomain:8529/TestAPI::uri
    my $parsed = $r->parsed_uri;
    $parsed->hostname($r->get_server_name);
    $parsed->port($r->get_server_port);
    print $parsed->unparse;
  
  prints:
  
    //localhost.localdomain:8529/TestAPI::uri
  
  forcing you to make sure that the scheme is explicitly set. This will
  do the right thing:
  
    # request http://localhost.localdomain:8529/TestAPI::uri
    my $parsed = $r->parsed_uri;
    $parsed->hostname($r->get_server_name);
    $parsed->port($r->get_server_port);
    $parsed->scheme('http');
    print $parsed->unparse;
  
  prints:
  
    http://localhost.localdomain:8529/TestAPI::uri
  
  Notice that if C<L<Apache::compat|docs::2.0::api::Apache::compat>> is
  loaded, C<unparse()> will transparently set I<scheme> to I<http> to
  preserve the backwards compatibility with mod_perl 1.0.
  
  See the C<L<APR::URI|docs::2.0::api::APR::URI>> manpage for more
  information.
  
  
  
  
  
  
  =head1 Miscellaneous
  
  =head2 Method Handlers
  
  In mod_perl 1.0 the method handlers could be specified by using the
  C<($$)> prototype:
  
    package Bird;
    @ISA = qw(Eagle);
    
    sub handler ($$) {
        my($class, $r) = @_;
        ...;
    }
  
  mod_perl 2.0 doesn't handle callbacks with C<($$)> prototypes
  differently than other callbacks (as it did in mod_perl 1.0), mainly
  because several callbacks in 2.0 have more arguments than just C<$r>,
  so the C<($$)> prototype doesn't make sense anymore. Therefore if you
  want your code to work with both mod_perl generations and you can
  allow the luxury of:
  
    require 5.6.0;
  
  or if you need the code to run only on mod_perl 2.0, use the I<method>
  subroutine attribute. (The subroutine attributes are supported in Perl
  since version 5.6.0.)
  
  Here is the same example rewritten using the I<method> subroutine
  attribute:
  
    package Bird;
    @ISA = qw(Eagle);
    
    sub handler : method {
        my($class, $r) = @_;
        ...;
    }
  
  See the I<attributes> manpage.
  
  If C<Class-E<gt>method> syntax is used for a C<Perl*Handler>, the
  C<:method> attribute is not required.
  
  
  =head1 C<Apache::src>
  
  For those who write 3rd party modules using XS, this module was used
  to supply mod_perl specific include paths, defines and other things,
  needed for building the extensions. mod_perl 2.0 makes things
  transparent with C<ModPerl::MM>.
  
  Here is how to write a simple I<Makefile.PL> for modules wanting to
  build XS code against mod_perl 2.0:
  
    use Apache2;
    use mod_perl 1.99;
    use ModPerl::MM ();
    
    ModPerl::MM::WriteMakefile(
        NAME => "Foo",
    );
  
  and everything will be done for you.
  
  META: we probably will have a compat layer at some point.
  
  META: move this section to the devel/porting and link there instead
  
  =head1 C<Apache::Table>
  
  C<Apache::Table> has been renamed to C<APR::Table>.
  
  
  
  =head1 C<Apache::SIG>
  
  C<Apache::SIG> currently exists only
  C<L<Apache::compat|docs::2.0::api::Apache::compat>> and it does
  nothing.
  
  
  
  =head1 C<Apache::StatINC>
  
  C<Apache::StatINC> has been replaced by C<Apache::Reload>, which works
  for both mod_perl generations. To migrate to C<Apache::Reload> simply
  replace:
  
    PerlInitHandler Apache::StatINC
  
  with:
  
    PerlInitHandler Apache::Reload
  
  However C<Apache::Reload> provides an extra functionality, covered in
  the module's manpage.
  
  
  
  =head1 Maintainers
  
  Maintainer is the person(s) you should contact with updates,
  corrections and patches.
  
  =over
  
  =item *
  
  Stas Bekman E<lt>stas (at) stason.orgE<gt>
  
  =back
  
  =head1 Authors
  
  =over
  
  =item *
  
  Stas Bekman E<lt>stas (at) stason.orgE<gt>
  
  =back
  
  Only the major authors are listed above. For contributors see the
  Changes file.
  
  =cut
  
  
  
  1.8       +4 -4      modperl-docs/src/docs/general/os/win32/faq.pod
  
  Index: faq.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/general/os/win32/faq.pod,v
  retrieving revision 1.7
  retrieving revision 1.8
  diff -u -r1.7 -r1.8
  --- faq.pod	9 Feb 2003 02:05:20 -0000	1.7
  +++ faq.pod	11 Apr 2003 02:24:37 -0000	1.8
  @@ -166,7 +166,7 @@
   See the discussion of configuring 
   L<Apache::Registry|docs::1.0::guide::config/My_CGI_Perl_Code_Gets_Returned_as_Plain_Text_Instead_of_Being_Executed_by_the_Webserver>; for mod_perl 2.0, a
   L<different
  -configuration|docs::2.0::user::compat::compat/C_Apache__Registry___C_Apache__PerlRun__and_Friends>
  +configuration|docs::2.0::user::porting::compat/C_Apache__Registry___C_Apache__PerlRun__and_Friends>
   is required.
   
   =head2 I get a "Save-As" dialogue box when calling a script.
  @@ -174,14 +174,14 @@
   See the discussion about 
   L<PerlSendHeader|docs::1.0::guide::config/My_Script_Works_under_mod_cgi__but_when_Called_via_mod_perl_I_Get_a__Save_As__Prompt>; note that for mod_perl 2.0, 
   there is a L<different
  -syntax|docs::2.0::user::compat::compat/C_PerlSendHeader_>.
  +syntax|docs::2.0::user::porting::compat/C_PerlSendHeader_>.
   
   =head2 My script displays a "Content-type" header in the browser.
   
   Check the setting of 
   L<PerlSendHeader|docs::1.0::guide::porting/Generating_correct_HTTP_Headers>;
   note that for mod_perl 2.0, there is a L<different
  -syntax|docs::2.0::user::compat::compat/C_PerlSendHeader_>.
  +syntax|docs::2.0::user::porting::compat/C_PerlSendHeader_>.
   
   =head1 Using mod_perl
   
  @@ -198,7 +198,7 @@
   You should check the setting of 
   L<PerlSendHeader|docs::1.0::guide::porting/Generating_correct_HTTP_Headers>;
   for mod_perl 2.0, there is a L<different
  -syntax|docs::2.0::user::compat::compat/C_PerlSendHeader_>.
  +syntax|docs::2.0::user::porting::compat/C_PerlSendHeader_>.
   If this setting is correct, and
   this occurs under mod_perl 2.0 and
   Perl-5.6.1, try upgrading to