FoxWeb, a Simplified Visual FoxPro Internet Automation Server

FoxWeb is a simplified ISAPI Automation server sample designed to quickly get a Web site up and running. FoxWeb provides a new version of Foxisapi.dll (also provided with the Visual FoxPro FoxIs server sample). Foxisapi.dll now can manage multiple instances of Visual FoxPro Automation servers, and provides additional debugging methods for Visual FoxPro applications designed for the Internet.

The FoxWeb Automation Server

The FoxWeb sample uses a simple Visual FoxPro server class intended to demonstrate the basic usage of a server run under FoxISAPI. All the code is stored in a file called Foxweb.prg. This file contains a class called Server, which is marked as OLEPUBLIC so that it gets registered as an Automation server COM component when it is built. This class is instantiated by FoxISAPI and contains a number of methods that can be invoked (such as the Hello and Delay methods) as shown below. These methods illustrate the structures required by FoxISAPI in order to function properly.

The FoxWeb Sample Files

The files for the new Visual FoxPro FoxWeb Automation server sample are located in the Visual FoxPro \Samples\Servers\Foxisapi\FoxWeb directory.

Setting up the FoxWeb Automation server

The following sections describe how to use Visual FoxPro to quickly get a Web site up and running with FoxWeb.

Registering the Visual FoxPro FoxWeb Automation server

The Visual FoxPro Automation servers that return HTML must be registered. Registration is done automatically if your .exe or .dll was built with the Visual FoxPro Project Manager or with the BUILD EXE, BUILD DLL, or BUILD MTDLL commands. For example, if you open the Foxweb project provided with the FoxWeb sample in the Project manager, you can choose Build to create an Automation server as an in-process .dll or an out-of-process .exe file. Note that the registration occurs only on the machine on which the file was built.

A Visual FoxPro Automation server built as an out-of-process .exe can also be registered by specifying the Automation server name and including the /RegServer switch. For example, the following command registers the Visual FoxPro FoxWeb Automation server:

Foxweb.exe /RegServer

A Visual FoxPro Automation server built as an in-process .dll can also be registered with Regsvr32.exe. For example, the following command registers the Visual FoxPro Foxweb Automation server:

Regsvr32 Foxweb.dll

**Note   **If your Visual FoxPro ISAPI Automation server uses additional files such as .gif or .jpg files, be sure to place these files in directories that your Internet Information Server or Personal Web Server can access.

Using your Web Browser to access a Visual FoxPro ISAPI Automation Server

A Visual FoxPro ISAPI Automation server is accessed from your Web browser by providing the URL (Universal Resource Locator) of the Automation server. The Web browser makes an HTTP request that is passed to your Internet Information Server or Personal Web Server. The Automation server passes the request to Foxisapi.dll, which, in turn, passes the request to your Automation server.

For example, the URL below accesses the ISAPI Automation server named Foxweb.Server:

HTTP://MyServer/Scripts/Foxisapi.dll/Foxweb.server.Delay?30

The following table describes each of the elements of the URL example above.

Passing Parameters to Methods

The following code is from the Delay method in Foxweb.prg, and demonstrates the structure for methods executed on the Visual FoxPro ISAPI Automation servers.

PROCEDURE Delay
   LPARAMETERS cParm1, cIniFile, nPersistInstance

** Your code here ** RETURN AnHTMLString ENDPROC

• cParm1
  A character string passed to the method. In the Delay method, this parameter specifies the number of seconds that execution is delayed.
• cIniFile
  The name of the .ini file (passed to the method by Foxisapi.dll) created each time a Visual FoxPro ISAPI Automation server is accessed. Each .ini file is created in the Scripts folder and has a unique name that begins with "Fox." You can use the GetPrivateProfileString function in Foxweb.prg, for example, to read information from the .ini file and return custom HTML based on a user's configuration.
• nPersistInstance
  Specifies if the instance of the Visual FoxPro ISAPI Automation server persists after it is finished executing your method. nPersistInstance is passed by reference to the method by Foxisapi.dll. If nPersistInstance is set to 0 in your web application, the instance of the Automation server remains alive after execution is finished. If nPersistInstance is a value other than 0, the instance of the Automation server is released. For optimal performance, nPersistInstance should be set to 0, otherwise the Automation server must be launched again the next time it is called.

Using Foxisapi.dll to Pool Automation Servers

Because Foxisapi.dll is free-threaded, it can now pool multiple Visual FoxPro ISAPI Automation servers to provide better scalability for your web applications. Pooled ISAPI Automation servers allow a free ISAPI Automation server to service a request when other ISAPI Automation servers are busy. To take advantage of ISAPI Automation server pooling, the instances of the ISAPI Automation servers should be made persistent by setting nPersistInstance to 0 in your web application.

The number of ISAPI Automation servers available to service requests is determined by settings in your Foxisapi.ini initialization file. To create a pool of multiple ISAPI Automation servers, include an entry in square brackets with the name of the ISAPI Automation server for which a pool is created. This entry is followed with a list of ISAPI Automation servers that comprise the pool, with a numeric value that specifies the maximum number of instances of each ISAPI Automation server that can be created.

For example, placing the following lines in Foxisap.ini creates a pool of seven ISAPI Automation servers for service requests to Foxweb.myserver. Foxisapi.dll creates up to four instances of the Foxweb.server ISAPI Automation server and up to three instances of the Foxweb2.server ISAPI Automation server to service requests.

[FOXWEB.MYSERVER]
FOXWEB.SERVER=4
FOXWEB2.SERVER=3

The following URL executes the Delay method on either an instance of the Foxweb.server or the Foxweb2.server ISAPI Automation servers:

HTTP://MyServer/Scripts/Foxisapi.dll/Foxweb.Myserver.Delay?30

Foxisapi.ini can specify that the ISAPI Automation servers are instantiated up front before a service request is received. To do so, add a comma followed by an asterisk (*) after the number of instances, as shown in the following example.

[FOXWEB.MYSERVER]
FOXWEB.SERVER=4,*
FOXWEB2.SERVER=3,*

Using the Pool Manager across Multiple Machines

Foxisapi.dll provides the ability to manage Visual FoxPro ISAPI Automation servers on multiple machines. You can use Remote Automation or DCOM (Distributed Component Object Model) to access the ISAPI Automation servers. Note that for optimal performance and scalability the instances of the ISAPI Automation servers should be made persistent by setting nPersistInstance to 0 in your web application.

The following example describes a scenario where two Visual FoxPro ISAPI Automation servers, Foxweb and Foxweb2, are placed on two machines.

Machine_A is your local machine running Windows 98, DCOM, and Personal Web Server. Machine_B is your remote machine, accessible over your network, running Windows NT 4.0 or later and DCOM.

1. Machine_A is your Visual FoxPro development machine on which you've installed the Visual FoxPro FoxISAPI Automation server samples. On this machine, open the Foxweb project in the Visual FoxPro Project manager, and choose Build to create an ISAPI Automation server as an out-of-process .exe file. Building the .exe automatically registers the ISAPI Automation server on the machine as Foxweb.exe. Now open the Foxweb2 project in the Visual FoxPro Project manager, and choose Build to create and register another ISAPI Automation server as a .exe.

2. To verify that the ISAPI Automation servers Foxweb and Foxweb2 are properly registered, you can use RegEdit and search for Foxweb and Foxweb2. Note that the ProgIDs for the servers are Foxweb.Server and Foxweb2.Server, respectively. Server is the class name specified in the OLEPUBLIC clause of the DEFINE CLASS command that creates the ISAPI Automation server. Foxweb.prg is the Visual FoxPro Internet application included in both the Foxweb and Foxweb2 projects.

3. The ProgIDs for the ISAPI Automation servers both point to Machine_A, the local machine. The Registry settings for the Foxweb2 ISAPI Automation server need to be changed to point to Machine_B, the remote machine. Use Clireg32.exe (for more information, see Clireg32.exe Remote Automation Utility) to change the pointer in the Registry. Clireg32.exe is used to redirect calls to Foxweb2 to Machine_B. The following command, executed in the Windows Run dialog box, runs Clireg32.exe:

   CLIREG32 FOXWEB2.VBR
   

   A dialog box is displayed, making it possible for you to specify Machine_B as the remote server to which calls to Foxweb2 are directed. The Remote Transport option in this dialog box makes it possible for you to choose DCOM or Remote Automation as the transport method; choose DCOM.

4. Now copy the Foxweb2.exe, Foxweb2.vbr, and Foxweb2.tlb files from Machine_A, the local machine, to Machine_B, the remote machine.

5. Use the /RegServer option to register Foxweb2.exe on Machine_B at the MS-DOS prompt:

   C:\VFP\FOXWEB2.EXE /RegServer
   

6. Finally, stop and restart the Personal Web Server on Machine_A to ensure that it is aware of the changes to the Registry.

You can execute the Status command on Foxisapi.dll to check the status of all the ISAPI Automation servers registered in Foxisapi.ini. The following URL executes the Status command:

HTTP://Machine_A/Scripts/FoxISAPI.dll/Status

You can execute the Reset command on Foxisapi.dll to reset all the ISAPI Automation servers registered in Foxisapi.ini. The Reset command releases all ISAPI Automation server instances. The following URL executes the Reset command:

HTTP://Machine_A/Scripts/FoxISAPI.dll/Reset

To test the installation, you can open up as many instances of your Web browser as there are ISAPI Automation servers in the pool. The Web browsers can be on multiple machines connected to your network. You can then call the Delay method in the URL from each Web browser so that Foxisapi.dll routes service requests to the other free ISAPI Automation servers. After the Delay method is executed from each Web browser, you can use the Status method to check to see if all ISAPI Automation servers in the pool received service requests.

Using FoxISAPI with DLL Servers

If you use FoxISAPI with multithreaded in-process servers in the previous version of Visual FoxPro, you will need to disable pool manager support in FoxISAPI. You can do this by using the PoolMode setting in the Foxisapi.ini file. The PoolMode setting is global to all servers, so we recommend that you do not let a single Foxisapi.dll service both EXE and DLL servers. Instead, you should copy and rename the Foxisapi.dll and Foxisapi.ini files so that you have one set for EXE servers and one for DLL servers.

For an example of using pool manager, see the Pool Manager: An Automation server Sample.

Debugging your ISAPI automation Servers

Foxisapi.dll also makes it possible for you to debug your ISAPI Automation servers on your local machine. Set the number of instances of the ISAPI Automation server you wish to debug to 0 as shown in the following example Foxisapi.ini file:

[FOXWEB.MYSERVER]
FOXWEB.SERVER=0

The Odebug.prg program file must be present in your Visual FoxPro root folder and the ISAPI Automation server source files must be present. Be sure that the ISAPI Automation server you wish to debug is configured as a persistent ISAPI Automation server, and debugging information is turned on in the project containing the ISAPI Automation server source files.

When the ISAPI Automation server is instantiated, Foxisapi.dll starts Visual FoxPro for debugging, making it possible for you to set breakpoints, trace through code, and so on.

Foxisapi.dll Commands

Foxisapi.dll has commands you can call to determine the status of your ISAPI Automation servers and to reset the servers. The following table lists the Foxisapi.dll commands with a description of each.

Each of the Foxisapi.dll commands is called by a URL that is specified in Foxisapi.ini. The following is the contents of the sample Foxisapi.ini file with the default URLs:

[FOXISAPI]
StatusURL = Status
ResetURL = Reset
SingleModeURL = SingleMode
MultiModeURL = MultiMode

The following URL executes the Status command:

HTTP://MyServer/Scripts/Foxisapi.dll/Status

In the following sample Foxisapi.ini file, the URL for the Status command is changed from Status to MyStatus:

[FOXISAPI]
StatusURL = MyStatus
ResetURL = Reset
SingleModeURL = MSingleMode
MultiModeURL = MultiMode

After this change to Foxisapi.ini, the following URL executes the Status command:

HTTP://MyServer/Scripts/FoxISAPI.dll/MyStatus

**Note   **You must reset Foxisapi.dll with the Reset command after you make changes to Foxisapi.ini file in order for the changes to take effect.

Additional FoxISAPI.ini Settings

Foxisapi.dll reads Foxisapi.ini and configures its settings according to the items contained in Foxisapi.ini. The following table describes each of the additional items you can place in your Foxisapi.ini file.

The following is taken from the sample Foxisapi.ini file, and demonstrates the formats of the additional items you can place in the file:

[FOXISAPI]
BusyTimeout = 5
ReleaseTimeout = 15

**Note   **You must reset Foxisapi.dll with the Reset command after you make changes to Foxisapi.ini file in order for the changes to take effect.

Microsoft Internet Information Server Configuration Tips

Two Microsoft Internet Information Server registry entries, PoolThreadLimit and ThreadTimeout, can be added to your registry to improve performance with the Visual FoxPro FoxISAPI Automation servers. These registry entries determine the total number of threads that Internet Information Server can create, and the length of time the threads exist. For more information about these registry entries, see your Internet Information Server documentation.

A Microsoft Knowledge Base article titled "How to Launch Automation servers from ISAPI Extensions" (number Q156223) is available on www.microsoft.com. This article provides information about the access security permissions required to launch Automation servers such as the Visual FoxPro ISAPI Automation Servers.

See Also

Solutions Samples | FoxISAPI Automation Server Samples | FoxIs, a Visual FoxPro Internet Server