\HeaderA{stam.serve}{StAM server launch and installation}{stam.serve}
\keyword{hplot}{stam.serve}
\begin{Description}\relax
stam.serve installs StAM's server feature if it has not been installed 
before. Moreover it launches the StAM server needed to use StAM output 
interactively through the internet.
\end{Description}
\begin{Usage}
\begin{verbatim}
stam.serve(tmp.path = NULL, cgi.path = NULL, cgi.url = NULL)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{tmp.path}] the path to the directory where files are stored for 
communication between your WWW-server and the StAM-server.
\item[\code{cgi.path}] the path to the directory in which the StAM-related CGI 
scripts are to be stored. Make sure that your WWW-server can execute 
CGI scripts from here and that access rights are set correctly.
\item[\code{cgi.url}] the URL prefix needed to access the CGI scripts, i.e. the 
directory specified in cgi.path.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The stam package provides a feature to manipulate some parameters interactively
using HTML forms. This feature needs a WWW browser which is able to execute CGI
scripts. The HTML output used to work with interactively must be generated with
the stam.write.forms option turned on. 

StAM provides a set of CGI scripts which are called from the forms written into 
the HTML code when the above mentioned option is turned on. This scripts write 
task files into the directory given by tmp.path. This directory must have write
permission for the WWW server. The StAM server regularly checks this directory
for such tasks and executes them. 

stam.serve installs the StAM server feature when it is called the first time after 
the installation of the stam package. Firstly, this consists of registering the 
three parameters of stam.serve into the package installation such that they can be 
reloaded when the packages is loaded into R the next time. For this purpose a 
dataset is written into the installation, thus you need write permissions in the 
corresponding directory. Secondly, the cgi.url is written into StAM's CGI scripts 
and these scripts are written into the cgi.path. 

When the installation of StAM's server feature is complete, stam.serve starts 
checking the directory where it expects the tasks written by the CGI scripts and 
is thus ready for operation. After the server feature has been installed the server
can be launched simply by calling stam.serve() without parameters. A second call
with parameters modifies the StAM server installation accordingly.
\end{Details}
\begin{Note}\relax
\item You need write permission in the stam installation directory 
in order to install StAM's server feature.
\item You need write permission in the directory where the CGI scripts
are to be deposited in order to install StAM's server feature.
\item You must regenerate all HTML you want to work with through the 
stam server after installation of the server feature.
\item You must turn on the stam.write.forms option when generating HTML
for use with the server feature.
\end{Note}
\begin{Author}\relax
Claudio Lottaz
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{stam.writeHTML}{stam.writeHTML}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
## Not run: 
# make sure subsequent calls to stam.writeHTML generate forms
options(stam.write.forms=TRUE)

# first call to stam.serve after installation of the stam package
stam.serve(tmp.path = "/home/myhome/upload", 
           cgi.path = "/home/myhome/cgi-bin/stam",
           cgi.url  = "http://www.myserver.com/cgi-bin/stam")

# subsequent calls to launch StAM server without modifying the installation
stam.serve()
## End(Not run)\end{ExampleCode}
\end{Examples}

