Business Shell (BUSH) Guide
Author: Ken Burtch

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