next up previous contents index
Next: 9. SQL Query Tool Up: Ovrimos version 3.0 On-line Previous: 7. Administrator's Console

Subsections

   
8. The HTTP server

8.1 Overview

This chapter explains how you can perform certain tasks on the HTTP server of a database and associates these tasks with the server's features.

The HTTP server, or in other words, the Web server , which is active per database, should be differentiated from Database Manager's Web server. The latter is only used for providing a user interface for the dbman.

  
8.2 Ovrimos URL-space

The Web is based on client/server communication. One of the protocols used in communication is HTTP (HyperText Transport Protocol) which specifies what type of communication and information is sent between them.

In HTTP, resources   (network and data objects and services) are denoted by URLs  and form a URL-space, in a similar way as Files are denoted by pathnames and reside in a file system. The Ovrimos URL-space can be partinioned along three independent axes: static/dynamic, internal/external, and database-specific/shared.

  static dynamic

  internal external internal external
dbase-specific   $\surd$ $\surd$ $\surd$
shared   $\surd$   $\surd$

   
8.3 Static Web Content

Static resources  are data files sent directly to the client. Static resources are always external. At your browser's request the Web server can serve up, for example, an HTML file or an image file from the directories where the Web resources are stored. Web resources shared by all databases are located in the $HTTPSHAREDDIR while the resources used only by a specific database are placed in the $HTTPROOTDIR. For example, we assume that you have prepared a Web page with sales information about the available products of your company. When the users of the database products request this page, the Web server first looks for it in the $HTTPROOTDIR and then in the $HTTPSHAREDDIR.

   
8.4 Dynamic Internal Resources

Dynamic internal resources, such as the system's tables accessed by Roadmap, do not correspond to anything outside the server. Each dynamic internal resource is mapped to a URL, so when this URL is requested, the associated Ovrimos code is executed. For example SQL Terminal which is mapped to /sqlterminal, can be accessed as shown in the example.

Example:
Start a database and request the following URL:
http://<servername>:<HTTP port number>/sqlterminal

Similarly the special URLs relating to Roadmap and Administrator Console are /roadmap and /console correspondingly.

  
8.5 Dynamic External Resources

Dynamic external resources are a powerful tool in the hands of users. They permit external Web content to be incorporated in the URL-space of an Ovrimos database. External Web content can either be the output of a program executing in a CGI 1.2 environment, of a Scheme script or of an SQL script, as explained in the following sections.

Last but not least, it should be noted that the dynamic external resources shared by all databases are located in the $HTTPSHAREDDIR, while those used only by a specific database are in the $HTTPROOTDIR.

  
8.5.1 SQL Scripts

The client program (a Web browser) can request an SQL script and the HTTP server can supply its output, after the script has been executed by SQL Query Tool. This feature is explained in detail in section 9.6.

   
8.5.2 Scheme Scripts

A Scheme interpreter , embedded in Ovrimos, allows the execution of Scheme scripts which may be used to produce an HTTP response. Before executing user scripts, the interpreter is initialized from the file $SCHEMEINIT. User defined macros and functions can be added in the file $SCHEMEINIT and are visible by all Scheme scripts.

Necessary elements for any script expected to handle a special URL are some environment variables:
*form-elements* It is a list of symbols, which contains the names of the form fields. The form field contents are the value of the variable denoted by each symbol.
*request-uri* It is a string showing what the HTTP request was.
*request-method* A string containing one of ``GET'', ``POST'', ``HEAD'', etc.

  
8.5.2.1 Stateless Scheme Scripts

A stateless Scheme script is invoked by the HTTP server, when the URL corresponding to it is requested. Stateless Scheme scripts have no special entry point; they are executed from top to bottom. After they have executed, their state is not maintained. Although they are simpler to construct, they are not as powerful and sophisticated as Persistent Scheme scripts.

   
8.5.2.2 Persistent Scheme Scripts

The way to specify that a Scheme script is to be treated as a persistent one is to map it to a URL in the $SCHEMEHANDLERS. For example, this file for Bookstore (a demo Scheme script) contains the line:
/demo/bookstore books.scm.
Users can add their own URL handlers in the $SCHEMEHANDLERS. Persistent scripts have the following additional features when compared to stateless scripts:

Unlike their stateless counterparts, persistent Scheme scripts have a special entry point, the procedure main.

   
8.5.3 HTTP Server and Persistent Sessions

Since an HTTP session is stateless, it was necessary to implement a mechanism that would allow persistent sessions.

The Ovrimos mechanism for persistent sessions does not depend on user-side cookies, since these make security-sensitive users nervous. Thus, a novel mechanism was implemented, which is based on the back-forth propagation of a unique identifier for each session.

As an example, we present a special URL /alpha, that makes reference at some later time to another URL, /beta.

CLIENT AGENT   HTTP SERVER
GET /alpha $\Longrightarrow$  
  $\Longleftarrow$ Redirect to /session/xxxxxxxxalpha (A session number is returned to the client program)
GET /sessionxxxxxxxx/alpha $\Longrightarrow$  
  $\Longleftarrow$ HTTP Server responds for /alpha
GET /beta (A link to /beta is requested, from referrer /sessionxxxxxxxx/alpha) $\Longrightarrow$  
  $\Longleftarrow$ Redirect to /sessionxxxxxxxx/beta
Get /sessionxxxxxxxx/beta $\Longrightarrow$  
  $\Longleftarrow$ HTTP Server responds for /beta

For the sake of resource management, sessions that remain idle for more than $HTTPSESSIONTIMEOUT minutes, are reclaimed.

     
8.5.4 CGI 1.2

The simplest case of a gateway program is an executable file. When a file with execute permission is served to the client, instead of sending the file contents, the file is executed in a CGI environment. In Unix, even scripts can be run this way. Scripts in certain interpreted languages, such as Perl, can be run directly using the #! mechanism. Other scripts can be run via a shell script.

To allow easy use of interpreted scripts that cannot be run directly, without incurring the cost of introducing an extra shell script, Ovrimos provides a custom mechanism. A parameter, called EXECEXT, defines ``executable extensions" .

In Windows NT, file associations usually associate a script extension with a File Type, and File Types define what is called an ``open command string" that can be used to run the script using the corresponding interpreter and appropriate flags. When a file with an extension included in $EXECEXT is requested, the open command string for that file (after expansion of environment variables) is executed in a CGI environment.

In Unix (or NT if no association is found), when a file with an extension included in $EXECEXT is requested, its MIME type is used for a similar mechanism: the bin subdirectory is searched for the executable <mime_type>-handler, which is called in a CGI environment having a single argument (the filename). In the executable's name, an underscore ``_" is substituted for the forward slash of the MIME type.

An example use of that would be to allow gzipped tar files to be used as "virtual directories" with an application_gzip-handler that extracts the actual file, or even runs it if it is executable. Additionally, handlers could be used to translate, on-the-fly, some format into some other.

8.5.5 Using CGI 1.2 for persistent HTTP sessions

Persistent HTTP sessions are not the exclusive privilege of internal Scheme scripts but its support has been extended to more traditional content generators, i.e. plain CGI programs or scripts. Analogous to Set-Cookie and Cookie, the header X-Session-Data transfers 'realm data' to and from the CGI program. This header will never be propagated to the HTTP client and serves only as a method to implement state. Refer to the Additional Ovrimos environment variables, in section 8.5.6.

  
8.5.6 CGI 1.2 environment

8.5.7 Gateway Program Output

As per the CGI/1.1 spec, when the program name begins with nph-, its output is sent directly to the client. The gateway program is responsible for returning a valid HTTP response. Note that in the CGI/1.2 spec, discrimination is left unspecified so the CGI/1.1 rule was followed.

Otherwise, the server parses the output. Output of gateway programs must begin with a small header of text lines, in the same format as HTTP headers, delimited with LF or CR/LF, ending with an empty line. The following headers are server directives and are interpreted appropriately by the server, while the rest are incorporated in the response sent to the client.

   
8.6 Appendix: Scheme

 
: SQL mapping
   
SQL Type Scheme Type
bigint/unsigned bigint string
   
integer integer
   
unsigned integer integer or real
   
smallint/unsigned smallint integer
   
tinyint/unsigned tinyint integer
   
bit symbols on and off
   
smallint/unsigned smallint integer
   
decimal/numeric real
   
float/double/real real
   
character/varchar string
   
unicode character/ varchar symbol unicode
   
binary/varbinary symbol binary
   
date `1999-12-25' list of the form `(date 1999 12 25)'
   
time `12:45:12.42' list of the form `(time 12 45 12 42)'
   
timestamp `1999-12-25 12:45:12.42' list of the form `((date 1999 12 25) (time 12 45 12 42))'
   
long varchar/ long varbinary symbol blob
   

 
: Procedures
 
Procedures
All procedures that return results other than boolean, return #f to indicate failure

(sql-login string-user string-password)
Attempts to authenticate as specified user. Returns boolean.
 
(sql-logout)
Abandons the SQL connection and frees the resources. Returns boolean.
 
(sql-start-session)
Allocates a Statement stream and returns an integer handle for it, or #f.
 
(sql-end-session integer-handle)
Deallocates the Statement stream.
 
(sql-exec-direct integer-handle string-sqlstatement)
Compiles and executes the SQL statement specified. This must not contain any parameters. Returns boolean.
 
(sql-result-columns integer-handle)
For SELECT statements, returns a list with the result names of the columns. Names missing are represented by '().
 
(sql-row-count integer-handle)
For update statements, returns the number of rows affected.
 
(sql-cursor integer-handle symbol-direction)
Depending on the parameter direction, fetches a row from the result set. For simplicity, there is no provision to specify an offset other than 1, or to fetch rowsets of more than 1 row. The parameter direction can be one of the symbols:
 
this: Fetch the current row
next: Fetch the next row
prev: Fetch the previous row
first: Fetch the first row
last: Fetch the last row
The row is returned as a list of values. Returns #f when not available.
 
(sql-commit)
Commits the transaction. This is necessary to make the updates permanent. Returns boolean.
 
(sql-rollback)
Rolls back the transaction. Returns boolean.
 

   
8.7 HTTP Log

The activity of the HTTP server is logged in the file $HTTPLOG . Its format is the Common Logfile Format which is understood by many log analyzers.

Each line in the HTTP Log consists of the following data:

<Hostname> or <IP address of client> - <User name> <Date/Time of request> ``<Request> <Protocol>'' <HTTP response number> <Byte count of returned entity>

The following is a sample of an HTTP Log File:
127.0.0.1 - admin [Mon, 17 Jan 2000 16:07:33 GMT] "GET /console HTTP/1.0" 302 -
127.0.0.1 - admin [Mon, 17 Jan 2000 16:07:33 GMT] "GET /console HTTP/1.0" 200 1534
127.0.0.1 - admin [Mon, 17 Jan 2000 16:08:33 GMT] "GET /shutdown HTTP/1.0" 401 -
127.0.0.1 - dbman [Mon, 17 Jan 2000 16:08:41 GMT] "GET /shutdown HTTP/1.0" 200 383
127.0.0.1 - dbman [Mon, 17 Jan 2000 16:08:43 GMT] "GET /shutdown/now HTTP/1.0" 200 318
127.0.0.1 - - [Tue, 18 Jan 2000 16:17:19 GMT] "GET / HTTP/1.0" 302 -
127.0.0.1 - - [Tue, 18 Jan 2000 16:17:19 GMT] "GET /index.htm HTTP/1.0" 200 2230
127.0.0.1 - - [Tue, 18 Jan 2000 16:17:19 GMT] "GET /welcome.gif HTTP/1.0" 200 7359
127.0.0.1 - - [Tue, 18 Jan 2000 16:17:20 GMT] "GET /manual.gif HTTP/1.0" 200 2188
The first line of the sample log is explained below:

HTTP Log File Example
<Hostname> or <IP address of client> DNS is disabled, thus the client's IP address appears
<RFC 931 information> (RFC 931 information - not implemented)
<User name> admin (user name entered by the client for authentication)
<Date/Time of request> Mon, 17 Jan 2000 16:07:33 GMT
<Request> GET /console
<Protocol> HTTP/1.0
<HTTP response number> 302 (Redirection)
<Byte count of returned entity> - means no entity was returned

  
8.8 Demo bookstore: An example of a Scheme script

The example presented here is written in a Scheme script, called books.scm. It is placed in the directory of testbase during installation and serves the URL /demo/bookstore. It is a simple bookstore application, with a demand-driven main loop.

A number of books are stored in table books of testbase . You can search for a specific book by its title or author name as a keyword. Available information about the bookstore's books consists of ISBN, Title, Author, Price and Cover. You can add displayed books to the Shopping basket and remove books from it. It is also possible to display the contents of the Shopping basket.

To try out the Demo bookstore:

Figure 8.1 is the introductory screen of the On-line bookstore.

  
Figure 8.1: On-line bookstore: Introductory screen
\includegraphics[width=12cm]{bookstore1}

Part of the book Keyword (the book's title) or part of the Author name may be used to request a search into the database. Books matching the search criteria appear in a list, similar to the one of figure 8.2 (where the search criterion is 'e' in the Author field).


  
Figure 8.2: On-line bookstore: List of books
\includegraphics[width=12cm]{bookstore2}

The user may add a book to the basket by checking on the Select box. Figure 8.3 shows the results of selecting two books and adding them to the Shopping basket.


  
Figure 8.3: On-line bookstore: Contents of shopping basket
\includegraphics[width=12cm]{bookstore3}

Finally, figure 8.4 shows the order you are about to place. The selected books are displayed as well as the Grand Total.


  
Figure 8.4: On-line bookstore: Order screen
\includegraphics[width=12cm]{bookstore4}

Note: In figure 8.4, the order is not really placed (i.e. it is not further processed). This part of the script is left as an exercise to the user who would wish to add code to an existing and running example.

next up previous contents index
Next: 9. SQL Query Tool Up: Ovrimos version 3.0 On-line Previous: 7. Administrator's Console