Power broker...

by Steve Parker and Jim DeFabia (a/k/a Bartles and James)

Published 1998-12-01    Printer-friendly version

Web sites use software to accept and respond to HyperText Transfer Protocol (HTTP) requests. This software is called a "Web Server." Server software understands these HTTP requests and knows what to do with them and how to respond to them.

Clarion Internet Connect includes specialized Web server software, called the Application Broker, to provide these services for your Internet Connect (IC) applications. In addition to handling the HTTP delivery, the Broker also synchronizes the connection between the application running on the server and the end user (the client).

What the Broker Does

When the client (browser) sends a request to the broker to run an IC application, the web-enabled application actually executes on the server. It does not appear on the server's monitor (system administrators would really hate that), but each instance actually does run on the server (this is how your application maintains state information). The Application Broker creates a visual representation of that running program back to the requesting client in the form of an HTML page.

Think of the page in the user’s browers as a remote control, which communicates (through the Application Broker) with the application running on the server. When the user does something on the remote control page, the Application Broker receives the information from the browser and sends it to the running application. The running application receives and processes the events, and then it sends information back though the broker to the client.

The manner in which these browser events are handled is specified in your web-enabled application. You have three options, all at the control level: Process on Browser, Partial Page Refresh or Full Page Refresh. You can read the chapter on Web Application Design Considerations to learn more about these options. They can make a significant difference in the way your application behaves.

Back to Our Story

Two different versions of this server software are included in the Internet Developer’s Kit (IDK) to use when developing and testing IC applications. This software is limited to a single user, which is sufficient for testing or demonstrating IC applications. For full deployment of IC applications, multi-user versions are available as a separate product.

One of these is the stand-alone, or EXE, Broker. The other is the ISAPI, or DLL, version, which functions with any ISAPI-compliant Web server.

Like other decisions you make when developing software, your selection of a Broker involves compromises. Unlike other development decisions, your choice of Brokers is not irrevocable. If your needs change, you can redeploy your applications from one Broker to the other. You don't need to change or recompile your web-enabled applications.

While both Brokers perform the basic functions in a similar manner (i.e., they receive requests addressed to your Clarion applications and return the generated HTML to the user), there are significant differences between them. Understanding these differences can help you choose which one is best for your needs.

The EXE Broker

As its name implies, the EXE version of the Broker is a standalone executable program. This means that it must be executed (started). It does not require any additional Web server software. However, if you do use another Web Server, it will run alongside other server software (on an alternate port) without any interference between the two.

The EXE Broker is extremely easy to deploy. All you really need to do is install it and deploy your application(s).

Additionally, the EXE Broker has its own configuration utility. Using the built-in Setup, you can configure the maximum number of simultaneous connections (full Broker only), whether or not to create and maintain a log, and the remote administration password (this may be set and changed locally only).

Figure 1

But, there is a "downside" to this version of the Broker. That is, it must be started on the server. While you may obviously put CWBROKR1.EXE in the server's Startup group, it is still tied to a user. When running under NT or Win 95/98 with User Profiles, a user must log in before any application in the Startup group executes. The Application Broker cannot load automatically under that configuration and when the user logs off, the Broker also terminates. In the case of a system crash/reboot, the log-in must be completed before your web site will respond to requests.

Another important consideration is the fact that the executable Broker does not support Secure Socket Layers (SSL). If your application requires the security of SSL encryption, use the ISAPI version.

Installation

Regardless of the version you decide to install, you begin by selecting a "Root Directory." This is also referred to as the "Virtual Root."

These terms are Unix-isms. Translated, you simply select the subdirectory into which the Broker is to be installed. The setup program defaults to \CWICWEB

Figure 2

but you can install to any subdirectory you wish:

Figure 3

Then, select which Broker to install:

Figure 4

When you install the EXE Broker, another directory is automatically created below the directory containing the Broker. This is the /PUBLIC directory and the Internet Connect Java Support Libraries (JSL) are installed there. (If you anticipate that Windows 3.x, Mac or UNIX users will be accessing your site, you should unzip CLARION.ZIP. Advance information: the install for C5IC will install the unzipped .CLASS files.)

Your compiled applications go into the same directory as the Broker (or a directory below it). Your data files also go here (or anywhere you can make them accessible to the application using, for example, the Name() attribute). You must also copy any DLLs required by your applications here (C5RUNX, C5DOSX, C5ASCX and your file driver DLLs, at a minimum). Images and HTML files used by your applications go into the /PUBLIC directory (or directories below /PUBLIC).

That’s it.

TopSpeed supplies a page to test your installation (btest.htm). Run your browser and try to access this page:

http://localhost/btest.htm

If the Application Broker delivers the HTML page, you have set up the broker correctly.

Next, try your application using:

http://localhost/AppName.exe.0

and your program should run.

Fast, easy, and it works. Click on the icon in the system tray, select Setup and enter whatever configuration options you need (Figure 1). These settings take effect immediately; you do not need to close and restart the Application Broker. In addition, the next time the broker is launched, it remembers these settings.

Alternate Ports

Web Server software attaches (binds) to port 80. So, if your server already has web server software installed, it is probably running on that port. If you wish to use the EXE broker, you will have to bind it to a different port.

All ports above 2000 are available, as are many below 2000. You may use the Broker’s Setup routine (Figure 1) to bind to a port or, if you created a shortcut on your desktop, you may add the port assignment to the command line. Keep in mind that if you specify a port on the command line, you cannot change it using the broker's setup option.

F:\CWICWEB\CWBROKR1.EXE 2001

When using an alternate port, you start your applications with the port assignment:

http://localhost:2001/AppName.exe.0

Note that users accessing your site from behind firewalls may have difficulty with alternate port assignments. That is because firewall configurations often limit the ports allowed.

The ISAPI Broker

The DLL/ISAPI Broker requires ISAPI-compliant Web Server software. ISAPI compliant servers are available from Microsoft, O’Reilly’s and Apache, among others. This allows the ISAPI version of the Application Broker to be called, on demand, by the Web server, essentially extending the Web server’s capabilities.

The DLL Broker, therefore, is automatically available whenever the PC boots, even if a user has not yet logged in. Since the web server runs as an operating system service and, therefore, starts before the log-in request, the ISAPI DLL is also available. (This also means that there is never a reason to bind it to an alternate port.)

The DLL Broker does support SSL. Therefore, if you require secure HTML transmission, this version of the Broker is the one you must use.

There is a "downside" to this version also.

First and foremost, because the DLL Broker runs under another piece of software, you may be subject to bugs or peculiarities in the main server software.

Logging and number of users cannot be controlled through the DLL Broker. These features are controlled by the server software. This means that if you do desire a hit log, it will cover the entire machine, not just your IC applications.

Finally, the DLL Broker is more exacting in its installation requirements. It is easier to make a mistake installing it and, therefore, to encounter an "Application did not execute" error.

If you, as the system administrator/webmaster, need to terminate an application for maintenance purposes (such as uploading a new version or data files), you have the ability to suspend the application and prevent users from accessing it until you enable it. A major feature of the ISAPI broker in C5IC will be the ability to remotely terminate an application instance. That is, C5IC’s ISAPI broker will allow termination of a single instance at the press of a button.

Installation

Before installing the DLL Broker, you must install and configure an ISAPI compliant Web Server:

Figure 5

If you will be using SSL, your digital certificate must be installed (though you are not required to have a certificate to use the ISAPI broker).

Enter your domain name or IP address and administrator’s password:

Figure 6

The installation creates a series of subdirectories:

/root

/admin

/scripts

/sec_scr

/secure

/public

/exec

(The /ADMIN directory contains ICONFIG.EXE which you may use to modify your broker’s settings.)

It also produces a file in the virtual root directory, CWICSET.TXT, containing information you will need to enter into your Web server’s administrator:

Figure 7

You need to make a total of four entries into your server’s administrator (one for each of the directories below the root with the exception of the /EXEC directory). You will need to tell your Web server the real directory name, its alias (i.e., that it is a virtual directory) and the rights/permissions for each. All are documented in the manual.

PWS: If you are using Personal Web Server for local testing, making these entries can be a source of problems. If your local machine does not have a fixed IP address, it may also fail to correctly resolve the default loopback address, 127.0.0.1 (a/k/a "localhost") and you will not be able to enter PWS’ Administrator or run your applications. This is not a problem with IC but with your local machine's configuration. (O’Reilly’s Web Server, for example, asks for you IP address/Domain Name as part of its setup and will force that, if your PC doesn’t, through its "test" option.)

The easiest way to test this is immediately after completing the PWS installation and before installing the Application Broker. Right click the PWS icon in the System Tray and select Administer. If the next page loads completely:

Figure 8

your setup and installation are correct.

If there is any error on this page (usually, the images are missing), you will not be able to enter the Administrator and, therefore, cannot make the entries required by the Broker.

If you own Frontpage, starting it once (you do not have to actually do anything) will adjust your IP configuration. You may also find creating a file named HOSTS in your \Windows subdirectory may resolve this. The contents of HOSTS should be:

where "default" is your machine name. A last ditch resort is to hardcode an IP address (e.g., 10.1.1.1), subnet mask (e.g., 255.0.0.0) and a domain ("localhost").

With all this, you may still fail to access your applications. Web Servers need to know where the directories for a given Domain Name are. When you install PWS, it sets its root (see "Unix-ism," above) to \WEBSHARE\WWWROOT. You will see this in the PWS Administrator Directories list. Make another entry for your /PUBLIC directory and click Home Directory (no Alias); accept the warning message that appears and you’re off to the races.

NT/IIS: If you are on NT Server, running IIS, grant write and delete privileges to the Internet Guest Account in the User Manager. Then use Internet Service Manager to "Add a Web" (IIS4). This will resolve the IP address to the operating directories.

Your apps and their DLLs go into /EXEC or directories below it. Images and HTML go into /PUBLIC (or directories below it), just as with the EXE Broker. If you are using SSL, you must deploy image files and support DLL files (including the all the Java class files) to /SECURE also.

If you add a Digital Certificate later, use the Broker administrator to make sure that your secure HTML is setup correctly:

Figure 9

Which Broker is best for you?

If you require or will require SSL, you have little choice. Actually, you have none: you must use the ISAPI Broker.

If you want bulletproof (or as close to bulletproof as you can get) restarting of the Broker or if your web site requires specialized add-ons (CGI, Frontpage extensions and the like) the DLL version recommends itself.

If you do not require SSL or specialized add-ons, the EXE Broker is easier to install, maintain and deploy. In fact, if there is no motivating requirement to run the DLL Broker, the EXE Broker is a better choice simply for its ease of use.

If you are adding your IC apps to an existing, non-ISAPI server, you must use the EXE broker.

If you are already running a web site, you can place another machine on your network. Assign this second machine a static IP address and you can run your IC apps from your existing site without further modification. This allows use of the EXE Broker with an existing site but without using an alternate port. It is the only way to run IC apps on a site served by non-Intel computers or non-Microsoft operating systems.

The second machine scenario is also a way to use the DLL version with an existing non-ISAPI compliant server. That is, if your existing main server is running a non-ISAPI server and you want to use the ISAPI broker, install IIS or a similar server on a second machine. Assign it a static IP address, adjust your hyperlinks and router tables accordingly. You’re in business.

Summary

While heavy exposure to networking certainly helps in installing IC’s Broker, it isn’t really necessary. What is necessary is a thorough analysis of your current and projected needs (viz., secured transactions) and environment (existing webs).

And, if you installed the EXE Broker and your needs change? Just install the DLL Broker and copy your files to the appropriate directories.

Yes, "We thank you for your support."

Printer-friendly version

Copyright © 1999-2008 by CoveComm Inc. All Rights Reserved. Reproduction in any form without the express written consent of CoveComm Inc., except as described in the subscription agreement, is prohibited.

Clarion Magazine ISSN 1718-9942