CGI Tutorial
This is a fragment which I leave here to provide beginners with a basic idea. There are quite a lot of good tutorials available for learning the basics of writing CGI-scripts or programs. More concrete information about Modula-2 and the Common Gateway Interface is available at Jan Verhoevens Modula-2 pages. You may also be interested in Web Family Tree, a freeware program by Peter J. Moylan that permits you to display your family tree in a web browser. It is a Modula-2 program using the common gateway interface. The source code is available.
If you want to have a look at the output of a simple Modula-2 CGI program wich can be written after learning from this tutorial click here.
[ top ] Introduction
As you may know, CGI is most times recognized as an interface used by scripting-languages. Perl, PHP and Python are the most common used languages in this context. They offer more than enough power and flexibility for nearly every task you'd like to manage. In a lot of cases it will be easier to use them instead of a compiled language. Some people familiar to Pascal or another language designed by Niklaus Wirth are simply distracted from these languages because they don't have the time to learn another language or they just want to get things done using their preferred language. The Common Gateway Interface gives you the freedom to use nearly every compiler or interpreter available. Before you try the basics described below just check your preferred compiler for two things - (1) is it able to read environment variables and (2) can it handle standard in- and output?
I used different Modula-2 compilers to run my programs, developing a simple database with a web based user interface I used the XDS-Modula-2 compiler - most other Modula-2 compilers can be used. Just try to copy the executables to the right directory and keep in mind you have to compile for the operating system your server uses.
[ top ] Getting Started
Before I begin to explain the basics of CGI, you should download a www-server to test your first programming approaches without uploading them to the web. As there are a lot of things possibly running out of control because of small mistakes I recommend you do such an installation. It does not do any harm to your existing internet-setup(s). And by the way: If you think of a server as an incredible huge program - have a look. And it's even not as small as it can get.
Here are a few links to download free server-software:
- http://www.apache.org
Apache Web Server: standard, free, lots of possibilities - http://www.roxen.com
Roxen Server: free, highly configurable, small - http://www.imatix.com/
Xitami Server: free, fine HTML-interface, my favorite - There also is XAMPP, an easy to install Apache distribution containing MySQL, PHP and Perl. Binaries for Windows, Linux, Solaris and Mac OS X are available. The packages are quite large ones but you get an installation which works out of the box.
[ top ] A First Program
Now we'll jump into it by having a look at a simple program, that does absolutely nothing except reading one of the predefined CGI-environment variables. It does not process any information sent to the server by a user. The variable used here is called GATEWAY_INTERFACE and holds the version number of the CGI used by your server (If you want to have a look at a list of predefined CGI-variables, follow this link). The code is not beautiful Modula, but it shows a few things very well.MODULE test_cgi;
FROM InOut IMPORT WriteString, WriteLn;
FROM ProgEnv IMPORT String; (* line 3 *)
TYPE aString = ARRAY [0 .. 255] OF CHAR;
PROCEDURE ReadEnvVar;
VAR Value: aString;
BEGIN
WriteString("Content-type: text/html");
WriteLn;WriteLn;
WriteString("<table border=1 width=80% align=center cellpadding=4>");
String("GATEWAY_INTERFACE",Value);
WriteString("<tr><td>GATEWAY_INTERFACE:</td>");
WriteString("<td>");
WriteString(Value);WriteString("</td></tr>");
WriteString("</table>");
END ReadEnvVar;
BEGIN
WriteString("<html><body><h3 align=center>cgi compiled with XDS Modula-2</h3>");
ReadEnvVar;
WriteString("</body></html>");
END test_cgi.
First have a look at line 3: the imported procedure String is essential to programming the CGI. The corresponding procedures for other compilers are:
- M2F and GNU Modula-2: Environment.def,
PROCEDURE GetEnvironment(Env: ARRAY OF CHAR; VAR a: ARRAY OF CHAR) : BOOLEAN; - XDS Modula-2: ProgEnv.def,
PROCEDURE String(name: ARRAY OF CHAR; VAR str: ARRAY OF CHAR); - ADW Modula-2: Environment.def,
PROCEDURE GetSymbol(name : ARRAY OF CHAR; VAR OUT result : ARRAY OF CHAR) : BOOLEAN; - GPM: ProgArgs.def,
PROCEDURE EnvironString(inStr :ARRAY OF CHAR; VAR outStr :ARRAY OF CHAR); - MOCKA: Arguments.md,
PROCEDURE GetEnv(VAR env: ArgTable); - FST 4.0: System.def,
PROCEDURE GetEnv(var :ARRAY OF CHAR; VAR val :ARRAY OF CHAR ); [this is only for completeness: FST is a pure dos-compiler - I've never heard of a Server running dos...]
http://127.0.0.1:1080/cgi-bin/test_cgi.exe
[ top ] Getting User Input
As the program we wrote just demonstrates we have a working environment, we'll move on and have a look at processing user-input from a html-form. The easy example below uses "method get" to send a simple string to the cgi-program. This method puts the user-input in the environment-variable "QUERY_STRING". You can read the contents of this var as shown above. But first we'll have to write this simple html-file:
<html><head><title>simple input</title></head><body>
<form action="http://127.0.0.1:1080/cgi-bin/user_dta.exe" method="get">
your input:<input name="eingabe" type="text" size="30" maxlength="30">
</form></body></html>
This provides a simple input-field and tells the browser to send the user-input to the program located at http://127.0.0.1/cgi-bin/ - this may differ on your machine, it depends on how you set up your server (In this case the server runs on my local machine and uses port 1080).
Now we have to write the code for the called program "user_dta.exe" (or for example "user_dta.cgi" under Linux). Again, you only need to import String and WriteString, the program simply returns the user input in a dynamically generated super-simple html-page:
MODULE user_dta;
FROM InOut IMPORT WriteString;
FROM ProgEnv IMPORT String;
TYPE aString = ARRAY [0 .. 255] OF CHAR;
PROCEDURE OutputData;
VAR UserInput: aString;
BEGIN
String("QUERY_STRING",UserInput);
WriteString("<p align=center>here's your unprocessed input: ");
WriteString(UserInput);WriteString("</p>");
END OutputData;
BEGIN
WriteString("Content-type: text/html");
WriteLn;WriteLn;
WriteString("<html><body><h3 align=center>cgi compiled with XDS-Modula-2</h3>");
OutputData;
WriteString("</body></html>");
END user_dta.
That's it. You can do whatever you want with the data sent to you.
[ top ] Modula-2 and CGI
What about modules? What's happened to the great features of Modula-2? Why should I use it with the Common Gateway Interface? Let's move on. We now have to do some more simple work after wich we'll write a more complex routine to do the URL-decoding. After that we'll concentrate on putting together some reusable modules. One for html-output, one for applying CSS to our dynamically generated pages, another one for cgi-specific routines.
For a start I think it's quite a good idea to create our first package. As you may know you have to create two files: one for the specification, another one for the implementation. Let's call these two files 'M2_CGI.def' and 'M2_CGI.mod'.
The Specification with the declaration of a first procedure:
DEFINITION MODULE M2_CGI;
PROCEDURE CGI_Header;
END M2_CGI.
And the implementation-part:
IMPLEMENTATION MODULE M2_CGI;
PROCEDURE CGI_Header;
WriteString("Content-type: text/html");
WriteLn;WriteLn;
END CGI_Header;
END M2_CGI.
You already know the procedure we just defined and 'implemented' - it outputs just a short header to the client (usually your browser), so the client knows what information will follow - here this is output of type text/html. You have to call this procedure every time before doing anything else from a CGI-program. Would be slightly illogical to write another procedure before this one...
