An interactive introduction to HTML and CGI scripts on the WWW (courseware)

Contents

CGI scripts
Example of calling a CGI script file
Decoding data sent to a CGI script
Script to record users of web page
Post vs. get
Check list

Warning if you are not using a browser that supports tables
such as Netscape 1.1 or later then this page
will probably be very difficult to read.

CGI scripts

A CGI script is a program that is stored on the remote web server and executed on the web server in response to a request from a user.

A CGI script file is written in a programming language which can be either:

Compiled to run on the server.
Interpreted by an interpreter on the server.

Examples, of languages used to write CGI scripts include:

Compiled languages
C, C++, Ada
Interpreted languages
perl, JCL (e.g. The unix sh command language)

The CGI script is executed when an anchor tag <A ... > or an image tag <IMG ...> refers to the CGI script file rather than a normal file. The determination of whether this is a CGI script file or just an HTML file is made on the physical placement of the file on the server. Remember, the script file is placed on the same machine on which the web server runs and not on your local machine.

[It is of course possible to run a local web server on the machine on which you run the web browser. However, for other people to access the files delivered by your web server you will need a permanent connection to the internet]

Usually this placement is in the remote web servers cgi-bin directory. However the exact location of this directory on the server machine is determined by the web administrator for that machine. This placement and control of the cgi-bin directory is determined by the web administrator to prevent security problems, that could occur if arbitrary programs where allowed to be executed by anybody accessing the machine.

Some web administrators may not allow you to create CGI scripts on their machine.

Call of a CGI script file

An anchor tag to execute the CGI script dynamic_page on the server www.mc.com is:

<A HREF="http://www.mc.com/cgi-bin/dynamic_page">Dynamic page</A>

When the web server process a request to fetch a file, if the requested file is in the servers nominated cgi-bin directory then as long as this file is marked as being executable the script will be run on the server. If the file is not executable then an error will be reported.

The script eventually returns an HTML page or image to be displayed as the result of its execution. When a CGI script file executes it may access environment variables to discover additional information about the process that it is to perform. The first line of the returned data must be:

Type of returned data	Text
An HTML page	`Content-type: text/html`
A gif image	`Content-type: image/gif`

A simple CGI script on a unix based web server to return a list of the current users who are logged onto the web server is as follows: is:

#!/bin/sh
echo Content-type: text/html
echo
echo
echo "<HTML>"
echo "<HEAD>"
echo "</HEAD>"
echo "<BODY>"
echo "<H2>Users logged in are:</H2>"
echo "<PRE>"
who
echo "</PRE>"
echo "</BODY>"
echo "</HTML>"

Remember:

The "'s around text with a < or > character.

On a Unix system:

The first line is #!/bin/sh
The file has executable permission set.

Note:: The JCL (Job Control Language) command echo echoes the rest of the line to the standard output
The JCL command who lists the current users who are logged onto the system.
Allowing users to create their own CGI scripts can lead to security problems on the server.

The major environment variables that can be accessed by the CGI script when it executes are:

Environment variable	Contains
QUERY_STRING	Data sent to the CGI script, by its caller. This may be the output from a form, or other dynamically or statically generated data.
REMOTE_ADDR	The Internet address of the host machine making the request.

A C++ program mas_env.cpp (Other files required: mas_cvo.cpp, t99_type.h ) when run prints many of the environment variables available to a CGI script.

CGI scripts can be written in any language. For example, a CGI script to return the contents of the environment variable QUERY_STRING can be written in Ada 95.

Note:: I used the gcc compiler version 2.7.0 to compile this source code. In particular this compiler recognises the new data type bool.

Decoding data sent to a CGI script
When a form is used, the information collected in the form is sent to the CGI script for processing. This information is placed in the environment variable QUERY_STRING.

To pass information explicitly to the environment variable QUERY_STRING a modified form of an anchor tag is used. In this modified anchor tag, the data to be sent to the environment variable QUERY_STRING is appended after the URL which denotes the CGI script. The character ? is used to separate the URL denoting the CGI script and the data that is to be sent to the script. For example:

The data "name=Your+name&action=find" is placed in the environment variable QUERY_STRING and the cgi script script executed.

A class written in C++ composed of the specification parse.h and implementation parse.cpp is used to extract the individual components in the QUERY_STRING . The header file t99_type.h contains definitions for C++ features not implemented in some compilers. The members of this class are:

Method	Responsibility
Parse	Set the string that will be parsed.
set	Set a different string to be parsed.
get_item	Return the string associated with the keyword passed as a parameter. If no data return NULL.
get_item_n	Return the string associated with the keyword passed as a parameter. If no data then return the null string.

When using the member functions get_item and get_item_n the optional second parameter specifies which occurrence of the string associated with a keyword to return. This is to allow the recovery of information attached to identical keywords. In addition the returned string will have had the following substitutions made on it.

+
Will be converted to a space.
%HH
Will be converted to the character whose hexadecimal value is HH.
~user
Will be replaced by the full path to the user's home directory, but only if the optional third parameter is true.

Note:: The definition of NO_MAP will cause the code for ~username processing to be not included. This is so that the code can be compiled for machines, which do not support the system function map_uname defined in the header file cgi/pwd.h.

For example, if the QUERY_STRING contained:

tag=one&name=mike&action=%2B10%25&tag=two&log=~mas/log&tag=three

Then the following program when compiled and run:

enum bool { false, true };

#include <iostream.h>
#include <stdlib.h>

#include "parse.h"
#include "parse.cpp"

void main()
{
  char *query_str = getenv("QUERY_STRING");

  Parse list( query_str );

  cout << "name  = " << list.get_item_n( "name" ) << "\n";
  cout << "action= " << list.get_item_n( "action" ) << "\n";
  cout << "log   = " << list.get_item_n( "log", 1, true ) << "\n";
  for ( int i=1; i<=4; i++ )
  {
    cout << "tag  (" << i << ") = ";
    cout << list.get_item_n( "tag" , i ) << "\n";
  }
}

would produce the following output:

name  = mike
action= +10%
log   = /usr/staff/mas/log
tag  (1) = one
tag  (2) = two
tag  (3) = three
tag  (4) =

Script to record users of web page
By using an URL denoting a CGI script in an <IMG> tag additional processing can be performed before the image is delivered. This additional processing records details about the current viewer of the web page. Additional information is sent to the CGI script to specify the exact details of the action to take. For example:

Formatted text	HTML markup required
	<IMG SRC="/cgi-bin/mas_rec?page=HTML&file=log&img=dot.gif" ALT="Record not made">

The CGI script mas_rec written in C++ (Other files required: parse.h, parse.cpp, mas_cvo.cpp, t99_type.h ) is sent the following information:

Parameter name	Specifies
file	The name of the file in which the usage information will be appended.
page	A name for the page that will recorded in the log.
img	The image that will be loaded.

Of course for this to work, the viewer of the page must be viewing and hence loading images. Several reasons why images may not be loaded include:

The browser does not support viewing of images.
The viewer has de-selected the view image option to improve performance when they have a slow link to the web server.
The server may not receive the request to return the image.

Post vs. Get

So far the method used to send information to the CGI script has been GET. When the method GET is used the data sent is placed in the environment variable QUERY_STRING for the CGI script to process.

An alternative method is to use POST. When the method POST is used the data is sent by a separate stream and becomes the standard input to the CGI script. The method used is specified on the <FORM ..> tag using the attribute METHOD="get" or METHOD="post". The default method is GET.

For example:

Generated form	HTML markup required
	<FORM METHOD="get" ACTION="http://host/cgi-bin/mas_form"> <INPUT TYPE="text" NAME="name" SIZE=20 VALUE="Try it (get)"> </FORM>
	<FORM METHOD="post" ACTION="http://host/cgi-bin/mas_form"> <INPUT TYPE="text" NAME="name" SIZE=20 VALUE="Try it (post)"> </FORM>

Generated form

HTML markup required

 <FORM METHOD="get"
       ACTION="http://host/cgi-bin/mas_form">
 <INPUT TYPE="text" NAME="name"
        SIZE=20 VALUE="Try it (get)">
 </FORM>

 <FORM METHOD="post"
       ACTION="http://host/cgi-bin/mas_form">
 <INPUT TYPE="text" NAME="name"
        SIZE=20 VALUE="Try it (post)">
 </FORM>

When using the POST attribute, the following environment variables are set:

Environment variable	Contains
CONTENT_LENGTH	The length of the data sent via the standard input to the CGI program.
CONTENT_TYPE	The MIME type of the data.

A simple script to record in a log file data sent by a user is:

#!/bin/sh echo Content-type: text/html echo echo echo "<HTML>" echo "<HEAD>" echo "</HEAD>" echo "<BODY>" echo "<H2>Data recorded</H2> echo Use the back arrow on the browser echo to return to the original web page echo "</BODY>" echo "</HTML>" cat >> /home/snowwhite/staff/mas/log echo >> /home/snowwhite/staff/mas/log
Remember:

To use a full path name for the location of the file in which the information is recorded.

On a Unix system:

The first line is #!/bin/sh
The file is set executable and setuid to you

An example of its use is shown below:

Generated form	HTML markup required
	<FORM METHOD="post" ACTION="http:/machine/cgi-bin/mas_cgi1"> <INPUT TYPE="text" NAME="name" SIZE=20 VALUE="fill in">

Check list
It is important to make sure that the CGI script is:

Executable
Placed in the cgi-bin directory. The location of this directory is defined by the WWW server administrator.
Capable of accessing any files that it needs.
As the CGI script runs in the servers cgi-bin directory, any file paths which are relative, must be relative to this directory. When returning HTML which accessing images or uses hypertext links, it is easier if these are specified by using the http form of a URL.
On a Unix server the set uid bit should be set on the executable script file. This causes the program to execute as if it had been run by the owner of the file. This is important if the program is to access resources that only the creator of the CGI script can access.
This of course may open up many security loop holes.

Warning if you are not using a browser that supports tables
such as Netscape 1.1 or later then this page
will probably be very difficult to read.

© M.A.Smith University of Brighton. Created July 1995 last modified June 1999.
Comments, suggestions, etc. M.A.Smith at brighton dot ac dot uk * [Home page] [CGI Environment variables]