WebPerl
 

FTP: Windows 95 Perl, Windows NT Perl, OS/2 Perl.
OS/2 GNU EMX0.9c runtime at ftp.cdrom.com or hobbes.nmsu.edu

Newsgroups: comp.lang.perl.announce and comp.lang.perl.misc and comp.lang.perl.modules

Table of Contents

Introduction
Installation
InSide HTML: Embedding Perl
Structure of a Perl Script
Creating Your Perl Libraries
Managing Your Perl Scripts
Performance Tips
Examples
Function Definitions
Introduction
 WebPerl is the fastest and easiest way to create dynamic documents and extend the functionality of PowerWeb. Perl is seamlessly integrated into PowerWeb to allow mixing of Perl with HTML, SQL and Rexx all in one document.

You can take advantage of the many existing Perl libraries as well as leverage the skills of many people who are already familiar with Perl.

WebPerl's strength is that you can embed Perl inside HTML and keep your code and document together in one place for improved management and development.

You can also create stand-alone Perl modules or functions that can be grouped into packages. The advantage of this approach is that your Perl code can be shared among many HTML documents.

PowerWeb also allows you to extend its internal engine by defining API Hooks which selectively override aspects of its behaviour, such as user authentication and access control. You can write these hooks in Perl as subroutines within packages and take advantage of PowerWeb's caching of Perl modules which compiles packages the first time they are used.

Special thanks are due to Ilya Zakharevich for assisting the Power Team with the OS/2 Perl interface.

Installation
 For OS/2:

You will need to install a copy of Perl version 5.00301 or later and ensure that Perl is operating correctly on your machine.

You will need a copy of the GNU EMX runtime 0.9c or later. Perl can be run from any drive, so long as you set your LIBPATH and PATH within your config.sys, such as in the following example:

LIBPATH=p:\perl5.003.os2\emx.add\dll
PATH=p:\perl5.003.os2\emx.add\bin

For Windows NT/95:

You will need to install a copy of Perl version 5.001m build 110 or later and ensure that Perl is operating correctly on your machine. It is important that you run the INSTALL program that comes with Perl, otherwise your System Registry will not be updated and some Perl facilities will not operate.

For all platforms:

You should be able to type the following from a command line and have it execute without any errors or warnings:

perl -w -e "print('Test Successful');"
If you see some warning messages about "locale", then your language setting is wrong in your "config.sys". One solution is to disable national language processing by using "SET LANG=" within your "powerweb.cmd" or within your "config.sys" file.

PowerWeb does not need any special installation to work with Perl because it automatically configures itself correctly on startup to be able to call Perl.

InSide HTML: Embedding Perl
 The easiest way to create your own Perl programs is to embed them within HTML. This is demonstrated by the "\powerweb\system\tour\perltime.htm" HTML document which shows how you can store Perl code within an HTML document and have it executed by the server before the page is delivered to the client's browser.

The process to follow is:

  1. Place your Perl code within a #Script WebMacro.
  2. Write the HTML portions of your document.
  3. Call the Perl code by using a #Call WebMacro.
The skeleton structure for your document is therefore:
<!--#script ScriptName -->
Your Perl Code
<!--#endscript -->
<html>
Your HTML text.
<!--#call perl=ScriptName -->
Your further HTML text.
</html>
Structure of a Perl Script
 Perl interfaces to PowerWeb through a package named WebPerl. PowerWeb calls WebPerl with a "parcel" that is a magic cookie for further communication between PowerWeb and Perl.

If you are using an embedded Perl script, you access this "parcel" within Perl as follows:

my($parcel) = WebPerl::GetParcel();
If instead you are using a subroutine within a Perl package as your script, you access this "parcel" within Perl as follows:
my($parcel) = @_;
By using this "parcel", you can gain access to any PowerWeb variable through the PowerWeb API functions, which are documented in the PowerWeb API Function Reference Manual.

Your Perl script is expected to return a scalar integer result indicating the success or failure of your script, according to the following table:

Creating Your Perl Libraries
 PowerWeb allows you to organise your Perl scripts into packages and then either call them from within HTML or directly by means of a URL.

For example, the "Tree" function within the example package in "\powerweb\system\perl-bin\Sample.pm" can be invoked with a URL as follows:

/example/perl-bin/Sample!Tree
or it can be included within an HTML page in one of the following ways:
  • <!--#exec perl=Sample!Tree -->
  • <!--#exec perl=/example/perl-bin/Sample!Tree -->

    • Through this mechanism, you can store your commonly used Perl scripts as subroutines within packages and thereby share them across HTML documents and also provide direct access to them with URLs.

    A benefit of using packages is that you can take advantage of Perl compiling your package on first usage for better speed on subsequent invocations.

    Caching

    By default, PowerWeb caches Perl, which means that often-used packages get the benefit of compilation. The disadvantage is that during development when the code within the package may change frequently, Perl remembers the package as it was originally compiled.

    So for development, use the Perl Management page to switch caching off so that you always get the results of your most recent change to the package. Another benefit for developers is that when caching is off, the Perl warnings switch "-w" is enabled, which helps in debugging your Perl scripts.

    An alternative is to use old-style Perl modules instead of packages. Packages have a ".pm" extension and are found by searching along the PERLLIB path, whereas Modules have a ".pl" extension and the full path must be explicitly provided. WebPerl does not compile and cache modules, so during development you can write your Perl script as a Module and then convert it to a Package when it is finalised and debugged, to obtain the extra speed. When operating like this, you can leave the Perl caching on.

    If you need to change a Perl script on a production server which is using Perl caching, use the Perl Management page to reload Perl which forces a recompilation next time the package is used.

    Managing Your Perl Scripts
     You can store HTML documents containing Perl scripts anywhere within your document tree. Just be sure to grant API execution permission to those documents by assigning, for example, either the ExecHTTP or the Macro template to the resource containing the documents.

    PowerWeb reserves the "perl-bin" sub-directory underneath your server root directory for storage of your Perl packages. PowerWeb is automatically configured to recognise files in that directory as Perl scripts and also automatically includes that directory on the PERLLIB search path so that Perl will find your packages.

    Performance Tips
     Perl compiles packages on first use, so placing your commonly used subroutines in a package will speed subsequent calls. You can call Perl packages from within your Perl code embedded within HTML, either directly or by using the #exec WebMacro.

    Perl is auto-loaded and cached by PowerWeb on demand, so all but the first usage of Perl on your server will be fast.

    It is generally faster to use Perl to concatenate strings before sending them to PowerWeb, instead of using the WebPerl::AppendText or WebPerl::Print functions for each sub-string.

    Examples:
    Browser Statistics:
    The module "browsers.pl" in the "\powerweb\system\perl-bin" directory shows how you can analyse your user-agent log files to report statistics on browsers accessing your site.

    TimeZone Display Example:
    Under "\powerweb\system\tour", there is a document "perltime.htm" which demonstrates how Perl can be embedded within HTML to display tables with dynamic content. Try it! The first time you try it, you may experience a delay while Perl loads and compiles the script.

    Directory Listing Example:
    Under "\powerweb\system\perl-bin", there is a Perl package "sample.pm" with function "DirList" which demonstrates how Perl can be used to process HTML forms and dynamically generate Web Macro code. Try it! The first time you try it, you may experience a delay while Perl loads and compiles the script.

    Tree Display Example:
    Under "\powerweb\system\perl-bin", there is a Perl package "sample.pm" with function "Tree" which is equivalent to the C-code Guided Tour example which displays your server configuration settings in a tree format. Try it! The first time you try it, you may experience a delay while Perl loads and compiles the script.

    Function Definitions
     The Perl Library is equivalent in functionality to the C-compatible API library. The function names have been kept consistent for ease of working in all language environments. It is a straightforward procedure to port a Perl implementation to C for speed because of this consistency.

    You will need to read the API Function Reference, before writing code which calls these functions.

    The WebPerl Interface Function Definitions Are:

    Return
    Value    		Function
    Name    		Input
    Parameters
    handle WebPerl::GetConfig parcel
    handle WebPerl::GetServer parcel
    handle WebPerl::GetConnect parcel
    handle WebPerl::GetRequest parcel
    handle WebPerl::GetParameters parcel
    handle WebPerl::GetArguments parcel
    handle WebPerl::Find parent, name
    type WebPerl::Kind handle
    size WebPerl::Size handle
    name WebPerl::Name handle
    bool WebPerl::Flush handle
    value WebPerl::ReadInteger parent, name
    value WebPerl::ReadFloat parent, name
    value WebPerl::ReadText parent, name
    value WebPerl::ReadBinary parent, name
    bool WebPerl::WriteInteger parent, name, value
    bool WebPerl::WriteFloat parent, name, value
    bool WebPerl::WriteText parent, name, value
    bool WebPerl::WriteBinary parent, name, value
    bool WebPerl::AppendText parent, name, value
    bool WebPerl::AppendBinary parent, name, value
    bool WebPerl::Print value
    bool WebPerl::NewInteger parent, name, value
    bool WebPerl::NewFloat parent, name, value
    bool WebPerl::NewText parent, name, value
    bool WebPerl::NewBinary parent, name, value
    bool WebPerl::NewList parent, name
    bool WebPerl::NewSemaphore parent, name
    bool WebPerl::Delete handle
    handle WebPerl::Parent handle
    handle WebPerl::Child handle
    handle WebPerl::Sibling handle
    bool WebPerl::Interpret parcel, code
    error WebPerl::GetError
    parcel WebPerl::GetParcel
    name WebPerl::GetFunction