\name{stam.serve}
\alias{stam.serve}
\title{StAM server launch and installation}
\description{
  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.
}
\usage{
stam.serve(tmp.path = NULL, cgi.path = NULL, cgi.url = NULL)
}
\arguments{
  \item{tmp.path}{the path to the directory where files are stored for 
    communication between your WWW-server and the StAM-server.}
  \item{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{cgi.url}{the URL prefix needed to access the CGI scripts, i.e. the 
    directory specified in cgi.path.}
}
\details{
  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.
}
\author{Claudio Lottaz}
\note{
  \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.
}
\seealso{\code{\link{stam.writeHTML}}}
\examples{
\dontrun{
# 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()
}}
\keyword{hplot}