Locating and Addressing Scripts

As we saw in the FoxWeb Overview topic, there are two types of content served by Web servers: Static content and dynamic content. Static content is stored in files and is directly served by the Web server. The majority of the content viewed on the Internet is static content. Dynamic content on the other hand, is not predetermined, but is rather created on the fly (dynamically) by a program that is called by the Web server. Content generated by FoxWeb scripts is dynamic.

Most Web applications use a combination of static and dynamic content. In general, most text content is generated dynamically by the application, while graphics and other static content is stored in files in the server's Web tree.

Static Content

Files containing static content are stored in the Web server's Web tree. The Web tree is defined as the Web server's root directory and all its subdirectories, plus all virtual directories set up in the server's configuration program. For example, the default root directory of Microsoft Internet Information Server (IIS) and Microsoft Personal Web Server (PWS) is c:\inetpub\wwwroot\. In order for a static file to be accessible over the Web, it must be in the root directory or one of its subdirectories. The exception to this rule is virtual directories, which are directories outside the Web root, mapped in the Web server's configuration, so that they appear to be in the Web tree. For a description of the Web root and virtual directories, as it pertains to your own Web server, consult your server's documentation.

FoxWeb Scripts

The dynamic content returned by FoxWeb applications is generated by FoxWeb scripts. Depending on how you have configured FoxWeb, script files are either located in the FoxWeb program tree, or in the Web tree. The FoxWeb Program Tree is comprised by the Program Root -- configured in the FoxWeb Control Center -- and all its subdirectories.

By default, FoxWeb is set up not to look for scripts in the Web tree, but rather to look for them in the FoxWeb Program Tree. The setting that determines this behavior is the Use Web Server's Directory Mappings check box in the FoxWeb Control Center. If this setting is disabled then FoxWeb looks for scripts in the FoxWeb Program Tree. If on the other hand the setting is enabled and the URL utilizes script mapping, then FoxWeb looks for scripts in the Web tree.

There are pros and cons for storing FoxWeb scripts in the Web tree. The main problem, and the reason why this is not the default setting, is that files located in the Web tree can be downloaded over the Web. This means that, unless you configure your Web server properly, files used by your application, such as databases, and programs, will be exposed to the Internet. On the other hand, storing scripts in the Web tree along with static files keeps the file structure more organized and makes it easier to move your applications to another location or another server.

Storing Scripts Outside the Web Tree

This is the default configuration of FoxWeb. With this configuration all scripts are stored in the Program Root and its subdirectories. Since the FoxWeb Program Tree is outside the Web tree, there is no danger that your data or other files used by your application would get downloaded by prying users. This same fact, however, means that you need to store all static files, used by your application, in the Web tree, separately from the rest of your files. The FoxWeb Program Root directory is configured in the Virtual Servers page of the FoxWeb Control Center. Note that if FoxWeb is configured to serve multiple host names (virtual roots), then each host can have its own Program Root. If you do not specify a program root for a particular server, then its program root defaults to the Default Program Root directory.

Storing Scripts in the Web Tree

This method should be used in conjunction with the Use Web Server's Mappings setting, and with Script Mapped URLs. If you chose to configure your server in this manner, then FoxWeb uses the PATH_TRANSLATED Server Variable to determine where to look for your scripts. There is no danger that users would be able to download your FWX files, because they would normally be mapped to foxweb.exe or foxweb.dll, but other files used by your application, such as data files, PRG and FXP files, will be exposed via your server, unless you protect them somehow. If you wish you can store your data files in a directory outside your Web tree and write your programs so that they include fully qualified paths in USE, SELECT, and other data access commands. Another solution is to configure your Web server, so that it does not allow the direct retrieval of files that should not be downloaded. If your Web server does not support the ability to prevent retrieval, based on file extension, you can also map the extensions of these files to a program that simply returns an error message. The FoxWeb setup program installs the file deny.exe, which can be used for this purpose. With the proper configuration you can be sure that your server will be equally secure no matter where you chose to store your script files.

The FoxWeb ISAPI and CGI Modules

FoxWeb channels are written in VFP in order to take advantage of Visual FoxPro's super fast data access engine, and to maintain 100% compatibility with the FoxPro language. Because of the significant overhead of VFP, it is impractical to open a new channel with every hit. Instead, channels are initialized when FoxWeb is started, and quitely sit in the background waiting for user requests. In order to connect to these channels, the Web server has to first call one of the two FoxWeb stub programs -- the ISAPI module (foxweb.dll), or the CGI module (foxweb.exe). These programs are designed to be extremely efficient and light, simply acting as a middle layer between the Web server and the resident FoxWeb channels. The ISAPI module runs an in-process DLL, so it is more efficient than the CGI module, which has to load as a separate process for each hit. For Web servers that support the ISAPI interface, such as Microsoft Internet Information Server (IIS) and Microsoft Personal Web Server (PWS), it is recommended that you use the ISAPI module. The CGI module, on the other hand, will work with virtually any Web server, so you should use it in environments where ISAPI is not supported.

The FoxWeb setup program asks for the location of the CGI directory and installs both foxweb.exe and foxweb.dll in that location. Most Web servers create a default CGI directory when they are installed. For example, in the default configuration IIS and PWS the directory c:\inetpub\scripts is set up as a CGI directory. You will need to consult your server's documentation for the location of the default CGI directory, and for instructions on how to define CGI directories yourself.

Once FoxWeb is installed properly, the Web server passes all requests for FoxWeb scripts to either foxweb.exe or foxweb.dll, which in turn transfer the information to the next free FoxWeb channel. There are two ways that you can instruct the server to call a FoxWeb program:

Calling the FoxWeb Stub Program Directly

With this method you simply pass the name of the FoxWeb stub program in the URL followed by the path and name of the script you wish to run: http://ServerName/scripts/foxweb.exe/samples/MyScript.fwx. After the Web server receives this URL it will run the program foxweb.exe in the scripts directory, and pass the string "/samples/MyScript" to it in the PATH_INFO server variable. FoxWeb parses this variable to determine which script to run. Note that the FWX extension is not necessary when calling the FoxWeb stub program directly.

Using a Script Mappings

Most Web servers support a feature called Script Mapping, which allows administrators to associate a particular file extension with a program. FoxWeb allows the mapping of the FWX extension with one of the two stub programs (foxweb.exe or foxweb.dll). If the server is configured to script map the FWX extension, then the URL http://ServerName/samples/MyScript.fwx is equivalent to the one in the previous paragraph. When the Web server encounters the FWX extension, it knows that it is supposed to pass the request on to FoxWeb, which executes the requested script. This method allows URLs to be much shorter and easier to read.

Note: You must use script mapped URLs in order to store your scripts in the Web tree with the "Use Web Server's Directory Mappings" setting.

Calling Scripts and Static Files From a Browser

As we saw in the FoxWeb Overview topic, in order to request a resource such as an HTML file from a Web server a user needs to enter a URL in the browser's Location field. A URL specifies the location of a target such as a file, directory, HTML page, image, program, and so on, stored on a local or networked computer. The general format of a URL is:

Syntax:

scheme://server/path/resource

Definitions:

URLs can be either fully qualified, absolute, or relative, based on which of the above qualifiers they include. A fully qualified URL includes the scheme and server names, as opposed to absolute and relative URLs, which include only a path and the resource name. Absolute and relative URLs can only exist in links included in content returned by a resource on a server and are always taken in the context of the fully qualified URL that was used to retrieve that resource. When requesting a file or script from a Web browser, users must enter a fully qualified URL. Note that modern browsers do not require user to enter the scheme portion of the URL. If the scheme is missing then most browsers try to retrieve the requested resource via HTTP. We will examine absolute and relative URLs later in this topic.

Calling Static Files

You probably already have some experience calling static files from a Web server. To call the file example.htm from the subdirectory chapter1 of the server's root directory, you would use the URL:

http://server/chapter1/example.htm

Calling FoxWeb Scripts

The URL syntax for calling a FoxWeb script follows the same general rules that URLs for static files follow, but the exact form depends on a number of factors:

• Whether script mapping is being used
• Whether you are using the CGI or the ISAPI module
• Whether "Use Web Server's Directory Mappings" is enabled

The full syntax of URLs that call FoxWeb scripts is as follows:

Syntax:

http://server[/CGIPath/StubModule]/ScriptPath/[ProcName@]ScriptName[?QueryString]

Definitions:

Examples

The following examples illustrate URLs that call FoxWeb scripts in a number of different situations:

Example 1a

This example assumes the following server configuration:

Server Name:	www.foxweb.com
Web Root:	c:\inetpub\wwwroot\
CGI/ISAPI directory:	c:\inetpub\scripts
CGI/ISAPI path:	/scripts
FoxWeb Program Root:	c:\Program Files\FoxWeb\Programs
"Use Web Server's Directory Mappings" setting:	Disabled
Script Mapping:	Not used

Following are URLs that can be used to call various scripts on the above server:

http://www.foxweb.com/scripts/foxweb.dll/MyApp.fwx
This URL calls the program c:\Program Files\FoxWeb\Programs\MyApp.fwx, using the ISAPI module.

http://www.foxweb.com/scripts/foxweb.exe/ContactMine/search@contact.fwx
This URL calls the procedure search in the program c:\Program Files\FoxWeb\Programs\ContactMine\contact.fwx, using the CGI module.

Example 1b

This example illustrates the use of script mappings and assumes the following server configuration:

Server Name:	www.foxweb.com
Web Root:	c:\inetpub\wwwroot\
FoxWeb Program Root:	c:\Program Files\FoxWeb\Programs
"Use Web Server's Directory Mappings" setting:	Disabled
Script Mapping:	The extension .fwx is mapped to the ISAPI module, foxweb.dll

Following are URLs that can be used to call various scripts on the above server. Note how the URL strings are shorter and simpler than the ones in example 1:

http://www.foxweb.com/MyApp.fwx
This URL calls the program c:\Program Files\FoxWeb\Programs\MyApp.fwx.

http://www.foxweb.com/ContactMine/search@contact.fwx
This URL calls the procedure search in the program c:\Program Files\FoxWeb\Programs\ContactMine\contact.fwx.

http://www.foxweb.com/c:/OtherScripts/SomeScript.fwx
This URL calls the program c:\OtherScripts\SomeScript.fwx, which is outside the FoxWeb Program Tree. Note that in order for this URL to work, you must enable the "Full Paths in URLs" option.

Example 1c

This example illustrates use of FoxWeb with the "Use Web Server's Directory Mappings" setting enabled. Note that you must always use script mappings in conjunction with this setting:

Server Name:	www.foxweb.com
Web Root:	c:\inetpub\wwwroot\
FoxWeb Program Root:	Since "Use Web Server's Directory Mappings" is enabled, this setting is only used to locate global procedures.
"Use Web Server's Directory Mappings" setting:	Enabled
Script Mapping:	The extension .fwx is mapped to the ISAPI module, foxweb.dll

Following are URLs that can be used to call various scripts on a server with the above configuration:

http://www.foxweb.com/MyApp.fwx
This URL calls the program c:\inetpub\wwwroot\MyApp.fwx.

http://www.foxweb.com/ContactMine/search@contact.fwx
This URL calls the procedure search in the program c:\inetpub\wwwroot\ContactMine\contact.fwx.

Fully Qualified URLs

This is the complete format of the URL as described earlier in this topic. It is in the form scheme://server/path/resource, so it includes all the information needed to fully resolve an address. It does not inherit any information from the context it is contained in.

You should use relative URLs in the following situations:

• When you need to link to a resource on another server.
• When you need to change the scheme (for example from http to https).
• When you must specify the server, regardless of the fact that the resource being linked to is currently on the same server as the one that contains the link. An example of this, is a situation where you expect to move the resource that contains the URL to a different server, without moving the resource that the URL points to.

Absolute URLs

This type of URL must be taken in the context of the fully qualified URL that was used to retrieve the resource it is contained in. Absolute URLs inherit the server name but not the path. They are in the form /path/resource and their distinguishing characteristic is that they start with a forward slash. The path in absolute URLs is relative to the root directory (either the Web root or the FoxWeb Program Root, depending on the situation) of the server.

For example, assuming that the user calls a FoxWeb script with the URL http://www.foxweb.com/billing/main.fwx, which returns HTML output containing the following tag: <img src="/images/bullet.gif">, the browser interprets this absolute URL in the context of the fully qualified original URL, and requests the resource: http://www.foxweb.com/images/bullet.gif.

You should use relative URLs in the following situations:

• When you need to link to a resource on the same server, but in a path that is unrelated to the current path.
• When you don't use script mapping to call FoxWeb scripts, and the content returned by your scripts contains links to static files. Using a relative URL in this case would cause FoxWeb to attempt to run the static file, which is obviously not the intention here.

Relative URLs

Like absolute URLs, relative URLs must be taken in the context a fully qualified URL. The syntax of relative URLs is path/resource, which is different from that of absolute URLs in the fact that it does not start with a slash. Relative URLs inherit both the server name and the path from the URL that is setting the current context.

For example, assuming that the user calls a FoxWeb script with the URL http://www.foxweb.com/billing/main.fwx, which returns HTML output containing the following tag: <a href="util/logout.fwx">Logout<a>, the browser interprets this relative URL in the context of the fully qualified original URL, and requests the resource: http://www.foxweb.com/billing/util/logout.fwx. You can specify the parent directory by starting the URL with two dots. Assuring the same full URL, the link <a href="../main.htm">Home<a> would be interpreted as http://www.foxweb.com/main.htm.

Relative URLs are very convenient, because they maintain portability of the code and are very easy to construct. You should use them in the following situations:

• When the resource you are linking to is in the same path as the one that returned the URL. This is usually the case when scripts call other scripts in the same application.
• When you are linking to a resource in path that is related to the one that returned the URL. For example, if all the images for a particular application are in a subdirectory called images, you should use relative URLs, because in most likelihood if you move the application, the images will be moved with it.

Examples

The following examples illustrate the use of links in FoxWeb scripts:

Example 2a

This example illustrates the simplest possible situation, in which both scripts and static files are in the same directory. This is achieved by enabling the "Use Web Server's Directory Mappings" setting, and placing scripts in the Web root. In this particular case, all files are located in the directory c:\inetpub\wwwroot\jobs, which can be accessed with the fully qualified URL http://www.foxweb.com/jobs/. This directory contains the scripts menu.fwx and search.fwx, as well as the static file default.htm. Images are contained in the subdirectory c:\inetpub\wwwroot\jobs\images. The following output is returned by the script menu.fwx:

<html> <head><title>Menu</title></head> <body> <img src="images/MenuTitle.gif"> <ul> <li><a href="default.htm">Home</a></li> <li><a href="search.fwx">Search for Jobs</a></li> <li><a href="http://www.jobsmart.com/">Other Resources</a></li> </ul> </body> </html>

As you can see, all links included in the above code are relative, except the last link, which points to a resource on another server.

Example 2b

This example is very similar to the preceding example, with some important distinctions: In this case, scripts and static files are not in the same directory. The "Use Web Server's Directory Mappings" setting is disabled, which means that scripts reside in the FoxWeb program tree, as opposed to static files, which are always stored in the Web tree. In order to retain the convenience of relative paths, the server is configured so that the absolute path to FoxWeb scripts is exactly the same as the absolute path to the static files they are associated with. For the purposes of this example the FoxWeb Program Root is c:\Program Files\FoxWeb\Programs and the Web root is c:\inetpub\wwwroot. Our application's script files are located in c:\Program Files\FoxWeb\Programs\jobs, while its static HTML files are located in c:\inetpub\wwwroot\jobs. Images are located in c:\inetpub\wwwroot\jobs\images.

As you can see, the absolute paths, needed to call both our scripts and static files, are identical and equal to "/jobs". The reason for this is that, with "Use Web Server's Directory Mappings" disabled, FoxWeb uses the FoxWeb Program Root as the root directory, while the Web server will use the Web root.

Just like in example 2a, the various static files and scripts in our application can use relative links to call each other, even though in this case they are in different directories. The output of menu.fwx can be identical to the one in example 2a.

Example 2c

In this example our Web server and FoxWeb are configured with the same directory structure as in example 2b, but unlike 2b, in this case our Web server does not support script mapping. To call our scripts we need to directly reference the CGI (or ISAPI) stub program in the URL. To call menu.fwx, for example, we must use the URL http://www.foxweb.com/scripts/foxweb.exe/jobs/menu.fwx.

As you can see, the absolute path to our application's static files is different than that pointing to our application's scripts. For this reason, we must use absolute paths to cross-reference scripts and static files. We can keep using relative paths to reference scripts from other scripts, and static files from other static files.

The following is some sample content that could be returned by the static file default.htm:

<html> <head><title>Home</title></head> <body> <img src="images/MenuTitle.gif"> <h1>Welcome!</h1> <p>If this is your first visit please read our <a href="intro.htm">Introductory Information</a>, otherwise proceed to the <a href="/scripts/foxweb.exe/jobs/menu.fwx">Main Menu</a></p>. </body> </html>

The above content is returned by a static file, so it uses relative URLs to point to other static files, and absolute URLs to point to scripts. Scripts, on the other hand, must use the opposite approach. The following is content generated by the script menu.fwx:

<html> <head><title>Menu</title></head> <body> <img src="/jobs/images/MenuTitle.gif"> <ul> <li><a href="/jobs/default.htm">Home</a></li> <li><a href="search.fwx">Search for Jobs</a></li> <li><a href="http://www.jobsmart.com/">Other Resources</a></li> </ul> </body> </html>