3. Configuration

3.1 Configure Pi3Perl

For quick start an example configuration called Pi3Perl.pi3 is provided with the installed package. The following gives you advise how to include Pi3Perl into existing configurations, if you're not willing to use Pi3Perl.pi3.

Included module and class configuration

In order to use Pi3Perl with Pi3Web, the file containing class configuration must be included into the main configuration file you are using:

include ../Conf/Pi3Perl.cnf

Mapping

The following will add code to map an URI starting with /pi3perl/ to the Pi3Perl handlers.

<Object>
        Name Start
        Class FlexibleHandlerClass
        # . . .
        Mapping P3PMapper From="/pi3perl/" To="../Pi3Perl/"
        # . . .
</Object>

<Object>
        Name P3PMapper
        Class PathMapperClass
        CaseSensitive "No"
        PathInfo "Yes"
        Action "&dbreplace(response,string,ObjectMap,Pi3Perl)"
</Object>

Invoke the handler

The configuration parameters used by the Pi3Perl handler are:

File

The Pi3Perl script file to be loaded and parsed, e.g. "../Pi3Perl/auth.pl"

Init

The Perl subroutine to be called optional on initialization, e.g. "init"

Execute

The perl subroutine to be called on execution, e.g. "execute"

...

All other parameters are forwarded to the Pi3Perl script as global perl variables

To invoke a Pi3Perl or a PSP handler, usually a flexible handler object is created. This handler must be added to the handler list of the server logic object in order to be activated.

<Object>
        Name HTTPLogicObject
        Class HTTPDispatcherClass
        # . . .
        Handlers Start P3P PSP Default
        # . . .
</Object>

<Object>
        Name P3P
        Class FlexibleHandlerClass
        Condition "&cmp(&dblookup(response,string,ObjectMap),Pi3Perl)"
        CheckPath ReturnCode ReturnCode=COMPLETED
        CheckType ReturnCode ReturnCode=COMPLETED
        CheckAccess AccessByFile RequirePermissions="X"
        CheckAccess ReturnCode ReturnCode=COMPLETED
        Handle Pi3Perl File="../Pi3Perl/snoopdb.pl" Execute="execute"
</Object>

The next example shows how to configure a Pi3Perl script, which is executed during CheckAuth phase in order to perform basic authentication. The example shows further the possiblity to hand over additional parameters to the Pi3Perl script as global perl variables $Realm and $AuthFile.

<Object>
        Name Authenticate
        Class FlexibleHandlerClass
        # Pass authentication if there is no realm 
        CheckAuth Condition="&not(&dblookup(response,string,AuthenticationRealm))" ReturnCode ReturnCode=COMPLETED
        CheckAuth Pi3Perl File="../Pi3Perl/auth.pl" AuthFile="../Pi3Perl/Users.txt" Realm="Administration" Init="init" Execute="execute"
</Object>

3.2 Configure PSP

Included module and class configuration

In order to use PSP with Pi3Web, the file containing class configuration must be included into the main configuration file you are using:

include ../Conf/Pi3Perl.cnf

Mapping

The following will add code to map an URI containing extension .psp to the PSP handlers.

<Object>
        Name Start
        Class FlexibleHandlerClass
        # . . .
        Mapping Condition="&regexp('*.psp*',$U)" PSPMapper From="/" To="WebRoot/"
        # . . .
</Object>

<Object>
        Name PSPMapper
        Class PathMapperClass
        CaseSensitive "No"
        PathInfo "Yes"
        Action "&dbreplace(response,string,ObjectMap,PSP)"
</Object>

Invoke the handler

The configuration parameters of the PSP handler are:

DestructLevel

The optional value determines, if the perl interpreter is destroyed on server shutdown or not. The default value of "0" does nothing.

To invoke a Pi3Perl or a PSP handler, usually a flexible handler object is created. This handler must be added to the handler list of the server logic object in order to be activated.

<Object>
        Name HTTPLogicObject
        Class HTTPDispatcherClass
        # . . .
        Handlers Start P3P PSP Default
        # . . .
</Object>

<Object>
        Name PSP
        Class FlexibleHandlerClass
        Condition "&cmp(&dblookup(response,string,ObjectMap),PSP)"
        CheckPath RefuseFileByMask AllowFileMask="EF" RefuseStatus=404
        CheckPath ReturnCode ReturnCode=COMPLETED
        CheckType ReturnCode ReturnCode=COMPLETED
        CheckAccess AccessByFile RequirePermissions="X"
        CeckAccess ReturnCode ReturnCode=COMPLETED
        Handle PerlSrvPages
</Object>