Future Wave Tech, Inc.

WebX User Guide

Version 1.0

Information in this document is subject to change without notice. The software described in this document is furnished under a license agreement or nondisclosure agreement. No part of this document maybe reproduced, transmitted in any form, or by any means without express written consent of Future Wave Tech, Inc.

© 2000 Future Wave Tech, Inc. All rights reserved.

Future Wave Tech, Inc.

4238 North Arlington Heights Road

Suite 210

Arlington Heights, IL 60004

All companies and their product names are trademarks or registered trademarks of their respective holders.

Table of Contents

1	Introduction to WebX	1-1

1.1	Installation	1-1

1.2	Dependencies	1-1

1.3	Help	1-1

1.4	Sample Applications	1-1

1.5	Technical Support	1-1

2	Sample Application	2-2

2.1	Project Setup	2-2

2.2	Project Notes	2-3

3	WebX Interface	3-4

3.1	Properties	3-4

3.2	Methods	3-8

3.3	Events	3-12

4	CGI Support	4-15

4.1	Standard CGI Environment Variables	4-15

4.2	CGI Environment Variables Extensions	4-16

4.3	CGI Support	4-16

5	Server Side Includes	5-18

5.1	Supported Include Tags	5-18

6	Reference Tables	6-19

6.1	Properties	6-19

6.2	Methods	6-20

6.3	Events	6-20

Index	6-1

Introduction to WebX

WebX is an ActiveX OCX that enables a developer to add a HTTP server to their application. It is designed and complied using Microsoft Visual Basic 6.0 (SP3) and is intended to be used in Visual Basic, Microsoft Access and Visual Basic for Applications environments.

WebX may also be compatible in other environments, but it has been specifically designed or tested for other environments, therefore, technical support will not be provided.

  Installation


Installation

Before installing WebX, please read the README.TXT file included with the setup program. To install WebX follow the instructions during the installation program.

WebX should be installed on a local hard drive.

It is strongly recommended that the option to make a backup is selected during the installation.

If you are going to work through the sample application, copies of the sample applications should be made.

  Dependencies


Dependencies

WebX has the following dependencies:

MSVBVM60.DLL – Version 6.0.8495 or greater

MSWINSCK.OCX – Version 6.0.8169 or greater

WINSOCK.DLL – Version 2.0 or greater of Winsock.

  Help


Help

Help files are installed as part of the WebX distribution and can be found in <drive>:\Program Files\FutureWaveTech\WebX, where <drive> is the local hard drive on which WebX was installed.

  Sample Applications


Sample Applications

Section 2 of this User Guide contains a sample application illustrating how to implement a web server using WebX. Other sample applications are included in the distribution of WebX. Please take the time to work through them.

  Technical Support


Technical Support

Free technical support is only available by e-mail. Send a detailed e-mail describing the issues, questions and source code when applicable to at support@futurewavetech.com.

Premium technical is also available to users of WebX. For questions and pricing please contact sales@futurewavetech.com.

  Sample Application


Sample Application

This chapter will work through the Web Server example included with WebX. If you would like to follow along with this example, the source code can be found in <drive>:\Program Files\FutureWaveTech\WebXSamples\SimpleWebServer, where <drive> is the drive letter that was used during the installation of WebX. The default drive letter is C:.

  Project Setup


 Project Setup

After starting Visual Basic, as shown in Figure 2.1.1, choose a Standard EXE as the project type you would like to create. From Project/Components add WebX as shown in Figure 2.1.2.

Figure 2.1.1 – Start Project	Figure 2.1.2 – Add Component

The control has been added to the components toolbar in the IDE, as shown in Figure 2.1.3. Double click on the icon to add it to the Form. Double click on a command button to also add it to the Form as shown in Figure 2.1.4.

Figure 2.1.3 – WebX Icon on Components Toolbar.	Figure 2.1.4 – WebX Component on Form.
Now add the following code to the Form:

Option Explicit

Private Sub Form_Load

    ' Set up the Form

    Command1.Caption = "Start Server"

    Caption = "Server Stopped."

End Sub

Private Sub Command1_Click

    With WebX1

        ' Check the State of WebX and

        ' take appropriate action

        If .ServerRunning = False Then

            .ServerPort = 8888

            .VirtualPath = App.Path & "\html"

            .StartServer            Caption = "Server Running."

            Command1.Caption = "Stop Server"

        Else

            .StopServer            Caption = "Server Stopped."

            Command1.Caption = "Start Server"

        End If

    End With

End Sub

Figure 2.1.5 – Visual Basic Code for Simple Web Server.

Run the program. If there are any errors, check for any typing mistakes that may have occurred. Once the program is running, open your web browser and go to the following URL: http://localhost:8888. When you go to the above URL, you should see the welcome page for the Simple Web Server example project. If you do not see it or receive any errors, carefully double-check your typing.

  Project Notes


Project Notes

The URL address is pointing to “localhost”, which has the IP address of 127.0.0.1. This will tell your browser to look for a web server that is running on your local PC. The :8888 after localhost tells the browser to go to Port 8888, instead of the standard web server Port 80. Port 8888 is used in case you have another web server running on your PC.

  WebX Interface


WebX Interface

For quick reference, a tabular version of the WebX Interface is included in Section 7.

  Properties


Properties

  Properties:AuthenticationSource


Properties:AuthenticationSource
AuthenticationSource

Integer, Read/Write

Returns/set the source of the usernames and passwords to access restricted directories in the web site. Allowable sources are: GlobalFile (0), DirectoryFile (1) and LocalACL (2), DomainACL (3).

The user will be prompted  for a password when they attempt to access directories that contain a file named htaccess.txt. If AuthenticationSource = GlobalFile, then the file defined by AuthenticationSourceFile will be used to authenticate the user. If AuthenticationSource = DirectoryFile then the htaccess.txt that resides in the directory the user is attempting to access will be used for authentication.

If AuthenticationSource = LocalACL and WebX is running on a Windows NT4 or Windows 2000 computer, the local NT user accounts will be used for authentication.

If AuthenticationSource = DomainACL,WebX will attempt to authenticate to the specified NT domain. In this case, the user will have to logon using the following format:

User Name = domain\user - (Domain is the NT domain used for authentication)

Password = user’s password

NOTE: If AuthenticationSource = DirectoryFile, you can separate your site into different Authentication Realms by adding Realm:RealmName to the password list in the  AuthenticationSourceFile. This will allow the developer to portion the site for different users, otherwise if AuthenticationSource = GlobalFile is used once a user is authenticated they may go to any directory in the site using the credentials.

For example, suppose you have a directory for Sales with the entry Realm:Sales in the access file, and a directory for Managers with the entry Realm:Managers in the access file. Users who enter a username and password to access the Sales directory will be prompted for a username and password when they try to access the Managers directory. If GlobalFile is used they would not be prompted for a username and password if there username and password also existed in the Managers directory access file.

  Properties:AuthenticationSourceFile


Properties:AuthenticationSourceFile
AuthenticationSourceFile

String, Read/Write

Return/set the fully qualified file name used for AuthenticationSource = GlobalFile and AuthenticationSource = DirectoryFile . See Section 3.1.1.

E.g. WebX1.AuthenticationSourceFile = "C:\MyWebSite\pswd_lst.txt"

  Properties:CGIDirectory


Properties:CGIDirectory
CGIDirectory

String, Read/Write

The fully qualified path to CGI directory. CGIDriectory can point to a local hard drive, mapped drive or UNC path.

E.g. WebX1.CGIDirectory = "C:\MyWebServer\Scripts" - WebX will search in C:\MyWebServer\Scripts for CGI scripts/executables. If the script or scripts directory does not exist, WebX will return and error the client.

  Properties:CGIEnable


Properties:CGIEnable
CGIEnable

Boolean, Read/Write

Specify or set if CGI processing is enabled. If this is set to FALSE, then the parsing engine will not search for <!-- tags. If you are not using CGI or CGI tags, setting CGIEnable = FALSE will improve performance by minimizing the time required to parse the HTML page.

  Properties:CGITimeout


Properties:CGITimeout
CGITimeout

Long, Read/Write

Return/set the timeout for CGI scripts in seconds. The longest time a CGI thread can execute is set by this timer. If the thread run time exceeds CGITimeout, it is terminated. If CGITimeout is set to zero the timer will be disabled.

  Properties:ConnectionTimeout


Properties:ConnectionTimeout
ConnectionTimeout

Integer, Read/Write

Return/set the minutes WebX waits between searches to clean-up ‘timed out’ for ‘bad’ connections. This timer is used to clean-up connections that may have stuck in a Closing or Error state. WebX will automatically look for connections stuck in closing or error states and will reset them if there are no available connections when a new request arrives.

  Properties:ContentTypeSource


Properties:ContentTypeSource
ContentTypeSource

Integer, Read/Write

Return/set the source used by WebX for the MIME Content Type returned to the client in the HTTP header. Allowable sources are: Registry (0), File (1), Internal (2).

If ContentTypeSource = Registry, the file type extensions in HKEY_CLASSES_ROOT are searched and the “Content Type” value is used to return the content type. If ContentTypeSource = File, the file specified in ContentTypeSourceFile (see Section 3.1.8) is used to search for MIME types associated with file extensions. If ContentTypeSource = Internal, an internal table containing approximately 200 MIME types is used for the lookup.

  Properties:ContentTypeSourceFile


Properties:ContentTypeSourceFile
ContentTypeSourceFile

String, Read/Write

Return/set the fully qualified file name used when ContentTypeSource = File. See Section 3.1.7.

E.g. WebX1.ContentTypeSourceFile = "C:\MyWebSite\mime_lst.txt"

NOTE: If the specified file is not found, WebX will automatically use the registry for MIME type lookups

  Properties:DirectoryBrowseEnable


Properties:DirectoryBrowseEnable
DirectoryBrowseEnable

Boolean, Read/Write

Return/set if the client will receive a directory listing if the URL does not specify a file.

  Properties:ErrorFilesEnable


Properties:ErrorFilesEnable
ErrorFilesEnable

Boolean, Read/Write

Return/set if external HTML files are used for HTTP error messages. If ErrorFilesEnable = FALSE then the error messages sent back the client are embedded in WebX.

If ErrorFilesEnable = TRUE then WebX will look for the error HTML files in /errors directory within the root of the Virtual Path. Using this setting will allow the developer to customize the error messages for their specific appication.

NOTE: This property is only used when VerboseErrorsEnable = TRUE.

  Properties:HTMLFunctionsEnable


Properties:HTMLFunctionsEnable
HTMLFunctionsEnable

Boolean, Read/Write

Enable/disable calling of functions that can be called from HTML. The desired function name is passed, along with the entire query string, to the application containing WebX. Within the HTML, the function name can be a virtual one and translated in code. See the documentation for the CallFunction event in Section 3.3.1 for an example of using HTML functions in WebX.

  Properties:IndexPageNames


Properties:IndexPageNames
IndexPageNames

String, Read/Write

List of allowable index/default page names (comma delimited).

E.g. WebX1.IndexPageNames = "index.html, default.htm"- If the client specifies a URL without a destination page (e.g. http://www.mydomain.com), WebX will assume the client is requesting the home page for that path (if one is included). WebX will search for index page names that are in IndexPageNames in the order they were specified. In the above example, WebX will first look for the home page index.html. If it does not exist, it will then try to find default.htm. If default.htm does not exist, the user will be sent back either the directory listing (if DirListEnable = TRUE) or a file not found error.

  Properties:MaxConnections


Properties:MaxConnections
MaxConnections

Integer, Read/Write

Maximum number of simultaneous active connections WebX will support. A connection is only active while transmitting or receiving data.

E.g. WebX1.MaxConnections = 100 – The total number of connections allowed will be 100. When the 101 connection attempt is made, the client will receive a server too busy error. If you expect a high volume of traffic where the connections will be busy for extended lengths of time (large file being downloaded), set this number to 100 or greater.

E.g. WebX1.MaxConnections = 1 – Use this setting when you expect short connection times with a small amount of data transferred with each request.

NOTE: If you intend to support only one user at time, you may want to set MaxConnections = 5. This will allow WebX to honor multiple requests from browsers (text and graphics). Since popular browsers usually have four threads running, they may request as many as four items (test, graphics, etc.) simultaneously.

  Properties:ServerIP


Properties:ServerIP
ServerIP

String, Read/Write

IP address of the WebX web server. If this is not set, WebX will use the IP address enumerated by the system.

  Properties:ServerName


Properties:ServerName
ServerName

String, Read/Write

This is the host name or IP address that WebX will use for self-referencing links. If ServerName is not set by the application, the Windows Local Host name is used.

  Properties:ServerPort


Properties:ServerPort
ServerPort

String, Read/Write

Returns/sets the IP Port that WebX will listen. If the application tries to use a port that is already being used by another application, WebX will raise Error Number 10048 and will not start.

E.g. WebX1.ServerPort = 3333 –This example will set the listener port to 3333. The URL for access to this server would be "http:.//www.mydomain.com:3333". By changing the value of ServerPort, you can have multiple web servers running on one computer.

Therefore, another web server such as Microsoft IIS (Internet Information Server) can be running on port 80 and a WebX based application on port 3333. Web pages hosted by the WebX application on port 3333 can then be linked from the main web site on port 80.

  Properties:ServerSoftware


Properties:ServerSoftware
ServerSoftware

String, Read/Write

Returns/sets the software Name and Version of this web server. The format that the developer should use is "Server Name/X.Y".

E.g. WebX1.ServerSoftware = "MyWebServer/1.0" – Will return "Server: MyWebServer/1.0" in the HTTP header sent to the client.

  Properties:SSIEnable


Properties:SSIEnable
SSIEnable

Boolean, Read/Write

Returns/sets if Server Side Include (SSI) processing is enabled. If the HTML source will have SSI tags, set this to FALSE as it will increase performance of the parsing engine.

  Properties:TrapFileEnable


Properties:TrapFileEnable
TrapFileEnable

Boolean, Read/Write

Trap all page requests through application. If enabled, WebX will raise the FileRequest event. When this event is fired, WebX will pass the name of the requested object (HTML page, file, etc.) and the Query String to the application. The developer can then decide if they want to TRAP the page and provide the output to the client, or if WebX should try to honor the request. See Sections 3.2.12 and 3.3.2 for more information and an example.

  Properties:TrapFileTypes


Properties:TrapFileTypes
TrapFileTypes

String, Read/Write

Returns/sets a comma delimited list of file types that will cause the FileRequested event to fire. If a blank string (“”) is set all files will cause the FileRequested event too fire. TrapFileTypes is only used by WebX if TrapFileEnable = TRUE.

  Properties:VerboseErrorsEnable


Properties:VerboseErrorsEnable
VerboseErrorsEnable

Boolean, Read/Write

If enabled, WebX will send an explanatory error to clients, otherwise, WebX will send only an HTTP header with the appropriate error code.

  Properties:VirtualPath


Properties:VirtualPath
VirtualPath

String, Read/Write

Fully qualified path to the directory of the site home page (site root). This is the directory where http://www.mydomain.com will have its root directory.

E.g. WebX1.VirtualPath = "C:\MyWebSite" – When WebX receives a request, C:\MyWebSite is the physical path it will search for the requested file.

  Methods


Methods

All values returned by all STAT methods will be reset when the StartServer is invoked. Therefore, if you would like to keep a grand total for STATs regardless of WebX uptime, you will have to store the STAT variables.

  Methods:CGIValue


Methods:CGIValue
CGIValue

Return Type: String

Returns the value of the specified CGI Environment Variable. If the Variable is a blank string  (“”), all the Environment Variables with Delimiter between each variable

For Example:

Private Sub WebX1_FileRequest(Index As Integer, FileName As String)

    ' This will print all the CGI Variables with

    ' a CRLF between each of them

    Debug.Print WebX1.CGIValue(Index, "", vbCRLF)

    ' This will print only the CGI Variable

    ' CGI_GATEWAY, which is "CGI/1.1".

    Debug.Print WebX1.CGIValue(Index, "CGI_GATEWAY")

End Sub

  Methods:QueryString


Methods:QueryString
QueryString

Return Type: String

Returns the value of the specified parameter in the Query String. If the parameter does not exist in the Query String, a blank (“”) is returned.

For Example:

If the URL is http://www.mydomain.com/prod.html?N=Eng&Cyl=4&N=Gas

and the application source code is:

Private Sub WebX1_FileRequest(Index As Integer, FileName As String)

    Debug.Print WebX1.QueryString(Index, "N")

    ' The next line will force a blank line between

    ' Eng and Gas since the Parameter Blah does not

    ' exists in the Query String.

    Debug.Print WebX1.QueryString(Index, "Blah")

    Debug.Print WebX1.QueryString(Index, "Cyl")

End Sub

The output in the Immediate Window would be:

Note: Index is the connection number returned by WebX

  Methods:QueryStringCount


Methods:QueryStringCount
QueryStringCount

Return Type: Integer

Returns the number of occurrences of a parameter within a Query String.

For Example:

If the URL is http://www.mydomain.com/prod.html?N=Eng&Cyl=4&N=Gas

and the application source code is:

Private Sub WebX1_FileRequest(Index As Integer, FileName As String)

    iCount = WebX1.QueryStringCount    For x = 1 to iCount

        Debug.Print WebX1.QueryString(Index, "N")

    Next x

End Sub

The output in the Immediate Window would be:

  Methods:ServerRunning


Methods:ServerRunning
ServerRunning

Return Type: Boolean

Returns TRUE if the WebX is currently running and FALSE if it is not running.

  Methods:StartServer


Methods:StartServer
StartServer

Return Type: Boolean

Returns TRUE if the WebX starts without any errors and FALSE if there are errors during startup. If there are errors, the LogEvent event is also raised which will contain the error number and description.

  Methods:Stats_BytesReceived


Methods:Stats_BytesReceived
Stats_BytesReceived

Return Type: String

Kilo-Bytes (1024 bits) received by WebX from client requests. This value (and all other stats) will be reset when the StartServer is invoked.

E.g. Debug.Print WebX1.Stats_BytesReceived – Will print  “2324K” in the Immediate Window, meaning 2324 * 1024 bytes sent.

  Methods:Stats_BytesSent


Methods:Stats_BytesSent
Stats_BytesSent

Return Type: String

Kilo-Bytes sent by WebX to clients.

  Methods:Stats_Errors


Methods:Stats_Errors
Stats_Errors

Return Type: String

Number of trapped errors by WebX. Whenever LOGEVENT is fired, Stats_Errors is increment. Usually, these are significant system or run-time errors.

  Methods:Stats_FreeConnections


Methods:Stats_FreeConnections
Stats_FreeConnections

Return Type: String

Number of free (available) connections. A connection is only in use when it is in the process of sending or receiving data.

  Methods:Stats_Requests


Methods:Stats_Requests
Stats_Requests

Return Type: String

Number of client requests (pages, images, etc.) to web server.

  Methods:Stats_UpTime


Methods:Stats_UpTime
Stats_UpTime

Return Type: String

The up-time of the server. Format is “dd:hh:mm:ss”.

E.g. Debug.Print WebX1. Stats_BytesReceived – This will print  “23:02:06:33” in the Immediate Window, meaning 23 days, 2 hours, 6 minutes and 33 seconds.

  Methods:StopServer


Methods:StopServer
StopServer

Return Type: Boolean

Returns TRUE if the WebX is stopped without any errors and FALSE if there are errors. If there are errors, the LOGEVENT event is also raised which will contain the error number and description.

  Methods:TrapFileData


Methods:TrapFileData
TrapFileData

If TrapFileEnable is set to TRUE (see Section 3.1.9), then FileRequest event will fire when a request is received by WebX. The developer can choose to inspect the name of the requested file and query string and also bypass the subsequent search for a file and return data directly to the client. The TrapFileData is used to return the data the application is to send to the client.

This will allow developers to embed all of their web pages within their applications, keeping proprietary and protecting users from modifying the HTML pages of your web site/application.

Parameter	Type	Description
Index	Integer	Used to link the returned data to the requesting connection.
Data	Variant	Contains the data to be sent to the requesting client.
[WebXProcess]	Boolean	Optional. Default Value =  TRUE. If TRUE, the application will not send any data to the client and WebX will look for the file (HTML or binary) to be sent. If FALSE the application will provide WebX the data to be sent to the client in Data.
[ContentType]	String	Optional. Default Value = "text/html". This is the Content Type (MIME) that is being sent to the client.
[Authorized]	Boolean	Optional. The user requesting the directory can be authorized to receive the page by the developer.

Table 3.2.1 – TrapFileData Method Parameters

  Events


Events

  Events:CallFunction


Events:CallFunction
CallFunction

If HTMLFunctionsEnable (see section 3.1.4) is set to TRUE, this event will fire whenever the Function tag is found in an HTML file. When the event is raised, the application can then return a string that will be substituted for the function call tag before the HTML page is sent to the client. See example below:

Parameter	Type	Description
Index	Integer	The index of the connection requesting a file.
FunctionName	String	The virtual function that is specified in HTML.
QueryString	String	The full Query String in the URL. E.g. If you request http://www.mydomain.com/index.html?Name=Joe, QueryString will contain “?Name=Joe”.
Table 3.2.1 – CallFunction Event Parameters

Example:

The HTML file contains the following:

<html>

<head>

<title>Future Wave Tech WebX</title>

</head>

<body>

<b>A Test Function:</b>

<%=Function MyFunction(P1=Hello%20World,P2=Test)%>

</body>

Visual Basic code contains the following:

Private Sub Form_Load

    WebX1.HTMLFunctionsEnable = TRUE

    WebX1.StartServerEnd Sub

Private Sub WebX_CallFunction(Index As Integer, FunctionName As String)

    Select Case sFunctionName

        Case "MyFunction"

            WebX1.ReturnData Index, MyFunction()

        Case Else

            WebX1.ReturnData Index, "Error: The Function _

                             Call failed. Function " & _

                             sFunctionName & " was not found."

    End Select

Exit Sub

Public Function MyFunction(sQS As String)

    MyFunction = "From a VB Function: " & vbCrLf & _

                 "<BR>" & vbCrLf

End Function

Index is used to track which TCP connection is making the request and must be passed back to WebX when responding to this event with the ReturnData method.

FunctionName is the virtual function name that is being called from HTML, <%=Function MyFunction("Hello World") in this example.

QueryString holds any additional parameter that are passed.

  Events:FileRequest


Events:FileRequest
FileRequest

Data As String

If TrapFileEnable is set to TRUE (See Section 3.1.9), all incoming requests will fire the FileRequest event. When this event is fired, WebX will pass the name of the requested object (HTML page, gif file, etc.) and the entire Query String to the application. The developer can then decide if they want to TRAP the page and provide the output to the client or if WebX should try to honor the request. See the example below.

Parameter	Type	Description
Index	Integer	The index of the connection requesting a file.
FileName	String	The name of the file being requested. The virtual path is included in file. E.g. If you request the following page http://www.mydomain.com/products/index.html, FileName will contain “/products/index.html”.
UserAuthentication	String	The user name and password for restricted directories. The format is: username:password.

Table 3.3.1 – FileRequest Event Parameters

For Example:

Private Sub WebX1_FileRequest(Index As Integer, FileName As String)

    If UCase(FileName) = UCase("/trap.html") Then

        Debug.Print FileName & QueryString

        ' Send data back to Server Engine

        WebX1.TrapFileData Index, "A Trapped Page.", False

    Else

        WebX1.TrapFileData Index, "", True

    End If

End Sub

In the above example, if FileName is trap.html, then the test "A trapped Page. " will be sent to the client. Otherwise, WebX1.TrapFileData Index, "", True  is executed which forwards the request back to WebX. See Section 3.2.14 for more information on the method TrapFileData.

  Events:HTTPLog


Events:HTTPLog
HTTPLog

Data As String

Raised when the server is starting and stopping, displaying server parameters and its associated values. Also raised whenever a request is received. The output is in NCSA format.

  Events:LogEvent


Events:LogEvent
LogEvent

LogEvent As String

Raised when significant events occur, such as those a developer would want to write to the Windows NT Event Log. Examples of such events are: starting and stopping WebX and errors raised by WebX.

  Events:StatusLine


Events:StatusLine
StatusLine

Data As String

Raised when basic server events occur. For example, when WebX is starting and stopping. Intended to be used for output to a Status Bar.

  CGI Support


CGI Support

Using in-line HTML Automation can greatly enhance the functionality of your web pages. In-line automation tags allow the HTML author to instruct an application built with WebX to dynamically insert content into the HTML output sent to the client.

WebX can accept CGI Variables and SSIs in two ways:

The standard method, for example, if <!--#echo var="DATE_LOCAL" --> is inserted into an HTML page, WebX will substitute the current date and time before sending the page to the client.

The shorthand ASP style method could also be used. <%=Date_Local%> will also substitute today’s date and time in the page returned to the client.

Note: There is a no space between the directive opening “<!--“and the pound sign,# . There should be a space between the last double quote and the beginning of the directive close. Extra or missing spaces will be ignored by WebX’s parsing engine, but HTML page authors should format them in this manner  to make their HTML pages more portable.

  CGI Environment VariablesReference Tables:CGI Environment Variables


CGI Environment VariablesReference Tables:CGI Environment Variables
Standard CGI Environment Variables

CGI Environment Variables are typically passed to an executable or script that can act on these variables if needed. However, with WebX, they can also be used as in-line automation tags.

Variable	Description
AUTH_TYPE	Returns the type of authentication used to access the page. A blank screen signifies that no log was used. Basic means that basic clear text was used.
CONTENT_LENGTH	Specifies the number of bytes that will be received from the client.
CONTENT_TYPE	Specifies the type of content (MIME) that will be sent using the POST method.
GATEWAY_INTERFACE	Version of the Gateway Interface that is being used. The Current version is CGI/1.1.
HTTP_ACCEPT	Returns a string listing the Accept fields (MIME) in the HTTP header.
HTTP_REFERER
HTTP_USER_AGENT
PATH_INFO	Returns the path from the client.
PATH_TRANSLATED	The virtual path translated from PATH INFO.
QUERY_STRING	Parameters that are passed by the client. A “?” Signifies the beginning of the QUERY STRING.
REMOTE_ADDR	The IP address of the client.
REMOTE_HOST	The host name of the client. Warning: This tag may significantly slow down page processing because of the required DNS lookup.
REMOTE_USER	Returns the Username supplied by the client. This is also the username that the server will use if authentication was used.
REQUEST_METHOD	The HTTP request method. Currently, WebX supports GET and POST.
SCRIPT_NAME	The name of the executable (or script) to run. For example, for http://www.mydomain.com/products/prod_list.exe?Type=DVD, the SCRIPT_NAME = prod_list.exe.
SERVER_NAME	The server’s IP address or hostname that is used in self-referring addresses.
SERVER_PORT	The IP port number the server is listening on. Normally 80 for web servers, but can set to other non-standard values. http://www.mydomain.com:3333 will connect to a web server at port 3333 instead of the default of 80.
SERVER_PROTOCOL	Name and version of the protocol used for the client request. WebX currently supports HTTP/1.0.
SERVER_SOFTWARE	The name and version of the web server. WebX sets this variable to “Future Wave Tech WebX/1.0", but this value can be changed to personalize your application.
Table 4.2.1 – CGI Environnement Variables

  CGI Environment Variables ExtensionsReference Tables:CGI Environment Variables Extensions


CGI Environment Variables ExtensionsReference Tables:CGI Environment Variables Extensions
CGI Environment Variables Extensions

WebX also includes some common extensions the standard set of CGI Environment Variables.

Variable	Description
COUNTER	The current hit counter value for the requested page.
DATE	The current local date and time.
DATE_LOCAL	The current local date and time.
DATE_GMT	The current GMT date and 24 hour format time. GMT format is "ddd, dd mmm yyyy hh:nn:ss".
DAY_OF_WEEK	The current local day of the week.
DOCUMENT_NAME	The requested document name. Example: http://www.mydomain.com/products/new.html will return “new.html”
DOCUMENT_URI	Uniform Resource Identifier. Typically, the Internet address string referring to an object. A URL is a type of URI.
DOCUMENT_URL	Uniform Resource Locator. URL and URI are often mistakenly used interchangeably, so DOCUMENT_URL was added to WebX to minimize page errors.
TIME	The current local time.

Table 4.3.1 – CGI Extensions

  CGI Support


CGI Support

WebX includes support for CGI processing. To enable CGI processing:

Creates a directory that will contain your CGI executables. Typically, this will be the “/scripts” directory that is in the same directory as “/html”. You can put this directory anywhere you please, since web pages will never explicitly refer to the physical path. Creating this directory is not a requirement but will help keep your site organized, as well as, enhancing security since you can set the permissions of this directory independent of other directories.

The directory where the CGI executables are kept must have WRITE permissions. This is important under Windows NT and Windows 2000 where the application hosting WebX may not be running under an account with the required permissions to write to this directory.

Place the CGI executable in the /scripts directory.

In your code, set .CGIEnable = TRUE and CGIDirectory = strPath, where strPath is the physical path to the directory containing the CGI executables.

NOTE: In order to minimize potential security issues, we recommend that the /scripts directory should not be placed within the /html directory. Locating the /scripts in the same directory as /html will avoid this issue.

When a CGI script is called, WebX will write a file to CGIDirectory containing all the CGI Environment Variables. It will then call the executable,  passing the name of the CGI Environment Variables file. The file is in Windows INI format and has the connection number in the name of the file. After the CGI script is executed, the file is deleted.

More information may be found on CGI processing in the sample applications and at the following web sites:

http://hoohoo.ncsa.uiuc.edu/cgi/ (CGI Interface at NCSA)

http://ds.dial.pipex.com/bulcockc/cpp_dev.htm (Excellent C++ CGI ISAPI Examples)

http://www.mrwizard.com/~mark/books/assg/asg05.htm#E68E39

http://developer.netscape.com/docs/manuals/communicator/jsref/glob19.htm

Microsoft MSDN has several informative documents regarding CGI processing informative documents regarding CGI processing. Search for “server-side includes”.

  Server Side Includes


Server Side Includes

Server-Side Includes (SSI) give the HTML author a mechanism for substituting SSI directives with the text returned by WebX. You can think of this as an In-Line Replace function. Tags allow the HTML author to instruct an application built with WebX to dynamically insert content into the HTML output sent to the client.

WebX can accept CGI Environment Variables and SSIs in two ways:

The standard directive method. For example, if <!-- #echo Date --> is inserted into an HTML page, WebX will substitute the current date and time before sending the page to the client.

The shorthand ASP style method could also be used. <%=Date%> will also substitute today’s date and time in the page returned to the client.

Note: There is a space after the opening directive “<!--“ tag. Extra or missing spaces will be ignored by WebX’s parsing engine, but HTML page authors should include them to make their HTML pages more portable.

  Reference Tables:Supported Include Tags


Reference Tables:Supported Include Tags
Supported Include Tags

Tag	Description
#config	Specifies the format used for error messages, dates, and file sizes returned to the client browser.
#echo	Inserts the value of an CGI Environment Variable into an HTML page. See sections 4.1 and 4.2 for a listing of supported CGI Environment Variables.
#exec	Runs an application or a shell command and inserts the output into an HTML page.
#flastmod	Inserts the file modification date and time into an HTML page.
#fsize	Inserts the file size into an HTML page.
#include	Includes a file in an HTML or ASP page.
Table 5.2.1 – SSI Tags

  Reference Tables


Reference Tables

  Reference Tables:Properties


Reference Tables:Properties
Properties

All properties are Read/Write.

Property	Type	Description
AuthenticationSource	Integer	The source of usernames and passwords for restricted directories. GlobalFile, LocalFile, LocalACL, DomainACL.
AuthenticationSourceFile	String	Fully qualified path to the file used if AuthenticationSource = GlobalFile.
CGIDirectory	String	Fully qualified path to CGI Directory.
CGIEnable	Boolean	Enables CGI processing.
CGITimeout	Long	CGI script timeout.
ConnectionTimeout	Integer	Clean-up timeout for connections.
ContentSource	Integer	The source of usernames and passwords for MIME content. Registry, File, Internal.
ContentSourceFile	String	Fully qualified path to the file used if ContentSource = Internal.
DirectoryBrowseEnable	Boolean	Enable/Disable directory browsing when index page is not present.
HTMLFunctionsEnable	Boolean	Enable/Disable Visual Basic function call from HTML.
ErrorFilesEnable	Boolean	Enable/Disable if external HTML files are used for HTTP error messages when VerboseErrorsEnable = TRUE.
IndexPageNames	String	List of allowable index/default page names (comma delimited).
MaxConnections	Integer	Maximum number of simultaneous connections.
ServerIP	String	IP address of web server.
ServerName	String	Server Name of web server.
ServerPort	String	IP Port of web server.
ServerSoftware	String	The name and version of this web server.
SSIEnable	Boolean	Enable/Disable Server Side Include (SSI) processing.
TrapFileEnable	Boolean	Traps all page/file requests and passes control to the application.
TrapFileTypes	String	A comma delimited list of file types that will cause the FileRequest event to fire. A blank sting will cause all file type to fire.
VerboseErrorsEnable	Boolean	Explanatory errors to clients or just error codes.
VirtualPath	String	Fully qualified path to the directory of the home page.

Table 6.1.1 – Properties

  Reference Tables:Methods


Reference Tables:Methods
Methods

Method	Return Type	Description
CGIValue	String	The value of the specified CGI Environment Variable. If no variable is specified all variables are retuned.
QueryString	String	Returns the value of the specified parameter in the Query String.
QueryStringCount	Integer	Returns the number of occurrences of a parameter within a Query String.
ServerRunning	Boolean	TRUE if the web server is running and FALSE if not.
StartServer	Boolean	Starts the web server engine.
Stats_BytesReceived	String	Bytes received by web server.
Stats_BytesSent	String	Bytes sent by web server.
Stats_Errors	String	Number of trapped errors by web server.
Stats_FreeConnections	String	Number of free (available) connections.
Stats_Requests	String	Number of client requests (pages, images, etc.) to web server.
Stats_UpTime	String	Up Time of web server.
StopServer	Boolean	Stops the web server engine.
TrapFileData	String	Sends data to WebX for client on trapped pages.

Table 6.2.1 – Methods

  Reference Tables:Events


Reference Tables:Events
Events

Method	Description
CallFunction	Contains the Index, FunctionName and QueryString for requested HTML functions.
FileRequest	Contains the Index, FileName and QueryString for requested files.
HTTPLog	HTTP request logging output in NCSA format.
LogEvent	Significant events intended to be written to system Event Log.
StatusLine	String that can be written to the status bar of a web server application.

Table 6.3.1 – Events

  Index


Index

CGI Environment Variables, 4-15

AUTH_TYPE, 4-15

CONTENT_LENGTH, 4-15

CONTENT_TYPE, 4-15

DATE_GMT, 3-12

DATE_LOCAL, 4-15

GATEWAY_INTERFACE, 4-15

HTTP_ACCEPT, 4-15

HTTP_REFERER, 4-15

HTTP_USER_AGENT, 4-15

PATH_INFO, 4-15

PATH_TRANSLATED, 4-15

QUERY_STRING, 4-15

REMOTE_ADDR, 4-15

REMOTE_HOST, 4-15

REMOTE_USER, 4-15

REQUEST_METHOD, 4-15

SCRIPT_NAME, 4-15

SERVER_NAME, 4-16

SERVER_PORT, 4-16

SERVER_PROTOCOL, 4-16

SERVER_SOFTWARE, 4-16

CGI Environment Variables Extensions, 4-16

COUNTER, 4-16

DATE, 4-16

DATE_GMT, 4-16

DATE_LOCAL, 4-16

DAY_OF_WEEK, 4-16

DOCUMENT_NAME, 4-16

DOCUMENT_URI, 4-16

DOCUMENT_URL, 4-16

TIME, 4-16

Events, 3-12

CallFunction, 3-6, 3-12, 3-13, 6-20

FileRequest, 3-8, 3-9, 3-11, 3-13, 3-14, 6-20

HTTPLog, 3-14, 6-20

LogEvent, 3-14, 6-20

StatusLine, 3-14, 6-20

Methods, 3-8

CGIValue, 3-8, 6-20

QueryString, 3-9, 3-9, 3-12, 3-13, 3-14, 6-20

QueryStringCount, 3-9, 6-20

ServerRunning, 3-10, 6-20

StartServer, 2-3, 3-8, 3-10, 3-13, 6-20

Stats_BytesReceived, 3-10, 3-11, 6-20

Stats_BytesSent, 3-10, 6-20

Stats_Errors, 3-10, 6-20

Stats_FreeConnections, 3-10, 6-20

Stats_Requests, 3-11, 6-20

Stats_UpTime, 3-11, 6-20

StopServer, 2-3, 3-11, 6-20

TrapFileData, 3-11, 3-14, 6-20

Microsoft Access, 1-1

Properties, 3-4

AuthenticationSource, 3-4, 6-19

AuthenticationSourceFile, 3-4, 6-19

CGIDirectory, 3-4, 3-5, 4-17, 6-19

CGIEnable, 3-5, 4-17, 6-19

CGITimeout, 3-5, 6-19

ConnectionTimeout, 3-5, 6-19

ContentSource, 6-19

ContentSourceFile, 6-19

ContentTypeSource, 3-5

ContentTypeSourceFile, 3-5

DirectoryBrowseEnable, 3-6, 6-19

ErrorFilesEnable, 3-6

HTMLFunctionsEnable, 3-6, 3-12, 3-13, 6-19

IndexPageNames, 3-6, 6-19

MaxConnections, 3-6, 3-7, 6-19

ServerIP, 3-7, 6-19

ServerName, 3-7, 6-19

ServerPort, 2-3, 3-7, 6-19

ServerRunning, 2-3

ServerSoftware, 3-7, 6-19

SSIEnable, 3-7, 6-19

TrapFileEnable, 3-8, 3-11, 6-19

TrapFileTypes, 3-8, 6-19

VerboseErrorsEnable, 3-8, 6-19

VirtualPath, 2-3, 3-8, 6-19

README.TXT, 1-1

Reference Tables

CGI Environment Variables, 4-15

CGI Environment Variables Extensions, 4-16

Events, 6-20

Methods, 6-20

Properties, 6-19

Supported Include Tags, 5-18

Visual Basic, 1-1, 2-2, 3-12, 6-19