This package is copyright (C) 1995 David A. Wheeler (wheeler@ida.org). You are free to use it in anything you wish without restriction or payment, but please provide credit if you use this package.
This Ada package provides two data access approaches from the CGI:
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 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?):
There are also a number of useful output functions:
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
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: