Using the CGI package, programmers can write scripts that run when invoked
by web servers using the Common Gateway Interface (CGI). SparForte's large feature
set and strong error checking make it ideal for writing web server applications.
Some functions will cause standard_input to be read. Some features of this
package are incompatible with gnat.cgi.
cgi.get_environment is not implemented: it is already available through
the command_line package.
The examples directory contains a script called minimal_cgi, a CGI script
that displays form variables.
procedure minimal_cgi is
-- Demonstrate SparForte's CGI interface
-- based on AdaCGI's minimal.adb example
-- To run this script directly (without a HTTP server), set the
-- environment variable REQUEST_METHOD to "GET" and the variable
-- QUERY_STRING to either "" or "x=a&y=b".
begin
cgi.put_cgi_header;
cgi.put_html_head( "Minimal Form Demonstration" ); if cgi.input_received then
cgi.put_variables; else
put_line( "<form method=" & ASCII.Quotation & "POST" & ASCII.Quotation &
ASCII.Quotation & "></form>" ); endif;
cgi.put_html_tail; end minimal_cgi;
Example: A CGI Package Example
To run it without a web server, define exported strings QUERY_STRING and
REQUEST_METHOD. If there is no information to process (QUERY_STRING is
an empty string) it will return a form, otherwise it will display the value
of the CGI variables.
Encode the string escaping illegal HTML characters. For example, '>'
becomes '>').
Example
safe_html := cgi.html_encode( "This is <illegal> HTML!"
Parameters
Param
Mode
Type
Default
Description
h
return value
string
required
the HTML-encoded string
s
in
string
required
the string to encode
Exceptions
-
See Also
-
Compare With
Ada: CGI.HTML_Encode
b := cgi.input_received
True if there HTTP GET or POST data was received by the script.
Example
if cgi.input_received then ...
Parameters
Param
Mode
Type
Default
Description
b
return value
boolean
required
true if there was input received
Exceptions
-
See Also
-
Compare With
Ada: CGI.Input_Received
b := cgi.is_index
True if an "IsIndex" request was made (a request with HTTP GET or
POST data without variable assignments).
Example
if cgi.is_index ...
Parameters
Param
Mode
Type
Default
Description
b
return value
boolean
required
true if a "IsIndex" request was made
Exceptions
-
See Also
-
Compare With
Ada: CGI.Is_Index
s := cgi.key( p )
Return the name of p-th HTTP GET or POST variable.
Example
first_variable := cgi.key( 1 );
Parameters
Param
Mode
Type
Default
Description
s
return value
string
required
the CGI variable name
p
in
positive
required
the variable position (1..cgi.argument_count).
Exceptions
An exception is raised if there is no variable at position p.
See Also
-
Compare With
Ada: CGI.Key
n := cgi.key_count( k )
Return the number of times the variable name (or name of a form field)
Example
-
Parameters
Param
Mode
Type
Default
Description
n
return value
natural
required
the number of occurrences
k
in
string
required
the variable to check
Exceptions
-
See Also
-
Compare With
Ada: Cgi.Key_Count
b := cgi.key_exists( k, i )
Return true if a HTTP GET or POST variable (a form field) exists
with the the given name.
Example
if cgi.key_exists( "credit_card_expiry_date", 1 ) then ...
Parameters
Param
Mode
Type
Default
Description
b
return value
boolean
required
true if the variable exists
k
in
string
required
the variable to check
i
in
string
required
which variable
Exceptions
-
See Also
-
Compare With
Ada: CGI.Key_Exists
n := cgi.key_value( p )
Return the value of the p-th HTTP GET or POST variable.
Example
first_value := cgi.key_value( 1 );
Parameters
Param
Mode
Type
Default
Description
s
return value
string
required
the variable value
p
in
positive
required
the position of the variable (1..cgi.argument_count)
Exceptions
An exception is raised if there is no variable at position p.
See Also
-
Compare With
Ada: CGI.Value (NOTE: a different name)
b := cgi.key_value_exists( v, s )
True if an HTTP GET or POST variable v has a value of s.
Example
if cgi.key_value_exists( "country", "US" ) then ...
Parameters
Param
Mode
Type
Default
Description
b
return value
boolean
required
true if the variable has the value
v
in
string
required
the CGI variable
s
in
string
required
the value to test for
Exceptions
-
See Also
-
Compare With
Ada: CGI.Key_Value_Exists
s := cgi.my_url
Return the URL of the script.
Example
script_url := cgi.my_url;
Parameters
Param
Mode
Type
Default
Description
s
return value
string
required
the URL of the script
Exceptions
-
See Also
-
Compare With
Ada: CGI.My_URL
l := cgi.line( s, p )
Return the p-th line of string s.
Example
second_line := cgi.line( address, 2 );
Parameters
Param
Mode
Type
Default
Description
l
return value
string
required
the line
s
in
string
required
the GET/POST variable value to get the line from
p
in
positive
required
the line number (1..cgi.line_count).
Exceptions
A bad line number raises an exception.
See Also
-
Compare With
Ada: CGI.Line
n := cgi.line_count( s )
Count the number of lines is value s, 0 if an empty string.
Example
if cgi.line_count( address ) > 4 then ...
Parameters
Param
Mode
Type
Default
Description
n
return value
natural
required
the number of lines (0 if null string)
s
in
string
required
the string to test
Exceptions
-
See Also
-
Compare With
Ada: CGI.Line_Count
n := cgi.line_count_of_value( v )
Count the number of lines in the value of variable v, 0 if an empty
Example
-
Parameters
Param
Mode
Type
Default
Description
n
return value
natural
required
the number of lines (0 if null string)
v
in
string
required
the CGI variable to test
Exceptions
-
See Also
-
Compare With
Ada: CGI.Line_Count_Of_Value
b := cgi.parsing_errors
True if there were errors parsing the data sent with HTTP GET or POST.
Example
if cgi.parsing_errors then ...
Parameters
Param
Mode
Type
Default
Description
b
return value
boolean
required
true if there were parsing errors
Exceptions
-
See Also
-
Compare With
Ada: CGI.Parsing_Errors
cgi.put_cgi_header( h )
Write the CGI header to current_output, including two carriage returns. This header determines the form of the program's reply (by default, an HTML document). A typical program would first call this function 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 automatically redirect someone to a different URL.
Example
cgi.put_cgi_header;
Parameters
Param
Mode
Type
Default
Description
h
in
string
Content-type: text/html
the CGI header to use
Exceptions
-
See Also
-
Compare With
Ada: cgi.put_cgi_header
cgi.put_error_message( s )
Write a short HTML document containing an error message. Use cgi.put_cgi_header
Example
-
Parameters
Param
Mode
Type
Default
Description
s
in
string
required
the error message
Exceptions
-
See Also
-
Compare With
Ada: CGI.Put_Error_Message
cgi.put_html_head( t, m )
Write a simple HTML header to current_output, including a title and
optional mailto link to the page author.
Return the value of an HTTP GET or POST variable (a form field).
If there are multiple variables with the same name, i will return the
ith value (starting from one). An exception will be raised when there
is no variable if b is true.
Example
username := cgi.value( "username" );
Parameters
Param
Mode
Type
Default
Description
s
return value
string
required
the value of the variable
v
in
string
required
the name of the variable
i
in
positive
1
which variable (1 = first)
r
in
boolean
false
raise an exception if missing variable
Exceptions
If b is true, an exception is raised if there is no variable.
See Also
-
Compare With
Ada: CGI.Value
l := cgi.value_of_line( v, p )
Return the p-th line of the value of CGI variable v.