CGI-BIN TUTORIAL USING PASCAL



You can write your first CGI script, if you know some HTML and how to use an ftp program like Filezilla, within ten minutes.

A cgi-bin program runs when called by a web page on a web server. The result (output) of the cgi-bin program is sent to the browser which displays it. What is sent is simply text with html as you will see.
A cgi-bin program placed in a cgi-bin directory of a webserver does not require any special suffix. However the extension required for a cgi-bin program in a user's directory will be '.cgi' for it to be able to be executed. Setting the READ and EXECUTE attribute for OTHERS is normally required too (chmod go+rx file.cgi for those on a Unix/Linux system but you can do the same with an ftp client). Script and program for this tutorial mean the same thing.
To recapitulate: whenever a cgi-bin script or program is called, the web server executes it, and puts in its place the result of the execution (the output). The browser will receive and display the resulting HTML or even an image (if just an image is sent, preceded by the particular content-type).
To call a cgi-bin script, there is more than one way. If we know we will simply output text we would use a special HTML tag (actually an SSI directive tag) in the html. The browser requests the page while the web server replaces this tag with the result of executing the cgi-bin script.

If you are in control of your own webserver (or have virtual hosting), then typically you will place your cgi-bin executable (renamed with *.cgi instead of *.exe on a Windows server, and with the added *.cgi suffix if you are on a Linux or Unix server) within the system-wide cgi-bin directory. If you are a unix user then you have to check with your administrator. An example configuration requires you to have a cgi-bin directory within your public_html, and then you may place your executables there.

Step 1 in writing a cgi-bin program is outputting a MIME-type header. This is an HTTP header which informs the client (browser) what sort of content will be received. This will in general look like:


       Content-type: text/html


Step 2 is to write output in html or any format which a browser is capable of displaying. (for instance: If you are sending an image directly, then you would send the image data itself - e.g a program which outputs a jpeg image.)

Your first cgi-bin program

Program first;
Begin
  Writeln('Content-type: text/html');
  Writeln;
  Writeln('Hello World!');
End.
Compile it and place it in your cgi-bin directory, calling the executable first.cgi. Call it using your browser:
http://your.web.server/cgi-bin/first.cgi
(in the case of a user account: http://your.web.server/~username/cgi-bin/first.cgi)


You will see the one line Hello World! on your browser. This was your first step in the world of cgi-bin.

To improve it, start writing html code within Writeln statements e.g. Writeln('<html><head><title>this is a title</title></head>'); followed by Writeln('<body><h1>Hello World</h1></body></html>');

There are 4 things that you can see when you output from a cgi-bin program:
  1. Your program's output - then everything went fine.
  2. A "POST method not allowed" or the executable itself is attempted to be downloaded (for a source language like perl, this would display the source code of your program, but it's different for Pascal) - this means the webserver requires configuration.
  3. A message saying "forbidden" - this is a permissions problem. Check the execute permissions of the file. Permissions should be RWXR-XR-X. The server does not run as you so the 'other' part of the file permissions are important.
  4. A message saying "internal server error" - within the Apache server log you might find "premature end of script headers" too with an error generated by your cgi program - check what might be stopping your program from emitting proper HTTP headers.

Environment variables are values that are "provided" to you as you use your computer. They contain useful information like your path (where the computer searches for a file when you type a command), your login name, your terminal type, and so on. To get a complete list of your normal environment variables, type env or set at a unix/linux shell prompt.
During the CGI transaction, the server and the browser also set environment variables, so that they can communicate with one another. They set information such as the browser type (Mozilla, Netscape, IE, Lynx), the server type (Apache, IIS, Roxen, WebSite), the name of the CGI program that is being run, and so on.

These variables are available to the CGI programmer as part of client-server communication. The complete list of required variables may be found http://hoohoo.ncsa.uiuc.edu/cgi/env.html.
In Pascal we may use GetEnv from the Dos unit to retrieve these environment variables. Look up your online-help (even the BP7 help example for GetEnv can be used) or any other standard GetEnv example to see how to retreive a CGI-BIN environment variable.

Tutorial, XHTML © Clyde Meli, 2004.