WebSite
Self-Test and Demonstration

Right now, check to see that you are reading this document through your WebSite server and not as a file. Look at the URL displayed in the box above this area. If it doesn't start with http://, then you are not using the server. If needed, start your web server now, and click here to switch to server-based reading.
Version 1.1e (23-Apr-96)
WebSite Documentation Overview
This document exercises (and demonstrates) many of the capabilities of your WebSite server and your browser. Please take the time to work through each feature. Don't worry if the more esoteric features don't seem to make sense; you'll know the reasons for them soon after you start using the server for real things.

For additional information on these features, check out WebSite Central, which has updates, Q/A, add-ons, betas, and more. If you are having difficulties, please consult the Frequently Asked Questions. You should also join the website-talk discussion list. Instructions for joining are on WebSite Central.


* Self-Test Checklist

Here's a checklist you can use to verify your setup:


Introduction

Your new server has the capabilities you need to produce powerful yet easy to use presentations and services. It supports the following main features:

Basic Document Retrieval

This is the most basic, yet most often used, function that your server provides. When the user clicks on a hot-spot, the browser sends a request to the server and the server returns the requested document.

Here is a plain text document
Here is a hypertext document
Here is a GIF image (the server author)
Here is an audio clip
You can also use an image as a hot-spot.


Directory Tree Navigation

Look here first

This feature permits the server to display directories on your PC and lets Web users browse and retrieve files. In addition, as server administrator, you can create text descriptions for files to assist your users in identifying and locating files. You can look at this feature as a "fancy FTP". It does not use the FTP protocol; it uses the Web's own HTTP for file transfers.

For this demo, I have created a small directory tree with some useless documents in it. Have a look and you'll get the idea. Clicking on the Parent Directory entry at the top of the demo tree will take you back to this demo document. Can you figure out how that happens?

HTML-3 Table Support

WebSite's directory listing format uses the HTML-3 table feature. This produces a much nicer looking listing, but it will be unusable by people without table-aware browsers. You can offer the older fixed-pitch format by including a link in the directory header with ?plain appended to the directory URL. If a directory listing does not have a header, WebSite puts a link for changing listing format at the top.

Here is the above sample directory tree in fixed-pitch format. Note that, once the server sees you use the ?plain argument, it will construct parent- and sub-directory links with this argument appended, preserving the fixed-pitch mode.

If you feel that most of your users do not have a browser that handles the new HTML-3 tables, you can tell the server to default to using fixed-pitch for its directory listings. Turn off the Use HTML3 Tables switch on the Indexing tab of the server's property sheet (Server Admin). WebSite ships with this switch enabled.

Disabling Directory Browsing

There are two ways that you can disable directory browsing: server-wide and path-specific. The Dir Index page of the server's property sheet has a checkbox that you can use to disable directory browsing server-wide. You can also create an access-control path on the Access Control page of the server's property sheet and check "Disable directory listings". This will prevent directory browsing on that path and it's children.

Here is a directory that has been protected against browsing with access control.


Image Maps

The server has the built-in ability to process clicks within an inline image and perform actions based on the location of the click. This is called "image map" support. With it, for example, you can create a graphical map of a complex set of Web pages and let your users navigate visually. Obviously, many other clever things can be done with image maps.

Here is an inline GIF image. Click in it and see what happens. If you get an error message, your server is not running, or you are reading this as a file. Try this link to see if your local server is running.

TEST

In contrast to most other Web servers, WebSite does not require running an external program to handle image map requests. The support is built into the server. This makes the server very efficient at handling image mapping.

Image Map Data

Using the WebSite Image Map Editor, you can graphically create the hotspots against a background of the image you want to map. This mapping information is stored in an image map file, which the server uses to determine what to do depending on where you click. The HTML used in the sample above is:
<A HREF="32demo.map">
<IMG SRC="images/imapdemo.gif" ISMAP WIDTH=300 HEIGHT=100>
</A>
The 32demo.map is the name of the map file. When WebSite sees a file name ending in .map it assumes that the file contains NCSA-format image mapping data. This activates WebSite's server's special built-in image mapper. WebSite reads the map file and uses the data in it to decide what to do. You can open the map with the WebSite MapThis imagemap editor and see the regions as they were defined, along with their target URLs (right click on a region). You may have to locate the background image yourself (one time only) after installing WebSite. Here is the image mapping data for the example above:
default /wsdocs/32demo/noshape.html
ellipse /wsdocs/32demo/circle.html 8,9 90,89
poly /wsdocs/32demo/poly.html 250,10 212,90 290,90 250,10
rect /wsdocs/32demo/rect.html 130,10 171,91

WebSite 1.1 uses standard NCSA-format image map files. You can put your map files in the same directory as the documents that use them.

The following example uses an image map file self-test.map.

Note that the NCSA image map format supports the point element, in which a click outside of any geometric region resolved to the nearest point. The presence of one or more point elements bypasses any background (default) element. The ellipse region is unique to WebSite. Most other imagemappers support only circles.

The HTML used in this sample is:

<A HREF="/wsdocs/32demo/self-test.map">
<IMG SRC="images/file-imap.gif" ISMAP>
</a>
and the contents of self-test.map are:
ellipse /wsdocs/32demo/ellipse.html 50,12 170,54
point /wsdocs/32demo/ptleft.html 24,34
point /wsdocs/32demo/ptright.html 194,34

The Two Ways to Code Image Maps in HTML

Actually, there are two ways to code image maps in HTML. The traditional way is to use the ISMAP element within an image tag, then enclose it with a link to the image mapper. The above examples use this method.

Another way to make an image map uses an obscure but useful feature of HTML forms. Create an input field of type IMAGE within a form whose execution target is the image mapper. Forms can use either the GET or POST method, but file-based image maps require using GET. An example, along with the actual HTML used, appears below.

<FORM METHOD="GET" ACTION="32demo.map">
<INPUT TYPE=IMAGE SRC="/wsdocs/32demo/images/imapdemo.gif">
</FORM>

Server-side Includes

Test Page Here

WebSite has a powerful powerful "server-side include" (SSI) feature found in some other web servers. This feature permits you to dynamically insert data from various sources into an HTML document.

NOTE: WebSite's unique built-in SSI support for page counters eliminates the need for CGI-based page counter packages completely.

This document demonstrates and tests WebSite's SSI facilities. See the WebSite book for details on the features and syntax for using SSI. If you downloaded this for evaluation, you may be able to figure out some of the SSI tags by looking at the test page ssi.html-ssi. As shipped, SSI operates only on documents with the extension .html-ssi.


Automatic URL-Fixup

This section checks out a vital feature of your server, its ability to fix up directory URLs that don't have a trailing slash. Don't bother to try to understand why this is needed for now. Look at the URL that is displayed at the top of your browser. It ends either with index.html or with a trailing slash. Click the link below. If this document is successfully redisplayed, the feature is working. If you get an error, your hostname is not configured correctly. Use the WebSite Server Setup applet to correct your hostname and then try this test again. Try it now:
http://localhost/wsdocs/32demo  <-- missing trailing slash
Now look at the displayed current URL. It should have a trailing slash on it, and it also has the port number after the host name if your server is running on a port other than 80 (the HTTP default).

Serving Java Applets (Java-enabled browser required)

WebSite is ready to serve Java Applets. The URL /java/ is mapped to the directory WebSite\java\applets\, and under there are three samples. You can add additional Java applets to your site by creating additional subdirectories under java\applets\.

Java Samples: (hit the back button on your browser to return here)


Sample Order-Entry Application

This example uses Windows CGI and a form to provide an order-entry service. The external forms-processing program pizza32.exe is a Visual Basic 4.0 (32-bit) application, compiled into an executable. The same program generates the form as well as processing its results. Note that the form has the current time on it.

NOTE: This example is an excellent reference implementation for forms applications. If you are interested in developing forms-based applications, please take the time to read the VB code in pizza32.bas.


Forms Processing

Forms must be processed by a CGI program. One of the difficulties encountered by most people who develop programs for their forms is that of decoding the form data. The browser sends this data in a special form called "URL-encoded". If you use the Windows CGI interface, the server will decode all forms information for you. Furthermore, the Visual Basic template application contains a module that handles reading the decoded form information into VB globals, then calls your module to do the actual processing. This is a major time (and frustration) saver, and is a feature available only on this server.

Sample search form

Here is a simple form that uses a VB CGI program. Fill in the field and select an option, then click the "Search" button. The demo back end simply reports what would ordinarily be submitted to the database search engine:

The "search on" field supports multiple selections (may not be supported by your browser). Try it and see how the server handles decoding it. Netscape lets you select multiple items with the shift and control keys, per standard Windows conventions.


Search on (multiple)

which

the following:

Case-sensitive


Document Based Queries

Most browsers have a feature that permits a hypertext document to trigger display of a "query field". When the user enters something into the query field the browser sends a special request to the server. You can set up your server to offer query documents and process queries by using the CGI program facilities. In this way, you can offer services that provide searching databases, etc.

Here are links to the Windows NT and Windows 95 versions. They differ because of differences in the capabilities and syntax of the NT and '95 DOS command processors. These demos use the server's DOS CGI support.


Database Integration with VB4 and Access 95

Visual Basic Professional 4.0 Runtime Required

This sample shows many useful techniques for using VB4 with Access (and any ODBC) databases. We suggest you read through the Introduction, which has links to browser-visible VB source code and Accesss design screens, as well as a live sample you can play with. If the live sample runs, then your VB and Access installations are OK.

Study this thoroughly if you plan to use VB and Access for database work. The sample is covered in detail in the WebSite book.


Server-push Animation (NT ONLY)

Try it now (NT only)

WebSite's Standard CGI interface supports a special non-spooled mode for doing live animations, a.k.a. "server-push". This page shows a demonstration. Note: Windows 95's TCP package cannot pass sockets to children, therefore this does not work on Windows 95.

Form-based File Uploading

Try it now (upload-capable browser required)

WebSite supports the new RFC-1867 form-based file uploading and multipart/form-data formats. Windows CGI decodes this new form data for you transparently. The uploader CGI program is one of the samples included with WebSite. As shipped, files are uploaded into a directory with an access controlled URL mapped to it.The upload area should never be accessible to anyone with a browser.

WARNING: BE CERTAIN TO READ AND UNDERSTAND THE CAUTIONS IN THE UPLOADER.BAS MODULE BEFORE MODIFYING THE UPLOADER OR CHANGING THE ACCESS CONTROL ON THE /UPLOADS/ URL.


Windows CGI Interface

The server supports a variant of CGI that is well suited to the Windows environment. In addition, the server comes with a template Visual Basic 3.0 kit that allows you to develop sophisticated CGI programs quickly. Since VB can access a wide variety of information sources such as Access and SQL Server databases, your flexibility is almost unlimited. It is this capability that sets the Windows Web Server apart from other Windows NT- and Unix-based Web servers.

The sample is a test program that produces various reports as to the CGI environment it gets from the server. The reports are in HTML format. The sources to this test program (and all of the other samples) are in the /cgi-src directory, plus a "usage" page in the server document root. The usage page is returned if no test selector is specified (as "extra path" info).

The URL to get the usage page is:

/cgi-win/cgitest32.exe
Try it now. Don't worry if you don't understand everything you see. Just understand that when you use this link, you are executing a compiled Visual Basic program. For more information, see the Windows CGI documentation.

Standard CGI Interface

Web pioneers have developed many CGI applications using Unix shell scripts and the perl language. Windows NT has a POSIX subsystem that can be used from the server to execute Unix applications as CGI programs. The Windows NT Resource Kit contains a basic set of Unix command utilities, including a Korn Shell clone.

Perl 4

There is a Windows NT port of perl available via FTP from the author, Clark Williams, or here at WebSite Central. In addition, I have done an upgrade to this perl that allows it to do bactic execution on Windows 95, supports filehandle access to sockets, and Win32 "mutex" support for interprocess synchronization. You can get this upgraded perl at WebSite Central. Note that you must already have the NT perl kit to use my upgrade.

Perl 5

The Windows NT 3.51 Resource kit contains an NT port of perl 5. A later version of this works on Windows 95 as well. If you are interested in the most up-to-date information on this new package, and to get the latest version, check out Perl 5 for Win32 home page (they use WebSite!).

Unix Compatibility

The Standard CGI interface provided by the server on NT is virtually identical to that provided by Unix-based servers. Therefore, you can use existing CGI applications written in shell and perl, as long as you have the other utilities needed by those scripts. You can also use 32-bit Windows applications and/or associated documents as long as the app is written for the standard CGI/1.1 interface.

16-bit Programs

Windows NT and Windows 95 cannot pass environment variables to 16-bit DOS/Console programs, so you must use the DOS CGI interface for this sort of thing. It's tricky. If you have a 32-bit Windows executable that can handle the pure CGI interface, you might be able to use such a program with Standard CGI on Windows 95.

Associations

The server uses the "associations" you set up to determine the correct shell to use for a script or document. In order for the demos below to work, you must associate files of type .sh with the SH.EXE Korn Shell from the resource kit, and .pl with the NT perl interpreter. You must use fully qualified pathnames for these associations. Do not rely on the "path".

Korn Shell Script (NT Only)

(demo requires sh.exe from the NT Resource Kit)

Here is a simple Korn shell script that sends back the names and values of some CGI environment variables. Note that the pathnames in system-generated and server-generated variables are in POSIX format. The server automatically determines whether the shell is a Win32 or POSIX type and makes the appropriate conversion on all physical pathnames it sends to the CGI program.

perl Script

(demo requires NT perl interpreter, and the extension .pl to be "associated" with your perl interpreter.)

Here is a small perl script which (of course) sends back the names and values of some CGI environment variables. Note that the pathnames are in the native Win32 syntax. The server knows that the perl interpreter is a native Win32 app, not a POSIX type.


DOS CGI Interface

The server can use batch files and programs that run in the DOS shell environment of Windows NT and Windows 95. The command processors are very limited, so you should use this interface for simple applications only. Actually, we strongly recommend that you take the time to learn Visual Basic and use the Windows interface for your CGI work.

The DOS command processors for Windows NT and Windows 95 are quite different in their capabilities, therefore we need different batch files for each. By convention we use .CMD for Windows NT batch files, and .BAT for Windows 95. Here is a simple example that uses a DOS batch file to send back the name and version of your browser. There is a version for Windows NT and one for Windows 95.

This batch file (NT version) (Win95 version) generates a report of some info it got from the server. This info is passed via environment variables, according to the Common Gateway Interface 1.2 (CGI/1.2).


Access Control

Your server has the ability to provide fine-grain control of access to documents and scripts. Access can be controlled by user, by group, by client host (domain) name, client IP address, or any combination of these. You can also disable directory browsing and file retrieval for parts of your web.

Browsers remember the username and password you enter. If you type in the correct username and password, you will be permitted to access the document, and you won't be able to try an incorrect combination until you exit and restart your browser. I suggest you start with the wrong username and/or password. Then when you try again, you'll get a "access failure" alert. Choose the try again button and you can type in another (correct) username and password.

User and Group Access Control

WebSite can provide per-directory protection to users and/or groups of users. Access control is not related to the Windows NT security system. There is no need to give an NT account to a Web user! This security is available under Windows 95, another reason WebSite has its own security system (Windows 95 has no built-in object-level access control).

Passwords are case-sensitive, usernames are not.

This document can be accessed only by user Dougherty with password balloon. This document can be accessed either by user Weber with password Jay, or by user Denny with password Bob.

The server also permits access by groups of users, and the Web Server Setup utility permits easy manipulation of group membership.All users are automatically included in the group "Users". Therefore, you can allow access to any valid user by allowing access by the group "Users".This document can be accessed by any user.

Hostname and IP Address Filtering

You can also control access by host name or IP addresses. For example, this document can be accessed only by hosts within the IP address range 198.211.*.*, and this one can be accessed by any hosts except those in the IP address range 198.211.*.*. Although it is possible to filter by host name, we don't recommend it because it requires that the server do a DNS reverse lookup (to convert the IP address to the host name) on every request. This will noticably degrade the response time of the server on all requests.

Combining Username/Password and Host/IP restrictions

New in WebSite 1.1 is the ability to apply username/password access and IP/host filtering in an "AND" or "OR" mode. Previously, only the "AND" mode was supported. With "OR", you can allow internal people to access your web (using IP filtering to reject outsiders) without needing usernames or passwords, while requiring outsiders to authenticate via username. See the "Access Control" tab on the server's property sheet.

Statistics Reports

The server will send a statistics report by sending it a URL of /~stats. Try it now. If you are connected to the net, you can see the WebSite Central server's statistics.

Server Administration

You may have noticed that the server responds to certain URLs that start with the tilde character in special ways. You have seen ~imagemap and ~stats so far. As you may have guessed, there are others. The two just mentioned are "safe", i.e., they don't "do" anything except retrieve data.

The server supports a few additional special URLs that can be used to perform some administrative tasks. These functions "do" something, therefore in keeping with the HTTP protocol, they must be issued with the POST method. Forms can issue POSTs, and they can have buttons, so you can make up an administration form that contains the special function buttons you want.

As shipped, the server is set up to protect these special URLs as well, since they can affect the operation of the server. In order to successfully use these functions, you must first authenticate yourself as a member of the Administrators group. If you haven't yet added yourself as a user in the WebServer realm, do so now. Then add yourself to the Administrators group.

If successful, these special functions return the HTTP 204 No Response result, so the browser stays on the current page (some browsers may report "link leads nowhere". This is cosmetic, and is not a server error!).

Now that you know the essentials, here are the buttons:

If you cycled either of the logfiles, take a look in the logs directory. You should see the cycled-out files with extensions like .001.
That's it for the demo. If you got this far without problems, you have also done a fairly thorough checkout of your server setup.
website-support@ora.com