Index: /trunk/docs/webUpgrade.tex
===================================================================
--- /trunk/docs/webUpgrade.tex	(revision 465)
+++ /trunk/docs/webUpgrade.tex	(revision 465)
@@ -0,0 +1,206 @@
+\documentclass{article}
+\usepackage[sort]{natbib}
+\usepackage{listings}
+\usepackage{color}
+\bibpunct[,]{(}{)}{;}{a}{}{,}
+\textwidth=161 mm
+\textheight=248 mm
+\topmargin=-13 mm
+\oddsidemargin=0 mm
+\parindent=6 mm
+
+\newcommand{\eg}{e.g.\ }
+\newcommand{\ie}{i.e.\ }
+\newcommand{\fdg}{\hbox{$.\!\!^\circ$}}
+\newcommand{\entrylabel}[1]{\mbox{\textsf{\bf{#1:}}}\hfil}
+\newenvironment{entry}
+{\begin{list}{}%
+{\renewcommand{\makelabel}{\entrylabel}%
+                        \setlength{\labelwidth}{30mm}%
+                        \setlength{\labelsep}{5pt}%
+                        \setlength{\itemsep}{2pt}%
+                        \setlength{\parsep}{2pt}%
+                        \setlength{\leftmargin}{35mm}%
+}%
+}%
+{\end{list}}
+
+\definecolor{blue_code}{rgb}{.8,.8,1}
+\definecolor{todo_color}{rgb}{1,.8,.8}
+
+\begin{document}
+
+\begin{center}
+{\Huge Pulsar Archive}
+\end{center}
+
+\section{Web Interface Structure}
+\subsection{Requirements}
+
+\begin{itemize}
+\item[psrcat]: This is required to obtaint he exact coordinates of a pulsar in order
+            to then perform a cone search centered on that pulsar.
+\item[tempo.cfg]: This is now a requirement for all psrchvie software, so pav/vap won't
+            execute unless TEMPO environment variable points to a directory containing
+            this file.
+\item[pav]: pav is used to plot observations and calibrations.
+\item[psradd]: psradd is used to combine CPSR2 data files into a single file for the observation
+\item[psrsh]: used for scrunching archives.
+\item[tar]: used to combine all the files together for download (gzip not required)
+\end{itemize}
+
+\subsection{Database policy}
+
+\subsubsection{Databases involved}
+There are two separate databases involved with this project. The first is a mysql database
+running on herschel which contains all information about the observations. The second database
+is the opal database running on serapis. This is an Oracle database, we don't write or update
+anything in this database, only examine it to authenticate a user against opal and get a list
+of projects that a user is associated with.
+
+\subsubsection{Deletion of data}
+No code ever executes an sql DELETE operation. Instead all tables have a column
+called deleted and all code will ignore any tuple where this is set to 1. This 
+reduces the possibility of accidental deletion of data or the possibility of
+data being deleted by a hacker performing sql insertions. 
+The sql user that is used to connect to the database by the web interface and
+the DBUpdater program should not have delete privileges. Instead another user
+account should exist, which a system administrator can use to perform deleting
+of records. The operation is simple, "DELETE FROM OBSERVATIONS WHERE DELETED = 1"
+but should only be done by hand on occasions when the number of stale records
+has grown large (in this project this is never expected to be the case).
+
+
+\begin{itemize}
+\item authenticate a user
+\item list the projects that a user is associated with.
+\end{itemize}
+
+\subsection{Configuration}
+The file htdocs2/config.php contains the following constants
+
+\begin{verbatim}
+DB_HOST         - host providing the mysql database containing observation data.
+DB_USER         - username to use when connecting ot the mysql database
+DB_PASSWD       - password for connecting to the mysql database
+DB_NAME         - name of the mysql database containing observation data
+OPAL_USER       - username to use when conencting to the opal database
+OPAL_PASSWD     - password to use when connecting to the opal database
+OPAL_DSN        - DSN of the opal database.
+GREEN_ZONE_DIR  - Location of GreenZone files.
+PSRHOME         - psrhome environment variable
+TEMPO           - tempo environment variable
+FIX_LD_LIB      - String for adding environment variables before commands
+PAV_CMD         - String for calling pav
+PSRCAT_CMD      - String for calling psrcat
+VAP_CMD         - String for calling vap
+PSRADD_CMD      - String for calling psradd
+PSRSH_CMD       - String for calling psrsh
+DATA_DIR        - The directory where psradded,scrunched etc files will be placed
+WEB_ROOT        - The root directory for this site (don't think this is needed anymore)
+DOWNLOAD_DIR    - The directory to place files ready for download
+PLOTS_DIR       - The directory to place plots
+MAX_ROWS        - The maximum number or records to return with each search
+PROP_PERIOD     - The number of days that observations remain proprietary
+DOWNLOAD_LIMIT  - The maximum size of a single download in MB
+\end{verbatim}
+
+\subsection{Directory Layout}
+
+\begin{verbatim}
+Clases
+|---------General
+|---------Astro
+|---------Pulsar
+|---------Model
+|---------Queries
+|---------Interfaces
+Forms
+templates
+\end{verbatim}
+
+The Forms directory contains the php code for each page, the templates directory contains the
+smarty templates for each page. 
+
+All forms have the same basic functionality which they inherit from GZBaseForm and override as necessary
+\begin{verbatim}
+ReadForm()       - Read in any input data from SESSION, GET and POST (excluding PostActions)
+ProcessActions() - Examine PostAction data perform operations selected by the user
+Display()        - Present the form in its current state
+\end{verbatim}
+
+Much of the functionality of the site exists in the directories under Classes.
+\begin{itemize}
+\item[General/File] Simple class representing a file, can also tell you if a file exists, if its a directory etc.
+\item[General/Dir] Simple class representing a directory, can create etc
+\item[General/TarBuilder] An algorithm class for creating tar archives. Specify the target file, source directory and filenames
+                          and it builds the file.
+\item[General/Date] A class representing a date, can be converted between some formats.
+\item[General/UserData] A class representing a user of the system, ie their email address, the method they used to login on and
+                        any projects they are associated with.
+\item[Astro/Angle] This class represents an angle, it can be specified in degrees or radians and converted between the two,
+                   it can also be read from and written to several formats, ie HMS,DMS etc.
+\item[Astro/Band] This represents a frequency band, for this project we have (70cm,50cm,20/18cm...)
+\item[Astro/MJD] A class representing an MJD, can be converted to/from a Date/string.
+\item[Astro/SkyCoord] Two angles representing a sky coordinate 
+\item[Pulsar/ArchiveScruncher] Give this class a source file, destination file and scrunching parameters and it will create
+                               a new archive scrunched accordingly, uses psrsh to do the dirty work.
+\item[Pulsar/CPSR2Combiner] Give this class a destination file and archives to add and it will combine them into a single archive
+                               uses psradd to do the work.
+\item[Pulsar/PulsarCatalog] Give this class the name of a pulsar and it will give you the coordinates. Uses psrcat to do the work.
+\item[Pulsar/ObservationData2] This class does all the work of managing the various data files in the pipeline from the source
+                               file to a file that can be plotted, to a file scrunched, to a file ready for download.
+\item[Model/ObservationHeader] This class represents the details of an observation, basically equivelant to a record in the
+                               observations table
+\item[Model/ObservationSet]    This class represents an observation and all the calibrations that were found to be within X minutes
+                               of it. A list of ObservationSet objects is the fundamental data structure used in the web code, they 
+                               form the result from a query, the contents of the cart and the data given to the table for display.
+\item[Model/ObservationSetFinder] Give this class the parameters from the query from, the database object and it will return a list
+                                  of observation sets matching that query.
+\item[Queries/ConeQuery] The basic cone query, it takes ConeQueryParameters and returns the ObservationHeaders it gets from the
+                         database. This class is used by conesearch.php (VO search) as well as the main site.
+\end{itemize}
+
+
+\section{Database Updater program}
+
+\subsection{Requirements}
+This program compiles against psrchive, and requires a properly setup psrhome including
+tempo configuration files in order to function (as of current release of psrchive, this
+may not be a requirement in future).
+
+\subsubsection{Specific requirements}
+\begin{itemize}
+\item libsofa
+\item libcfitsio
+\item psrchive (see below for build requirements)
+\item tempo installation files
+\end{itemize}
+
+\subsubsection{Psrchive requirements}
+\begin{itemize}
+\item psrchive won't build without the following
+\item libsofa
+\item libfftw or a compatible floating point fft library
+\end{itemize}
+
+\subsection{Compiling}
+
+The only parameters you need to specify are, PSRHOME and PACKAGES in the Makefile
+file. However, all the packages listed in the requirements above must be present
+either under these two directories, or the system path.
+
+\subsection{Operation}
+To run DBUpdater, simply specify the directories you want to search on the command line
+
+\lstset{backgroundcolor=\color{blue_code}}
+\begin{lstlisting}
+DBUpdater /pulsar/archive09/ /pulsar/archive10/
+\end{lstlisting}
+
+The program will only mark observations as deleted if they are under the directory
+tree being examined by DBUpdater during that run.
+
+
+
+\end{document}
