Running Caché WebLink with Apache Web Servers

Apache Version 1.2.x and 1.3.x for UNIX and NT Systems

Installing and Operating WebLink's Network Service Daemon

Apache Version 1.2.x and 1.3.x for UNIX and NT Systems

The Microsoft and Netscape line of Web servers both support a multi-threaded API which allows extensions, in the form of dynamically bound libraries, to be made to the Web server's core functionality. Current versions of WebLink make full use of these APIs in order to bring high-performance Web connectivity to the Caché system.

Apache is different to the Microsoft and Netscape Web servers in that it does not support the Microsoft/Netscape style of API. However, extra functionality can be added to Apache by means of user-defined modules (compiled C programs). In fact, a large part of Apache's core functionality is implemented as a set of modules.

Unfortunately, adding a new module to Apache involves reconfiguring and rebuilding the Web server. A WebLink module is provided for this purpose. For those who do not wish to rebuild their Web server, WebLink also provides a high-performance CGI-based solution. Both the WebLink module and the CGI executables are small functional blocks designed to exclusively communicate with WebLink's Network Service Daemon (NSD). The NSD is responsible for providing WebLink's core functionality and persistent links to Caché.

The key decision to make at this point is whether or not you wish to rebuild the Apache Web server in order to add the WebLink module or opt for the less complicated CGI solution instead. The performance of the two approaches appears to be similar though, technically, the bound-in module ought to be faster. Read on to the section describing how you add WebLink's module for guidance on how to build the module into the Apache core or skip to the section describing how you add WebLink's CGI module for the CGI-based approach.

Adding the WebLink Module to Apache

Be sure to read these instructions in conjunction with the specific documentation contained within your Apache distribution. Note that the instructions given here assume that the root directory for the Apache installation is apache. In practice, this directory name will usually have the apache version number appended to it. The instructions given here refer to UNIX systems - the procedure for NT/95/98 systems is similar.

Adding the WebLink Module Source Code to the Apache Source Directory

The code for user-defined modules resides under directory:


/apache/src/modules

Create the following directory for the WebLink module:


/apache/src/modules/weblink

While in the /apache/src/modules directory, type


mkdir weblink

Copy the source for the WebLink module (mod_weblink.c) into this directory. You should now have:


/apache/src/modules/weblink/mod_weblink.c

Creating a Makefile for the WebLink Module

Now we need to create a Makefile. The Makefile contains instructions on how the WebLink module should be compiled and linked. Apache always provides an example module - we will make a copy of the example's Makefile and modify it for WebLink.

Make sure you are in the weblink directory:


/apache/src/modules/weblink

Copy the example Makefile by typing:


cp ../example/Makefile* ./

Depending on the version of Apache you have, you will find one of the following files in the weblink directory:

For Apache 1.3.x: Makefile
For Apache 1.3.x: Makefile.tmpl (Makefile template)

Edit whichever file you have and replace all references to mod_example with mod_weblink.

Configuring the Apache Build Process to Recognize the WebLink Module

Return to the src directory:


/apache/src

Edit the file: Configuration.

For Apache 1.2.x:

Near the end of this file you should find the line:


# Module example_module modules/example/mod_example.o

After this line, add the following line:


Module weblink_module modules/weblink/mod_weblink.o

For Apache 1.3.x:

Near the end of this file you should find the line:


# AddModule modules/example/mod_example.o

After this line, add the following line:


AddModule modules/weblink/mod_weblink.o

Running the Configure Script to Build the Main Makefile

You can now configure the build process. Make sure you are in the src directory:


/apache/src

Type:


./Configure

Building Apache on Red Hat Linux

Red Hat Linux is distributed with a pre-built version of Apache. Provided you chose to install Apache as part of the Linux installation procedure, you will find that Apache is automatically started when Linux is booted. The layout of the run-time file system for this pre-built version is slightly different to that which is prescribed as the default layout in the Apache source code. In order to account for this, the following change should be made to the header file httpd.h:

For Apache 1.2.x:


/apache/src/httpd.h

For Apache 1.3.x:


/apache/src/include/httpd.h

The Web server root (HTTPD_ROOT) is one of the first items defined in this file. For Red Hat Linux this should be defined as follows:


#define HTTPD_ROOT "/etc/httpd"

Building the Apache Executable

We can now build the Apache executable. Make sure you are in the src directory:


/apache/src

Type:


make

This should produce a new Web server executable (httpd) with the WebLink module's functionality built-in. The httpd executable will be created in the src directory. For normal operation this should be copied to (and run in) the apache directory.

For Red Hat Linux, the executable httpd should be copied to:


/usr/sbin

Note: Be sure to backup the existing copy first.

Run-time Configuration

Edit the Apache configuration file httpd.conf. For the standard Apache distribution this file will be found in:


/apache/conf

For Red Hat Linux, the run-time version of httpd.conf will be found in:


/etc/httpd/conf

Assuming that you wish to invoke WebLink from the usual /scripts location, add the following section to the end of this file:


<Location /scripts>


SetHandler weblink-handler 


</Location>

It is not necessary to physically create the scripts directory, but it is recommend that you do just in case a previously invoked module (i.e., invoked before WebLink) takes exception to the fact that the /scripts directory does not exist. Note that all requests to Apache are serviced by a set of modules invoked in sequence - WebLink is one of these modules, but will be one of the first invoked provided you added its definition near the end of the Configuration file as suggested previously.

The /scripts directory should be created below the documents root. For the standard Apache distribution this will be:


/apache/htdocs

Create:


/apache/htdocs/scripts

For Red Hat Linux, the document's root is:


/home/httpd/html

Create:


/home/httpd/html/scripts

Now, proceed to the section describing how to install and set up WebLink's Network Service Daemon.

Adding WebLink's CGI Module to Apache

Copy the two WebLink-CGI executables (mgwcgi and nph-mgwcgi) into the CGI directory, which for the standard Apache distribution is:


/apache/cgi-bin

For the Red Hat Linux distribution, the CGI directory is:


/home/httpd/cgi-bin

That's all you need to do - proceed to the section describing how to install and set up WebLink's Network Service Daemon (NSD).

Note that WebLink's CGI modules are also available for NT/95/98 platforms (mgwcgi.exe and nph-mgwcgi.exe). Note also that because CGI is an open standard, WebLink's CGI modules will work with any Web server.

Installing and Operating WebLink's Network Service Daemon

In order for the two Web connectivity options to operate, the WebLink NSD must be up and running. If necessary, create the following directory directly below the system root:


/cachesys/weblink

From the distribution, copy the NSD executable (mgwmt for UNIX and mgwmt.exe for NT/95/98) into this directory.

To start the NSD type:


./mgwmt

Before retiring to the background, the NSD will display various lines of text indicating the running configuration. It will show the TCP port number dedicated to this service, which is, by default, port number 7037. This can be overridden by starting the service as follows:


./mgwmt <port_no>

where port_no is the TCP port number of your choice.

All startup messages for this command can be suppressed using the -s qualifier. For example, if you wish to silently start the NSD from a script invoked when the system is booted use:


/cachesys/weblink/mgwmt -s [port_no]

To close down WebLink's NSD, issue the following command (UNIX systems):


kill -TERM `cat /cachesys/weblink/wlserver.pid`

This will close down WebLink in an orderly manner - WebLink will close down all the open connections to Caché and release all its system resources before terminating. Do not use the 'kill -9' command to terminate WebLink's NSD! For NT/95/98, follow the instructions given on the screen.

All errors will be reported in WebLink's event log (i.e. mgw.log). This file will be created and maintained in the /cachesys/weblink directory. WebLink's configuration file mgw.ini will also reside in this directory.

The NSD will also create the following file:


/cachesys/weblink/wlserver.ini

This file is extremely important because it tells the clients how to communicate with the NSD. In this context, the clients are the WebLink module contained within Apache and the WebLink CGI modules invoked by Apache. It is, therefore, essential that this file is not deleted or moved. It is also important that the Apache processes can read this file. Set the privileges accordingly, bearing in mind the UNIX user under which your Apache server is operating.

Calling WebLink through Apache

Having started the WebLink NSD, you are ready to start Apache and run WebLink applications. The order in which these services are started does not actually matter.

If you chose the WebLink module approach, point your browser at:


http://<ip_address>/scripts/mgwms32.dll

- you should see the WebLink Systems Management forms. If you chose the CGI route, point your browser at:


http://<ip_address>/cgi-bin/nph-mgwcgi

- You can choose to run via both methods! You will have noticed that two CGI modules are supplied - mgwcgi and nph-mgwcgi. These are, in fact, the same. The nph prefix is the CGI convention for instructing the Web server not to parse the HTTP headers (i.e. non-parsed-headers). The Web server will simply forward your headers on to the browser.

WebLink and WebLink-based applications usually assume the responsibility for sending a full HTTP header. Under CGI, the first line of the header (the request status line) has traditionally been the responsibility of the server-side of the CGI interface. Some Web servers are strict about this - Apache is one such example. Apache expects the first header line sent by your application to be the Content-type line and not the request status line (e.g. HTTP/1.0 200 OK) - it will return an error if it parses the header and does not detect a Content-type line first. Using the 'nph' version of the CGI module alleviates this problem. Not all Web servers are so strict about this - Microsoft's Web server does not object to receiving a full HTTP header via mgwcgi.exe.