## PowerWeb Server++ Guided Tour

Welcome to the PowerWeb Server++ Guided Tour which demonstrates some of the many features of PowerWeb Server++. You may also wish to read the categorised feature list which will appeal to the technically minded.

## Before You Start the Tour

Please check the following features and options are enabled in your Web Browser:

> Your browser supports forms, image maps, user authentication and tables.
> You have enabled the loading of graphic images.
> You have loaded this page from the PowerWeb server, and not locally from a file.

## Overview of the Tour

> Information Retrieval

> > Retrieving Documents
> > Automatic Directory Indexing
> > Image Maps for Hot-Zone Graphics
> > Automatic Fixup of Abbreviated URLs

> Security Features

> > User Authentication
> > Access Control

> Three Methods of Extending PowerWeb

> > API Extensions
> > PowerWeb Macros
> > CGI Programs
> > Direct Call API Programs

> Dynamic Documents

> > Conditional Documents
> > Automated Forms Processing

> Miscellaneous

> > Local or Remote Server Administration
> > Monitoring Real-Time Statistics
> > Viewing Current Connections
> > Examining Logs

## Retrieving Documents

The primary purpose of a Web server is typically to retrieve documents, images or data files for display by a client browser. When a user clicks on a hyperlink, a request is sent to the server, which responds with the specified document.

## Automatic Directory Indexing

PowerWeb Server++ provides automatic indexing of document directories for display on the client's browser. This means your Web server can act as a visual and interactive equivalent of an FTP server, without having to run an FTP service.

Two basic views are provided: simple and fancy. The "fancy" view allows customisation of which columns are included in the directory index.

Click here to see an example of a directory index.

## Image Maps for Hot-Zone Graphics

PowerWeb Server++ uses its built-in imagemap command to process mouse clicks based on hot-zones within an image. The location of the click defines the next document to retrieve. For example, a map of a production plant could redirect users to information specific to a section or machine within the factory.

PowerWeb Server++ eliminates the overhead of other Web servers that process image maps using a CGI program, by processing image maps internally. Existing documents that use the CGI method automatically use the new built-in imagemap command without having to modify the original document.

The image below illustrates the three main ways of defining hot-zones within the image - a circle, a rectangle and a generalised polygon. PowerWeb Server++ also implements the nearest point algorithm. Point your mouse and click on various regions within the image to see how PowerWeb Server++ can serve different documents according to where you click.

The HTML code that accomplished this is:

> `<a href=/$imagemap/tour/mapdemo.map> <img src="mapdemo.gif" ISMAP width=500 height=140></a>`

## Automatic Fixup of Abbreviated URLs

When a user sends a request which doesn't specify a document name, the server either treats it as a directory index request or as a request to see the home or welcome page for that resource.

In either case, if the user ommitted the slash at the end of the name, such as using "http://widget.com/products", the browser must be informed that the information being returned comes from a directory, so PowerWeb Server++ automatically adds a trailing slash (in our example, the result would be "http://widget.com/products/") and informs the browser accordingly.

Servers which don't provide this feature force Web authors to use absolute instead of relative document references, making administration of the documents on a server much more time consuming and error prone.

Another very useful feature of PowerWeb Server++ is the automatic fixup of URLs that use long file names, while the server is running on a FAT 8.3 disk partition. This allows easy cross-compatibility between UNIX servers and MS-DOS based servers.

For example, the current document can be referred to as any of:

- http://localhost/tour
- http://localhost/tour/
- http://localhost/tour/index.htm
- http://localhost/tour/index.html

and the same document will be returned.

## User Authentication

User Authentication is a separate issue to Access Control within PowerWeb Server++. This separation not only gives greater flexibility in terms of security rules, it also allows for a plug-in-replacement of the authentication method, with alternatives such as SSL.

Whenever you access a server administration document, you are subject to user authentication. If you haven't previously accessed an admin document then accessing the administration main menu will cause you to be prompted for your administration user name and password. Most browsers will cache your most recently used name and password, so if you are not prompted, it means your browser authenticated you automatically.

## Access Control

Access Control within PowerWeb Server++ refers to a set of security rules that define who can access what, from where, with what protocol. A default access control configuration is created for you upon installation.

This default configuration allows any user to retrieve documents within the document root directory tree. It also allows users to append to form databases (the guided tour will demonstrate these later) but only allows admin users to create new documents on the server.

## API Extensions

API Extensions let you change or extend the behaviour of the PowerWeb Server++, without any cost in performance. CGI is very slow and is far more limited. PowerWeb Server++ APIs allow you to override any part of the server, including user authentication, command processing, and error logging.

An API extension can be global, specific to a given service, or specific to a given resource (such as all documents matching a specific wildcard pattern). The browser-based configuration utilities let you associate an API extension with whatever you wish, without having to manually edit complex operating system specific initialisation files.

This example shows you how you can define a custom viewer for database files. These files are protected by access control and authentication, so you need to know your user name is "tourist" and your password is "guide". Click here to see a directory of comma-separated-variable files and then choose one of them to see it in HTML tabular format.

This kind of transparent dynamic document translation is impossible with CGI.

You can view the C source code for the API extension which performs the dynamic translation.

You can also read the PowerWeb API Reference Manual for more detail.

## PowerWeb Macros

PowerWeb Macros are a way of extending the server through simple HTML tag language extensions. They can query or modify the status of the server, conditionally show documents or sections of documents, process forms automatically, create new documents through wizards, execute other programs, as well as many other uses.

For example, through simple status queries, it is easy to determine the following:

> Number of Requests Serviced: |
> Current Number of Connections: |
> This Document's Size: |
> This Document was Last Modified: |

With PowerWeb Macros, you can query the value of any server configuration setting, status variable, form input field, or in fact all server data structures. For example, the code to display the number of current connections was simply:

> `<!--#echo var=Server:/Stats/Clients -->`

You can also use Web Macros for conditional text. For example, the next paragraph will either read "You are the only user", or it will read "There are nn current users on the server".

There are current users on the server. You are the only user.

The HTML to achieve this is:

> `<!--#if @Server:/Stats/Clients > 1 -->
> <b>There are <!--#echo var=Server:/Stats/Clients--> current users on the server.</b>
> <!--#else -->
> <b>You are the only user.</b>
> <!--#endif -->`

There are many more PowerWeb Macro features, some of which you will see highlighted later on during this tour. You can also read the PowerWeb Macro Reference Manual for more detail.

## CGI Programs

PowerWeb Server++ implements a mechanism to call external programs to deliver custom documents. The method is known as the Common Gateway Interface (CGI) and is a standard across most Web servers.

It is not recommended that you use CGI for new development because PowerWeb Server++ Macros and API Extensions offer a far superior solution for almost all purposes.

Click here to see the output of a batch program that was invoked by PowerWeb through CGI when you clicked on the hyperlink.

## Direct Call API Programs

It is easy to call C and Rexx API functions directly, without the overhead of CGI, and with all the power of the API extensions available.

If your browser supports "Server-Push" (such as Netscape 1.1 or later), view a dynamic series of documents displayed using a Rexx module.

The Direct C Interface is very simple to use. The common Hello World example, here is written in C (view the source code of function "TourDirect").

A more sophisticated example of the Direct C Interface is given by the function "TourTree" (in the same module) which displays a tree view of the settings of your server. For example, /bin/tour!TourTree displays your configuration whereas /bin/tour!TourTree?Request:/ displays details of your current HTTP request.

If you would like to contribute your own examples, please upload them with FTP to the site "www.compusource.co.za" in the "/incoming" directory, for others to share.

## Conditional Documents

With PowerWeb Macros, it is easy to show different documents, or different parts of documents, according to a variety of conditions. For example, you might have a document which you know can only be shown properly with one type of browser, but you want an alternative to be shown for all other browsers. You could request people to use two different URLs, but that isn't practical. PowerWeb Macros make it easy to manage this process.

Point your browser here to show one of two documents based on whether you are using an IBM Web browser.

Here is the HTML source code:

> `<!--#if @Request:/Header/In/User-Agent ? "IBM" -->
> <!--#include file=ibm.htm -->
> <!--#else -->
> <!--#include file=other.htm -->
> <!--#/if -->`

Of course, there are many other reasons to show documents conditionally. For example, you could show a user different documents according to the data entry content of a form. A good example of this is the PowerWeb installation and enrolment which transparently shows different documents according to your current registration status.

## Automated Forms Processing

Unlike other Web servers, PowerWeb Server++ makes it easy to manage the processing of forms. In many cases, the processing and storage of the form data can be accomplished entirely with PowerWeb Macros. The benefit of this is that you can develop rapid prototypes and then use the final prototype for production.

If you are feeling hungry, order a Power Pizza now. This example shows automated storage of your order details into a database file, calling an external calculation routine with an API extension, and conditional document display. Of course, you can now use our earlier API extension for viewing database files to take a look at the order database. Remember your username is "tourist" and password is "guide".

You can also read the PowerWeb Command Reference Manual for more detail.

## Local or Remote Server Administration

With PowerWeb Server++, you administer and configure the server with your Web browser. You can operate locally or remotely and manage your server from any workstation and operating system that supports a Web browser with table support. All the management utilities are user name and password protected, and the WebMaster has the ability to restrict admin access to particular workstations.

Click here to go to the main menu of the Administration and Configuration utility. If you haven't changed the default password yet, then this screen lets you change the admin password.

## Monitoring Real-Time Statistics

PowerWeb Server++ makes it easy to monitor your server and its throughput. It keeps real-time statistics which can be viewed at any time.

If you are running multiple services, such as HTTP and POP3, then each service can be monitored separately, all from the same Web browser interface.

## Viewing Current Connections

The advanced real-time multi-threaded architecture of PowerWeb Server++ is illustrated by the ability to view the status of all current connections. The IP address of each connection is shown, along with its activity and current status.

For example, take a look at the current connections on your own server.

## Examining Logs

PowerWeb Server++ keeps a log of all activity on the server. The two basic logs are the audit log which tracks all requests submitted to the server and the error log which records all errors that occur (such as invalid configuration settings). PowerWeb Server++ uses the NCSA/CERN common log format by default, but this can be changed through API Extensions.

By clicking here you can view the recent activity in the audit log and the error log. Go here instead for more complete management of the logs, including rotating or truncating the logs.