Setting Up Application Servers

General

It is highly recommended that you build and test your application using the traditional CGI approach. Only after you have tested your application as a CGI and are happy with the way it works should you convert it to an application server.

To upgrade an existing project may require no code changes at all - just load it into Sapphire/Web 3.0, change a few options, perform a few manual steps, and that's it.

If your projects contain C or C++ code that you have written you should read the section of this file titled "Changing existing CGI code to work with Application Servers"

Set-up Steps

Setting up your development environment to create an application server (instead of a CGI program) consists of a number of simple steps. The last three steps need to be repeated for every new application server program created.

: 1. Installing the Sapphire/Web Application Server Manager.
: 2. Install the NSAPI or Generic server extension and verify that it works. This may involve shutting down your web server if it is already running another copy of the extension. See the next sections for individual instructions.
: 3. Develop, test, and prove your application as a CGI application. This is a good step to do because a CGI exits as soon as it is finished, while an Application Server does not. You cannot overwrite a program on disk while it is running, so developing as an Application Server would require either waiting for the time-out period to expire before trying a new build, or else manually closing the task.
: 4. Change project options to convert the project from a CGI to an application server and re-create the executable from the Sapphire/Web project.
: 5. Modify the Sapphire/Web Application Server Configuration File.

Server Setup for Netscape & NSAPI

Sapphire/Web 3.0 for UNIX supports NSAPI with the SaPlugin.so. This shared object can be found in the /bin directory of your Sapphire/Web installation.

Server Extension Installation

If you want to use Application Servers with NSAPI you will need to edit the Netscape HTTP server configuration files, stop, and then start your HTTP server. You can find these files in the config directory where you installed your Netscape server.

: 1. In obj.conf add these lines near the top :
: Line 1

Init fn="load-modules" 
shlib="/usr/Sapphire/bin/SaPlugin.so" funcs="sapphire-
form,sapphire-init"

: Line 2

Init fn="sapphire-init" 
file="/usr/Sapphire/config/apserver.txt"

Notes to item 1:

the value for shlib and file depend on your operating system and platform. shlib must be the full path to the SaPlugin.so file that was delivered with Sapphire/Web in the /bin directory ($SAPPHIRE/bin).
The value for file must be the full path to the Sapphire Application Server configuration file described below.
the slashes are forward slashes because Netscape may have problems if you use back slashes for the file name (even on NT).

: 2. In obj.conf add these lines somewhere between the <Object name="default"> and </Object> tags:

Service fn="sapphire-form" method="(GET|POST)" 
type="magnus-internal/sapphire"

: 3. In mime.types add this:

type=magnus-internal/sapphire exts=sph

After changing these options you must stop and start your Netscape server so it can start processing Sapphire Application server requests. When you go to the Netscape administration pages be sure to apply the changes you have just made by hand. If you do not apply these changes when you run Netscape Administration you will lose your manual edits.

NSAPI default file

You need to add a file somewhere on your web site called default.sph. It is recommended that you put this in the document root of your web server but you can place it anywhere that your web server can get at it. This file contains nothing, it is just there so the HTTP server will process your requests and not give you a "file not found" error. The .sph extension tells the web server to process this as a Sapphire/Web application server request.

Verifying that the HTTP server can find your NSAPI plugin

Before you try to build a real application server it is a good idea to make sure that the server extension is installed correctly. Otherwise you will not know whether your failure is due to an error in setting up your system or in the project.

1. Check that you have correctly configured your HTTP server to find the server extension.

: a. Verify this by running your HTML browser and pointing it to the URL that tells the HTTP server to use the Sapphire/Web server extension.
: b. The URL that you should open with your browser is:

http://<server>/default.sph


 Replace <server> with the name of the machine that is running the Netscape HTTP server. Your browser should display something like the following: 

No Path Info
Your client is not allowed to access the requested 
object.

If you see this then your Netscape HTTP server setup is complete. If you did not see this message in your browser then make sure that you edited the three Netscape Server configuration files correctly and then re-started the server.

2. Verify that you have placed default.sph in the correct place.

: a. Take the URL used above and append a "/test" to it.

http://<server>/default.sph/test


b.	 You may get a "File not found" error, indicating that the web server could not locate the default.sph file

c.	 Alternatively, you will get an error message from the Sapphire/Web server extension because you do not have an app. server called "test".

To Continue

Go now to the section on Setting Project Options

Server Setup for Generic Servers

The Sapphire Generic Web Server Extension (GWSE)

If your web server does not support NSAPI you can still use Sapphire Application Servers by using the generic web server extension delivered with Sapphire/Web.

There is a file named SaCGI.cgi in the bin directory of your Sapphire distribution. This is a CGI program that allows any web server talk to an Application Server. You must copy this file to a directory on your web server that can execute CGI programs. Once this file is copied to a CGI directory you must make sure that the project option Test.Generic Extension URL points to this value. A typical value for this option is

http://server/cgi-bin/SaCGI.cgi

You can verify that it works by using your HTML browser and pointing it to:

http://server/cgi-bin/SaCGI.cgi

You should see a message like the following in your browser:

No Path Info

If you do not see the above message make sure SaCGI.cgi has been copied to a directory that has execute access and you are typing in a valid URL in your browser.

The GWSE looks for the configuration file in one of two places. The first place it looks is $SAPPHIRE/config/apserver.txt. Since some HTTP servers do not pass all environment variables to CGI programs $SAPPHIRE may not be defined.

To get around this problem the GWSE will look in the working directory of the CGI for this file. Since the CGI specification does not state what the working directory is supposed to be for a CGI program, different HTTP server vendors set this directory differently. Some vendors use document root and other vendors use the directory in which the CGI is located.

GWSE will tell you what directory is the working directory when you successfully run it as a CGI and neither apserver.txt is in the working directory nor $SAPPHIRE/config/apserver.txt can be found.

[Top] [Prev] [Next] [Bottom] [Contents]

info@bluestone.com