User's Guide for FLS CGI Program /
Using the FLS CGI Program on your World Wide Web
David Bowen / Interdisciplinary Studies Program / Wayne State
University / Detroit, MI 48202
[Return to Welcome Page]
NOTE: The links below this point are all internal to this document.
If you are really linear and read all the way through this document
from start to finish (not recommended), you will have seen the
full contents and the links will not show you anything new.
CONTENTS:
On the World Wide Web, CGI programs provide interactivity;
the ability to accept information from the user and respond. The
user enters information on an HTML Form, and the CGI program responds.
The FLS program has these interactive features:
- Accept user information and store it in a text file. Appropriate
for comments, free-form answers and reports of LAN problems.
- Summarize all comments stored in the text file format above.
- Accept user information and store it in a text file suitable
for importing into a spreadsheet or database program. Appropriate
for evaluations.
- The response to the user is customizable. FLS makes a minimal
response to the user, which is augmented by means of an HTML customization
file.
Below, we will use the following terms to describe different roles
on the World Wide Web:
- USER. This is the person with the Web Browser or Client (e.g.
Netscape, MS Explorer, Mosaic) who is accessing your Web site.
- WEB AUTHOR. The Web author originates and maintains the Web
pages using HTML (HyperText Markup Language).
- WEB SITE ADMINISTRATOR. The Administrator manages the Web
Server and will install the FLS CGI program on the Web Server.
- WEB PROGRAMMER. The Web programmer develops CGI programs.
FLS functions can be incorporated in other CGI programs.
This User's Guide has separate sections for the Web Author, the
Web Site Administrator and the Web Programmer. We assume that
you already know basic HTML, including HTML forms. A good source
is HTML for Dummies by Ed Tittel and Steve James, published
by IDG Books.
And a final word in this section, concerning computer platforms.
A computer platform is a general type of computer, such as Macintosh,
Unix or Windows. The four roles of user, author, administrator
and programmer each have their own platform. The CGI program runs
on the Web Server, not on the user or author computer. The user
and author computers do not have to be compatible with the CGI
program. The platforms can be:
- User platform. The user can use any platform, provided s/he
has a Web Browser that runs on that platform. Browsers are available
for virtually all platforms.
- Web author platform. The author can use any platform, provided
s/he has HTML authoring tools that run on that platform. Authoring
tools are available for virtually all platforms.
- Web Site platforms. FLS must run on a Windows-based Web Server
using the Windows CGI interface. Examples are (a) WHTTPD, which
runs under Windows 3.x (including Windows for Workgroups) and
is available from city-net.com, and (b) WebSite, which runs under
Windows 95 and Windows NT, and is available through O'Reilly.
- Web programmer platforms. FLS is written in Microsoft Visual
Basic Version 3.0, and that or a more recent version must be used
in incorporating FLS functions in other CGI programs.
[Return to Contents]
The Web Author creates and maintains Web documents using Hypertext
Markup Language (HTML) . This section of the guide explains how
to incorporate FLS functions in your documents. We assume that
you have a basic familiarity with HTML, including HTML forms.
See, for example, HTML for Dummies by Ed Tittle and Steve
James, published by IDG Books.
HTML forms get input from the user by means of the following elements:
- Radio buttons (only a single choice in a sequence can be checked)
- Checkboxes (multiple choices in a sequence can be checked)
- Text boxes and text areas (free-form keyboard input)
- Pull-down menus (can be structured so that a single choice
can be checked, or so that multiple choices can be checked)
Below, it is important to realize that elements for which multiple
choices can be checked only send information for choices that
are checked. For example, if a sequence of checkboxes have favorite-flavor
choices for vanilla, chocolate, strawberry and cherry, and if
the user checks vanilla and chocolate, then the values fields
for vanilla and chocolate are returned, but not those for strawberry
or cherry.
On the other hand, for elements where only a single choice can
be checked or where text is typed into a window, information is
returned for the sequence even if no choice is checked, or if
no text is entered.
The actions that FLS takes are
- Saves the user input to a file in one of two formats
- Prepares one of several responses to the user
- Incorporates author-created HTML into the response to the
user via a customization file
- Summarizes one of the user information forms for review
FLS is started and your options are made in the HTML FORM statement.
Below we present the general form of the FLS FORM statement. The
variable parts of the statement are in italics, and explained
below.
<FORM ACTION="/cgi-win/fls.exe/customfilename/mode/datafilename/fieldname/"
METHOD="POST">
- customfilename = Name of customization file (extension
.htm not to be used; is supplied by FLS program)
(see customization file for details)
- mode = Mode of program operation, specifying the
file format and the response to the user
(see FLS modes for details)
- datafilename = name of output data file in which
to save user information (extension .txt not to be used; is supplied
by FLS program). If the file does not exist, it is created. For
the summarization mode, this is the input file containing the
entries to be summarized.
- fieldname = name of user input field to be summarized
for review (only used in summarization mode)
The response to the user consists of three parts, two taken from
a customization file written by the author (you), and the third
generated by the FLS program, specified by the program Mode. The
three parts appear on the user's screen in the following order:
- A "header" taken from the customization file.
- The response generated by the FLS program, depending on the
Mode variable.
- A "footer" taken from the customization file.
The customization file is a regular HTML file that contains only
the header and footer, along with special text dividing the file
into the header and footer sections. The header and footer can
contain any valid HTML, with the exception of HTML Form sections.
The special text elements are "[start]", which starts
the header; "[finish]", which ends the header and simultaneously
starts the footer, and "[end]", which ends the footer.
HTML before [start] and/or after [end] is ignored. The general
form of the customization file is then:
HTML before the header is ignored
[start]
The header is any HTML between start and finish
[finish]
The footer is any HTML between finish and end
[end]
HTML after the footer is ignored
EXAMPLE:
[start]
<H2>Thank you for responding.</H2>
[finish]
Thank you for trying our Web site.<P>
Come back again.
[end]
In the example, the header is (in H2 format)
Thank you for responding.
and the footer is
Thank you for trying our web site.
Come back again.
NOTE: If the [start], [finish] and/or [end] lines
contain any other text, it is ignored. The user does not see any
text on these lines. These lines may be used for comments for
the Web author.
FLS Modes
The FLS Mode determines both the format for saving user input
in a file, and the format for the response message. So before
describing the Mode options, we first present the file format options,
and the response message formats.
The Modes are listed following the
file and response message formats.
The information fields stored in the file all contain the same
information; only the format is different, as described further
on. The information stored is:
- Web Software and version
- CGI Software and version
- Date and time of the user information
- The URL that started the CGI program
- The "Referer", or URL for the form
- The user's IP address (numerical unless otherwise specified
by the Web Server administrator)
FLS saves user information in a file in one of the following formats:
- Standard. In the standard format, information is stored in
a "key: value" format. Here, the key is the name of
the information field and the value is the content. For example,
if the Remote Address (user IP address) is 132.32.45.61, then
this is saved in the file as
Remote Address: 132.32.45.61
This format is suitable for review as text. It might be used
to turn in an answer to a short-answer question.
Each set of returned information is headed by a line reading
********** Start Entry **********
For each set of returned information, if a multiple choice
field is missing because it was not chosen, neither the key nor
the value appears in the Standard file format.
- Spreadsheet. This is a format suitable for importing into
a spreadsheet or database program. User input is arranged in columns
by field and in rows by set of returned information, with the
list of fields in the first row (that is, after the first row,
the first set of returned information is in the second row, the
second set of returned information is in the third row, and so
on.). Fields are separated by Tab characters, a common convention
in text files for spreadsheet and database programs. If a multiple
choice field is missing because it was not chosen, a blank appears
in that column. We strongly suggest that VALUE="1" be
used for all multiple choice fields; then summing the column in
a spreadsheet or database program gives the number of times the
field was chosen by users, which is usually what you want. This
is because blank entries are counted as zeroes by spreadsheet
and database programs.
NOTE: For the spreadsheet format, the first use should be by the
Web author, and have all multiple choice fields chosen.
The data for this first use is not recorded, but the entry is
used to set up the list of fields. FLS counts a use as the first
use if the data file named in the URL does not exist, so you should
not create the file yourself; let FLS do it.
- None. Some FLS modes do not store user information in a file.
The options for FLS response messages are listed below. Recall
that the FLS response message has a header above and a footer
below from the customization file created by the Web author.
- Acknowledgment. This option produces a single line reading
We have recorded the information you entered - thank you.
- Echo. This message echoes the user input back, in the key:
value format. It does not echo information such as the IP address,
which is supplied by the user's Browser.
- Full. This displays all available information, in the key:
value format. The amount of information not entered by the user
will usually confuse users; the normal use for this format is
in debugging either your HTML form or the CGI program itself.
- Summary. As described above, this summarizes a given field
in a Spreadsheet data file. The specified field is displayed for
each entry, with entries separated by horizontal rules. If there
is a field in the data file called either "name" or
"names", then the value of that field is displayed underneath
the summary entry. The intent is that this be the name of the
person entering the comment.
NOTE: Field names are established by the Web author in the HTML
form using NAME="fieldname" in the tag for
each form element.
The table below lists the FLS modes.
Mode File format Response message
* echoit None Echo
* fileit Standard Acknowledgment
* echofile Standard Echo
* spread Spreadsheet Acknowledgment
* echospread Spreadsheet Echo
* summary None Summary
* debug None Full
[Return to Top]
(Installing FLS.EXE on your Web site)
FLS.EXE runs with Web Severs using the Windows CGI convention
as described by Robert Denny, and incorporated in the City Net
Web Server (WHTTPD) for Windows 3.x and the O'Reilly Web Server
(WebSite) for Windows 95 and Windows NT. Documentation with these
Web Servers suggests that the same CGI program should not be able
to run with both, but FLS will run with both. Different fields
will be empty depending on which Server is used, but these fields
are usually not of interest to users and Web authors.
FLS.EXE is designed to be used in system in which each directory
on the Web Site is an independent entity. Specifically, each customization
file should be in the same directory as its corresponding form
file. Any data files are put in the same directory, or read from
the same directory, in the case of the summary function.
To install FLS,
- Copy the file FLS.EXE to your cgi-win or equivalent directory
- Copy the file VBRUN300.DLL to your Windows directory
- Copy this User's Guide file, FLS_U_G.HTM to a directory accessory
to your Web authors and integrate it into your menu structure.
The return link at the top of the file, to welcome.htm, will have
to be changed if your menu file has a name other than welcome.htm.
- The User's Guide is also distributed as a MS Word 6.0 file,
FLS_U_G.DOC.
[Return to Top]
FLS is written in Microsoft Visual Basic, version 3.0, and the
routines can be incorporated in other CGI programs. This section
describes the FLS routines.
Module: CGI.BAS
This is the CGI.BAS distributed with O'Reilly WebSite. We have
modified the routine InitializeCGI so that it runs transparently
with WHTTPD from CityNet.
Module: FLS.BAS
- Subroutine: CGI_Main ( )
This decodes the mode information from the form and calls the
routines that carry out the actions.
- Subroutine: DoDebug (allpart$)
DoDebug prints the response document. If the string argument is
"part" then only the user input is put into the response.
If the argument is "all" then all other information
is added as well.
- Subroutine: DoFile ( )
This routine writes the Standard file format.
- Subroutine: DoIni ( )
This routine is used for the "makeini" mode that is
not documented for Web authors. It creates a *.ini file for use
in using Visual Basic debugging. In Visual Basic, under the Options
/ Project menu item, change the command line to refer to this
ini file. You can then debug your Visual basic code using the
Visual basic environment. If you are using the WebSite Web Server,
you can more conveniently use the "CGI tracing" option
on the "logging" tab of the Web Site control panel.
- Subroutine: DoSpread ( )
This routine writes the tab-delimited output file for use by spreadsheet
and database programs.
- Subroutine: DoSummary ( )
This summarizes the specified field of the specified file, by
writing the field to the response file.
- Subroutine: StartDocument ( )
Writes the HTML header for a response document. Supplied with
CGI.BAS. No longer used in FLS.
- Subroutine: EndDocument ( )
Writes the HTML footer for a response document. Supplied with
CGI.BAS. No longer used in FLS.
Module: SUBS.BAS
- Function: DOSfn$ (Raw$)
This turns the string argument into a legal DOS 8.3 file name.
- Subroutine: ParseString (In$, p$, n%, out$( ))
This breaks the string input string In$ into substrings at the
input parse character p$. There are n% resulting substrings stored
in out$( ).
- Subroutine: Replacer (Strng$, Find$, Replace$)
Replacer takes the string argument Strng$ and replaces all instances
of Find$ with Replace$
Module: UTILITY.BAS
- Subroutine: Customize (d$)
This routine reads the customization file and copies it to the
response file. If the string argument is "start" then
everything between [start] and [finish] in the customization file
is sent to the response document. If the string argument is "finish"
then everything between [finish] and [end] is sent. The customization
file is opened at the beginning of the "start" call
and closed at the end of the "finish" call.
NOTE: Relative links are changed to absolute using subroutine
MakeAbsRefs.
- Subroutine: Getfiles ( )
This subroutine constructs DocumentRoot$ and AbsoluteFormDir$,
respectively the root directory for documents on the Web site,
and the absolute directory that the form (Referer) is in. AbsoluteFormDir$
will be incorrect if the Referer is also a form.
- Subroutine: MakeAbsRefs (t$)
This makes the relative URL contained in t$ into an absolute URL.
[Return to Top]