CGI Startup Guide for COSI developers

CGI mechanics

HTML Syntax

A CGI script is referred to using a URL like any HTML document. The difference is that CGI scripts normally need some parameters in its standard input, based on which they generate something meaningful (in HTML format) to their standard output. This input is usually generated by using a "front end" HTML page with an input form.

In its input form the "front end" HTML page specifies an action to take when the client submits the input [for further processing]. E. g.:
<form name="PrimTextForm" action="http://cosi-nms.sourceforge.net/cgi-bin/cgi_prim/cgi_prim.cgi" method="Post">
or
<form name="PrimTextForm" action="/cgi-bin/cgi_prim/cgi_prim.cgi" method="Post">
How does the webserver understand that the CGI script needs to be executed rather than displayed like a regular HTML page? CGI scripts reside in a special directory ("cgi-bin" in the above example). When a webserver receives a request for a page from this directory it will not display it, but rather run it and send back what the program printed to its standard output.

Summary

CGI scripts read data from standard input and print results to standard output.
Input to a CGI script is conveyed via a "front end" HTML page by using an input form.
The above statements are correct for method="Post"as in the above example. This is not the only possible method though.
It is not required that the "front end" HTML page resides on same webserver as the CGI script itself.
CGI scripts are stored in a special designated directory of the webserver. Their files need to have permissions set to allow execution (read and/or write permissions aren't required, but may be helpful while making CGI work).

CGI syntax

A CGI script can be anything as long as the webserver can execute it: a binary program, a set of shell commands, a script in any language, etc. The first step to make sure it works is to log into the shell of the webserver and try running it in command line. Unless special modifications are made, only "normal" standard output will be displayed to the client browser: error messages will be seen in shell only.

Summary

Before testing the HTML "front end" make sure the underlying CGI works ok.
The HTML "front end" refers to the CGI script using a directory structure as the webserver presents it on the WWW. The CGI script sees the directory structure as the webserver presents it to its internal programs. The two presentations may differ considerably (see example below).

Exchange format

Data sent and received by the CGI script has different formats.

Text input

The client browser replaces all spaces with '+' and a good deal of non-alphanumeric characters with their hexadecimal values. Besides, each input is prepended by its input field name followed by '='.

File input

The client browser converts the input into [Quoted-Printable] MIME format.

Output

The client browser expects the output to begin with "Content-type: text/html" followed by data in HTML format.

Summary

It's generally a good idea to do a "foolproof" check before submitting the input to CGI: if the script aborts, there will be no error message displayed to the browser. E.g. in the below example a JavaScript function makes sure the input field is not blank.
Converting the input back to its original form is somewhat tricky. To keep the change outside the main program, consider making a standalone script for this: it can be included into a pipe between the input and the main program This standalone script can later be used for converting all other programs to CGI as well.
If the main program generates output in plain text, it does not require any modifications as long as "Content-type: text/html", HTML header and footer are generated e. g. by using "echo" shell command(s) before and after the main program is invoked. To preserve the original formatting use "<pre>" tag.

Example

The program displays what the web browser sends to its standard input

HTML

<html><head><title>CGI primer</title>
<script language="JavaScript"> <!--
 function ChkBlank(FormField) {
  if(FormField.value == "") {
   alert("The input field is empty");
   return(false);
  }
  else {
   return(true);
  }
 }
//-->
</script>
</head>

<body><h1>CGI primer</h1>

<h2>Cut'n'paste input</h2>
 <form name="PrimTextForm" action="http://cosi-nms.sourceforge.net/cgi-bin/cgi_prim/cgi_prim.cgi" method="Post" onSubmit="return ChkBlank(document.PrimTextForm.InText);">
  <textarea name="InText" rows="5" cols="80"></textarea><br>
  <input type="reset" value="Reset"> <input type="submit" value="Analyse">

 </form>
<h2>Input by filename</h2>
 <form name="PrimFileForm" action="http://cosi-nms.sourceforge.net/cgi-bin/cgi_prim/cgi_prim.cgi" method="Post" enctype="multipart/form-data" onSubmit="return ChkBlank(document.PrimFileForm.InFile);">
  <input type="file" name="InFile">
  <input type="submit" value="Analyse">
 </form>

</body></html>

CGI

gdragon@sc8-pr-shell1:/home/groups/c/co/cosi-nms/cgi-bin/cgi_prim$ ls -al
total 12
drwxr-sr-x    2 gdragon  cosi-nms     4096 Mar 14 23:59 .
drwxrwsr-x    4 dummy    cosi-nms     4096 Mar 14 23:28 ..
-rwxr-xr-x    1 gdragon  cosi-nms      234 Mar 14 23:33 cgi_prim.cgi
gdragon@sc8-pr-shell1:/home/groups/c/co/cosi-nms/cgi-bin/cgi_prim$cat cgi_prim.cgi

#!/bin/sh
echo Content-type: text/html
echo
echo "<html><head><title>CGI primer</title></head>"
echo
echo "<body><h1>CGI primer</h1>"
echo "("
echo | date
echo ")<hr>"
echo "<pre>"
cat
echo "</pre>"
echo "</body>"
echo
echo "</html>"
gdragon@sc8-pr-shell1:/home/groups/c/co/cosi-nms/cgi-bin/cgi_prim$ echo "Test input string" | cgi_prim.cgi
Content-type: text/html

<html><head><title>CGI primer</title></head>

<body><h1>CGI primer</h1>
(
Sat Mar 15 02:06:06 PST 2003
)<hr>
<pre>
Test input string
</pre>
</body>

</html>
gdragon@sc8-pr-shell1:/home/groups/c/co/cosi-nms/cgi-bin/cgi_prim$

See Example in action

          * *
        *     *
     ||*       *||
     || *     * ||
    ||||  * *  ||||
..:||||||:....:||||||:..

Back to COSI Homepage

*If you would like to become a COSI developer, have questions, or need your group member permissions modified please contact Deborah