PowerWeb Server++ supports custom application development with a variety of compiled languages, Perl, Rexx and SQL. Applications can extend PowerWeb in one of two ways:
Scripts that modify the runtime behaviour of PowerWeb through WebHooks.
Extensions
A simple example is that of writing an equivalent of a CGI program, except that the API extension is far more efficient because it removes the overhead of the CGI interface which is typically many times greater than the overall time taken by PowerWeb Server++ to service a normal request. For example, PowerWeb Server++ might service an entire request within 30 milliseconds, whereas a CGI script could take 3 seconds just to load!
If your server is linked to a database to perform queries, an even better speedup can be achieved by using the API extensions. CGI scripts are forced to log on to the database server every time a request arrives. With an API extension, you can log on once when the PowerWeb Server++ starts up and then keep the connection open to service queries until such time as the PowerWeb Server++ shuts down, in which case you can log off from the database server. This results in far less network traffic as well as requiring less powerful hardware to sustain a given throughput.
WebHooks
PowerWeb Server++ APIs are calls to libraries written by the WebMaster or an associated programming team. They extend the functionality of PowerWeb Server++ by allowing selected portions of the operation of the server to be overridden. If necessary, every aspect of the server's handling of a request can be modified, to totally customise the server, while taking advantage of PowerWeb Server++'s fast, secure, and reliable kernel.
WebHook Categories
The WebHooks are broken up into three groups: Global, Server and Resource, according to the object to which they attach. Global WebHook apply across all services and requests, while Server WebHooks apply to a specific service and its operation. Resource WebHooks modify the behaviour of the PowerWeb Server++ when accessing or manipulating a particular resource, such as a document.
This fine level of granularity gives powerful control and flexibility so that the WebMaster can change the method of operation for a single document, while leaving all others unchanged, or the WebMaster could define a WebHook that applies to all resources across the entire server.
The management of all these WebHooks is performed through the Administration and Configuration Pages with a web browser. There is no need to manually modify operating system configuration files with arcane details.
Languages
WebScripts and API extensions can be written in Perl, Rexx or in any compiled language compatible with the C language calling convention (such as COBOL or FORTRAN). The ability to write extensions in Perl and Rexx provides quick prototyping and in most cases will give satisfactory speed (achieved through caching Rexx scripts in tokenised form to reduce overhead, and compiling Perl packages).
Guided Tour
You should take some time to work through the Guided Tour which illustrates many of these concepts in action.
The CGI interface requires the server to load a new process for every request. If the server doesn't have to run such CGI programs all that often, there is typically no performance problem, but if CGI is being used often, the overhead of simply creating the new process to run the CGI program is normally far higher than that of servicing the request itself (usually 10 to 100 times longer).
CGI is also limited to the extent with which it can interact with the server. A CGI program is passed a fixed set of a few server status variables and has no way of obtaining more information, or of returning information, other than documents, to the server. This severely limits the types of applications that can be created with CGI.
CGI is targeted at one specific purpose: the task of returning a document to the server to be relayed to the client's browser. There is no facility to modify aspects of the server's operation, such as customising the authentication procedure or altering the format or destination of the audit log (to store it in a relational database for example).
All these limitations and efficiency issues are overcome through the PowerWeb Server++ APIs. The lowest possible overheads, full access to the entire Server status and data structures, and the ability to customise any aspect of the server's operation are key benefits of the API.
There are specific reference manuals for each supported language:
If an API extension encounters an error, it should log it in the error log (by writing to the variable "Server:/ErrorOutput"), set a protocol-dependent status code (by writing to the variable "Request:/StatusCode") and return HOOK_ERROR or HOOK_ABORT_xx. Custom error message text to be sent to the client browser can be stored in "Request:/StatusText".
PowerWeb Server++ function calls and variables are multi-thread safe, so there will be no problems with partially interleaved text being sent to the error log, for example.
With both your script and your document being kept in a single file, file management becomes very simple, as does making changes.
Automatic document generation through Web development tools becomes much easier with the application of our InSide HTML technology which mixes and matches languages within a single file so that you can use the most appropriate language for each part of the task, such as SQL for database queries, HTML for formatting and Perl for general text manipulation.
Each language reference manual has a section on how to embed code for that language within HTML.
With a URL:
Modules can be called directly by using a URL, and do not need to be associated with a specific Resource.
Rexx Example: /example/rexx-bin/svrpush.cmd Perl Example: /example/perl-bin/Sample!Tree C Examples: /example/bin/tour!TourDirect /bin/property!ShowMenu
Perl Example: /example/perl-bin/Sample!Tree
C Examples: /example/bin/tour!TourDirect /bin/property!ShowMenu
Modules can be called directly from within PowerWeb Macros. The Macro is named exec and is used as follows:
Rexx Example: <!--#exec rexx="/rexx-bin/svrpush.cmd" --> Perl Example: <!--#exec perl="Sample!Tree" --> C Examples: <!--#exec api="/example/bin/tour!TourDirect" --> <!--#exec api="/bin/property!ShowMenu" -->
Perl Example: <!--#exec perl="Sample!Tree" -->
C Examples: <!--#exec api="/example/bin/tour!TourDirect" --> <!--#exec api="/bin/property!ShowMenu" -->
You can use Web Macros within HTML text generated by an Extension. To do this, you need to instruct PowerWeb that your text contains Web Macros. In Rexx, use: call ServerWriteText parcel, "Request:/Header/Out/Content-type", "text/x-server-parsed-html" in Perl, use: WebPerl::WriteText($parcel, '', 'Request:/Header/Out/Content-type', 'text/x-server-parsed-html'); and in C or C++ use: ServerWriteText(parcel, "Request:/Header/Out/Content-type", "text/x-server-parsed-html");
In Rexx, use:
call ServerWriteText parcel, "Request:/Header/Out/Content-type", "text/x-server-parsed-html"
in Perl, use:
WebPerl::WriteText($parcel, '', 'Request:/Header/Out/Content-type', 'text/x-server-parsed-html');
and in C or C++ use:
ServerWriteText(parcel, "Request:/Header/Out/Content-type", "text/x-server-parsed-html");
Within text output by an Extension, you can include files already stored on your server, in addition to dynamically generated text. This is achieved through using the "#include" Web Macro as follows: ServerWriteText(parcel, "Request:/Result", "<!--#include virtual=/standard/incl.htm -->"); which will cause the contents of the document with URL "/standard/incl.htm" to be included into the response.
ServerWriteText(parcel, "Request:/Result", "<!--#include virtual=/standard/incl.htm -->");
which will cause the contents of the document with URL "/standard/incl.htm" to be included into the response.