Configuring FoxWeb

FoxWeb is configured from the FoxWeb Control Center, which can be started by clicking in the corresponding icon in the Start menu. The FoxWeb Control Center can also be started by running the program fwconfig.exe in the FoxWeb directory.

The Configuration page


The Configuration screen in the FoxWeb Control Center.

VFP.EXE
Select the full path to VFP.EXE (including the file name), by clicking on the button on the right of this field. This setting is required, unless you are using the VFP run-time DLL.

Error Template
Select a FoxWeb script, which can be used to return script errors to users, by clicking on the button on the right of this field. This setting is optional. If no script is specified then FoxWeb will use its default template. The template must be a valid FWX or PRG file. The file ErrHandler.fwx in the FoxWeb directory is supplied as an example. The commented text at the top of the file contains instructions on how to modify it or create your own templates from scratch.

Temp. Directory
This location is used by FoxWeb to store some of its internal data, such as session information. You should point this entry to a location where both the FoxWeb Service and the CGI/ISAPI modules have read/write privileges.

Script Timeout
The amount of time in seconds that the server waits for a user program to finish before returning an error message. This should be higher than the time it takes for your slowest program to execute under busy conditions. If a channel is busy for longer than this setting and
Restart Channels is enabled, then the FoxWeb Channel Monitor will attempt to restart the channel.

Session Timeout
This setting specifies the default timeout period in minutes of user sessions. If the user does not request a script within the timeout period, the session ends and all session variables are destroyed. The setting can be overridden for a particular session, by changing the
Session.Timeout property.

Total Channels
This setting determines the number of channels that will stay resident waiting to serve incoming requests for FoxWeb scripts. Each channel is actually separate instance of the VFP portion of FoxWeb (fwserver.exe) and can only serve a single script at any one time. Multiple channels allow you to serve requests simultaneously. Channels are created as soon as FoxWeb is started and remain active, continuously serving new requests as they arrive. Incoming requests are routed to a free channel if one is available at the time. If a channel is not available the request is placed in a queue and is served as soon as a channel is freed up.

Please note that the total number of channels does not have to match the total number of users, or even the maximum number of requests that could potentially arrive at the same time. If you are running too many channels then you may be hurting performance. The total Buffer Mem. Size specified in the configuration page is divided between open channels, so if you have too many open channels, each one will have less Buffer Memory available for queries and other data-access operations. For example, if your total Buffer Mem. Size is set to 500 MB and you are running 5 channels, each channel will have 100 MB available to it. If on the other hand you decide to run 15 channels, each channel will only be allocated about 33 MB. In addition to Buffer Memory, channels also have to share your server's CPU's. Running more channels on a single CPU does not guarantee faster performance, even given the same amount of memory allocated to each channel. If 15 requests arrive at exactly the same time, it is quite possible that the overall time of response will be better if you are running 5 channels than if you are running 15. In the first case requests will be queued and run serially, with only 5 of them being served at a time, but each request may take less time to run, which could translate to a faster overall performance.

The optimum number of channels depends on a lot of factors, including what your programs do, the operating system, the server hardware, the amount of memory, the web server software, etc. With later versions of FoxWeb, a rule of thumb is to run 3-6 channels per processor, but this may vary widely from system to system. The best way to determine how many channels give you the optimum performance is to experiment on the actual server environment.

Buffer Mem. Size
The maximum buffer memory pool shared by FoxWeb channels in megabytes. This setting makes it possible to optimize FoxWeb performance in data access operations, by adjusting the amount of memory VFP allocates for its buffers. This setting is related to VFP's SYS(3050), but is in megabytes instead of bytes and applies to both foreground and background mode. The Buffer Mem. Size setting is divided equally between the total number of channels specified in the
Total Channels setting. For example, if your Buffer Mem. Size is set to 500 MB and you are running 5 channels, each channel will have up to 100 MB available to it.

Admin User ID
Enter a user id to be used in conjunction with the internal
fwAdmin script, as well as the Auth.AdminAuthenticate method.

Admin Password
Enter a password to be used in conjunction with the internal
fwAdmin script, as well as the Auth.AdminAuthenticate method.

Enforce SSL in fwAdmin
This option determines whether FoxWeb will require the use of Secure Sockets Layer (SSL) to allow access to
fwAdmin.fwx. SSL encrypts request data, such as passwords, so that they don't get intercepted between the browser and the web server. In order to use SSL your web server must be equipped with an SSL key. For information on how to use SSL with your web server please consult your server's documentation.

Enabled fwAdmin Functions
This set of checkboxes can be used to limit the functions that are available in
fwAdmin.fwx.

Hide Windows
If this value is checked then FoxWeb channel windows are hidden. If you would like to show the channel windows while FoxWeb is running, click on the "Hide Windows" option of the menu that pops up when you right-click on the FoxWeb tray icon. Channel windows can not be visible if FoxWeb is running as a system service.

Close Tables
If this entry is checked (recommended) FoxWeb closes all open databases after execution of user programs. If this option is disabled, user programs will have to check whether a table has already been opened by a previous program before deciding whether to open it or select it. This option can be disabled in situations involving extremely large table/index files, in which there would be a performance hit if tables were opened and closed every time.

Use Run-Time DLL
Even though FoxWeb user programs must be compiled with Visual FoxPro, the web server does not necessarily need to have a license of VFP installed on it. If you already own a license of VFP and do not wish to purchase another one for the server, you may elect to run FoxWeb with the VFP run-time library. The FoxWeb setup program automatically installs the VFP 9 run-time DLL files, but if you want to use a different version of VFP you will need to manually install the corresponding run-time DLL files.

Note that scripts are not always compiled automatically if you choose to use the run-time DLL. Fortunately, starting with version 3, FoxWeb provides alternate methods of compiling scripts directly on the Web server by using the internal fwAdmin script (at least if you are using VFP 6 SP3 and above). For details please refer to the documentation of fwAdmin.

Log Script Errors
This setting specifies whether FoxWeb will log run-time script errors in the
FoxWeb Error Log.

1.x Compatibility
This setting specifies whether FoxWeb will populate the properties of the CGI object, as well as the cgi_fields array, which are necessary for compatibility with FoxWeb 1.x scripts. Disabling this setting may marginally improve the performance of your server.

Note: You can selectively use the 1.x API by disabling this option and calling the CGI.InitVars method at the beginning of the programs that require it.

Restart Channels
If this value is checked then FoxWeb will restart closed channels and channels that have been unresponsive for longer that the
Script Timeout period. This option is also available on the menu that pops up when you right-click on the FoxWeb tray icon.

Run as Service
This option determines whether FoxWeb will run as a
system service. It is not available on servers running Windows 95/98/Millennium.

Buffer Output
The Buffer Output setting specifies whether script output will be
buffered. When script output is buffered, the server does not send a response to the client until the current scripts has been processed. The setting can be overridden for the currently executing script, by changing the value of the Response.Buffer property.

Session Support
The Session Support setting enables or disables session state. When session state is enabled, FoxWeb creates a session for each user who accesses a script so that so that the application can identify the user across its pages. When session support is disabled, FoxWeb does not track users and does not allow scripts to store information in the
Session object. The Auth object utilizes session variables, so it requires that session support is enabled. Disabling this setting may marginally improve the performance of your server.

Note: You can selectively turn on session support in certain programs by disabling this option and calling the Session.InitVars method at the beginning of the programs that require it. The InitVars method sends a cookie to the browser, so if you are not buffering script output you must call it before you send any content to the browser.

Full Paths in URLs
Use this checkbox to specify whether FoxWeb will allow fully specified paths to be included in URLs.
Warning: Enabling this setting may open security holes in your site, so make sure to read the
Securing your Server topic before doing so.

Keep PRG Files
The Keep PRG Files setting determines whether FoxWeb will keep or delete temporary PRG files, generated from FWX files. These PRG files are useless for normal operation, because FoxWeb directly executes the compiled FXP files. You must enable this checkbox if you plan on
tracing through your programs.

Reset After Errors
The Reset After Errors setting determines whether FoxWeb resets channels after a script error occurs. Resetting a channel ensures that any corruption to its environment is corrected, but also has the adverse effect of interrupting any script output being sent back to the browser as a result of previously executed requests on the same channel. FoxWeb 3 introduced a new algorithm, favoring channels that are completely free, over channels that are finished with request execution, but are still in the process of sending output to the browser. As a result, the chance of script output being disrupted by a script error is extremely low, regardless of how "Reset After Errors" is configured. You may want to disable this setting if you notice "FoxWeb Channel Stopped Responding" errors. Such errors will only occur if your scripts return large amounts of data to the browser, you are running a relatively low number of channels, and your users have slow Internet connections.

The Virtual Hosts Page


The Virtual Hosts screen in the FoxWeb Control Center.

Use Web Server's Directory Mappings
This setting determines whether FoxWeb will look for scripts in the FoxWeb
Program Root, or in the Web tree along with static files. For a discussion of this setting refer to the Locating and Addressing Scripts topic.

Default Program Root
In this space you should enter the full path to the default root directory of your FoxWeb user programs. If a particular virtual host does not override this setting with a
host-specific Program Root, then the location specified in this setting will be the effective program root for that particular server. The functionality of the Program Root setting varies, depending on the setting of the Use Web Server's Directory Mappings checkbox. If Use Web Server's Directory Mappings is disabled, then this setting does what its name implies -- it acts as the root directory for FoxWeb script files. If on the other hand Use Web Server's Directory Mappings is enabled, then the Program Root directory is simply the location where FoxWeb looks for the global procedures fw_enter and fw_exit.

The Virtual Hosts Grid
In most cases the Virtual Hosts grid will contain a single entry, corresponding to the host name and ip-address of your site, but in the case of multi-homed sites you will need to create a separate entry for each site that will serve FoxWeb scripts. FoxWeb will return an error message if you attempt to call a script on a virtual host that is not included in this grid. The only exception is the special host name "localhost" (ip-address = 127.0.0.1), which can only be used to refer to the local computer. You only need to add localhost to the grid if you wish to specify a program root other than the
Default Program Root. In order to add a virtual host to the grid you must specify its server name and/or its ip-address. The grid holds the following settings for each virtual host entry:

Server Name
The host name of the virtual host. This must match exactly the host name entered in the URL. For example the server name "foxweb.com" only matches the URL http://foxweb.com/ -- it does not match http://server1.foxweb.com/ even if the two are pointing to the same ip-address. The only exception to this rule is that host names starting with "www" also match the corresponding host name without the "www" part. For example, "www.foxweb.com" matches http://www.foxweb.com, as well as http://foxweb.com.

IP-Address
The ip-address of the virtual host. This entry is only necessary if you plan to refer to the server by its ip-address in URLs.

Program Root
If this entry is populated then it will override the
Default Program Root setting as the Program Root for this particular virtual host. If you are only running a single virtual host, then you should leave this setting blank and use the location specified by the Default Program Root.

The PDF page

This page contains configuration options that get used by the fwPDF object.

PS To PDF Printer
The printer that will be used to produce Postscript, or PDF files. Several 3rd-party products can be used for this purpose.

PS To PDF Converter
The application that will be used to convert Postscript files to PDF format. The fwPDF object is able to use the Adobe Acrobat and Ghostscript APIs, but for other products you will need to provide the command line for the conversion application.

PS To PDF Command Line
The command line to be used for the conversion of Postscript files to PDF format if the PS to PDF Converter option is set to 'Command Line'. The command line may contain the following tags, which get substituted by the corresponding values at run time:

%PSFILE%
The full path to the Postscript file to be converted to PDF format.

%PDFFILE%
The full path to the resulting PDF file.

%OPTIONS%
Additional conversion options that can be specified in FoxWeb scripts via the
fwPDF.PS2PDFOptions property.

PS To PDF Command Timeout
Specifies the timeout in seconds, used by FoxWeb during the conversion of Postscript files to PDF format if the PS to PDF Converter option is set to 'Command Line'.

PS To PDF Presets
The name of the Presets option to be used during the conversion of Postscript files to PDF format if the PS to PDF Converter option is set to 'Adobe Acrobat', or 'Ghostscript'. Each product has its own set of default presets options, which are programmed in the drop-down list for this option. Both products allow users to create additional user-defined presets. In order to use user-defined presets, you will need to populate the
fwPDF.PS2PDFPresets property. For details, refer to the documentation of your particular PDF creation software.

Ghostscript DLL
The path to the Ghostscript DLL that gets used for the conversion of Postscript files to PDF format. The name of this DLL file is typically gsdll32.dll.


© Aegis Group