[BUSH User Guide]
 
Home Page Introduction Tutorials Reference Packages Hacking
 
  Packages  
4.1 Using Packages
4.2 text_io (Console I/O)
4.3 text_io (File I/O)
4.4 sound
4.5 source_info
4.6 System
4.7 numerics
4.8 strings
4.9 command_line
4.10 lock_files
4.11 cgi
4.12 calendar
4.13 units
4.14 arrays
4.15 files
4.16 db (Database)
4.17 stats
4.18 pen
4.19 mysql
4.20 os
4.21 directory_operations
 
This part of the guide contains detailed descriptions of the BUSH built-in packages.
 

4.11 cgi Package

The BUSH 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). Bush's large feature set and strong error checking make it ideal for writing web server applications.

The examples directory contains a script called minimal_cgi, a CGI script that displays form variables.

procedure minimal_cgi is
  -- Demonstrate Bush'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;
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 )
=> bush examples/minimal_cgi.bush
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>
</body7gt;</html>
=> QUERY_STRING : string := "x=a&y=b"
=> bush examples/minimal_cgi.bush
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>
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.


b := cgi.parsing_errors

True if there were errors parsing.
Example: if cgi.parsing_errors then ...
Ada Equivalent: CGI.Parsing_Errors
Parameters:
b return value boolean required true if there were parsing errors


b := cgi.input_received

True if there were CGI variables passed to the script.
Example: if cgi.input_received then ...
Ada Equivalent: CGI.Input_Received
Parameters:
b return value boolean required true if there was input received


b := cgi.is_index

True if an "IsIndex" request was made.
Example: if cgi.is_index ...
Ada Equivalent: CGI.Is_Index
Parameters:
b return value boolean required true if a "IsIndex" request was made


m := cgi.cgi_method

Identify the CGI standard that was used to communicate with the web server.
Example: if cgi.cgi_method = cgi.get then ...
Ada Equivalent: CGI.CGI_Method
Parameters:
m return value cgi.cgi_method_type required the method (cgi.get, cgi.post or cgi.unknown)


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

Return the value of a CGI variable (a form field).
Example: username := cgi.value( "username" );
Ada Equivalent: CGI.Value
Parameters:
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 match, 2 = second match, etc.)
r in boolean false if true, an exception will be raised if the variable is missing, otherwise an empty string is returned


b := cgi.key_exists( v )

Return true if a CGI variable (a form field) exists.
Example: if cgi.key_exists( "credit_card_expiry_date" ) then ...
Ada Equivalent: CGI.Key_Exists
Parameters:
b return value boolean required true if the variable exists
v in string required the variable to check


n := cgi.key_count( v )

Return the number of times the variable name (or name of a form field) occurs.
Example: for k in 1..cgi.key_count( "phone_number" ) loop ...
Ada Equivalent: CGI.Key_Count
Parameters:
n return value natural required the number of occurrences
v in string required the variable to check


n := cgi.argument_count

Return the total number of variables, including duplicates with the same name. occurs.
Example: for k in 1..cgi.argument_count loop ...
Ada Equivalent: CGI.Argument_Count
Parameters:
n return value natural required the number of variables


s := cgi.key( p )

Return the name of pth CGI variable.
Example: first_variable := cgi.key( 1 );
Ada Equivalent: CGI.Key
Parameters:
s return value string required the CGI variable name
p in positive required the variable position (1..cgi.argument_count). A bad value will raise an exception.


n := cgi.key_value( p )

Return the value of the pth CGI variable.
Example: first_value := cgi.key_value( 1 );
Ada Equivalent: CGI.Value (NOTE: a different name)
Parameters:
s return value string required the variable value
p in positive required the position of the variable (1..cgi.argument_count)


b := cgi.key_value_exists( v, s )

True if a CGI variable v has value s.
Example: if cgi.key_value_exists( "country", "US" ) then ...
Ada Equivalent: CGI.Key_Value_Exists
Parameters:
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


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).
Example: first_value := cgi.key_value( 1 );
Ada Equivalent: CGI.Value (NOTE: a different name)
Parameters:
h in string Content-type: text/html the CGI header to use


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: cgi.put_html_head( "Search results", "itdept@yourorg.com" )
Ada Equivalent: CGI.Put_HTML_Head
Parameters:
t in string required the page title
m in string no mailto the email address of the author


cgi.put_html_heading( s, l )

Write a simple HTML <h1> to <h6> heading.
Example: cgi.put_html_heading( "OmniCorp Sales Statistics", 1 )
Ada Equivalent: CGI.Value (NOTE: a different name)
Parameters:
s in string required the heading text
l in positive required the heading level (1..6)


cgi.put_html_tail

Complete an HTML document by writing " to current_output.
Example: cgi.put_html_tail;
Ada Equivalent: CGI.Put_HTML_Tail;
Parameters:
none


cgi.put_error_message( s )

Write a short HTML document containing an error message. Use cgi.put_cgi_header first.
Example: cgi.put_error_message( "the disk is full" )
Ada Equivalent: CGI.Put_Error_Message
Parameters:
s in string required the error message


cgi.put_variables

Display the CGI variables in HTML format. Use for debugging.
Example: cgi.put_variables;
Ada Equivalent: CGI.Put_Variables;
Parameters:
none


s := cgi.my_url

Return the URL of the script.
Example: script_url := cgi.my_url;
Ada Equivalent: CGI.My_URL
Parameters:
s return value string required the URL of the script


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 ...
Ada Equivalent: CGI.Line_Count
Parameters:
n return value natural required the number of lines (0 if null string)
s in string required the string to test


n := cgi.line_count_of_value( v )

Count the number of lines in the value of variable v, 0 if an empty string.
Example: if cgi.line_count_of_value( address ) > 4 then ...
Ada Equivalent: CGI.Line_Count_Of_Value
Parameters:
n return value natural required the number of lines (0 if null string)
v in string required the CGI variable to test


l := cgi.line( s, p )

Return the pth line of string s.
Example: second_line := cgi.line( address, 2 );
Ada Equivalent: CGI.Line
Parameters:
l return value string required the line
s in string required the CGI variable value to get the line from
p in positive required the line number (1..cgi.line_count). A bad value raises an exception.


l := cgi.value_of_line( v, p )

Return the pth line of the value of CGI variable v.
Example: second_line := cgi.line( "address", 2 );
Ada Equivalent: CGI.Value_Of_Line
Parameters:
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). A bad value raises an exception.


s := cgi.url_decode( u, b )

Decode HTML-encoded %HH hexadecimal characters into their corresponding ASCII characters. If b is true, translate plus signs to spaces.
Example: s := cgi.url_decode( encoded_url );
Ada Equivalent: CGI.URL_Decode
Parameters:
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


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 );
Ada Equivalent: CGI.URL_Decode
Parameters:
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


h := cgi.html_encode( s )

Encode the string escaping illegal HTML characters. For example, '>' becomes >).
Example: safe_html := cgi.html_encode( "This is <illegal> HTML!" );
Ada Equivalent: CGI.HTML_Encode
Parameters:
h return value string required the HTML-encoded string
s in string required the string to encode


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" );
Ada Equivalent: CGI.Set_Cookie
Parameters:
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


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

Get the value of pth instance of cookie c.
Example: cookie := cgi.cookie_value( "date_visited" );
Ada Equivalent: CGI.Cookie_Value
Parameters:
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


n := cgi.cookie_count( c [, p] )

Return the number of cookies.
Example: for i in 1..cgi.cookie_count loop ...
Ada Equivalent: CGI.Cookie_Count
Parameters:
s return value natural required the number of cookies

cgi.get_environment is not implemented: it is already available through the command_line package.

 Back to Top