CGI Scripts

© Mike Smith M.A.Smith at brighton dot ac dot uk University of Brighton UK.

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.

 

Index 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:

Examples, of languages used to write CGI scripts include:

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.

 

Index 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.

 

Index 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:

<A HREF="/cgi-bin/script?name=Your+name&action=find"> Link </A>

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.

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) =

 

Index 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

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:

 

Index 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>
 

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.

Try it

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">
 

 

Index Check list

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


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]