
Self-Test & Demonstration
CGI Usage and Interfaces
18-Apr-96
Using CGI Programs:
WebSite's Three CGI Interfaces:
Sample Order-Entry Application (VB4 Runtime Required)
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.
Sample Order-Entry Application
(using Server-Side Java)
This example also uses Windows CGI and a form to provide an
order-entry service.
The external forms-processing program pizza.class
is a server-side Java application built using the
WebSite Server-Side Java SDK.
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
Java code in Pizza.java.
Forms must be processed by a CGI program. One of the difficulties
encountered in developing programs for forms is 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 data 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 approach is a major time (and frustration)
saver and is a feature available only on the WebSite and WebSite Pro
servers.
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. Spyglass Mosaic and Netscape
Navigator let you select multiple
items with the shift and control keys, per standard Windows conventions.
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
databases searching and so forth.
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 Win95 DOS command processors. These demos use the
server's DOS CGI support.
Database Integration with VB4 and Access
95
VB 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 Access 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 Chapter 10 of
WebSite Professional Advanced Topics.
Server-Push Animation (NT ONLY)
Try it now (NT only; server-push capable
browsers required)
WebSite Pro's
Standard CGI interface
supports a special non-spooled mode
for doing live animations, also known as server-push.
This page shows a demonstration.
Note: Windows 95's TCP package cannot pass sockets to children;
therefore, server-push does not work on Windows 95.
Form-Based File Uploading
Try it now (upload-capable browser required)
WebSite Pro 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 Pro. 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
4.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 WebSite and WebSite Pro apart from other Windows-
and Unix-based Web servers.
The sample is a test program that produces various reports from the
server about the CGI environment. The reports are in HTML
format. The sources to this test program (and all of the other
samples) are in the /cgi-src directory with 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 (VB4 runtime required)
/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, C, C++, and the perl language. Windows NT has a POSIX
subsystem that can be used from WebSite Pro 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.
WebSite Professional comes pre-configured with the complete
perl for Win32 package. It can be used via the
Standard CGI interface using file associations if your perl script's
file name ends in .pl (.plx is used for
API-based perl execution).
Here is a
small perl script
which sends back the names and values of some CGI environment variables.
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 and console applications and/or associated documents as long as
the application 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. It's tricky.
If you have a 32-bit Windows executable that can handle the standard CGI
interface, you might be able to use such a program with
Standard CGI on Windows 95.
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.
WARNING!

You must be very careful with the DOS CGI interface. For example, never
echo script parameters without quoting them. Think very carefully and test
thoroughly before releasing any CGI application that makes use of a
shell! There are many opportunities for security risks. See the comments
in the sample DOS CGI scripts.
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 information it got from the server. This info
is passed via environment variables, according to the
Common Gateway Interface 1.2 (CGI/1.2).
[email protected]