Internet Publishing

"Materials used in this course are the property of the author. These lessons may be used only by course participants for self-study purposes. Application for permission to use these materials for other educational purposes such as for teaching or as a basis for teaching should be directly submitted to the author."

This lesson deals with the following:

8. CGI Scripts on WWW Servers
8.1 Clickable Images
8.2 CGI Scripts
8.2.1 ISINDEX Tags
8.2.2 Starting Scripts with the Help of Forms
8.2.2.1 Unix Platform
8.2.2.2 MSWindows/MSDOS Platform
8.2.2.3 Transferring Data
8.3 Exercise

This lesson was published 30 April 1997.

8. CGI Scripts on WWW Servers

In Lesson 7, we went through the principles of CGI scripts which are:

Input from the user via forms or clickable images
The server's transfer of this information to the processing script
Sending of information back to the client

Lesson 7 covered forms in as mentioned in Point 1 in detail. In Lesson 5, we prepared a clckable image by creating a .MAP file for sensitive areas.

In this lesson, we shall look more closely at Points 2 and 3 in the list above. We will practice a little with using scripts. We will create a very simple script in DOS batch programming. Some of you may think it is odd that I have chose DOS batch files over these alternatives:

UNIX scripts with the help of perl or shell programming
Windows programming with the help of Visual Basic

These two alternatives would be the most realistic in a real life situation. In this course, I must take into account that not everyone has access to UNIX and/or Visual Basic. The little bit we will do here can be done in DOS batch files, but it won't exactly be a pretty sight.

The material in this lesson is also covered in the textbook, Chapter 15.

(Lessons) (Start Lesson 8) (8.2 CGI Scripts) (8.3 Exercise)

8.1 Clickable Images

In Lesson 5, we described two intrinsically different ways to create clickable images:

Client-side Management: (Use of IMG tags and MAP elements) This is a Netscape 2.0/Microsoft specific expansion of HTML 2.0 standard which is now included in the HTML 3.2 standard. The map lies on the client and all the processing occurs on the client's end. This is experienced as easier for those who publish because one doesn't need administrative rights on the server in order to put in maps. We tried this in Lesson 5.
Server-side Management: (Use of IMG tags and the attribute ISMAP) This is the HTML 2.0 way of constructing clickable images - but it is, of course, also described in the 3.2 standard. The map lies on the server and the client sends image co-ordinates to the server script. This is what we'll work on in this lesson.

Earlier, we looked at the HTML code for placing images in our documents:

<img src="trndheim.gif">

Here we will need to split up the descriptions for those running Win 3.x/httpd 1.4 and those using Win95/WebSite.

In order for a picture to become touch clickable, the following must be done:

For those running httpd1.4 (Win3.x) (No, I am using WebSite.)

A map of the sensitive areas must be created. This map is then saved in its own .MAP file. The contents must be in a special format, and here are the two different formats which shall be used on different HTTP servers. There is either "CERN httpd imagemap support" or "NCSA httpd imagemap support". We shall use the latter. Let's, for the sake of argument, call this file trheim.map.
You must no give the map a name. Let's use finby. This name must also be placed in a configuration file on the httpd 1.4 server with a pointer to the map file.
In the HTML code for the clickable image, we must create a link to a URL which can compare co-ordinates from the client against a map. For our practice server, this script is called imagemap.exe and lies in the /cgi-win directory.
We must give the name of the map in the HTML code.
In the <img> tags, we must say that the client will read the co-ordinates when we click on the image and then send these to the server. This is done by adding the attribute ISMAP.

The HTML code could look like this, for example:

<a href=/cgi-win/imagemap.exe/finby><img src="images/trndheim.gif" ISMAP></img></a>

In the figure below you can see what is happening:

The image shows:

A click on the clickable image on the client sends the URL for the script to be started up (imagemap.exe) along with the name of the map (finby) and the actual co-ordinates clicked upon to the server.
The server starts up imagemap.exe. The script has also received the name of the map, namely finby. The script now looks up the filename finby in its configuration file imagemap.cnf. In this case, it is trheim.map. Notice that the map has both a name and a filename.
For a given set of co-ordinates, the map will tell which HTML file the server will send back to the client.

Let's take a look at the details in the configuration file for the map descriptions. A new line with the name of the map and its corresponding filename must be added to the imagemap.cnf file:

# imagemap.cnf
#
imapdemo : c:\httpd\conf\maps\imapdemo.map
wizflow : C:\httpd\conf\maps\wizflow.map 
finby : C:\httpd\conf\maps\trheim.map

For those running WebSite: (No, I run httpd1.4)

A map of the sensitive areas must be created. This map is then saved in its own .MAP file. The contents must be in a special format, and here are the two different formats which shall be used on different HTTP servers. There is either "CERN httpd imagemap support" or "NCSA httpd imagemap support". We shall use the latter. Let's, for the sake of argument, call this file trheim.map.
This .MAP file can be placed in a directory along with the HTML code.
In the HTML code for the clickable image, we must create a link to a URL which is the .MAP file.
In the <img> tags, we must state that the client will read the co-ordinates when we click on the image and send these to the server. This is done by adding the attribute ISMAP.

The HTML code could look like this, for example:

<a href=/public/trheim.map><img src="images/trndheim.gif" ISMAP></img></a>

WebSite will see from the file type .MAP that it is a map. At the same time, the co-ordinates clicked upon on the image will be transferred. WebSite will now compare the co-ordinates and the information in the .MAP file, and find the URL to be displayed for the client.

This is a somewhat simpler procedure than httpd 1.4's.

This applies for both Web-servers:

The map should have the following format:

# Image map for Trondheim, finby
#
# - Per Borgesen
default <URL0>
rect <URL1> 25,50 112,99
circle <URL2> 160,160 212,160
poly <URL3> 22,50 310,99 120,77

One must place the real URLs at the places I have written <URLz> on the map. This example is similar to the map you made in the exercise for Lesson 5.

This is the NCSA way to make a map. The co-ordinates are created automatically if you use a map tool. If you edit the .MAP file manually (with a simple text editor), here's the format for specifying the different "hotzones":

rect <URL> <x,y-upper_left> <x,y-lower_right>
circle <URL> <x,y-center> <x,y-a place in the circle>
poly <URL> <x,y-point1> <x,y-point2> <x,y-point3> .....
point <URL> <x,y-point>

Note that the definition of default which states which URL should be used if one clicks on the image, but doesn't hit any of the defined hotzones.

CERN HTTPD uses another format for its .MAP files. Here is the same example again, in CERN/HTTPD format:

rectangle (<x,y-upper_left>) (<x,y-lower_right>) <URL>
circle (<x,y-center>) <radius> <URL>
polygon (<x,y-point1>) (<x,y-point2>) (<x,y-point3>) .....<URL>

Here, the co-ordinates must be written inside parentheses. Notice that the value for radius does not appear in parentheses.

(Lessons) (Start Lesson 8) (8.1 Clickable Images ) (8.3 Exercise)

8.2 CGI Scripts

Starting a program via Common Gateway Interface (CGI) is done on the client with the help of HTML code. There are two ways of doing this:

Use of ISINDEX tags (Such a page may contain only one text input field.)
Use of forms with one or more input fields

8.2.1 ISINDEX Tags

This is a technique which works well for sending one-word search criteria to a search engine. The following is a description of the principle for using ISINDEX.

If ISINDEX tags are used in the HTML code, the client will generate a text input field as shown below:

The HTML code for generating this follows:

<! This is a test for looking at HTML code for ISINDEX>
<! and to see how this would appear in the browser>
<! Written by: Per Borgesen>
<! Date: 6.11.95>
<HTML>
<HEAD>
<TITLE> Show layout of ISINDEX</TITLE>
</HEAD>
<BODY>
<ISINDEX>
<P>
OBS! This code should have been generated from a script - and not with a
HTML-file like I have done here. The purpose here is only to show the layout of 
an ISINDEX field. Therefore - You will in this case not receive any result if
you enter a keyword
</P>
</BODY>
</HTML>

Note that the no URL is given, nor is a program named for receiving data from this input field. If you complete the input field and press ENTER, you will see that the client returns the same URL, but with the search criteria added at the end followed by a question mark. Here is a hypothetical example, where I entered HELLO:

http://www.idb.hist.no/fu/mecpol/poi/lessons/08/sindex.html?HELLO

Try this!

The explanation for this follows:

When using this technique, the opening image must not be generated with the help of a HTML file as shown above, but by a program (CGI script).
The same program will be called after the input field is completed, but now the contents of the field will also be sent.
The script must test if something has been sent in order to find out how it should react. If nothing is sent, the HTML code for the start-up page is generated. If the input field contains information, it is processed.

Conclusion: This is a way to get simple input from the user, but the entire mechanism must be created with the help of scripts.

Here is an example of an ISINDEX script which is run on my practice PC.

(Lessons) (Start Lesson 8) (8.1 Touch Sensitive Images ) (8.3 Exercise)

8.2.2 Starting Scripts with the Help of Forms

Earlier, in Lesson 7, we looked at generating forms with input fields and selection fields. The server starts via its CGI, a program for processing data from the user:

We have seen in the exercise for Lesson 7 that these fields are often sent as a long string of fields and corresponding values:

FirstName=Per&LastName=Borgesen

These are two fields, FirstName with the value Per and LastName with the value Borgesen. The ampersand (&-character) separates the Name/Value pairs. How this data is sent to the processing program will vary according to which operating system the server uses.

(Lessons) (Start Lesson 8) (8.1 Clickable Images ) (8.3 Exercise)

8.2.2.1 UNIX Platform

The most used platform for information servers is probably UNIX. Here all the necessary tools are available, and there are several possible programming languages. The most used languages for CGI programs are:

A UNIX shell, such as C or Bourne shell. This is very simple for those already familiar with UNIX.
Perl - which is a language resembling a high level language such as C++ with strong functions for data definition. Perl is also a language which can be found on other platforms (MSDOS, OS/2, Windows95/NT), making the programs portable.

There are many standard scripts for UNIX platforms which one may find useful. Search the Internet yourself.

We will not talk any more about UNIX scripts - since we won't practice these in this course.

The point that separates the different platforms and methods is how the input string (name/value pairs) are transferred from the server, via CGI, to the processing program. See the table below:

(Lessons) (Start Lesson 8) (8.1 Clickable Images ) (8.3 Exercise)

8.2.2.2 MSWindows/MSDOS Platforms

For WWW servers running on MSWindows or MSDOS platforms, it is possible to us a MSDOS shell, perl or another high level programming language. The usual MSDOS shell COMMAND.COM is not well-suited for the following reasons:

Functionality of files and in/out functions in Windows is very limited
"< " and ">" are used to steer input/output in MSDOS batch programs. It is then impossible to use them directly for producing HTML code. You have to put them in textfiles, and let the batch program copy these files.

Still, we will use MSDOS batch files to create simple scripts in the lesson, because this is the tool to which we can assume everyone has access.

It is obviously possible for those able to write executable programs (Pascal, C, Basic or any other language) for MSDOS to call these programs in a MSDOS batch file.

For MSWindows, which doesn't have batch language, it is possible to choose Visual Basic or Visual C++.

(Lessons) (Start Lesson 8) (8.1 Clickable Images ) (8.3 Exercise)

8.2.2.3 Transferring Data

The table below shows how data is sent to the processing program:

Platform        Method: GET               Method: POST
UNIX            Environment Variable      stdin
MSDOS           Environment Variable      data file
MSWindows       CGI data file             data file

In our case where we use MSDOS, it is recommended that we use the POST method. Here, the HTTPD will place the string of input data in the form of Name/Value-pairs in a file. Thereafter, the program named in the URL will be called. When the CGI program has finished, HTTPD expects to find the result which will be sent back to the client in a certain file.

Our HTTPD saves two MSDOS environment variables %CONTENT_FILE% and %output_file% which contain the names of the input and output files.

Generating HTML code in the MSDOS batch environment is accomplished by:

Writing the text "New text" to the output file:

set of=%output_file%
echo New text > %of%

Adding a new line with the text "even more text" to the output file:

echo even more text >> %of%

Adding a text file (which may contain HTML code) to the output file:

type c:\tmp\somehtml.txt >> %of%

Copying the contents of the input file to another file:

type %CONTENT_FILE% > C:\tmp\inputfile.txt

Adding the contents of the input file to another file:

type %CONTENT_FILE% >> C:\tmp\inputfile.txt

(Lessons) (Start Lesson 8) (8.1 Clickable Images ) (8.2 CGI Scripts)

8.3 Exercise

Part 1: Clickable Image

You have earlier created a .MAP file for the image of the client/server in Lesson 5. You will now make a page with the same image in clickable format so that a short descriptive text will appear on the screen when the zone is clicked upon (see below). There should be three zones, client, server and net. In addition, a fourth text should be displayed if the user clicks outside of the three zones. These 4 pages should also have reciprocal links and can look like this:

1 The Client

This is the program which services the user and sends the user's requests over to the server.

(Client/Server Model) (Server) (Network)

2 The Server

This program receives requests from the client program, runs them and sends the answer back to the client.

(Client) (Client/Server Model) (Network)

3 The Network

The network acts as the mediator between the client and the server.

(Client) (Server) (Client/Server Model)

4 Client/Server Model

The client/server construction reduces the amount of traffic on the network because the data is processed locally as much as possible. Only the results of the processing are transmitted.

(Client) (Server) (Network)

You can try my version on httpd.

You can try my version on WebSite.

Turn in:

for those running Win3.x/httpd1.4: c:\httpd\conf\imagemap.cnf
your .MAP file
your 4 HTML files

Part 2: Simple MSDOS Script

Create a simple CGI script in the form of a MSDOS batch file. This is done a little differently in the these three cases:

Win3.x and httpd1.4
WinNT and WebSite
Win95 and WebSite. OBS! So that CGI scripts work on WebSite for Win95, you must create place for transferring of data between WebSite and the MSDOS program. You can do this by: locate the System.ini file (C:/Windows/System.ini), find the section called [NonWindowsApp], and add the line CommandEnvSize=8192
You will need to reboot your machine for this change to take effect !

A few examples of the different cases follows, and you will need read a little about this topic in the documentation included with your web-server, either for WebSite or for httpd1.4. Httpd1.4 has some general information about CGI which those of you running WebSite can read on my httpd1.4 machine.

Below you will find a form for signing up:

Example: Answer from Per's Practice Machine

A simple example of a "Form".

If you try the Send button, you will see that FieldName and Value will be returned to you as the text under the Send button indicates. If you look at the HTML code (View/Source in Netscape), you will see that the CGI script used is form-rpt.bat

Now, try it yourself:

If you are running Win3.x, you also have this script on your own httpd machine.

I have created corresponding files for WebSite:

corresponding form-rpt.cmd for WebSite run on WindowsNT.
corresponding form-rpt.bat for WebSite run on Windows95.

If you download form-rpt for WebSite, save the file in your directory called WebSite\cgi-dos\
under the filename form-rpt.cmd if you are running WinNT
under the filename form-rpt.bat if you are running Win95

Do it this way (so that you avoid problems with carriage returns):

Start Notepad
On the web-client, click on the form-rpt.bat (Win95) or form-rpt.cmd (WinNT) link above.
You will now have the batch file opened in a new web-window, and you can select all the text.
Paste the text in Notepad and save it at WebSite\cgi-dos\form-rpt.bat (Win95) or WebSite\cgi-dos\form-rpt.cmd (WinNT)

The same example is repeated below, only this time, you will receive an answer from your own machine. (This will also work even if you are not hooked up to the Internet, but you must have httpd running.)

Example: Answer From Your Own Win3.x, Httpd (Will Not Work on WebSite)

A simple example of a "Form".

Example: Answer From Your Own WinNT, WebSite (Will Not Work on Httpd1.4 or Win95)

A simple example of a "Form".

Example: Answer From Your Own Win95, WebSite (Will Not Work on Httpd1.4 or WinNT)

A simple example of a "Form".

Task:
Create an alternative script (MSDOS batch file) which doesn't just return the Name/Value pair, for each click of the Send button, but which accumulates registrations and returns a list of those signed up. Hint: You must make a working file where you accumulate registrations. You can try the demo below which runs on my machine and shows how I have imagined it.

Example: Registration - Demo of Solution on Winhttpd

A simple example of a "Form".

Example: Registration - Demo of Solution on WebSite Run on NT

A simple example of a "Form".

In order to make this, it is acceptable to use the principles outlined under point 8.2.2.3
Send in the .BAT file (or the CMD-file in the case of WindowsNT) and help files with HTML code. (If you have a permanently connected server, just send a URL so that the teacher's assistant can try your machine.)
Date due: 14.05.97

(Lessons) (Start Lesson 8) (8.1 Touch Sensitive Images ) (8.2 CGI Scripts) (8.3 Exercise)

Per