<!--
  - Authors:
  -   Christian Schulte <schulte@ps.uni-sb.de>
  -
  - Copyright:
  -   Christian Schulte, 1998
  -
  - Last change:
  -   $Date$ by $Author$
  -   $Revision$
  -
  - This file is part of Mozart, an implementation
  - of Oz 3
  -    http://www.mozart-oz.org
  -
  - See the file "LICENSE" or
  -    http://www.mozart-oz.org/LICENSE.html
  - for information on usage and redistribution
  - of this file, and for a DISCLAIMER OF ALL
  - WARRANTIES.
  -
  -->

<Chapter id="chapter.servlets">
  <Title/Servlets/

<p>
A <em>servlet</em> is a small application that exists 
on a Web server and that can be invoked by a CGI command.
A servlet is usually called a <em>CGI script</em>.
CGI (Common Gateway Interface) is a protocol
that defines how data is passed between
a Web server and a servlet.

<p>A servlet is a program that accepts an input and calculates a result.
To be precise, it does the following steps:
<list>
<item>Get the arguments for the servlet by calling <<Application.getCgiArgs>>. 
A standard application would call <<Application.getCmdArgs>>
for this purpose.
The former is used in exactly the same way as the latter,
but instead of parsing
command line arguments, it parses CGI arguments.

<item>Calculate the result.

<item>Print a header on <<stdout>> that defines the content type.
The content type
tells the Web browser what the type of the result is,
so that it knows how to display it.
For example, if the
servlet outputs HTML,
you have to print something like:
<code display proglang=fundamental>'Content-type: text/html\n\n'</code>
<P>(without the quotes).
The <<Open.html>> class has support for this (see example below).

<item>Output the real data.  For example, text in HTML format.
</list>
<p>The following example follows this structure.
It uses a class <<Open.html>> to generate HTML code on the fly.
You can test it by sending a URL that looks like this:
<<<
'http://www.you.edu/~you/small.cgi?number=10&amp;text=Hi'
>>>
<p>In this example,
the value <<10>> is passed
for the argument <<'number'>>
and the value <<"Hi+Guys">> for 
the argument <<'text'>>
(in CGI argument syntax,
the plus is used to quote a space).

<<<
functor
import Application Open
define
   %% Parse the arguments
   Args={Application.getCgiArgs 
      record(number(single type:int default:0)
             text(single type:string default:"none"))}
 
   %% A file that supports HTML output
   Out={New class $
               from Open.file Open.html
            end
        init(name:stdout)}
 
   %% Print MIME content header
   {Out header}
 
   %% Print HTML output
   {Out tag(html(head(title('My First CGI'))
                 body(bgcolor:'#f0f0e0'
                      h1('My First CGI')
                      p('The number is: '#Args.number)
                      p('The text is: '#Args.text))))}
 
   %% Terminate
   {Application.exit 0}
end
>>>

<P>In order to compile this servlet,
you have to do:
<code display proglang=sh>
ozc --execpath=?{OZHOME}/bin/ozengine -x small.oz -o small.cgi
</code>
<P>Where ?{OZHOME} denotes the installation directory of the Mozart
system. The <<execpath>> argument is needed because the
servlet needs an absolute path.
Servlets are normally executed by the Web server
in an extremely minimal user environment. 
The user is typically called <<nouser>>
or <<www>> and has almost no rights.
In particular you cannot expect the Mozart system
to be in the path of the user!
This is why you need an absolute pathname when compiling
the servlet.

<P>On a Unix system, you can more simply invoke:
<code display proglang=sh>
ozc --execpath=`which ozengine` -x small.oz -o small.cgi
</code>

<P>The final step is to install the servlet
in your Web server.
For this you should contact your local
Web site administrator.

</Chapter>
