Class wwServer - West Wind Web Connection

Class wwServer

wwServer is your FoxPro application's entry point - when a Web request comes in wwServer is the first point of contct with FoxPro code that starts of the request processing sequence.

wwServer is:

The server application's entry point
A 'server' waiting for requests
Accepts COM or File based requests
A router that routes request to the appropriate wwProcess class

Multiple wwServer Instances

You can run multiple wwServer instances simultaneously in separate processes. In File based operation multiple EXEs can be started, in COM the COM instance pool can be set to load multiple instances.

File based or COM based use the same Server

The server supports both file based and COM based through the same wwServer implementation. In file based messaging the Web server request data is sent via message files that the server picks up and processes and then writes out results to files which are picked up by a timer in the server form. In COM based messaging the Web Server directly instantiates and calls the wwServer instance and Web Connection returns a string based HTTP response as a result.

For your code the mode should have no direct impact other than perhaps permissions and the execution environment in terms of location. Web Connection always sets the server's execution path to the EXE's startup folder.

Startup Sequence and Server Configuration

It's useful to understand how the startup order of events works in Web Connection.

OnInit

The initial server initialization that fires off the server class' Init() operation. Fires once when the server class is instantiated, before Web Connection configures server instance.

This method should not have any code beyond what's auto-generated and is required to run the internal configuration of Web Connection during startup. The default implementation merely points at the startup configuration file (<myApp>.ini) and rarely should have anything else in it.

All application configuration code should go into OnLoad(). This method only fires once when the server starts up

OnInitialized

Still part of the server's Init() sequence during server startup, this method is fired immediately after the Web Connection server has initialized itself and has read configuration values from the application configuration. This method only fires once when the server starts up

Onload

This method is called to initialize the server with your application configuration logic. This method can be used to:

Set the FoxPro Environment for your application
Set paths to find your application dependencies
Load Classes and Class library dependencies
Open persistent SQL connections
Set up any global objects or cache values

Use this method to configure your application's environment to make sure your application can run. Note that this method fires only after the first request is hitting your server which is changed behavior from older (pre-7.x) versions of Web Connection.

This method only fires once, when the first request fires against the server

Process

Fired on every incoming request from the Web Server. This generated method contains the routing logic that routes request to the appropriate wwProcess class that house your Web processing logic. This class contains logic that parses the URL and based on the URL parameters or script extension route the request to the wwProcess class. Typically you don't have to change code in this method unless you manually change your scriptmaps.

This method is fired for every request

ProcessHit

Process() is the application level entry point where application code is written in your server instance, but ProcessHit() is the low level entry point for the application. This is the method that is initially called by COM server calls, or from the timer that fires when files are found in File based processing.

This is an internal method and generally you don't ever override it.

When requests come in, ProcessHit() is the initial entry point for Web Connection. This method gets passed the raw request data from the Web Server. It takes this data and parses it into a wwRequest object that wraps this data and makes it accessible to your application. The method also handles logging, timing, bringing up the UI and last resort error handling, before passing off a valid request to be processed in the Process() from the last section.

Think of OnInit() and OnLoad() as your one time configuration methods. Process() is a static handler for every request that comes into Web Connection. The only method you typically change and add code to is OnLoad() where you configure your application startup environment.

Use OnLoad() for Configuration

The main Web Connection start program contains a small bit of non-class FoxPro code that is used to bootstrap the Web Connection server when running in file mode. It may be tempting to put configuration code there, but you should not put configuration code into the startup code. When running under COM that code is not fired, so if you switch between COM and File based you won't get the same behavior.

Always use .OnLoad() to configure you Web Connection application to ensure that the startup code always runs.

Implementation

When you create a subclass of wwServer you should implement the following methods:

OnInit()
OnLoad()

The code looks something like what's outlined below - this should change very little with a few adjustments for your server environment.

Class Members

Member		Description
	Dispose	The event is called when the server is released it's called explicitly but also from the destroy. If you have any references you've created that might be circular or otherwise need cleaning up it's recommended you override this method and clean up the code.
	OnInit	This method is called at the very beginning of the server's initialization sequence and should make no assumptions about any server state.
	OnInitCompleted	Fired after `OnInit()` after the server has finished initialization, but before `OnLoad()` which fires on the very first hit against the server.
	OnLoad	This event hook is fired exactly once when the first request hits the server.
	AddResource	Allows adding an embeddable resource like an image, CSS or JS file or other file to be stored and then served as a WebResource url of the application. o.AddResource(lcKey,lcContent,lcContentType)
	ErrorMsg	Creates a self contained error page. Used internally to create error pages that occur during startup processing and when an invalid URL is passed to Web Connection. o.ErrorMsg(lcHeader, lcBody, lvHeader, lcStatus)
	GetProcessID	Called by the ISAPI extension to finalize the initialization process. o.GetProcessID(lnInstance)
	LogError	Logs an exception into the error log stored in the database (typically in wwRequestLog in the app folder). o.LogError(loException,lcTitle)
	LogRequest	Used to log request data into the logging database. Called internally to log requests when request logging is enabled and also used to log errors when errors occur. o.LogRequest(lcParameter,lcRemoteAddress, lnSeconds, llError)
	Process	The Process method is the main routing routine for incoming Web Connection requests. This method parses the base parameters/filenames and decides which Process class to call for request processing. o.Process()
	ProcessHit	This is Web Connection's mainline entry routine that is entered by the server. Each of the server mechanisms calls this method first to activate Web Connection and pass forward the Web server request information. o.ProcessHit(lcRequestBuffer,llFile)
	ProcessHit	This is the top level entry point for external COM code calling the Web Connection server that's passing binary (`byte[]`) data for request data and receiving blob data in return. o.ProcessHit(lcRequestBuffer,llFile)
	SendAdminEmail	Sends an admin email to the specified recipients. o.SendAdminEmail(lcTitle, lcMessage, lcRecipients, lcSender, llHtml, llAsync, lcRefErrorMessage)
	ShowServerForm	Loads the server form for display. The server form is a separate object that gets created by this method. Pass an optional parameter of .T. to release an already running form. o.ShowServerForm(llRelease)
	ShutDown	Shuts down the server in File Mode. o.ShutDown()
	Trace	Trace logging method that allows you to write out trace messages to a trace log file. The default file is wcTraceLog.txt and is written to the server's startup folder. o.Trace(lcMessage, lcFileName)
	cAppIniFile	This is the name of the INI file that the application will lookup to read configuration values from. This value is pre-set in the Initialization of the server, prior to accessing SetServerEnvironment. You can modify this value in SetServerEnvironment as needed. The value is then used by ReadConfiguration() to actually read the data from the INI file.
	cAppName	The application's name. This value typically will be the server's class name, which is used in the INI file as the root reference. Note this should be more of an ID type value rather than a descriptive name, although either will work.
	cAppStartPath	This is the application's startup path. This should point to the directory where the server was started in and where wcmain.ini (or your implementation thereof) should reside.
	cCOMReleaseURL	In order to release a WWWC COM object from a visual form the request has to run over HTTP to release the server. When you click on the server's Exit button for example the code actually launches an HTTP session (via wwIPStuff) and then releases the server via this link.
	cErrorMsg	An error message that is sent when an error occurs in the server's error method. This value is valid only when wwServer::lError = .T.
	cLogFile	Determines the filename where requests are logged to when lLogToFile is set to .T. Default file is RequestLog.dbf.
	cOutput	This property receives the HTTP output from your code when operating under COM. The wwProcess class handles assignment of the HTTP output to this property when the wwProcess object is released in its Destroy. For this reason, if you decide to write to this property it must occur outside of the process object.
	cRequestClass	The class that Web Connection creates when to do request processing. Keep in mind that this may vary depending on whether you use ASP or plain Web Connection processing.
	lASPObject	This flag determines whether the component is running under Active Server Pages. If so the server changes its behavior to use a different request class and sets up the appropriate Request and Response objects that map to the ASP objects.
	lComObject	This flag determines whether the server is running under COM based messaging as opposed to file based processing.
	lDebugMode	Determines whether the server is running in DebugMode or 'release mode'. When this flag is set to .T. error handling is disabled and errors stop in code. When .F. errors are handled and managed to various handlers that by default display error messages.
	lError	Error flag set to .T. if a request fails. You can check cErrorMsg to see what error actually occurred.
	lShowDesktopForm	Determines whether Web Connection tries to hide the VFP desktop and runs as a Desktop window application.
	lShowRequestData	Flag that can be passed forward to a wwProcess object to determine whether to show the current request data at the end of the current request. Note that this flag is not automatically respected in wwProcess - it's only used as a 'global' guideline.
	lShowServerForm	Determines whether the server form is displayed on the desktop.
	lShowStatus	Determines whether the server form displays status information.
	lUnattendedComMode	When set causes the COM server to be run in VFP unattended mode (SYS(2335,0)) which prevents any user interface operation from firing. This will prevent accidental file open dialog boxes (which are not trappable) and generate errors for any modal UI operations (like an accidental MessageBox somewhere).
	lUseErrorMethodErrorHandling	Flag that allows you to bypass TRY/CATCH error handling and instead implement your own Error() method on the Process class for error handling.
	lUseRegistryForStartupPath	This property can be set to force Web Connection not to look in the registry for the startup path. This might be useful if you have multiple separate applications that use the same wwServer derived class names as the registry stores the wwServer classname as the registry key.
	nLogFormat	Determines how Web Connection logs requests.
	nPageParseMode	Determines how Web Control Framework Pages are parsed by Web Connection.
	nScriptMode	These modes determine how the ASP style (WCS scripts) scripting files are compiled and executed. This flag affects how Response.ExpandTemplate() works and how generic WCS scripts fired through the wwScriptMaps Process class operate.
	nWebControlFrameworkCompileMode	Determines how pages are run when the WebControlFramework operates. Runs either in compiled mode or in 'always' parse mode.
	oCache	A global wwCache instance that can be used to cache string data. Useful for caching responses for a period of time so it doesn't have to be re-generated.
	oConfig	Object that holds all of the configuration values stored in the YourApp.ini file.
	oResources	A global wwNameValueCollection object that can be used to store 'static' or 'global' values and properties to avoid extending the wwServer instance with new properties.

Requirements

Assembly: wwServer.prg

Multiple wwServer Instances