CGI executable 'testCGI' written with Mocka

Nothing beats an example. This is my first CGI executable, written in Modula-2 and compiled for Linux. Although it also runs on a server running FreeBSD.
The file is called 'testCGI' and it does just that. It lists all the environment variables that belong to the CGI system on the server it is installed on.

'testCGI' was written with the Mocka Modula-2 compiler. This results in clear sources and fast execution since this is not an interpreted language. OK, the executable is slightly bigger than a few lines of Perl, but a compiled executable is tamperproof. You can only change it if you know:

Modula-2
Mocka
the CGI specification

I consider Perl a 'write-only' language. If you aren't experienced in it, you cannot read or understand it. And I dare say that everyone can read and even understand a Modula-2 source. Clarity above all.

      
MODULE testCGI;

FROM  InOut	  IMPORT  WriteCard, WriteLn, WriteString, WriteBf;
FROM  Arguments   IMPORT  ArgTable, GetEnv;
FROM  Strings	  IMPORT  Assign, Length;


TYPE aString = ARRAY [0 .. 511] OF CHAR;


VAR  EnvVars		 : ArgTable;


PROCEDURE ReadEnvVar;

VAR   Value	     : aString;
      i		     : CARDINAL;

BEGIN
   WriteString ('<table border="1" width="80%" align="center" cellpadding="4">');
   i := 0;
   LOOP
      IF  EnvVars^ [i] = NIL  THEN  EXIT  END;
      Assign (Value, EnvVars^ [i]^);
      WriteString ("<tr><td>");
      WriteCard (i, 4);
      WriteString (' :  [');          WriteCard (Length (Value), 4);
      WriteString ('] </td><td>');    WriteString (Value);
      WriteString ("</td></tr>");
      WriteLn;
      INC (i)
   END;
   WriteString("</table>");
END ReadEnvVar;


BEGIN
   GetEnv (EnvVars);
   WriteString ('Content-type:text/html');
   WriteLn;
   WriteLn;
   WriteString ('<html><head>');
   WriteString ('<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">');
   WriteString ('</head><body>');
   WriteString ('<h3 align=center><tt>cgi compiled with Mocka Modula-2</tt></h3>');
   ReadEnvVar;
   WriteString ('</body></html>');
   WriteBf;
END testCGI.

You can run 'testCGI' in a terminal to list the Unix environment variables (although it will be a bit tough to read, try it!) but it was meant to explore the environment variables that are active when you're browsing the web.
These environment variables are then the CGI (Common Gateway Interface) variables. They enable the browser to communicate with the (remote) server and exchange data.

The 'testCGI' program gets these environment variables from the operating system and prints them one by one in the active window of your web browser. To make reading a bit easier, testCGI exports it's data in HTML format so the browser will print a two column table.

testCGI is fully based upon the operation of 'GetEnv' (qv). The GetEnv program (called 'trye') just prints characters to the user console. But we're in HTML country now so we'd better fit in with the rest.
So I made 'testCGI' to deliver HTML data to be interpreted by a browser. In order to facilitate this, there are some STRICT rules that 'must' be followed to the letter:

Tell the browser what's coming up
Issue two linefeeds
Send the HTML data

Skip one linefeed and the program will execute but nothing will be printed in your browser. Also the position of the 'upcoming format' identifier is crucial. Anything before it, will be ignored.

This is a Modula-2 program, so if you know some english, you can at least read the sources and understand 90% of it's operation. In order to fully understand the flow of execution of the program for those 10%, I will explain in some more detail below:

In the 'FROM...' section we import predefined functions from libraries we made earlier, or that came with the compiler.
In the 'TYPE' section we declare a new kind of varaiable to be used in the program. Modula-2 is very picky about comparing apples and pears, so it wants the programmer to be very explicit. Which is why most half-baked programmers prefer C.
Next we define a global (i.e. program-wide) variable that will hold the environment data table. 'ArgTable is a TYPE that was defined in a Mocka specific library.
Now is the time to declare a function or procedure that does the line by line printing of environment variables.
This PROCEDURE will use two variables which are unique to this function ('Value' and 'i').
We start the function with printing how our table has to look like. We do so with normal HTML codes.
Then we initialize the 'i' variable to zero.
Now we start an infinite loop (between the words 'LOOP' and 'END') which does the following:
- At the last entry of the CGI environment table, exit the infinite loop
- Assign element 'i' of the environment table to variable 'Value'
- Open a table row/cell
- Write out which element this is; use 4 places
- Write some tokens and the length of this variable
- End current table cell and open next table cell
- Write out the value of the environment string
- End the table cell/row
- Advance one line up
- Increment variable i by one
- Restart the infinite LOOP
We end the table to conclude this procedure.
What follows is the actual 'main' routine of testCGI. This is the actual executable which is defined here.
We instruct the system to fetch the (CGI) environment variable and to store them in the 'ARRAY' called "EnvVars"
We tell the browser what kind of data is coming up
Issue two linefeeds (i.e. one blank line)
Set up the HTML document just as if you were using an editor
Call the PROCEDURE 'ReadEnvVar' to do the row by row filling of the on-screen table.
Close the HTML page
Instruct Unix to flush the outgoing buffers
And the program ends here

What you saw here is a typical Modula-2 programsource. It does what it says. Sometimes you need to get used to the abbreviations, but the language is clear from moment one. Compare that to Perl. An impossible language to learn due to the intensely obscure syntax.

You can download the sources and the executable for 'testCGI' in the download section (see navigator frame on the right). The source is handy for studying this program and can be printed well with soup and emit (consult navigator frame).
You will need to do the following if you want to run the 'testCGI' executable in a Unix environment:

Unpack the tar.gz file	gzip -d testcgi.tar.gz tar xvf testcgi.tar
for testing the executable	chmod 755 testCGI testCGI
for running the CGI 'script'	su root <enter password> cp testCGI /var/www/cgi-bin/ exit <start your browser> surf to 'http://yourserver/cgi-bin/testCGI'

This last command may be different between Linux verions and flavours. This data is valid for Slackware 8.0 but your milage may vary.

What use is a bicycle in the shed? Nothing. You need to ride it to make it worth the effort of making it.
Same with this testCGI executable. You need to run it. Not on your own computer, but out there, in the harsh world of the internet. So I put it on-line at my webhost.
One remark however: testCGI is an executable, not a script. So it will only run on a server running Linux. If your webhost runs under Windows, you cannot run testCGI. You could try, but chances are you will halt this magnificent Windows computer...

Nuf said. Time to act. The following steps were taken by me to get testCGI online and working:

ncftp
open connection
cd to directory
put testCGI
chmod 755 testCGI
close
exit

Keep in mind that I run Slackware Linux and my favorite ftp program is ncftp. After connection, it's just like you're running 'bash' at a remote host.

If you want to check it out, run the script in your browser (I will open a new window for your convenience): run testCGI now via my webhost: http://verhoeven272.nl/cgi-bin/testCGI.
If you are running this on a local machine, like I do when debugging, run it local via http://192.168.56.4/cgi-bin/testCGI.

Now you can also do some tests with the commandline of a CGI script. In the URL window, add the following strings after '/testCGI' and watch how the output changes:

?123456
?I am lazy
?I%20am%20lassie
?UnixTime
?Unix&Time?Show

See what happens? Pay special attention to the lower part of the table. In my case, it's options 21 and 22. What's the hassle with the '%20'? Are you lassie? :o)

By now you should have the knack of CGI operation and production. If I can do it in Modula-2, it should be a snap to do a comparable thing with gcc.
But keep in mind that we do NOT make scripts that are interpreted on all platforms. We make executables that will only run on the platform it was developed for. In my case: Linux.

Have fun with the experiments. Come back now and then to see what I added to the CGI events.

Page created on August 25, 2004.

Page equipped with FroogleBuster technology