Building FoxISAPI Applications

Building applications with FoxISAPI

By Rick Strahl, West Wind Technologies
http://www.west-wind.com/

Session notes from the Visual FoxPro DevCon '98 in Orlando
Sample Files, Doc and Slides

Overview

See how to build Web Server applications with Internet Information Server and FoxISAPI to take full advantage of Visual FoxPro's speed and power. Discussion starts with the basic mechanics of ISAPI and the FoxPro interface and examples on how to service basic requests and common operations performed in requests. We'll also cover how to debug FoxISAPI requests, deal with scalability issues and integration of FoxISAPI with other Web and COM technologies. You'll also see examples on how to extend FoxISAPI with custom classes that provide unique functionality not available with other tools.

This session will cover the following areas:

Basic operation of FoxISAPI
How to create a Hello World application
Accessing database tables from your requests
Handling form and server variable access
HTML generation
Introduction to a simple FoxISAPI framework and some examples
Extending FoxISAPI with a FoxPro scripting engine
Running VFP forms as DHTML sample
Taking advantage of a FoxISAPI backend from a VFP client application

What is FoxISAPI?

One of the tools available to build Web application with Visual FoxPro is FoxISAPI. FoxISAPI ships in the box with Visual FoxPro and is provided as a 'server' example that demonstrates how to use Visual FoxPro as a Web backend.

Server Side Web Tool
FoxISAPI runs on the backend as an IIS ISAPI application which means it runs only on the server, not on the clients. As such clients do not need Visual FoxPro to run your application over the Web. Also, the application is maintained in one place (on the server) so updates are immediately available to the entire client base.

High performance direct interface to Visual FoxPro Code
In terms of performance for Visual FoxPro backends FoxISAPI is a very efficient. It connects to the Web server via COM calls that access your Visual FoxPro server directly and uses the resulting data to create output. Since a single COM call is used per request and the result is directly embedded into the page it's very efficient. In addition, FoxISAPI's built in pool manager is manages simultaneous instances of requests more efficient than other solutions such as Active Server Pages.

Uses Internet Server API (ISAPI)
Another reason for FoxISAPI's performance is that FoxISAPI is implemented as an Internet Server API (ISAPI) extension which is a very efficient, multi-threaded, operating system level interface that is written in C++. This allows for maximum performance and flexibility in the actual connector application that communicates between IIS and your FoxPro application.

Uses COM for Messaging
ISAPI provides the low level interface to the Web server and it uses the Common Object Model (COM) to talk to your Visual FoxPro application. Your application is built as a COM object that acts as a server to FoxISAPI which becomes the client.

Creates HTML output from your Visual FoxPro Code
Once your server receives a request it's responsible for retrieving input from the server in the form of several parameters and then has to generate HTTP compliant output, which in most cases ends up being HTML.

How it works

FoxISAPI consists of two basic components which are required to make it tick: The FoxISAPI.dll and your implementation code created as a Visual FoxPro COM object:

When the browser makes a request on the Web server it asks to load FoxISAPI.dll via a URL link very much like this:

http://someserver.com/scripts/foxisapi.dll/YourServer.YourClass.YourMethod

This causes the Web server to load FoxISAPI into its memory space. Since Foxisapi.dll is a Win32 DLL it loads once and then stays loaded in the calling process of the Web server for the duration of operation. The DLL is also multi-threaded which means it can take multiple simultaneous requests from the multi-threaded Web server – if 10 people request the same URL that takes 10 seconds to process you can have 10 threads asking to access your COM object. Unfortunately, Visual FoxPro is single threaded and cannot walk and chew gum at the same time, so in its default implementation foxisapi.dll will have to queue these incoming requests. However, FoxISAPI includes a pool manager which we'll look at later on to manage multiple simultaneous instances of the COM objects to make it possible to run requests concurrently.

Once loaded the Foxisapi.dll now goes ahead and tries to create an instance of the COM object specified on the URL – Yourserver.YourClass - by issuing the equivalent of:

o=CREATEOBJECT("YourServer.YourClass")
o.YourMethod("FormVar1=Test+Value","c:\http\foxisapi\XXX.ini",0)

For this to work the OLE server must exist and be registered in the Windows Registry in order for FoxISAPI to be able to create the object from the Class ID passed on the URL command line. If you look back on the URL you'll see that all three pieces of the server - the server, class and method - are described with the YourServer.YourClass.YourMethod text in the above link following the DLL name with a slash (this is known as the Physical path) in order to allow the two above commands to be described as a single string.

At this point FoxISAPI.DLL has created an instance of your COM server and has called your method in this server. FoxISAPI is smart enough to load an instance of this server and then keep the reference to this server loaded. This means that the first hit on the server will be slow as the entire VFP runtime loads into memory, but any subsequent hits are very fast as they access a server that is already loaded in memory.

Build your application code with Visual FoxPro

What happens next? Essentially you now have received a blank check from the Web server to go wild and run Visual FoxPro through its magic paces. You can now run any queries, inserts, access remote data, call classes and business objects if you choose - all of Visual FoxPro is available to you.

Well, not all of it actually. You can' run any interactive code that requires user intervention. You can't run a form or even pop up a dialog box to have a user start entering data. By the time the request reaches your FoxPro code you're essentially looking at building a one-way transaction based request handler. The Web server is waiting for a single response from your code in the form of a complete HTML document. There's no interactivity happening at this point. All of your user interface needs to be generated as HTML that is sent back as the character return value from your COM server method.

Any attempt to call an interactive form or dialog will cause the server to hang. It's very important to understand this! Any prompt in your code whether voluntary (forms, MessageBox etc) or involuntary (a File Open dialog, a program error) will cause your server to hang and no longer be available to serve requests!

Once your code is complete it needs to return a string back to the FoxISAPI.DLL as the return value. This string must contain HTTP compliant output. In most cases this output will be an HTML document, but a number of other responses such as a redirect, request for authentication, or an error result can also be

Building the COM Server

Let's take a look what a FoxISAPI compliant COM server looks like in terms of FoxPro code. You might be surprised that a 'Hello World' application with FoxISAPI takes less than 10 lines of code! Here's what the most basic FoxISAPI compatible COM server that you can build looks like:

*** System Defines
#DEFINE CR CHR(13)+CHR(10)

DEFINE CLASS TFoxISAPI AS Custom OLEPUBLIC

FUNCTION Helloworld
LPARAMETER lcFormVars, lcIniFile, lnReleaseFlag
LOCAL lcOutput

*** HTTP header - REQUIRED on each request!

lcOutput="HTTP/1.0 200 OK"+CR+;
         "Content-type: text/html"+CR+CR

lcOutput=lcOutput+;
   "<HTML><BODY>"+CR+;
   "<H1>Hello World from Visual FoxPro</H1><HR>"+CR+;
   "This page was generated by Visual FoxPro...<HR>"+CR+;
   "</HTML></BODY>"

RETURN lcOutput


ENDDEFINE

If you take this code above, stick it into a PRG file, add it to a project and compile it as an EXE or DLL based COM server you will be able to call the server from your Web browser simply by typing:

/localhost/scripts/foxisapi.dll/TFoxServer.TFoxIsapi.HelloWorld

into the browser's location window. Who said Web development has to be difficult?

The above code is pretty simple and doesn't do anything fancy, but it demonstrate most of the key pieces that each method that is called from a Web link must support. First off the class created must be created as OLEPUBLIC in order to be accessible as an COM object once compiled. Note that you can use a single server that contains multiple publicly accessible classes. We'll talk more about that in a minute but first let's see how to configure your server properly for operation.

Server Configuration

Once you've build your Automation server the next step is to properly configure it to run on the Web server. You should make a point of always including a very basic request in your server, so that you can easily test operation of it through the Web page without fear of potentially causing an error. More on error handling later, but the best thing to do is to include a very simple method which simply takes three parameters and returns a string:

Procedure ServerTest

LPARAMETER lcFormVars, lcIniFile, lnRelease

RETURN "<HTML>FoxISAPI Test Request</HTML>"

You'll see in a moment why this is useful. The first step is to test your server inside of Visual FoxPro as a native class:

o=CREATE("TfirstServer")

? o.ServerTest()

You can also do this with other simple requests. If you need some form variables to to work with you can simulate URL encoding manually. For example:

o=CREATE("TfirstServer")

? o.ServerTest("Name=Rick+Strahl&Company=West+Wind+Technologies")

and so on. It'll get tedious quickly with more than a few parameters, but it's a good idea to test forms inside of VFP first before building them into COM objects which can't be interactively debugged as they are EXE files.

Build the Server as an OutOfProcess EXE server

Next, build your server into an OutofProcess EXE COM object. For example:

BUILD EXE FirstServer FROM FirstServer RECOMPILE

or you can use the project manager. Make sure that the class you're going to call from the Web page has the OLEPUBLIC flag set (if you're building a visual class or the OLEPUBLIC keyword if you're doing it in code).

Then check for operation of your server as you did with the native class, but use the COM ProgId for the server's creation:

o=CREATE("FirstServer.TfirstServer")

? o.ServerTest()

You should see the result from that method just as you did before. Notice that this is a COM object that you can now see in Task Manager, showing as FirstServer.EXE.

Copy FoxISAPI.dll into a Web script directory

In order to call Foxisapi.dll from a Web page it needs to be accessible to the Web server in a directory that has Execute rights set. You can use the Web server's default script directory or create a new virtual directory (as I do usually) and set execute rights on it:

You'll also want to copy FOXISAPI.INI into this directory. It contains various configuration information about how FoxISAPI runs.

In order for foxisapi.dll to create the INI files in this directory you should also give CHANGE rights to the IUSR_ account using the NT Explorer:

Run DCOMCNFG to configure your server

And now for the fun part – NOT! In order to properly run your COM object inside of IIS, you need to configure it for the proper Impersonation of an NT User account. Without this Impersonation your server will run under the IIS default user account called IUSR_MachineName where machine name will be your machine's actual name. Mine is IUSR_RAS_NOTE as you can see in the Security dialog above.

Problem is that this account has next to no rights on your machine, meaning you most likely will not be able to access your data files, ODBC connections, INI files or most anything else that's not directly in a Web root.

To get around this problem a process called Impersonation can be used on EXE based COM objects using a utility called DCOMCNFG. There are two settings you should make – global settings and settings for your individual server.

Global default settings allow you to configure all servers for default launch and access rights. These rights determine whether a given NT account will have the rights to launch and access your server. I'm not sure why you'd want to separate these options – launching and not accessing would be kind of silly – but you have to set both launch and access rights:

Set up the IUSR_ account in this fashion for both the Default Access and Default Launch Permissions. You can also configure this option directly on your specific server, but I prefer to do it here, so I don't have to worry about it for each server I build.

The next step is to configure the individual server. Click on the Applications tab, then find the name of your server (VFP Default) or the descriptive name you gave the server in the project manager. Note that you are looking for the 'Class' name, rather than the EXE (Server) name. Also note that if you have multiple classes in the same server only one of the entries will show – usually the first one in the project manager.

For the individual server you'll want to configure the Impersonation:

By setting the Impersonation level to the 'Interactive User' you are telling COM to use whoever is logged on currently or the SYSTEM account if noone's logged on to be the controlling account for your COM object. So if you're logged on as an Administrator that's the account the server will use.

Note:

Be careful with SYSTEM account logons. The SYSTEM account rights may or may not allow access to your data and application directories – make sure you check permissions on these directories explicitly if you plan on running your FoxISAPI application prior to logon.

Updated in VFP 6.0:

Visual FoxPro 6.0 no longer blows away the DCOMCNFG registry settings as VFP 5.0 did everytime you rebuilt your project. Unless you rename your servers or you explicitly tell them to Generate new ClassIds when building, the settings you make in DCOMCNFG on a particular server remain intact after each rebuild.

COM Server Instancing

In the previous section I discussed server configuration based on building EXE components, rather than InProcess servers. That's because of the way FoxISAPI is designed – it works best with Out of Process components as these can be efficiently pooled using FoxISAPI's internal pool manager.

InProcess COM Objects

Very fast call interface
Affects only the DLL operation, not your VFP server, but on short request the lack of overhead can be noticable.

Crash it – Crash the Web server
If you crash your COM DLL there's a good chance you'll take the Web Server or the IIS4 Application down with it. At the very least a stuck session will hang your application.

Can't be unloaded completely
Once a COM DLL has been loaded into IIS it cannot be unloaded. For development this is a problem since you're likely to update your servers frequently while debugging. Even live sites suffer, since there's no chance to do online updates.

Security Issues – no configuration available
DLL COM objects run in the calling process and they inherit that process' security attributes. Under IIS that means usually your server gets called using the IUSR_machinename account, which has very limited rights. For example, by default it won't have access to your data directory to read or write data from there! In order to work around this you have to give the IUSR_ account additional permissions which may be risky in terms of system security as this account is used by all Web users accessing your machine. Be careful with this and review the options carefully!!! BTW, this applies to ASP COM objects as well!

VFP 6 does allow for multiple COM DLL instances
VFP5 was unable to process more than 1 request to a COM DLL in the same process. VFP 6.0 fixes this with the new threading model that allows for multiple apartment threads to enter multiple VFP runtimes simultaneously. In order to run multiple instances you still have to use the FoxISAPI pool manager.

Out of Process COM Objects

Slower Call Interface
The call interface for Out Of Process components always requires cross process marshalling which is slower than InProcess calls or even InProcess marshalling. However, keep in mind that FoxISAPI makes a single method call per request so although marshalling can be up to 100 times slower for OutOfProcess Components we're still talking less than a millisecond of overhead here. IOW, don't base your decision on Call Interface speed.

Crashes don't affect Web server
OutOfProcess components run in their own process and thus are not as vulnerable to the host environment. Hence stables tend to be more stable running OutOfProcess. When they do crash it doesn't affect the client much, other than the client request on the server failing. The client may be able to detect the error and unload or kill the original server and reload it.

Servers can be unloaded easily
Servers are easily unloaded with FoxISAPI's Reset option.

Allows multiple simultaneous servers
FoxISAPI includes a pool manager which can effectively manage several instances of OutOfProcess components.

Support for DCOM remotable objects
In order to call components hosted on another machine via DCOM the server must be built as an EXE.

In my own work, I rarely use InProc servers with FoxISAPI, because frankly it's a hassle and I've found it to be rather unstable. At the writing of these notes VFP 6.0 is still in beta and some of the InProc features of VFP 6.0 like concurrent method calls are not working resulting in blocking for multiple servers making scalability iffy. This will be fixed by the time VFP 6 ships, but it points to the complexity of this issue, which is bypassed with the FoxISAPI pool manager and EXE servers entirely. Out Of Process servers have been working great since VFP 5.0 and the overhead in calling the EXE is so minimal that in most situations there's no reason to take a chance on DLL servers.

Building FoxISAPI Requests

Ok, now you have a good idea on how to create and call a basic FoxISAPI server. Now lets take it step by step and create a few requests. I'll show you how to use a framework that will simplify you're life dealing with the repetitive code that's used on almost every request, so we can start focusing on running the business logic we're trying to show on the Web.

When FoxISAPI calls your COM server it passes along 3 parameters to each request method that is called. While you might not need to do anything with these parameters, your method must support these three parameters or else an COM Server error will be raised when the method is called.

lcFormVar
The first parameter contains any form variables retrieved from an HTML form via an HTTP GET or POST or any 'parameters' passed on the Query String or any form variables retrieved from an HTML form via an HTTP GET or POST.

The format of the parameter string contains a key/value pair for each of the form variables or 'parameters' passed. The keys in the above example are UID and Name the values are 1111 and Rick Strahl. These key value pairs are what is known as URL encoded, which means they follow a specific protocol of encoding to allow passing special characters on the URL or via form variables. It works something like this:

Key value pairs are separated by &.

Spaces are converted to +.
All 'extended' characters are converted to Hex escape codes. The escape code uses a percent sign plus a hex number to store the ASCII code of the characters. For example a carriage return (ASC(13)) is encoded as %0D.

The FoxISAPI framework provided with these notes takes care of properly decoding form variables and the querystring for you.

lcIniFile
This parameter contains the path to an INI file that contains all the server, browser and system variables. This INI file is created by FoxISAPI.dll before control passes to your OLE server and is deleted after you method call returns. You can retrieve these with calls to the GetProfileString API call (or use the wwFoxISAPI::ServerVariables(cVarname,cSection) from the listings below). You can see what's available by looking at the following sample

[FOXISAPI]
Request Method=GET
Query String=UserId=11111&UserName=Rick+Strahl
Logical Path=/wwDevcon.TFoxIsapi.TestMethod
Physical Path=c:\westwind\wwDevcon.TFoxIsapi.TestMethod
FoxISAPI Version=FoxISAPI v1.1
Request Protocol=HTTP/1.0
Referer=/cgi-win/foxisapi.dll
Server Software=Microsoft-IIS/2.0
Server Name=rasnote
Server Port=80
Remote Host=111.111.111.113
Remote Address=111.111.111.113
[ALL_HTTP]
HTTP_ACCEPT=image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*
HTTP_ACCEPT_LANGUAGE=en
HTTP_CONNECTION=Keep-Alive
HTTP_HOST=rasnote
HTTP_REFERER=http://rasnote/devcon/
HTTP_UA_PIXELS=800x600
HTTP_UA_COLOR=color8
HTTP_UA_OS=Windows NT
HTTP_UA_CPU=x86
HTTP_USER_AGENT=Mozilla/2.0 (compatible; MSIE 3.01; Windows NT)
HTTP_COOKIE=WWLASTVISIT=10/20/96; DENALISESSIONID=PUWFKVSKIVSVQCVG
[Accept]
image/gif=Yes
image/x-xbitmap=Yes
image/jpeg=Yes
image/pjpeg=Yes
*/*=Yes
[SYSTEM]
GMT Offset=-28800

Typically you'll use only a few of the keys from the INI file. The Query String is frequently read to figure out what 'parameters' where passed to a form. The User Agent can help you to determine whether the user's setup allows you to show browser specific features. The Referer tells where the user was coming from - HTTP_REFERER contains the link the user clicked on to arrive at the current location. HTTP Cookies can be retrieved using a Browser stored ID that you can use to track a user over several requests through a site.

lnReleaseFlag
This parameter concerns itself with the persistence of the OLE server. By default FoxISAPI contains logic to create OLE server instances and keep those instances loaded in memory. By keeping instances loaded successive accesses to the same server are quite fast as the server is already loaded in memory. In essence each OLE server called maintains only one persistent instance in memory at any time. It's a good idea to keep the reference by leaving lnReleaseFlag at its default value of 0 to keep a connection in order to minimize load time of the server. The parameter is passed in by reference so changing it in your code will effectively pass back the result to the FoxISAPI connector. The possible values for lnReleaseFlag are:
0 - Keep Server Reference
1 - Release Server Reference (default)

Once your code gets control you can use VFP as you see fit to run queries or run any other kind of transaction or logic operation using FoxPro code. The end result of each exit point of your method must be an HTTP compliant string.

In most cases the output will be an HTML document, but you have to be sure to add an HTTP header to the top of it. Typical HTML output should look like this:

HTTP/1.0 200 OK
Content-type: text/html

<HTML>
<H1>Hello World</H2>
</HTML>

The HTTP header and Content-type are important since not all browsers will support headerless results. Leaving of the header can result in a 'Invalid Response' error on the browser. Note each line of the header must be separated by a CHR(13)+CHR(10) and the final header line must be followed by a blank line containing only the CHR(13)+CHR(10).

While you will almost always return an HTML document it's possible to generate standard HTTP header responses as well. For example, if you wanted to cause Authentication to occur you might return:

HTTP/1.0 401 Not Authorized
WWW-Authenticate: basic realm=west-wind.com

<HTML>
Get out and stay out!!!
</HTML>

An authentication box that was initiated from a Web request forces authentication against the NT user/security manager if Basic Authentication is enabled in the Web server.

This would cause an authentication box to be thrown up by the browser unless the user accessing the link was previously authenticated. If the user was not authenticated the password box pops up. If the user types in an invalid password an error message is returned, otherwise the same link is re-executed and the now validated user can get passed the password check. You can then check the password entered as passed back in a the Authenticated Username CGI variable to determine whether to allow the user in (actually NT will first authenticate the user and fail if the user is not valid as per the User Manager).

Here's what this looks like in code (using some of the methods described in the next section):

lcUserName=THIS.ServerVariables("Authenticated Username")

IF EMPTY(lcUserName)   
    *** Send Password Dialog
    lcOutput=;
      "HTTP/1.0 401 Not Authorized"+CR+;
      "WWW-Authenticate: basic realm=west-wind.com"+CR+CR+;
      "<HTML>"+CR+;
      "Get out and stay out!!! "+CR+;
      "</HTML>"+CR

    RETURN lcOutput
ENDIF

*** Go on processing - user has been authenticated
...
RETURN lcOutput

We'll discuss more examples of wwFoxISAPI class implementation later on, but now lets deal with the remainder of installation of your servers.

Another Simple Example

Here's another simple example that retrieves some data from a table and returns the output as a string:

FUNCTION FirstQuery
LPARAMETER lcFormVars, lcIniFile, lnReleaseFlag

lcIniFile=IIF(type("lcIniFile")="C",lcIniFile,"")

*** Don't release the server
lnReleaseFlag=0

lcOutput="HTTP/1.0 200 OK"+CR+;
         "Content-type: text/html"+CR+CR

SELECT  Company, Careof, Address, custno, phone ;
   FROM (".\data\TT_CUST") ;
   ORDER BY COMPANY ;
   INTO Cursor TQuery


lcOutput = lcOutput + ;
  [<HTML><BODY BGCOLOR="#FFFFFF">] + ;
  [<H1>Customer Lookup</H1><HR>] + ;
  [Matching found: ]+STR(_Tally)+[<p>]

lcOutput = lcOutput + ;
   [<TABLE BGCOLOR=#EEEEEE CELLPADDING=4 BORDER=1 WIDTH=100%>]+CR+;
   [<TR BGCOLOR=#FFFFCC><TH>Name</TH><TH>Company</TH><TH>Address</TH></TR>]+CR

SCAN
   *** Build the table row - note the second column is hotlinked by CustId for display
   lcOutput = lcOutput + [<TR><TD>]+;
          TRIM(IIF(EMPTY(TQuery.Careof),"<BR>",Tquery.CareOf))+[</TD><TD>]+;
          TRIM(IIF(EMPTY(Tquery.Company),"<BR>",TQuery.Company))+[</a></TD><TD>]+;
          TRIM(IIF(EMPTY(Tquery.Phone),"<BR>",STRTRAN(TQuery.Phone,CHR(13),"<BR>")))+[</TD></TR>]+CR
ENDSCAN          

lcOutput = lcOutput  + [</TABLE><HR>] + ;
                       [</BODY></HTML>]

USE IN Tquery
USE IN TT_Cust

RETURN lcOutput

which generates an HTML table like this:

Now the problem with the above request is that it doesn't interact with the Web page at all. We're simply running a query, but we're not parameterizing that query in any way. Up to now I haven't shown the tools to decode the form variables and perform some basic HTML generation automatically. Read on.

The next step – a basic framework

The first thing you notice when you look at the code for the last request is that there's a lot of stuff going on that has very little to do with the business logic of what you're trying to accomplish. You'll find that lots of things are rather repetitive and need to occur on every request. Adding an HTTP header to a request, parsing form variables (which we haven't done yet), sending error messages that are standard pages.

So, let's introduce a framework here. This framework is included here courtesy of West Wind Web Connection and provides a small subset of that Web application framework.

Why do you need a framework?

Requests are repetitive.
The same things need to be done over and over again. Save some time and call a method in your server instead. Just about every request will need to read some input from the Web server and every request needs to output some text. The framework simplifies this process.

Common Operations should be abstracted
In particular HTML generation and form variable parsing should be abstracted in an extensible way so that the process of creating your application is simplified. In the framework we'll build here we'll use support objects and methods very similar to the Active Server Page Objects. oResponse is used for output, oRequest for input.

Generic HTML generation
I'm not going into huge detail here - if you want that you can check out Web Connection, which contains extensive HTML generation tools. Here we'll focus on the base implementation and one particular implementation to allow for scripting using ASP like syntax with VFP code.

Scripting is essential for HTML applications
Scripting is the key to make it easy to create HTML output without having to recompile your code every time a tiny change is made to the interface. In my opinion the combination of a code request and a script template page to display is the best possible way to generate an application. We'll look at how to create a scripting engine with this class.

The wwFoxISAPI framework

This framework is fairly simple and straight forward. It consists of three objects:

wwFoxISAPI
The server object that you subclass your FoxISAPI apps from.

wwRequest
Member object of wwFoxISAPI handles retrieval of Form and Server Variables to allow you to use information provided by the user and the Web server in your requests.

wwResponse
Member of wwFoxISAPI handles output of all HTML/HTTP.

wwFoxISAPI

This class represents the basic server object which is also a container for the wwRequest and wwResponse objects. The following methods and properties exist.

Property	What it does
oRequest	Instance of a wwRequest object used for retrieving HTML Form and server variables.
oResponse	Instance of wwResponse. Used for all output to be sent back to the Web server.
lError	Flag that determines whether an error occurred
cErrorMsg	If lError is .T. this contains an error message

Method	What it does
Process()	Entry point method that provides an entry point for every request of the server. Optionally called, but recommended to centralize access! Set Method = on the URL. Pass: <cFormVars>, <cIniFile>, <nRelease> Return: returns completed HTML output
StartRequest()	Method that configures the oRequest and oResponse members from the current request input data. Pass: <cFormVars>, <cIniFile>, <nRelease> Return: nothing
StandardPage()	Simple HTML page generation method. Creates a fully functional page from a header and body parameter. Pass: <cHeaderText>,<cBodyText> Return: nothing
ErrorMsg()	Same as StandardPage, but implemented to allow for showing error message differently than standard pages. Pass: <cHeaderText>,<cBodyText> Return: nothing
Error()	Internal, protected error handler method. Important. Calls ErrorMsg() to generate an error response and turns off further output.

wwRequest

This class handles access to the input that's made available by the Web server. This includes access to HTML Form variables, the Query String and Server Variables. This object is configured on each call by calling wwFoxISAPI::StartRequest which sets the cContentFile and cFormVars properties

Property	What it does
cFormVars	Used to hold the HTML form variables for parsing.
cContentFile	The name of the INI file that holds all server variables.
cQueryString	The full Query String as passed on the URL. This is everything following the ? on the URL.

Method	What it does
LoadRequest()	Initializes the request. This method is called from wwFoxISAPI::StartRequest. Pass: <cFormVars>,<cIniFile> Return: nothing
Form()	Returns an individual HTML Form variable entered by the user. Pass: <cFormVarName> Return: content of form var or "" if it doesn't exist or is empty
QueryString()	Returns named parameters of the Querystring. Pass: <cQueryStringKey> or <nPositionalParameter> Return: content for querystring key or ""
ServerVariables()	Returns any of the server variables available in the INI file. See the INI file listing above for details on what keys are available. Pass: <cServerVarKey>,[<cSection>("FoxIsapi")]
GetFormMultiple()	Returns a multivalue HTML form variable into an array. Pass: <@aFormVars>,<cFormVarName> Return: Number of formvars retrieved or 0
SetKey()	Forces a form variable to be set to a new value. Used for overriding values on auto updates. Pass: <cFormVar>, <cValue> Return: Nothing
aCGIParms()	Creates an array of positional parameters separated by ~'s. For compatibility with Web Connection and the optional positional parameter scheme. Parses into Protected aCGIParms property.
GetCGIParameter()	Returns a positional parameter. You can also use QueryString(nValue) for this, but only after you've called aCGIParms!
GetAuthenticatedUser()	Returns the REMOTE_USER environment variable. User that's logged on to NT on the server
GetPhysicalPath()	Returns the name of the script. Note: this doesn't work correctly for Foxisapi.dll but it works with script maps. Use this to retrieve the path to a script for template expansion.
GetLogicalPath()	Returns the virtual path to a script mapped document. Again, doesn't work with Foxisapi.dll but works with script mapped docs mapped to it.
GetPreviousUrl()	Returns the URL that called this document. If the user typed the URL manually this value will be blank.
GetBrowser()	Return the browser's full name
IsLinkSecure()	Returns .t. if the link is secure. Pass a server as a string if the port is different from 443 (standard SSL port).
GetCookie()	Retrieves an HTTP Cookie.
GetRemoteAddress()	Retrieve the client's IP address
GetServerName()	Name of the server's domain or ip as specified on the client's URL

wwResponse

This class is responsible for creating output for the Web application. All output should flow through the Write or Send methods of this class in order to properly handle output to different output sources as well as error response handling that allows turning off of output after an error has occurred and an error message was generated.

Property	What it does
cOutput	Property that holds the cumulative HTTP (mostly HTML) output.
lNoOutput	When .t. any request for output doesn't write to the output source. Typically used after an error occurred to prevent further output to occur after an error message

Method	What it does
Write Send()	Low level output methods that can be called directly and are used internally by all framework functions to send output to the output source. If lNoOutput is .T. output is not sent to the output source, but rather returned as a string. All internal methods call Send or Write and return the result to the user – most methods also support the lNoOutput parameter with the same result. Pass: <cText>,<lNoOutput> Return: nothing or the text if lNoOutput is .T.
Rewind()	Clears all output and resets the lOutput flag
SendLn()	Just like Send or Write but appends a Carriage Return for easier source formatting.
GetOutput()	Returns the cumulative output. Doesn't clear the cOutput property.
ContentTypeHeader()	Creates a full Content Type Header Pass: <cContentType (text/html)>, <lNoOutput> Return: "" or header if lNoOutput is .T.
HTMLHeader()	Creates a header for a document. Header includes ContentType Header, title, large text header and background formatting. Pass: <cHeaderText>, <cTitle>, <cBackground>,<cContentType>,<lNoOutput> Return: "" or header if lNotoutput is .T.
HTMLFooter()	Inserts end BODY and HTML tags into the document. Also, allows you to put some attach some extra HTML prior to the end tags. Pass: <cFooterText>, <lNoOutput> Return: "" or header if lNotoutput is .T.
Authenticate()	Create a request for Authentication that pops up a login dialog on the client. Pass: <cDisplayServerName>, <cErrorHTML>, <lNoOutput> Return: "" or header if lNoOutput is .T.
ExpandScript()	Takes an input file and expands the text using program based evaluation. The page is converted into a TEXTMERGE program that's run by VFP (in compiled mode) or by CodeBlock (interpreted mode). Pass: <cPage>, <nMode>, <lNoutput> Return: "" or header if lNoOutput is .T. nMode switches: 0 – Auto (compiled in VFP Dev, Interpreted in runtime), 1 – Interpreted, 2 – Force VFP compiled (must be pre-compiled in runtime)
ExpandTemplate()	Takes an input filename and expands the text using expression based evaluation and Codeblocks. Unlike scripting this mechanism does not support control structures in the HTML page except in distinct CodeBlocks. Pass: <cPage>, <lNoOutput> Return: "" or header if lNoOutput is .T.

Looks like a lot of stuff, huh? But it sure makes life easier. Let's take a quick look at the examples we previously ran with the framework now.

DEFINE CLASS TFirstserver AS Custom OLEPUBLIC

FUNCTION Helloworld2
LPARAMETER lcFormVars, lcIniFile, lnReleaseFlag
LOCAL lcOutput

THIS.StartRequest(lcFormVars, lcIniFile, lnReleaseFlag)

THIS.StandardPage("Hello World From Visual FoxPro",;
                  "This page was generated by VFP at" +time())

RETURN THIS.oResponse.GetOutput()

ENDDEFINE

This reduces the Hello World program down to 3 lines of code and not having to remember arcane syntax for the HTTP header. Note the RETURN value: We're returning the HTML output of the oResponse object back to the client. Standard page writes output to the oResponse object so even though we didn't access the response object directly it was used for output and hence we have to return its content back to the client. You'll want to call THIS.oResponse.GetOutput() on every exit point of your request.

Let's take a look at the data request we wrote before and embellish a little bit by allowing it to be 'parameterized' with a query string option to pick an individual customer and show each customer as a link so we can view the detail by calling another FoxISAPI request. The URL to access the list page may look like this:

/foxisapi.dll/FirstServer.TfirstServer.LookupCustomer?CustNo=10

FUNCTION SimpleQuery
LPARAMETER lcFormVars, lcIniFile, lnReload
LOCAL lcCustno
PRIVATE Response

THIS.StartRequest(lcFormVars, lcIniFile, lnReload)

lcCustno = THIS.oRequest.QueryString("CustNo")

*** If no custno was passed let's show all custs
IF !EMPTY(lcCustNo)
   lcCustno = PADL(lcCustNo,8)
ENDIF   

*** Easier reference
Response = THIS.oResponse

*** NOTE THE USE OF THE PATH!
SELECT [<A HREF="/foxisapi/foxisapi.dll/FirstServer.TFirstServer.LookupCustomer?Custno=]+ALLTRIM(Custno)+[">]+Company+[</a>] as COMPANY,;
       CareOf, phone, custno, company as sort ;
 FROM .\Data\TT_Cust ;
 WHERE CustNo = lcCustNo ;
 ORDER BY Sort ;
 INTO Cursor TQuery

IF _TALLY = 0
   THIS.ErrorMsg("No customers match the customer number.",;
                 "Please retry your request or omit the "+;
                 "customer number for a list of all customers.<p>"+;
                 [<A HREF="]+THIS.oRequest.GetPreviousUrl()+;
                 [">Return to the previous page</a>])
   RETURN Response.GetOutput()
ENDIF 

*** Creates ContentTypeHeader and HTML header
Response.HTMLHeader("Simple Customer List")

Response.Write([<TABLE Border=1 CellPadding=3 width="98%">] + ;
 [<TR BGCOLOR="#CCCC88" ><TH>Company</TH>]+;
 [<TH>Name</TH><TH>Phone</TH></TR>])

SCAN
  Response.Write("<TR><TD>" + Company + "</TD><TD>" + Careof + ;
                 "</TD><TD>"+ STRTRAN(Phone,CHR(13),"<BR>") +;
                 "</TD></TR>")
                 
ENDSCAN
             
Response.Write("</TABLE>")

RETURN Response.Getoutput()
ENDFUNC

Pretty straightforward. Again, note the call to StartRequest to configure the oRequest and oResponse member objects. We use the Request.QueryString() method to retrieve the customer number and use it in the query to retrieve the appropriate customer. If no customer was supplied we'll display the full list instead.

Also, note how the HREF links are embedded into the page: The SQL statement actually creates the links as part of the result cursor. When the time comes to display these items we don't have to worry about reformatting it – it's faster in the SQL statement since the expression evaluates only once for the query.

As before, Response.GetOutput() is used to return the HTML back to the client. Notice that there's an error check if no records are returned from the query. It creates an error message and then also returns the Response Output!

Since the link is embedded into the page, lets show the record display as well:

FUNCTION LookupCustomer
LPARAMETER lcFormVars, lcIniFile, lnReload
PRIVATE Response

THIS.StartRequest(lcFormVars,lcIniFile,lnReload)

Response = THIS.oResponse

lcCustId = THIS.oRequest.QueryString("Custno")
lcCustId = PADL(lcCustId,8)

IF !USED("TT_Cust")			
   USE .\Data\TT_Cust IN 0
ENDIF
SELE TT_Cust

LOCATE FOR CustNo = lcCustId
IF !FOUND()
   THIS.ErrorMsg("Customer does not exist","["+lcCustId+"] Please select a valid customer.")
   RETURN Response.GetOutput()
ENDIF

Response.HTMLHeader(Company)

Response.Write([<TABLE BORDER="1" CELLSPACING="3" width="300">])
Response.Write("<TR><TD>Company:</td><TD>"+Company + "</TD></TR>")
Response.Write("<TR><TD>Name:</td><TD>"+Careof + "</TD></TR>")
Response.Write("<TR><TD>Phone:</td><TD>"+Phone + "</TD></TR>")
Response.Write("<TR><TD>Address:</TD><TD>"+STRTRAN(Address,CHR(13),"<BR>") + "</TD></TR>")
Response.Write("</TABLE>")

RETURN Response.Getoutput()

ENDFUNC

Error Handling

I haven't talked much about error handling, but one crucial aspect of Web Applications is what to do if an error occurs. If an error occurs and the server pops up a dialog box your server is dead in the water and hung. This is something that must be avoided at all costs.

One of the things the framework does is use an Error method in the wwFoxISAPI class. The error method looks like this:

#IF NOT DEBUGMODE

***********************************************************************
* wwFoxISAPI :: Error
*********************************
***  Function: Limited Error handler. Not much we can do here other
***            than exit. Displays error page.
***********************************************************************
PROTECTED FUNCTION Error
LPARAMETERS nError, cMethod, nLine
LOCAL lcOutput

THIS.lError = .T.
THIS.cErrorMsg = THIS.cErrorMsg + STR(nError) + " - " + Message() + " - " + Message(1) + " - " +cMethod + " @ " + STR(nLine) + CHR(13)

THIS.StandardPage("Hold on... we've got a problem!",;
                  "The current request has caused an error.<p>"+CR+;
                  "Error Number: "+STR(nError)+"<BR>"+CR+;
                  "Error: "+Message()+"<BR>"+CR+;
                  "Code: "+Message(1)+"<BR>"+CR+;
                  "Running Method: "+cMethod+"<BR>"+CR+;
                  "Current Code Line: "+STR(nLine) )
                  
THIS.oResponse.SendLn("<HR>")
                  
*** Stop further output
THIS.oResponse.lNoOutput=.T.

RETURN TO Process
ENDFUNC
* Error

#ENDIF

Since the wwFoxISAPI class (or your subclass of it really) is at the top of the call stack its error method will capture any error that occurs and is not handled by a local class error. This is useful as we can capture the error and report it in the form of an error message that contains error information. You can also log this error, but that's beyond the scope of this session here.

The important thing of the handler is to make it avoid popping up an error dialog – essentially the error is ignored and an error message generated. The code turns off further HTML output by setting Response.lNoOutput =.F. – this means if the code returns to a calling method all HTML output will not be sent to the output source, but will just be discarded.

Finally the code exits by issuing RETURN TO PROCESS. We'll discuss the Process method in the next session – it's a central entry point method that allows handling global server operations. If this method is used returning to it will cause the request to terminate immediately and cleanly and still be able to return the error message to the browser.

Centralizing your Entry point

Even as we've simplified our task through the framework there's still a lot of duplication that occurs when you look at these requests. You still have to remember to call StartRequest() on each hit and make sure that you return Response.Getouput() on all exit points. And there's the issue of cleanly handling an exit from an error.

The solution is to build your server with a centralized method, which I call Process(). Rather than calling each server method directly from the Web Page you'd always call the Process method and tell it which method you'd like to run via a QueryString parameter. You'd end up with a URL like this:

/foxisapi.dll/FirstServer.TfirstServer.Process?Method=FirstQuery

/foxisapi.dll/FirstServer.TfirstServer.Process?Method=LookupCust&CustNo=43

When called in this fashion you can now centralize your requests. The Process() method can be generic or you can override this functionality with your own, but it must at the very least handle parsing the Method querystring parameter and calling the appropriate method. Here's what the wwFoxISAPI::Process method looks like:

***********************************************************************
* wwFoxISAPI :: Process
*********************************
***  Function: Genereric Entry Point Method used for all requests.
***            This method requires that a ?Method=SomeMethod query
***            string is provided on the command line.
***            This method makes it possible to automatically load
***            the Request and Response objects automatically.
***    Assume: Always called from the Web server directly!
***      Pass: lcFormVars
***            lcIniFile
***            lnRelease
***    Return: HTML OUtput
***********************************************************************
FUNCTION Process
LPARAMETERS lcFormVars, lcIniFile, lnRelease
LOCAL lcMethod
PRIVATE Response, Request

Response=THIS.oResponse
Request=THIS.oRequest

lnRelease = 0
THIS.StartRequest(lcFormVars, lcIniFile, lnRelease)
lcMethod = Request.QueryString("Method")

DO CASE
   *** Protect against illegal method calls
   CASE INLIST(lcMethod,"PROCESS","LOAD","INIT","DESTROY")
      THIS.StandardPage("Invalid Method: " +lcParameter) 

   *** Generic! Method names must be Method= on QueryString
   *** If you use different method names or parameters a custom CASE 
   *** should be added *ABOVE* this line!
   ***
   *** Call methods that were specified on the command line's 1st parm
   ***  ie:   wwcgi.exe?Project~Method~MoreParameters
   CASE !EMPTY(lcMethod) AND PEMSTATUS(THIS,lcMethod,5)
      =EVALUATE("THIS."+lcMethod+"()")
ENDCASE

RETURN THIS.oResponse.GetOutput()
ENDFUNC
* wwFoxISAPI :: Process

This simple method frees you from a lot of work on each request! It automatically sets up Response and Request objects for you. Your handler methods no longer need to receive multiple parameters as they're not called directly from the Web page. Rather the EVALUATE("THIS."+lcMethod) is what calls your server method.

Remember the Error Method? It did a RETURN TO PROCESS, right? Well, let's presume there's an error in your request handler method or one of the functions/classes etc it calls that are not handled. The Error method gets control, generates the Error message to the Response object and then issues RETURN TO PROCESS, which returns to the line following the EVALUATE() in this case the RETURN THIS.oResponse.GetOutput() to still return the result output.

No matter what, THIS.oResponse.GetOutput() will always get called so you no longer have to worry about making sure that you remember to call it on all exit points of your code. You simply write to the Response object and exit and the Process method handles sending the result back to the Web server.

An additional benefit is the fact that you can now also make all of your request methods PROTECTED, so the Automation interface that your server exposes is leaner which results in a smaller footprint and faster load time. This may not matter on small servers you create, but on those that have more than 50 or so methods the load issue becomes significant.

Scripting and Templates

In order to build HTML application efficiently it's extremely important to have a mechanism available for building the display without having to write a lot of code that has to be recompiled before installation. The combination of code and scripting is an extremely powerful that can provide the maximum flexibility for your applications where you can run some code in a request method as shown above and you then use a template or a script page to actually display the output.

Implementating a scripting engine with Active Server Syntax

Let's walk through the creation of a scripting engine that will allow you use syntax similar to Active Server Pages but use FoxPro code instead of VBScript. I'll introduce two concepts here: Scripts and Templates.

Template
A template is an Evaluated document. It primarily uses expressions or field names to display on a page, but no or minimal code that can reside in blocks. A template works through a Visual FoxPro program parsing the expressions and embedding the result values into the page instead of the expressions or code blocks.

Scripts
Scripts are a little different – they're turned into a real program that's run by Visual FoxPro either in interpreted mode (using CodeBlock by Randy Pearson) or runtime mode by running a precompiled file from disk. Since these scripts are programs you can use control structures and HTML in the same document. Scripts have a number of issues with compilation that may be difficult, but compiled scripts can run at VFP native speed!

Templates with MergeText

Implementing a scripting engine in VFP is actually rather simple. Both mechanisms can be created with relatively little code. Let's start with Templates. For templates I use a function called MergeText() which walks through the page loaded from a string and expands the expressions. You can find the code to MergeText in wwUtils.prg. You call it like this:

lcTextToMerge = File2Var("SomeScriptFile.FIT")
lcExpandedText = MergeText(lcTextToMerge)

Typically you'll find a file from disk and use File2Var to convert the file to a string that you can feed to MergeText to expand. Inside of a template you can use the following syntax:

<%= AnyFoxExpression %>

<% BlockOfCode %>

Expressions are evaluated and embedded directly and can be of any type that but Object. CodeBlocks use Randy Pearson's CodeBlk class to interpret commands sequentially. A couple of rules apply for CodeBlck:

LOCAL variables are not allowed.
Any variables in a control structure must be preinitialized as PRIVATE and set to a value.

CodeBlk is interpreted using Macro Expansion for each line of code and can be very, very slow for iterative looped commands, so use it sparingly. If you find yourself creating more than a few lines of code within a code block, write a UDF as part of your application instead and use an expression to call it instead:

<%= CreateListTable() %>

Note that you can do things like this:

<% PUBLIC o
   o=CREATE("SomeClass")  
%>   

Some HTML here…

<%= o.ShowHTMLTable() %>
<% RELEASE o%>

Here's an example of request you might want to run using a template. You may have a snippet of code that does this:

PROCEDURE ShowCustomer

lcCustno = Request.QueryString("CustNo")
USE TT_CUST
LOCATE FOR CUSTNO = lcCustNo
IF !FOUND()
   THIS.ErrorMsg("Customer Not Found")
   RETURN
ENDIF

Response.ContentTypeHeader()

Response.ExpandTemplate("c:\westwind\Foxisapi\Customer.wc")

ENDPROC

The HTML template in customer.fit (Web Connection Template) then looks like this after setting it up in FrontPage:

<html>

<head>
<meta NAME="GENERATOR" Content="Microsoft Frontpage 3.0">
<meta HTTP-EQUIV="Content-Type" content="text/html">
<title>Document Title</title>
</head>

<body>

<table width="400">
  <tr>
    <td bgColor="#ffffcc" vAlign="top" width="212"><strong><font face="Arial">Company</font></strong></td>
    <td width="180"><strong><font face="Arial"><%= Tquery.Company %> </font></strong></td>
  </tr>
  <tr>
    <td bgColor="#ffffcc" vAlign="top" width="212"><strong><font face="Arial">Name</font></strong></td>
    <td width="180"><strong><font face="Arial"><%= CareOf %> </font></strong></td>
  </tr>
  <tr>
    <td bgColor="#ffffcc" vAlign="top" width="212"><strong><font face="Arial">Phone</font></strong></td>
    <td width="180"><strong><font face="Arial"><%= STRTRAN(Phone,CHR(13),"<BR>") %> </font></strong></td>
  </tr>
<% IF TQuery.Billrate > 0 %>
  <tr>
    <td bgColor="orangered" width="212"><strong><font face="Arial">Billable Customer at $<%= BillRate %></font></strong></td>
  </tr>
<% ENDIF %>
</table>
</body>
</html>

Note that in FrontPage all the expressions show up as script tags. Since MergeText uses ASP syntax FrontPage and most other HTML editors will treat these FoxPro script tags as if they were native Active Server tags. For example in Visual Interdev the tags are highlighted as code just as with VBScript and most keywords even show up in the proper syntax color highlights.

You can call MergeText in your own methods or you can use the wwFoxISAPI::ExpandTemplate() or the wwResponse.ExpandTemplate() methods. The wwFoxISAPI version creates a full freestanding request including content type header, which the Response method simply sends the template right to the Response output source.

Scripting – more power and more work

Templates are very nice, but for truly free standing scripts using CodeBlk is a little too slow. While I believe the best way to build Web apps is with a combination of code and scripts/templates scripting makes it possible to do it all in a single scripted page without any code that needs to be compiled into the application.

Like Templates, Scripts use Active Server Syntax. All of the features of a template also work with scripts so you can embed expressions as well as CodeBlks. However, Scripts provide some additional functionality: They allow creation of structured statements that can mix FoxPro code and HTML. For example, the following SCAN loop will work only in a scripted page:

<HTML>
<% SELECT * FROM TT_CUST INTO Tquery 
   SCAN %>
Name: <%= Company %>
<HR>
<% ENDSCAN %>
</HTML>

The reason why this works is that scripts are actually converted into full programs that are run by Visual FoxPro. The script above is converted into a textmerge document that looks something like this:

TEXT
<HTML>
ENDTEXT
  SCAN 
TEXT
Name: << Company >>
ENDTEXT
 ENDSCAN
TEXT
</HTML>

ENDTEXT

The wwVFPScript class takes the original Script file and converts it into this type of TEXTMERGE code, then actually runs the code to create a temporary output file which contains the generated final HTML.

You can look at wwVFPScript for more details, but here's how the CodeBlock execution works:

***********************************************************************
* wwVFPScript :: cbExecute
**********************************
***  Function: Forces operation through CodeBlock
***      Pass: lcCode     -   Code to run as string
***            llVFPCode  -   ASP Scripting or VFP code
***    Return: Evaled output or ""
***********************************************************************
FUNCTION cbExecute
LPARAMETER lcCode, llVFPCode
LOCAL lcVFPCode

IF !llVFPCode
   lcVFPCode = THIS.ConvertPage(@lcCode,.t.)
   File2Var("Code.PRG",lcVFPCode)
ENDIF

IF llVFPCode
   THIS.RenderPageFromVar(@lcCode)
ELSE
   THIS.RenderPageFromVar(@lcVFPCode)
ENDIF   

RETURN THIS.oHTML.GetOutput()
ENDFUNC
* wwVFPScript :: ExecuteCodeBlock

The ConvertPage method can convert the HTML scripting into a MergeText compatible VFP program. The code is then passed to the RenderPageFromVar() method which actually runs CodeBlk to evaluate the page. CodeBlk interprets the code 1 line at a time and is rather slow if you're doing anything inside of a loop.

You can also run a page in compiled mode. However, since COM objects are EXE files that are compiled and can't compile code on their own this option requires that you compile the pages on your own. To accomplish this you can run the following in VFP:

o=CREATE("wwVFPScript","c:\westwind\foxisapi\somepage.wcs")
o.ConvertPage()
o.CompilePage()

which creates the .WCS files into compiled .FXP files that can be run directly from disk. Or use this function in wwUtils.prg which can do it with wildcards compiling a bunch of files altogether. So you can do:

SET PROCEDURE TO wwUtils Additive
DO WCSCOMPILE WITH "c:\westwind\foxisapi\*.wcs"

The idea is that you can run scripts interactively with CodeBlk until you get it working, then compile them. Once compiled making changes requires recompiling. Since scripts are compiled they run very fast at native VFP speed.

Hooking it in…

Templates called from code is very powerful. It gives you the opportunity to call a template after you've done your processing logic and even run minimal code and expression logic inside of the HTML page.

But let's take this a step further and make it so that no code at all is required and you can fire off a scripted page automatically.

Note

In order to allow simple script and template access I had to make a very useful modification to FoxISAPI.dll. The addition of a new INI file setting called DefaultServer allows specification of a Server.Class.Method string that is used if none is supplied. For the examples above we might use:

DefaultServer=FirstServer.TfirstServer.Process

This makes it possible to create links like this:

/foxisapi/foxisapi.dll?Method=CustomerLookup

Note the lack of the 'extra path'. This change also makes it possible to create a scriptmap that calls foxisapi.dll. Scriptmaps cannot have extra paths, so the DefaultServer option makes it possible to fire off scripts automatically with syntax like this:

/foxisapi/MyScriptPage.wc

To make this work you need to use the Foxisapi.dll that's included in the DLL directory of the CD rather than the one that ships with VFP.
Modify the FoxISAPI.ini file and add:
DefaultServer=FirstServer.TfirstServer.Process or whatever your server name is. Make sure you use a subclass of wwFoxISAPI as it contains the logic to route .WC and .WCS pages.
Create a script map for .WC and .WCS on the Web server.

Open up the System Management Console
Select either you default Web site (if you want the script mapto be global – not a bad idea) or the virtual that you're working on.
Right click and select Properties|Virtual Directory|Configure
Set up two script maps for .WC and .WCS and point them both at your copy of Foxisapi.dll.

You now have a scriptmap for your DLL and it's now possible to run your script pages without having to hook any code in the COM servers you build. For example,.to run the customer lookup page from before you can now simply go:

/foxisapi/Customerlookup.wc

This call will fire up your Automation server through the script mapping and interpret that page by virtue of the logic built into the Process method of the wwFoxISAPI class. Here's how it does it:

lcPhysicalPath = Request.GetPhysicalPath()

It starts by retrieving the Physical path of the page which comes back as something like c:\westwind\foxisapi\CustomerLookup.wc. The Process method handler code checks for the .wc and wcs extensions which indicate we're running a generic script:

*** Handle Template and Script Pages
   CASE ATC(".wcs",lcPhysicalPath) > 0
      THIS.ExpandScript(lcPhysicalPath)
   CASE ATC(".wc",lcPhysicalPath) > 0
      THIS.ExpandTemplate(lcPhysicalPath)

and passes on the request to the ExpandTemplate and ExpandScript methods.

***********************************************************************
* wwFoxISAPI :: ExpandTemplate
*********************************
FUNCTION ExpandTemplate
LPARAMETER lcFileName

*** Default Content Type 
Response.ContentTypeHeader()

*** And expand the actual template
Response.ExpandTemplate(lcFileName)

RETURN

************************************************************************ wwFoxISAPI :: ExpandScript
*********************************
FUNCTION ExpandScript
LPARAMETER lcFileName

Response.ContentTypeHeader()
Response.ExpandScript(lcFileName,THIS.nScriptMode)

RETURN

*wwFoxISAPI :: ExpandTemplate

These methods only forward the request to the Response object which in turn do the dirty work of evaluating these objects and then return back to the Process method which takes the output from the Response object and sends it back to the Server.

***********************************************************************
* wwResponse :: ExpandScript
*********************************
***  Function: Takes a script page and 'runs' it as a TEXTMERGE 
***            document. 
***      Pass: lcPage  -  Physical Path to page to expand
***            lnMode  -  1 - Interpreted (CodeBlk)
***                       2 - Compiled FXP (default)
***    Return: Nothing
***********************************************************************
FUNCTION ExpandScript
LPARAMETERS lcPage, lnMode

lnMode=IIF(EMPTY(lnMode),1,lnMode)

lcFileText = File2Var(lcPage)
IF EMPTY(lcFileText)
   RETURN THIS.Send("<h2>File " + lcPage + " not found or empty.</h2>",llNoOutput)
ENDIF

*** Add default content Type
THIS.ContentTypeHeader() 

*** Create Script Object and pass THIS HTML object to it
IF lnMode = 1   && CodeBlock
	loScript = CREATE("wwVFPScript",,THIS)
	loScript.oCgi = Request

	*** Outputs to script object
	loScript.cbExecute(lcFileText)
ELSE
    loScript = CREATE("wwVFPScript",lcPage,THIS)
	loScript.oCgi = Request
	loScript.lRuntime = .T.
	loScript.lAlwaysUnloadScript = .T.
	
	*** Converts the name to FXP and tries run the page
	loScript.RenderPage()
ENDIF	

ENDFUNC
* wwResponse :: ExpandScript

***********************************************************************
* wwResponse :: ExpandTemplate
*********************************
***  Function: Evaluates embedded expressions inside of a page
***      Pass: lcPage   -    Full physical path of page to merge
***    Return: "" or merged text if llNoOutput = .T.
***********************************************************************
FUNCTION ExpandTemplate
LPARAMETERS lcPage,llNoOutput
LOCAL lcFileText

lcFileText = File2Var(lcPage)
IF EMPTY(lcFileText)
   RETURN THIS.Send("<h2>File " + lcPage + " not found or empty.</h2>",llNoOutput)
ENDIF
   
RETURN THIS.Send( MergeText(lcFileText),llNoOutput)
ENDFUNC
* wwResponse :: ExpandTemplate

Multiple instances via Pool Manager

Note: You must download the latest version of FoxISAPI.DLL from the MS Web site. VFP 5.0a did not ship with the final build of this tool.

I've talked quite a bit of multiple instances of your servers. Since VFP is single threaded and the ISAPI interface is multi-threaded the only way to be able to process simultaneous requests in Visual FoxPro is to use multiple instances. In order to do so FoxISAPI and Web Connection as well use pool manager inside of the ISAPI DLL to create multiple instances of your single use EXE servers.

Be careful with multiple instances and how you instantiate them. Multiple instances can improve performance drastically on multi-processor machines, but on single processor machines they can only provide a perceived increase in speed when serving requests of varying lengths. For example, a second instance can continue to serve short requests while another instance is busy serving a lengthy query. But actual performance and load on the PC is still bound to the hardware, and two requests running simultaneously might run take twice as long as the requests would take running one after the other. Testing these scenarios is crucial for your particular application!

Figure 1.3 – FoxISAPI (and Web Connection's) Pool Managers handle instantiation and rotation of multiple servers to provide simultaneous request processing.

So how does it work? With multiple instances of the same server, requests are served by the pool manager, which maintains a pool of multiples of your servers. If the first instance is busy the second instance will take the request. If all servers are busy and the pool of servers is exhausted the request is queued. In order to use the internal Pool Manager the server must be single use EXE!

Multiple servers are configured via the FoxISAPI.INI startup config file:

[foxisapi]
busytimeout = 5
releasetimeout=13
statusurl = Status
reseturl= Reset
SingleModeModeUrl = SingleMode
MultiModeUrl = MultiMode

[wwFoxISAPI.TFoxISAPI]
wwFoxISAPI.TFoxISAPI=2
R_FoxIsapi.T_R_Foxisapi=1

[foxis.employee]
foxisr2.employee=2
foxisr1.employee=1
foxis.employee = 2

The first keys in the [FOXISAPI] section determine how you can manage servers. The various URL keys allow you to customize the commands used on the URL to run that command:

foxisapi.dll/status
foxisapi.dll/reset
foxisapi.dll/singlemode

The Status URL displays a list of all servers that are currently loaded. Reset releases all servers. SingleMode releases all servers but the first so you can run maintainenence operations that require EXCLUSIVE access to the data.

The actual Automation servers are configured with a separate section in FoxISAPI.INI. The section serves as a map to translate your ClassID passed on the URL to translate to the actual ClassIDs that you want to call. Since you can call both the same server or a local and remote server. Since locals and remote must have different class ids this mechanism allows you transparently to load the remote with the same URL as the local.

In the [foxis.employee] example above FoxISAPI would first load the FoxISr2 server when starting up. Once this server gets busy it would load another instance since the key value is 2. When both of these are busy foxisr1 would get loaded. Finally, a local copy gets started and two instances of that can be running before requests start queuing.

Typically, you'd want to load the local servers first, but it depends on your server load.

Configuring Remote Servers

Be careful with Remote servers. While they run reasonably fast there are a number of important issues to deal with.

Essentially, in order to build remote servers you need to make sure you build your server with some conditional logic for each location that it'll run in in order to properly point at the data and the Web Server for retrieving HTML templates.

The following issues have to be dealt with:

File pathing
In my experience I've had to compile in a set of #DEFINEs for each location that establishes the startup path (Automation servers have no default start path), the data path and the HTML page path.

Getting the Server Variables INI file
The server variables files goes to the Web server, but the Web server returns c:\TEMP\FOX01.INI for example. You'll need to translate that path to the actual path from your remote machine to get at it.

Security Configuration
If you thought configuration for local Automation Servers under Automation was a drag think again! In order to run a remote server from the Web service you need to do some more configuration.
(The following provided from the Web Connection manual but it applies the same way to FoxISAPI servers):

In this setup your Web server is the Client (Web Connection DLL manages multiple client instances of your server) and the remote machine is the Server that serves contest.
If you want to mix local and remote servers you need to create separate EXE files with separate OLE ClassIds for each remote server. This is so DCOM can properly determine which machine to run the server on based on the entries in the registry from the single machine that wc.dll runs on. For example, you might have a local server called wcDemoOle.wcDemoServer. You can then create wcRemote1.wcRemoteServer1, wcRemote2.wcRemoteServer2 etc. In VFP 5 the server name corresponds to the EXE/DLL name and the class corresponds to the OLEPUBLIC class that your code exposes (your wwOLEServer subclass in this case).It's important that the Class names are different or else you will run into conflicts in the DCOMCNFG utility discussed above!
Build the server and make sure it's registered on the remote machine. It's best to test the server locally on the remote before attempting to run it over DCOM. Make sure you apply the DCOMCNFG settings described in the previous section. To see the server come up locally try code like the following:

o=CREATEOBJECT("wcRemote.wcRemoteServer")
o.show()

Copy the .VBR files created when you build your Automation server to a directory on your Web Server for each Automation server you want to remote. The remote EXE file is not needed on the Web Server.
Run CliReg32 (in your \VFP directory) and pass it the name of each of the VBR files. Choose DCOM for the transport and set the appropriate IP address for the remote server! Important: the server must be registered on the remote or load will always fail.
At this point you should test the server from the Web server machine. Fire up VFP and see if you can instantiate the remote object on the remote machine. Use the CREATEOBJECT code a few steps back.If the server comes up on the remote box your server is installed correctly for operation under DCOM.
On the Remote machine start DCOMCNFG and add the IUSR_ account of the Web server to the Default Access and Launch permissions on the Default Security tab. If you don't use a Domain Server you'll need to explicitly create new account/password and match it to the Web Server's account and password. With IIS the IUSR_ password is a random value so you'll have to change it both in User Manager and in the IIS configuration utility. If you don't want to hassle with the IUSR_ account you can also use the EveryBody group to allow access for all, but keep in mind that this is a potential security risk.
You should now be ready to load the server through FoxIsapi. Add the remote servers to foxisapi.ini:

[wwDemoOle.wcDemoServer]
wwDemoOle.wcDemoServer=2
wcRemote.wcRemoteServer=1

This setting will load two local servers and one remote server.

If all is well, the server will come up on the remote box as expected. Note that load time for remote server is significantly slower than local servers as is the time it takes to release the server. Operation of method calls however, is swift. If the server fails to load, you'll see a COM error message returned.
For debugging this setup I suggest you log on to your Web Server box as your IUSR_ account then fire up VFP to try and create the remote object. This allows you to interactively change the DCOM settings plus get the COM error messages properly returned to you by VFP. It's much easier to handle and respond to the errors in VPFs interactive environment than trying to handle the Web server and its error messages.

Running your FoxISAPI servers as MTS Components

There's been lots of talk about Microsoft Transaction Server support in Visual FoxPro 6.0. Sure enough MTS works with Visual FoxPro, but keep in mind that MTS will not buy you very little in terms of scalability or speed with Visual FoxPro and Web applications.

As with any server judge your use of MTS entirely by the utility that the MTS environment can provide you with. In particular:

Distributed SQL transactions that can span multiple requests
MTS provides the ability to handle transactions on the component level rather than at the SQL level which makes it possible to make multiple server calls in succession and treat them as a single atomic unit. With Web request and stateless clients however, this is not quite as useful as it sounds as it really is only controlled by the server on the backend. Distributed transactions can span multiple databases, devices and even different DBMS systems.

Role based security
MTS introduces a simplified security model that allows assigning groups of components to specific security contexts without involving the NT User manager. It's easy to set up specialized roles for a group of users – these roles can then be picked up by role inside of the MTS component code to verify a given user.

Easier remote operation
MTS makes it easy to create packages that can be moved to a remote machine and run from it. Installation of a package allows the option of making a package operate on another machine. Package installation handles all the background configuration for security and impersonation that otherwise has to be done manually.

Ability to unload a package
It's possible to unload a package and all of its loaded components should there be a problem. If a package crashes it tries to automatically restart itself several times.

Do not use Transaction Server with FoxISAPI if you're after the following:

Scalabilty
FoxISAPI already includes a built in pool manager which provides much more scalability and customizability than MTS does.
MTS cannot pool COM objects – it can only deactivate and reactivate multiple connections to a COM object providing seamless, continuous persistence to the client. This can be useful for client server applications but is not so useful for Web apps which usually have only a few COM clients driven by a server side application. MTS 2.0 provides no true pool management services yet, although the interfaces for it are in place. I suppose this might be in the next MTS release (NT 5.0 probably).

Speed
MTS is an extra layer on top of COM, so it's actually slower than calling objects directly. MTS sets up a proxy between the client and the actual object and the overhead of proxy to object communication actually cause some overhead. Overhead is not a killer, but it's not worth it unless you have a need for MTS.

Ease of Development
MTS is what I consider production technology in that it's not easily worked with in a development environment. Everytime you rebuild your COM object you need to reinstall it in MTS which is not a two click process…

If you get the idea, that I'm not a fan of MTS you're right – too much hype with not enough of the key features implemented yet. However, there are legitimate uses for MTS and I'm sure it will live up to its promise in the future when pool management is supported. If you need the features from the first list of items here's how you can integrate them into FoxISAPI.

Remember, earlier on I mentioned it was a good to have a central entry point method? Well, here's another good reason why this is useful. You can use this entry point method to handle the initialization and cleanup for every request as it relates to MTS. To do this correctly we need to do the following:

Add the following properties to the server:

*** MTS methods
lUseMTS = .T.
oMTS = .NULL.
oMTSContext = .NULL.
lMTSCompleted = .F.

lUseMTS is a global flag that determines whether MTS functions should be accessed. oMTS is the MTS COM master object to which you need a reference in order to access any of the Context object methods. In the Init add:

IF THIS.lUseMTS
   THIS.oMTS = CREATE("MTXaS.Appserver.1")
ENDIF

We can load it in the Init of the class, then update the oMTSContext object on every hit in the Process method. At the very top add:

IF THIS.lUseMTS
   THIS.oMTSContext = THIS.oMTS.GetObjectContext()
   THIS.lMTSCompleted = .F.
ENDIF

and just prior to the RETURN.

IF THIS.lUseMTS AND !THIS.lMTSCompleted
   THIS.oMTSContext.SetAbort()
ENDIF

This basically implements automatic transactions. Note that the lMTSCompleted property is checked to see whether we want to automatically abort the current transaction. The idea here is that you should manually Complete transactions as necessary. For example:

FUNCTION MTSTransaction
o=CREATE("wwSQL","DSN=MYSQL;UID=sa;PWD=")
o2=CREATE("wwSQL",DSN=OTHERSQL;UID=sa;PWD=")

IF !THIS.oMTSContext.IsCallerInRole("Manager")
   THIS.ErrorMsg("Access Denied",;
                 "You don't have access to this function")
   RETURN
ENDIF

o.Execute("INSERT CUSTOMER (company, name) values ;
         ('West Wind','Rick Strahl')")
IF !o.lError
   o2.Execute("INSERT orders (custno, total) values ;
             ('   10',120.00)")
ENDIF

*** If there was an error in either transaction - Abort
IF o.lError or o2.lError
    THIS.oMTSContext.SetAbort()
    THIS.StandardPage("Order not Updated.",;
                       o.cErrorMsg + CR + o2.cErrorMsg)
ELSE
    THIS.oMTSContext.SetComplete()
    THIS.StandardPage("Order Updated")

ENDIF

THIS.lMTSComplete = .T.

ENDFUNC

This example runs a transaction that updates two distinct servers and treats the entire transaction as one atomic unit. If any of the two fail SetAbort() is called to undo the transaction.

To test MTS you don't need to use this complex type of setup, but this is one of the few things MTS does really well. To see MTS work, you can just wrap your requests in SetComplete() calls even if no transactions are required.

The call to SetComplete or SetAbort tells MTS that the object can submit any outstanding transactions. But it also tells MTS that it can recycle this object – you don't have any state to maintain so MTS can unload it and recycle the resources. The object unloads after the call completes. Next time a call comes in MTS reloads the object. Since your client application (foxisapi) only holds a pointer to the proxy not the real object it thinks the client was there all along and is none the wiser that the object has unloaded. However, be aware there's serious overhead with this approach as the server has to be reloaded. The Init of the server refires whenever the server is reloaded.

Note the use of the oMTSComplete flag to tell the Process() method code that the appropriate Transaction method has been called already. Note that on the security check above no call to SetAbort() is necessary – the Process() method will pick it up and do it for me.

Installing the object in MTS

Go to the project manager, Project Options|Servers and make sure to set the server to MultiUse. Note this is different from the SingleUse EXE I recommended before. Always build DLLs MultiUse and EXE as SingleUse and don't forget this when you switch between the two!
Build the server into a COM DLL. Note the Prog Id: FirstServer.TfirstServer.
Start up the Microsoft Management Console
Go to the Transaction Server Tree|MyComputer|Packages and create an empty package.
Add your component as new component from file. When asked for files add your DLL and the corresponding TLB file. You can add multiple COM objects at once as long as you specify both the DLL and the TLB files.
After the component is all installed right click and select Properties. Bring up the Transactions tab and set it to 'Supports Transactions'. If you want to force transactions at all times choose 'Requires Transactions' – it shouldn't matter much as Process() will automatically force the transactions through.
Remember once installed you can't rebuild the server without reapplying these steps to reconfigure the server!

You're now ready to run the server through MTS. That's the easy part. Just hit any of the previous requests and you should see something like this in the MTS Explorer…

Note, that the object is running two instances (FoxISAPI.ini is set to run multiple instances in the pool), and that none are activated. What this means is that I hit a request that called SetComplete/SetAbort and let MTS unload the server behind the scenes. If I don't call SetComlete/SetAbort the Activated count would show 2 as well. In fact, any call that goes through the Process method will deactivate objects when lUseMTS is .T. I lUseMTS is not set .t. the server runs without transactions and all server stay activated. You also loose any benefit of MTS altogether…

FoxISAPI Debug Mode

To make it easier to debug your Automation Servers the latest version of FoxISAPI also adds a debug mode. When running in Debug mode FoxISAPI loads the Visual FoxPro development environment as an Automation Server rather than your actual server. The VisualFoxPro.Application object is created and is called with syntax equivalent to this:

oServer=CREATEOBHECT("VisualFoxPro.Application")
oServer.EVAL(oDebug("Server.Class.Method(‘lcFormVars’,’lcIni’,0)")

This causes Visual FoxPro to pop up and call a program file called oDebug. oDebug is a .PRG file that you have to create to respond to this request, and it must be located in your global Visual FoxPro path as set in the Tools|Setting options (most likely your VFP startup path or your Utils directory).

Once oDebug has control it needs to go ahead and parse the parameter passed, which contains the full server string, plus the three standard FoxISAPI parameters. Once the class and method have been parsed you can then create an instance of the class as a VFP object (rather than an Automation object) and then use EVAL() to invoke the method with the parameter returned. The code to do this looks something like thus:

LPARAMETER lcParameter

*** lcParameter = full OLE server string
*** FirstServer.TfirstServer.Process('Method=TestUser=Id1&Name=Rick',

                                     'fox.ini',0)


*** Make VFP Visible
_SCREEN.visible=.T.

SET PATH TO c:\wwapps\wc2\classes; c:\wwapps\common; c:\utilprg

set default to c:\wwapps\foxisapi

SET PROCEDURE TO WWFOXISAPI ADDITIVE
SET PROCEDURE TO FIRSTSERVER ADDITIVE

*** Load Web Connection classes for use in FoxISAPI sample
DO WCONNECT

lnDot2=AT(".",lcParameter,2)
lnBracket=AT("(",lcParameter)

lcParms=EXTRACT(lcParameter,"(",")")
lcClass=EXTRACT(lcParameter,".",".")
lcMethod=SUBSTR(lcParameter,lnDot2 +1, lnBracket - lnDot2 -1)

oServer=CREATE(lcClass)

*** Set the breakpoint here or in your actual code
set step on

*** Now eval the server string
RETURN EVAL("oServer."+lcMethod+"("+lcParms+")")

Notice that you need to explicitly set up your environment here, because VFP starts in your System directory. So, as with any Automation application you need to set your path and set your default. Also, you need to load any class libraries that normally would be built into your project, because you're now calling your server class as a standard VFP class. Hence the SET PROCEDURE TO and the call to WCONNECT.PRG which loads my application framework classes into memory.

Once this code gets control, though, VFP is in full development environment mode. You can SET STEP ON to bring up the debugger and press CTRL-F2 to bring up a command window. Off you go to debug your server interactively.