[SparForte][Banner]
[Top Main Menu] Intro | Tutorials | Reference | Packages | Examples | Contributors   [Back Page]      [Next Page]  

Cgi Package

The SparForte CGI package is based on and uses David A. Wheeler's AdaCGI package. It provides form processing, string encoding, and cookie operations.

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 &
 
       ">What's your name?<input name=" & ASCII.Quotation & "username" &
       ASCII.Quotation & "><input type=" & ASCII.Quotation & "submit" &
 
       ASCII.Quotation & "></form>" );
  end if;
  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.

=> QUERY_STRING : string := ""
=> pragma export( shell, QUERY_STRING )
=> REQUEST_METHOD : string := "GET"
=> pragma export( shell, REQUEST_METHOD )
=> spar examples/minimal_cgi.sp
content_type: text/html
 
<html><head><title>Minimal Form Demonstration</title>
</head><body>
<form method="POST">What's your name?<input name="username"><input type="submit"></form>
</body></html>
 
=> QUERY_STRING : string := "x=a&y=b"
=> spar examples/minimal_cgi.sp
content_type: text/html
 
<html><head><title>Minimal Form Demonstration</title>
</head><body>
<pre>
 
<b>x</b>: <i>a</i>
<b>y</b>: <i>b</i>
</pre>
 
</body></html>
 

Example: Running a CGI Script from the Command Line

The CGI package uses the standard Ada types except for one additional enumerated type:

  • type cgi.cgi_method_type is (cgi.get, cgi.post, cgi.unknown); -- the form posting method

To use cgi_method_type or its elements, prefix the items with "cgi." as you would with any other package declaration.

n := cgi.argument_count

 

Return the total number of variables, including duplicates with the same name.

Example

-

Parameters

Param Mode Type Default Description
n return value natural required the number of variables

Exceptions

-

See Also

-

Compare With

Ada: CGI.Argument_Count

m := cgi.cgi_method

 

Identify the CGI standard that was used to communicate with the script (cgi.get, cgi.post or cgi.unknown).

Example

-

Parameters

Param Mode Type Default Description
m return value cgi.cgi_method_type required the method

Exceptions

-

See Also

-

Compare With

Ada: CGI.Cgi_Method

n := cgi.cookie_count

 

Return the number of cookies.

Example

for i in 1..cgi.cookie_count loop ...

Parameters

none

Exceptions

-

See Also

cgi.cookie_value
cgi.set_cookie

Compare With

Ada: CGI.Cookie_Count

s := cgi.cookie_value( c [, p] )

 

Get the value of p-th instance of cookie c.

Example

cookie := cgi.cookie_value( "date_visited" );

Parameters

Param Mode Type Default Description
s return value string required the cookie value
c in string required the cookie name
p in positive 1 the instance of the cookie name

Exceptions

-

See Also

cgi.set_cookie
cgi.cookie_count

Compare With

Ada: CGI.Cookie_Value

h := cgi.html_encode( s )

 

Encode the string escaping illegal HTML characters. For example, '>' becomes '&gt;').

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.

Example

-

Parameters

Param Mode Type Default Description
t in string required the page title
m in string no mailto the email address of the author

Exceptions

-

See Also

-

Compare With

Ada: CGI.Put_HTML_Head

cgi.put_html_heading( s, l )

 

Write a simple HTML <h1> to <h6> heading.

Example

cgi.put_html_heading( "OmniCorp Sales Statistics", 1 )

Parameters

Param Mode Type Default Description
s in string required the heading text
l in positive required the heading level (1..6)

Exceptions

-

See Also

-

Compare With

Ada: CGI.Put_Html_Heading

cgi.put_html_tail

 

Complete an HTML document by writing "</body></html>" to current_output.

Example

cgi.put_html_tail

Parameters

none

Exceptions

-

See Also

-

Compare With

Ada: CGI.Put_HTML_Tail

cgi.put_variables

 

Display the HTTP GET or POST variables in HTML format. Use for debugging.

Example

cgi.put_variables

Parameters

none

Exceptions

-

See Also

-

Compare With

Ada: CGI.Put_Variables

cgi.set_cookie( v, s, x, p, d, b )

 

Set a cookie's properties. Call this before Put_CGI_Header.

Example

cgi.set_cookie( "last_visit", "none" );

Parameters

Param Mode Type Default Description
v in string required the cookie name
s in string required the cookie value
x in string none the expiry date
p in string PATH_INFO value the cookie path
d in string SERVER_NAME value the domain value
b in boolean false true if secure

Exceptions

-

See Also

cgi.cookie_count
cgi.cookie_value

Compare With

Ada: CGI.Set_Cookie

s := cgi.url_decode( u, b )

 

Decode HTML-encoded %HH hexadecimal characters into their corresponding

Example

-

Parameters

Param Mode Type Default Description
s return value string required the decoded string
u in string required the URL-encoded string
b in boolean true translate plus signs to spaces if true

Exceptions

-

See Also

cgi.url_encode

Compare With

Ada: CGI.URL_Decode

u := cgi.url_encode( s, b )

 

Encode the string using %HH hexadecimal characters. If b is true, translate plus signs to spaces.

Example

encoded_url := cgi.url_encode( s );

Parameters

Param Mode Type Default Description
u return value string required the URL-encoded string
s in string required the string to encode
b in boolean true translate plus signs to spaces if true

Exceptions

-

See Also

cgi.url_decode

Compare With

Ada: CGI.URL_Encode

s := cgi.value( v, i, b )

 

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.

Example

second_line := cgi.line( "address", 2 );

Parameters

Param Mode Type Default Description
l return value string required the line
v in string required the CGI variable 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.Value_Of_Line

 
[Right Submenu]

 Summary

 arrays

 btree_io

 calendar

 cgi

 chains

 command_line

 db/ postgresql

 dbm

 directory_operations

 doubly_linked...

 dynamic_hash_...

 enums

 exceptions

 files

 gnat.cgi

 gnat.crc32

 hash_io

 lock_files

 memcache

 memcache.highread

 mysql

 mysqlm

 numerics

 os

 pen

 pen (OpenGL)

 records

 sound

 source_info

 stats

 strings

 System

 teams

 templates

 text_io

 units

[Back to Top] Back To Top [Small Forte Symbol]