The wc.ini configuration file

The wc.ini file contains settings that determine the operation of the Web Connection ISAPI interface. The values set in the INI file affect the operation of the low level interface that runs inside of IIS under the security context configured for IIS or the specific IIS Application Pool that hosts the ISAPI DLL.

NOTE:
Note the wc.ini file applies to operation with the ISAPI extension (wc.dll). When operating with the Web Connection IIS Module the configuration file settings are stored in web.config in the root of your Web application.

This file contains several runtime options that are used by the ISAPI DLL to determine how to operate. A typical wc.ini file looks like this:

[wwcgi]
;*** THIS DIRECTORY MUST HAVE READ AND WRITE ACCESS FOR THE
Path=c:\TEMP\

;*** Time to allow request to finish
;*** Process will be terminated after number of secs
;*** specified here.           REQUIRED 
Timeout=50

;*** Specify how often wc.dll polls for 'completion' message
;*** Specify in milliseconds.  REQUIRED FOR FILE BASED
PollTime=100

;*** Max size allowed for the POST buffer. If the post buffer is bigger
*** than this value in bytes the data is not posted. 0 - means no checks.
PostBufferLimit=0

;*** Message File Template (1st 3 letters)
;*** Default is "wc_"          Only needed if using a different template
Template=wc_

;*** Messaging Mechanism  of the DLL:    REQUIRED
;*** File       -   Original Web Connection Logic of 
;                   file based messaging
;*** Automation  -  Use OLE Automation Server Interface
;*** Interactive -  Call up the VFP development environment via Automation
Mechanism=File

; PostMethod   -  URLEncoded or INI   -  Match POSTMETHOD in WCONNECT.H
PostMethod=UrlEncoded

; Determines whether Web Connection DLL uses Impersonation (1) of the
; Web user account (IUSR_ or logged in user) or whether it uses the
; underlying IIS account (0)(SYSTEM/NETWORK SERVICE or Application Pool
; configured value.
; 0 - No Impersonation (default) 1 - Impersonation
Impersonation=0

;*** Account for Admin tasks    REQUIRED FOR ADMIN TASKS
;***       NT User Account   -  The specified user must log in
;***       Any               -  Any logged in user
;***                         -  Blank - no Authentication
AdminAccount=gonzo,ricks,maxhead

;Admin Page that is used for Backlinks from various internal pages
;Use a full server relative Web path!
AdminPage=/wconnect/Admin.asp

;*** You can update an EXE on the fly from the UpdateFile
;*** With File base messaging you can also use StartEXE to start the
;*** ExeFile running
ExeFile=d:\wwapps\wconnect\wcCOMdemo.exe
UpdateFile=c:\temp\wcComdemo.exe
FileStartInstances=0

[Automation Servers]
;*** Severloading - 0 - Normal  1 - Round Robin
ServerLoading=1

;*** KeepAlive  0 - Normal  1 - Force extra COM reference to keep alive
KeepAlive=1

;*** Force users to see message while servers are loading
;*** Set to one if you have problems getting servers loaded
;*** in high volume environments to reduce thread backups
COMLoadLockout=0

ServerObject=0
Server1=wcDemo.wcDemoServer
Server2=wcDemo.wcDemoServer
;Server3=wcDemo.wcDemoServer,WestWindServer2
;Server4=wcDemo.wcDemoServer,WestWindServer2

[Extra Server Variables]
Var1=LOCAL_ADDR
Var2=APPL_MD_PATH
Var3=HTTP_CACHE_CONTROL

[HTML PAGES]
;*** Use these to override DLL messages
DLLStatusHeaderText=
Busy=
NoOutput=
OleError=

Timeout=

;Maintenance=c:\westwind\wconnect\dllerror.htm
Exception=
Maintenance=
NoLoad=

Busy=
NoOutput=
OleError=
Execption=
Maintenance=
NoLoad=
Timeout=
PostBufferSize=

Here's a description of what these values do:

Key	Description
Path	Determines where the DLL sends the server request file that contains the content of a particular request. Typically this will be your system Temp directory
Timeout	Determines how long a request can take before it is timed out and an error page is returned to the Web server. If you plan on requests taking more than 60 seconds each youll need to bump this value up. Default: 60 (seconds)
PollTime	Applies to file based only and determines how often the DLL polls for a return result. Default: 200 (millisecs)
Template	Applies to file based only and determines the 3 letter prefix that is used for the messaging files. Default: WC_
Mechanism	Determines whether file based or Automation based messaging is used. Values are: Automation or File
PostMethod	Determines how the Request data is encoded. Older versions of Web Connection used an INI file newer version pass URLEncoded strings. If using the default of URLEncoded wconnect.h must have #DEFINE POSTDATA .T. Values are: URLEncoded or INI.
Impersonation	Determines under which user context wc.dll executes internal ISAPI requests. 0 (default) No impersonation. wc.dll runs under the underlying IIS account (SYSTEM/NETWORK SERVICE or Application Pool defined user) 1 wc.dll uses user impersonation and runs under the account that is currently logged in. This means IUSR_ for anonymous requests or the specific user if Basic Auth or Windows is applied against the request.
AdminAccount	Allows setting of the Administrative account that is allowed to access the DLLs internal Maintenance functions that can start and stop servers. If an account is specified only that account will be allowed access. If not logged into the Web server a login will be prompted. Values: AccountName The account to check for Account List - Comma delimited list of accounts Any Any account as long as the user is logged in Or leave the key blank to disable account checking.
AdminPage	Full path to the admin page you use. This is used to provide a back link from the various Maintenance functions built into the DLL. Example: c:\http\wconnect\admin.asp.
ExeFile UpdateFile	These two entries allow you to update EXE files online while the server is running. You can set up the EXE file of the server and provide a name for another file that serves as an update file. The Maintain?UpdateExe allows you to upload a file to a server and hot swap server EXEs without stopping the Web service. For file based messaging you need to make sure all servers are shut down first or else the update will fail. You can also use StartEXE to restart a stalled server or to restart after an update. ExeFile=c:\wwapps\wwdemo\wwdemoole.exe UpdateFile=c:\ftp\uploads\wwdemoole.exe
FileStartInstances	This flag allows you to automatically launch Web Connection servers when the Web Connection DLL is first loaded. This key uses the value in ExeFile to determine which EXE to launch. Make sure you test operation of this feature first by using the wc.dll/maintain?StartExe function to load your EXE, since this function returns error information. If FileStartInstances cannot load your servers no indication is given of the failure.
[Automation Servers]	This section of the INI file determines which servers are loaded on requests. Note the ability to access remote servers with the last example. [Automation Servers] Serverloading=0 Server1=wwDemoOle.wwDemoServer Server2=wwDemoOle.wwDemoServer ;Server3=wwDemoOle.wwDemoServer,\\MachineName
ServerLoading	Used only in the Automation Server section this option determines how requests cycle through the loaded servers. 0 -Load Based Server only gets called when the previous one is busy. Typically the first server is worked heaviest and the last server the least. 1 -Round Robin Request always cycle through servers sequentially. All servers are loaded equally.
KeepAlive	This flag allows getting around a DCOM bug that causes COM objects loaded by IIS threads to unload after 8 minutes of idle time. KeepAlive forces an extra reference on the server making COM keep the server locked and making it not unloadable. 0 Normal Servers can unload. Use this if your servers are lightly loaded and run with short requests and you want the system to unload these servers to preserve resources. 1 Keep Alive Keeps an extra COM reference to force servers to stay alive at all times. Servers unload only when IIS unloads or when you use Web Connection's own unload links.
[Extra Server Variables]	Use this section to add additional HTTP Server variables that IIS provides to your incoming Request object. Web Connection provides the most common varialbe - this option allows you to retrieve any additional ones that aren't natively provided. Use Var1, Var2, Var3 etc. keys to specify each of the server vars to add.

Adding Extra Server Variables

Web Connection provides most of IIS Server Variables by default. However it selectively pulls these variables to optimize performance so some server variables may not be available via the native Request.ServerVariables() method. You can easily see what server variables are pulled on each request by using the Show Status button after a request has been fired with Save Request Data checkbox checked. Look Request Data.

However, Web Servers evolve and some servers other than IIS might expose additional server variables that don't get pulled by default. For this instance you can override the default behavior to allow adding any custom HTTP Servervariables explicitly by specifying the Server variable names in the [Extra Server Variables] section of the wc.ini file. To add any server variables not provided use the following syntax:

[Extra Server Variables]
Var1=LOCAL_ADDR
Var2=APPL_MD_PATH

To find out about the server variables IIS exposes see MSDN online.

Custom DLL Error Messages

The Web Connection ISAPI extension can throw several errors internally. By default these errors generate error messages that are displayed as HTML generated to a simple template inside of the DLL. Since these errors never hit the Web Connection Visual FoxPro server, this means you can't change the error message directly. In some instances this may not be appropriate. While errors are rare and usually point to a problem in the Visual FoxPro server code, it's sometimes necessary to provide an error message that is suitable for end users rather than the technical message that the DLL pops up. So, to do this you can provide an override form for each error message via settings inside of wc.ini. The following entries and error messages are available for customization: Ini Entry [HTML PAGES] Conditions:

Exception
An exception occurred during Web Connection processing. This is a wc.dll internal error and should hopefully never occur.
NoOutput
The Web Connection server returned no output to the ISAPI extension. This means your Web Connection VFP code failed to create any output, which should never happen.
Maintenance
Your server is set into Maintenance mode and the HoldRequest flag is set to 1, which doesn't allow requests to reach your VFP server. Use this for maintenance while the server is running. Users will see a message that says the server is in Maintenance mode.
NoLoad
The Web Connection servers couldn't be loaded (Automation only)
Busy
All server instances are busy (Automation only)
OleError
An exception occurred while calling the Automation server.
Timeout
The request has timed out.
PostBufferSize
Displayed when the incoming POST buffer exceeds PostBufferSize key
TransmitFileFailure
Occurs when TransmitFile can't access or process the file to send.
InvalidRequestId
Occurs when the RequestId returned in the returned HTTP header does not match the inbound request Id.

If entries are left blank the default error messages are brought up generated by the DLL. You can assign files to each of these keys that identify the page that you would like to load. Pages are loaded from the specified file - pages should not exceed 16k in size.

[HTML PAGES]
DLLStatusHeaderText=Custom Web Connection Status DLL Text
Exception=C:\westwind\wconnect\error.htm
Maintenance=C:\westwind\wconnect\error.htm
NoLoad=C:\westwind\wconnect\error.htm
Busy=C:\westwind\wconnect\error.htm

Timeout=
PostBufferSize=
TransmitFileFailure=

The special DLLStatusHeaderText key allows you to override the DLL Status page header. The default value you see is Web Connection DLL Status. You can override this header with your own to remove references to Web Connection.

Displaying Error information in custom pages
This mechanism is very low tech, but you can also embed two special %s keys into the page to match the error message that the Web Connection request creates. Embed the %s string into the page and the first encountered will expand to the error header, the second to the error message.

<html> <body> <h1>%s</h1> <hr> The following error occurred: %s </body> </html>

Note that you can hide the first parameter with something like this:

<html> <body>  <h1>A request has timed out on the server</h1> <p> The following error occurred: %s </body> </html>