Ada 95 Binding to CGI

"Package CGI" is an Ada 95 interface to the "Common Gateway Interface" (CGI). This package makes it easier to create Ada programs that can be invoked by World-Wide-Web (WWW) HTTP servers using the standard CGI interface. Using it, you can create Ada programs that perform queries or other processing by request from a WWW user.

This Ada package provides two data access approaches from the CGI:

As an associative array; simply provide the key name (as a string) and the value associated with that key will be returned.
As a sequence of key-value pairs, indexed from 1 to Argument_Count. This access approach is similar to the Ada library Ada.Command_Line.

The main access routines support both Ada 95 types String and Unbounded_String.

The source files are available in zip format in file cgi.zip.

This documentation assumes that you are already familiar with the Common Gateway Interface (CGI) and HTML. To use this package you'll need to learn a little about Ada 95; the Lovelace Ada 95 tutorial provides one good way to do so.

Below are the following:

Details on the Ada 95 Binding to CGI.
A Minimal Example.
Contents of the CGI Distribution.
Related Information Sources.
Version Information.

Details on Ada 95 Binding to CGI

To use package CGI, "with CGI" in your Ada program. Package CGI will automatically load the CGI information when your Ada program begins executing. CGI handles both "GET" and "POST" forms of CGI data automatically. The form information from a GET or POST form is loaded into a sequence of variables; each variable has a Key and a Value. Package CGI transforms "Isindex" queries into a form with a single key (named "isindex"), and the key's value is the query value.

Once the main Ada program starts, it can make various calls to the CGI subprograms to get information or to send information back out.

A typical program using package CGI would first call "CGI.Put_CGI_Header", which tells the calling HTTP server what kind of information will be returned. Usually the CGI header is a reply saying "I will reply a generated HTML document", so that is the default of Put_CGI_Header, but you could reply something else (for example, a Location: header to refer to another file).

Most CGI programs handle various types of forms, and most should automatically reply with a blank form if the user hasn't provided a filled-in form. Thus, your program will probably call CGI.Input_Received, which returns True if input has been received (and otherwise it returns False). You should reply with a blank form if CGI.Input_Received is False.

You can then use various routines to query what data values were sent. You can query either by the name of a variable (what is the value of 'name'?) or by position (what was the first variable's key name and value sent?):

To query by variable name, use the "Value" function with the variable name as its parameter. Normally if the variable wasn't sent you'll just get an empty string back, but you can call Value with Required=>True to cause the exception Constraint_Error to be raised if the variable was not sent. To determine if given a key was sent, you can also use Key_Exists, which will return True if the given key was sent (and False otherwise). A given key can have more than one value; you can use the "Index" parameter to return the Nth value of a given key (the default is to return the first value). Function Key_Count will return how many values there are for a given key.
To query by position, use the "Value" function with a Positive to get that value and the "Key" function to get the variable name. For example, Value(1) is the value of the first variable and Key(1) is the name of the first variable. The number of values sent is stored in CGI.Argument_Count.

There are also a number of useful output functions:

Procedure Put_Variables is useful while debugging; it will cause all form values sent to be printed (in HTML format) to the Current_Output.
Procedure Put_HTML_Head will put out an HTML header. It is given a title and an optional Mail_To email address.
Procedure Put_HTML_Heading will put out an HTML heading (such as <H1 ...> Title </H1>).
Procedure Put_HTML_Tail will put out an HTML tail, (</BODY></HTML>).
Procedure Put_Error_Message will put an error message (including an HTML_Head, an HTML_Heading, and an HTML_Tail). Call "Put_CGI_Header" before calling this.

Function Get_Environment simply calls the underlying operating system and requests the value of the given operating system variable; this may be useful for acquiring less-often-used CGI values. If the variable does not exist, function Get_Environment replies with a null string ("").

Minimal Example

Here is a minimal example. Procedure "Minimal" always replies with an HTML document. If input is received, the document is simply a list of the variable values. If no input is received, procedure Minimal replies with a simple fill-in form:

with CGI, Text_IO; use CGI, Text_IO;

procedure Minimal is
-- Demonstrate CGI interface.

-- To run this program directly (without an HTTP server), set the
-- environment variable REQUEST_METHOD to "GET" and the variable
-- QUERY_STRING to either "" or "x=a&y=b".

begin
  Put_CGI_Header;   -- We will reply with a generated HTML document.
  Put_HTML_Head("Minimal Form Demonstration"; -- Output <H1>Minimal ..</H1>
  if CGI.Input_Received then  -- Check if input was received.
    Put_Variables;  -- Input received; show all variable values.
  else
    -- No input received; reply with a simple HTML form.
    Put_Line("<FORM METHOD=POST><INPUT TYPE=""submit"">Your data is: " &
             "<INPUT NAME=""fieldname""></FORM>");
  end if;
  Put_HTML_Tail;  -- End the HTML document, sending </BODY></HTML>
end Minimal;

Procedure Minimal is stored in file minimal.adb. A more sophisticated sample program is included in file demo.adb.

Contents of CGI Distribution

File cgi.zip is the distribution collection of package CGI. It contains the following files:

cgi.html      - Documentation for package CGI.
cgi-doc.htm   - A duplicate of cgi.html (see README for an explanation).
cgi.ads       - The Ada 95 package specification for CGI.
cgi.adb       - The Ada 95 package body for CGI.
minimal.adb   - A minimal demonstration of how to use CGI.
demo.adb      - A larger demonstration of how to use CGI.
makefile      - The makefile to compile demo and minimal using GNAT.
README        - A short list of the files.

Note: all of the text files are stored in Unix text file format. MS-DOS users will need to convert them to MS-DOS text file format (some MS-DOS text editors will do this automatically).

Related Information Sources

The current version of this Ada binding to CGI is available via the Public Ada Library (PAL). The PAL card catalog provides a nice general way to find Ada components (this binding is categorized as a "software component").
General information on CGI is available from the NSCA.
Package CGI is inspired by the perl CGI interface by Steven E. Brenner (S.E.Brenner@bioc.cam.ac.uk).
Another source of inspiration was the perl CGI interface by L. Stein.
A different method for interfacing binding Ada with CGI is to use the "Un-CGI" interface.
Many Ada resources are available through the Ada WWW server in Switzerland, including an on-line Ada 95 reference manual and a free on-line Ada 95 tutorial, Lovelace.
GNAT, a no-cost Ada 95 compiler, is available through New York University (NYU).
You can download an `unzip' program from the Info-ZIP archives, which has software to unzip files as well as create zip files (including both a free implementation and the shareware pkzip/pkunzip programs). The Info-ZIP archive index lists what files are available., An alternate (mirror) site for these zip format utilities is wuarchive.wustl.edu.

Version Information

This is version 1.3. Version 1.3 fixes a nasty bug in the low-level "getenv" routine, which kept this program from working on OS/2 and some other systems.

Version 1.2 added routines which get a Value and then get a Line or Line_Count all at once. The Ustrings package (used by the search demo) has had two minor changes: Put_Line to a designated file now works correctly (instead of putting to the current output), and Get_Line can read in a line up to the maximum length of an Unbounded_String.

Major additions in version 1.1 are:

Added Index parameter to Value(Key) so multi-valued keys could be handled. Also added Key_Count, which returns the number of values for a given key.
Added routines (Line and Line_Count) to help handle multi-line text values.

David A. Wheeler (wheeler@ida.org)