\documentclass[a4paper,twoside,BCOR19mm]{scrbook}

%----------------------------------------------
% PACKAGE MANAGEMENT
%
\usepackage[latin1]{inputenc} 
\usepackage{times}
\usepackage{fancyhdr}
%\usepackage[all, light]{draftcopy}
%\usepackage{supertabular}
%\usepackage{colortbl}
%\usepackage{epsf}
\usepackage{graphicx}
\usepackage{wasysym}
\usepackage{lastpage}

%----------------------------------------------
% Document DATE and VERSION
% set these values when releasing a new version

\def\cleanunderscore#1_#2_#3{\expandafter #1\_#2\_#3}
\def\CVS$#1: #2 ${\expandafter\def\csname CVS#1\endcsname{\cleanunderscore#2}}
\CVS$Id: great-er_web_specification.tex,v 1.15 2003-08-19 13:08:15 silke Exp $

\newcommand{\documentdate}{19. August 2003}
\newcommand{\documentversion}{1.11}
\newcommand{\documentID}{\CVSId}

%----------------------------------------------
% MACRO DEFINITION
%
%   \Fig{figure}{text}  : creates an mbox around 'figure' and
%                         writes 'text' at the bottom with leading
%                         'Fig. section.figno:'.
%                         Example:
%                         \Fig{\epsfxsize30mm \epsffile{x.eps}}{the x}\\
%   \FigNoEntry{}{}     : same as above, no entry in figures list
%
%   \FigCaption{}       : line with figure caption, setting figure
%                         counter and figures list
%

%****************************************************************************
%       Figure makro for graphics continously enumerated.
%

\newcounter{FigCnt}[chapter]
\newcommand{\Fig}[3]%
{
        \refstepcounter{FigCnt}
        \addcontentsline{lof}{figure}%
                {\protect\numberline{\thechapter.\arabic{FigCnt}}{#2}}
        \mbox{#1}
\nopagebreak

        {Fig. \thechapter.\arabic{FigCnt}: #3}
}

\newcommand{\FigNoEntry}[2]%
{
        \refstepcounter{FigCnt}
        \mbox{#1}
\nopagebreak

        {Fig. \thechapter.\arabic{FigCnt}: #2}
}

\newcommand{\FigCaption}[1]%
{
        \refstepcounter{FigCnt}
        \addcontentsline{lof}{figure}%
                {\protect\numberline{\thechapter.\arabic{FigCnt}}{#1}}

        %{Figure \thechapter.\arabic{FigCnt}: #1}
}


\newcommand{\APIMethod}[1]{{\small\tt #1 }}

%
% END MACRO DEFINITION
%----------------------------------------------


%----------------------------------------------
% DOCUMENT
\begin{document}


%-----------------------------------
% HEADER/FOOTER DEFINITION
% The settings here are for single page documents (only odd page set)

% for some pages latex switches back to pagestyle plain :-(
\fancypagestyle{plain}{%
	\fancyhf{} % clear all header and footer fields
	\fancyhead[LO,RE]{\footnotesize GREAT-ER Web Specification\\ \leftmark}
	\fancyfoot[RO,LE]{\footnotesize Intevation GmbH} % Author
	\fancyfoot[CO,CE]{\footnotesize \thepage/\pageref{LastPage}}
	% set the document title for the footer here!
	\fancyfoot[LO,RE]{\footnotesize \documentdate 
	\\\documentID}
	\renewcommand{\footrulewidth}{0.4pt}
}

% and now define pagestyle fancy
\fancyhead{} % clear all fields
\fancyhead[LO,RE]{\footnotesize GREAT-ER Web Specification\\ \leftmark}

\fancyfoot{}% clear all fields
\fancyfoot[RO,LE]{\footnotesize Intevation GmbH} % Author
\fancyfoot[CO,CE]{\footnotesize \thepage/\pageref{LastPage}}
% set the document title for the footer here!
\fancyfoot[LO,RE]{\footnotesize \documentdate 
\\\documentID}

\renewcommand{\footrulewidth}{0.4pt}

%
% END Header/Footer Definition
%-----------------------------------

%-----------------------------------
% DOCUMENT SETTINGS
\pagestyle{fancy}
\parindent0cm
% \parskip0.2cm 


%-----------------------------------
% TITLE PAGE
{
	\includegraphics[width=0.3\textwidth]{./brieflogo.eps}\\[0.1cm]

	 {\tt http://intevation.net}\\[2.0cm] 
}

% reenter the TITLE here
{
	\sffamily\bfseries\Large 
% e.g.:
	GREAT-ER II\\[0.5cm]
	\huge Specification GREAT-ER Web\\[4cm]

}

% a possible SUBTITLE
%\begin{flushleft}
%	\sffamily\bfseries\large 
%    	by Intevation GmbH\\[0.5cm]
%\end{flushleft}

\thispagestyle{empty}

\vfill

{\sffamily\small
	Intevation GmbH\\
	Georgstrasse 4\\
	49074 Osnabrück\\
	Germany\\
	\\
	Date: \documentdate
}


\newpage

% PAGE 4

\vfill

This document has been designed with \LaTeX{}.
It is available as source code, PDF- and HTML-format.\\

{\scriptsize
\begin{verbatim}
$Revision: 1.15 $
$Id: great-er_web_specification.tex,v 1.15 2003-08-19 13:08:15 silke Exp $

$Log: not supported by cvs2svn $
Revision 1.14  2003/07/28 12:30:13  frank
Gaspell checked, CVS Id and lastpage package added.

Revision 1.13  2003/07/23 07:55:06  silke
changed document version to 1.0.0 and date to 23. July 2003
added GNU FDL
corrected footnote of MapServer License

Revision 1.12  2003/07/22 17:08:05  silke
Adapting call of API Methods for all functions.
Some minor changes in the general functionality section.
Merging section architecture and functionality.

Revision 1.11  2003/07/18 12:58:57  tkoester
* doc/great-er_web_administration.tex, doc/great-er_web_manual.tex,
doc/great-er_web_specification.tex: Use twoside printing with binding
correction of 19mm. Added fancy headers/footers for even pages.

Revision 1.10  2003/07/17 16:17:11  tkoester
* doc/great-er_web_administration.tex, doc/great-er_web_manual.tex,
doc/great-er_web_specification.tex: Use GNU FDL 1.2.

* doc/great-er_web_specification.tex: Use the term "GREAT-ER II".

Revision 1.9  2003/03/07 13:37:11  frank
Document info updates, software version updates, added final
interface design screenshot

Revision 1.8  2003/01/27 18:42:39  silke
ChangeLog

Revision 1.7  2003/01/15 14:32:07  silke
updated specification of session management

Revision 1.6  2002/11/12 16:34:34  frank
Changed image source file extension from *.ps to *.eps

Revision 1.5  2002/11/11 10:17:02  frank
Added licence information to software section.

Revision 1.4  2002/11/06 10:46:57  frank
Added screenshot to illustrate GREAT-ER Web user interface design.

Revision 1.3  2002/10/29 11:24:58  frank
Substance Management (2.4.3, 2.4.4) added.

Revision 1.2  2002/10/28 14:27:33  frank
Added GREAT-ER Web component details (Section 1.2 Software).

Revision 1.1.1.1  2002/10/23 17:18:57  frank
Imported sources

\end{verbatim}
}
%Version: \documentversion \\
%Date: \documentdate

\vfill

\begin{center}Copyright (c) 2002 Intevation GmbH.\end{center}

%    Permission is granted to copy, distribute and/or modify this document
%    under the terms of the GNU Free Documentation License, Version 1.2
%    or any later version published by the Free Software Foundation;
%    with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
%    A copy of the license is included in the section entitled ``GNU
%    Free Documentation License''.

\tableofcontents

\chapter{Concept}
\label{chap:concept}

\section{General Overview}
\label{sec:generaloverview}

\begin{center}
\FigNoEntry{\includegraphics[width=\textwidth]{./great-er_web_components.eps}}{
\label{fig:ComponentOverview}GREAT-ER Web Component Overview}
\end{center}

Figure 1.\ref{fig:ComponentOverview} gives an overview of the GREAT-ER II
architecture and the components covered by this specification. 
Components with direct relation to GREAT-ER Web are displayed in gray, blue
or green others in white.

The core component is the GREAT-ER Web Server, which 
\begin{itemize}
	\item controls access on the database, 
	\item manages the users with their sessions 
	\item generates maps 
	\item generates the different pages of the user interface
\end{itemize}

The following section details the concept for the GREAT-ER Web Server

\section{Software}
\label{sec:software}

All software tools the GREAT-ER Web Server is based on are chosen under the
conditions of being Free Software and providing platform independence.

Figure \ref{fig:ComponentDetails} illustrates the component details of
the GREAT-ER Web Server. Its central element is the Zope Application Server,
which manages the different user sessions and therewith is directly
communicating with the Database (API) and the Model Server. Zope invokes the
UMN MapServer to render maps (based on user actions). The Apache WebServer
provides SSL encryption for the GREAT-ER Web application and can be used as
the common web server for additional GREAT-ER Services like the Web Repository.

The Apache WebServer is optional. If SSL encryption is not required the 
internal WebServer of Zope can be used to manage requests from the 
Internet.

\begin{center}
\FigNoEntry{
    \includegraphics[width=\textwidth]{./great-er_web_component_details.eps}}{
        \label{fig:ComponentDetails}GREAT-ER Web Component Details
    }
\end{center}

\subsection{Web Server}

\begin{tabular}{|p{2.5cm}|p{9.5cm}|}\hline
Name, URL:	& Apache Web Server, {\small\verb+http://www.apache.org/+} 
		  \\ \hline
Version: 	& 1.3.27 \\ \hline
Licence:	& Apache Software License, Version 1.1 \\ \hline
Description: 	& Apache has been the most popular web server on the Internet 
              	  since April of 1996. It has proven its reliability and 
		  applicability on numerous high volume Internet domains. \\
		  \hline
Task:		& Apache provides the SSL security protocol and is the first
		  instance in authentication (i.e. controlled access on the 
		  GREAT-ER Web Server) \\ \hline
\end{tabular}

\subsection{Application Server, Content Management System}

\begin{tabular}{|p{2.5cm}|p{9.5cm}|}\hline
Name, URL:	& Zope, {\small\verb+http://www.zope.org/+} \\ \hline
Version: 	& 2.6.0 \\ \hline
Licence:	& Zope Public License, Version 2.0 \\ \hline
Description: 	&  Zope is a leading free software application server, 
		   specializing in content management, portals, 
		   and custom applications. 

		   It provides a fine grained authorization concept and due to
		   its implementation in Python an easy enhancement and reuse 
		   of code for the GREAT-ER II project.
		  \\\hline
Task:		& \parbox[t]{9.4cm}{Zope is used for 
		    \begin{itemize}
			\item authorization to handle multiple users 
		              on one GREAT-ER Web Server
			\item session management
			\item user interface (content management) 
			\item control flow (python enhancements)
			\item map server control
		    \end{itemize}
		   }
\\ \hline
\end{tabular}

\subsection{Web Mapping System}

\begin{tabular}{|p{2.5cm}|p{9.5cm}|}\hline
Name, URL: 	& UMN MapServer, {\small\verb+http://mapserver.gis.umn.edu+} 
		  \\ \hline
Version: 	& 3.6.7 \\ \hline
Licence:	& MapServer Licence\footnotemark\\ \hline
Description: 	& MapServer is a  Free Software development environment 
                  for building spatially enabled Internet applications.
		  
		  It provides rendering of geographic data for specified 
		  extends as well as capabilities to query the data and 
		  representation of query results. \\ \hline
Task:		& Visualization of simulation results and general mapping.
\\ \hline
\end{tabular}

\footnotetext{This licence is most similar to the MIT Licence (expat Licence).} 
\bigskip
\begin{tabular}{|p{2.5cm}|p{9.5cm}|}\hline
Name, URL:	& ROSA-Applet,

		  {\small\verb+http://www2.dmsolutions.ca/webtools/rosa+} 
		  \\ \hline
Version: 	& 1.2.0 \\ \hline
Licence:	& MIT Licence (expat Licence) \\ \hline
Description: 	& The main purpose of the applet is to extend the 
		  standard {\small\verb+<INPUT TYPE=IMAGE...>+} form control. 
		  It displays an image (GIF, JPEG or PNG) on which operations 
		  can be performed.
		  \\ \hline
Task:		& In combination with the UMN MapServer the ROSA Applet
		  provides navigation on the maps, e.g. drag a zoom box, 
		  select geographic objects. \\ \hline
Hints:		& The ROSA-Applet requires a web browser with JAVA 1.3.x
		  runtime environment. 
\\ \hline
\end{tabular}

\newpage


\chapter{Functionality}
\label{chap:functionality}

\section{General}
\label{sec:general}

\subsection{Available parameters}
The GREAT-ER Web Interface provides access on the parameters needed to run a
mode 1 simulation:
\medskip

\begin{tabular}{l|l|l|l}
Model & Parameter & Section & accessible \\ \hline

Emission & Consumption                       & Substance & \checked \\ 
	 & Population                        & Catchment & \checked \\
	 & Local Consumption                 & Discharge & \checked \\
	 & Additional non-domestic mass flux & Discharge & \checked \\
	 & Additional run-off mass flux      & Discharge & \checked \\
\hline

Sewer & R$_{Sewer}$ & Substance & \checked \\
\hline

WWTP & R$_{PrimarySettler}$  & Substance & \checked \\
     & R$_{ActivatedSludge}$ & Substance & \checked \\
     & R$_{TricklingFilter}$ & Substance & \checked \\
     & Daily Flow            & Catchment & \checked \\
     & Treated Fraction	     & Catchment & \checked \\
\hline

River & R$_{River}$           & Substance & \checked \\
      & Flow Distribution     & Catchment & - \\
      & Velocity Distribution & Catchment & - \\
      & Stretch Length        & Catchment & - \\
\hline

\end{tabular}
%\medskip

The functionality provided for session management are 
limited.
\\

\subsection{User interface}
Figure 2.\ref{fig:GUIDesign} gives an impression of the proposed web based user
interface\footnote{
For the final version the design was slightly changed to get 
more horizontal space for the dialogs (Fig. 2.\ref{fig:FinalGUIDesign}).
}
. The screen is split in three section:
\begin{itemize}
	\item A navigation bar at the right,
	\item a dialog field at the top and 
	\item a mapping section below the dialogs.
\end{itemize}

The screen should be organized using frames, to avoid frequent reload of maps
while parameter input actions or menu navigation are performed. Since the
mapping component draw already enough attention the dialog field is placed at
the prominent position at the top of the screen.

The frame map is only loaded if one of the relevant components (session,
catchment, substance or result) has been changed or if the user interacts
directly with the map by using the navigation functions. The navigation
functions, the emission and discharge editing tool and the concentration
profile analysis tool are provided by the map toolbar within the map.

\begin{center}
%\FigNoEntry{\includegraphics{./screenshot-13.eps}}{
\FigNoEntry{\includegraphics[height=\textheight]{./screenshots/screenshot-13-rot.eps}}{
\label{fig:GUIDesign}GREAT-ER Web GUI Design}
\end{center}

\begin{center}
%\FigNoEntry{\includegraphics{./screenshot-13.eps}}{
\FigNoEntry{\includegraphics[width=\textwidth]{./screenshots/screenshot-finalversion.eps}}{
\label{fig:FinalGUIDesign}GREAT-ER Web Final Version GUI Design}
\end{center}

\subsection{Database connections}
For each process only one database connection is possible. Therefor the
following mechanism is used when connecting to the database:

A Lock object has to be required before a database connection can be
opened. Afterwards the Zope Server connects to the database with the users
Connection String which is stored in the Zope Session Data Container
(see below). Then the necessary DB API methods are
called. Afterwards the connection will be closed and the Lock object is
released. 
\\

\subsection{Web session management}
The main information related to session management is stored in the integral
Zope Session Data Container. 
To store data in the Zope Session Data Container it has to fulfill a
special form (the objects have to "`pickable"'). Since not all relevant
objects for session management are pickable, changes in temporary sessions
are synchronized immediately with the database. 

It is not possible to retrieve an earlier state of the database entries by
using the back button in the web browser.

\clearpage
\section{Login/Account Management}
\label{sec:login}

The GREAT-ER Web provides a two tier Account Management concept:
\begin{itemize}
	\item A {\bfseries default user} who can only create 
	temporary sessions and run simulations. All such users are connected
	under one special account. 
	
	Accessing GREAT-ER Web via the default account allows the user to
	select one of the sample sessions to work with or to create a new
	session.

	If no default user has been specified a login dialog will be prompted
	to the user when starting GREAT-ERWeb.

	\item A {\bfseries privileged user} with a specific account 
	can be granted on request. This requires an 
	administrator to create such an account.

	The privileged user is allowed to store sessions on the server.
	Therewith the user is provided with further session management 
	functionality (see \ref{sec:session}).

	The privileged user access requires password authentication, 
	therefore username and password are requested and transmitted 
	via SSL.
\end{itemize}


\subsection{Login}
\label{subsec:connect}

A login asks for a username and a password of a privileged user. Then a
connections to the default database will be opened to check whether the
user is allowed to connect to database.  If the user wants to use another
database, it can be specified in the login dialog. After the connection has
been established it will be closed immediately. If the connection was
successful, the connection string will be stored in the Zope Session Data
Container.

If the default user had an open session the temporary web session will be
deleted from the database.

\subsubsection{DB API Method Calls}
\begin{tabular}{p{6cm}|p{7.5cm}}
API method & Description\\ \hline
\APIMethod{da\_db\_connect()} 	   & Connect with User/Password to DB.\\
\APIMethod{da\_db\_disconnect()}	   & Disconnect from the DB.\\
\multicolumn{2}{l}{If a session was open before the login:} \\ \hline
\APIMethod{da\_delete\_sess()}	   & Delete temporary web session\\

\end{tabular}

\subsection{Logout}
\label{subsec:disconnect}

Before really disconnecting, for the privileged user the status of the 
current session is checked and in case an option is offered to 
save modifications. If there is an open session the temporary web session
will be deleted from the database. Disconnecting sets the connection string
in the Zope Session Data Container to the default connection.

\subsubsection{DB API Method Calls}
\begin{tabular}{p{6cm}|p{7.5cm}}
API method & Description\\ \hline
\multicolumn{2}{l}{If old session should be saved:} \\ \hline
\APIMethod{da\_make\_temp\_sess\_permanent()}   & Save current session\\
\APIMethod{da\_create\_temp\_sess ()}  & Open current session as anew as temporary session\\
\APIMethod{da\_db\_commit()}     				& Make changes permanent\\
\multicolumn{2}{l}{If a session was open before the logout:} \\ \hline
\APIMethod{da\_delete\_sess (2411)}     		& delete current temporary
web session\\

\end{tabular}

\clearpage

\section{Session Management}
\label{sec:session}


\subsection{New Session}
\label{subsec:newsession}

The New Session-Dialog  is offered
to enter the session's name and comment. Substance and catchment can be
selected from a list. All but the name is optional and can also be 
specified later.

If a session is open with unsaved modifications and if the user is
privileged, the user is offered a screen to save the session before
creating a new one. 

After the new session is loaded substance and catchment are stored in the
Zope Session Data Container (ZSDC) and the map-frame will be updated.

\subsubsection{DB API Method Calls}
\begin{tabular}{p{6cm}|p{7.5cm}}
API Method                   & Description \\ \hline
\multicolumn{2}{l}{New session dialog functionality:} \\ \hline
\APIMethod{da\_get\_subst()}     & Get list of substances from database. \\
\APIMethod{da\_get\_catch()}     & Get list of catchments from database. \\

\multicolumn{2}{l}{If a new session has been 
specified\footnote{The following sequence creates a new session.}:} \\ \hline

\APIMethod{da\_cleanup\_temp\_sess()}   & Delete old temporary sessions\\
\APIMethod{da\_create\_temp\_sess()}   & Create temporary web session\\
\APIMethod{da\_get\_sess()}  & Get new session \\

\multicolumn{2}{l}{Create the substance and model data by looping through all parameters:} 
                                \\ \hline
\APIMethod{da\_get\_subst()}    & Get substance record of chosen substance. \\
\APIMethod{da\_insert\_subst()}	& Insert new substance. \\
\APIMethod{da\_get\_subst\_det()}	& Load and ... \\
\APIMethod{da\_insert\_subst\_det()} 
			& ... copy substance details. \\
\APIMethod{da\_insert\_mod()}	& Insert new model parameter data set. \\
\APIMethod{da\_insert\_mod\_det()}	& Copy default model parameter details. \\
\APIMethod{da\_update\_sess()}	& Update session record.\\
\APIMethod{da\_get\_subst()}	& Get substance for insert in ZSDC\\
\APIMethod{da\_get\_catch()}	& Get catchment for insert in ZSDC\\
\multicolumn{2}{l}{If catchment has been selected and not loaded by another
user yet load new map:}\\\hline
\APIMethod{da\_get\_bin\_obj()}	& Load geographic data. \\
\APIMethod{da\_get\_backgrd()}	& Load information about background data. \\
\APIMethod{da\_get\_bin\_obj()}	& Load background data. \\
\end{tabular}

\subsection{Open Session}
\label{subsec:opensession}

A screen offers a selection of available sessions. Available are all
sessions that are readable for the user according to the privileges of the
session.

If a session is open with unsaved modifications and if the user is
privileged, the user is offered a screen to save the session before
creating a new one. 

After loading the session the map-frame will be updated.

After the new session is loaded substance and catchment are stored in the
Zope Session Data Container (ZSDC) and the map-frame will be updated.

\subsubsection{DB API Method Calls}

\begin{tabular}{p{6cm}|p{7.5cm}}
API Method 	& Description \\ \hline
\multicolumn{2}{l}{Open session dialog functionality:} \\ \hline
\APIMethod{da\_get\_sess()}  &  Get list of sessions.\\
\APIMethod{da\_get\_subst()} &  Get substance (for details of session).\\
\APIMethod{da\_get\_catch()} &  Get catchment (for details of session).\\
\APIMethod{da\_get\_user()}  &  Get user of session (for details of session).\\
\APIMethod{da\_get\_group()} &  Get group of session (for details of session).\\

\multicolumn{2}{l}{If a session has been selected:}\\ \hline
\APIMethod{da\_create\_temp\_sess()} 
			     &  Create temporary session from selected\\
\APIMethod{da\_get\_sess()} 	& Load session data. \\
\APIMethod{da\_get\_subst()}	& Get substance for insert in ZSDC\\
\APIMethod{da\_get\_catch()}	& Get catchment for insert in ZSDC\\
\multicolumn{2}{l}{If catchment has been selected and not loaded before, 
		load new map:}\\\hline
\APIMethod{da\_get\_bin\_obj()}	& Load geographic data. \\
\APIMethod{da\_get\_backgrd()}	& Load information about background data. \\
\APIMethod{da\_get\_bin\_obj()}	& Load background data. \\
\end{tabular}
\medskip

\subsection{Edit Session}
\label{subsec:editsession}

A screen is offered to enter the session's name and comment. Substance and
catchment can be selected from a list. The session name is mandatory and
cannot be empty.

If a new catchment has been selected the map-frame will be updated.

After the new session is loaded substance and catchment are stored in the
Zope Session Data Container (ZSDC) and the map-frame will be updated.

\subsubsection{DB API Method Calls}
\begin{tabular}{p{6cm}|p{7.5cm}}
API Method 	& Description \\ \hline
\multicolumn{2}{l}{Edit session dialog functionality:} \\ \hline
\APIMethod{da\_get\_subst()}    & Get list of substances for selection. \\
\APIMethod{da\_get\_catch()}    & Get list of catchments for selection. \\
\multicolumn{2}{l}{If changes to the session have been made:}\\ \hline
\APIMethod{da\_get\_sess()}  & Get new session \\

\multicolumn{2}{l}{Create the substance and model data by looping through all parameters:} 
                                \\ \hline
\APIMethod{da\_get\_subst()}    & Get substance record of chosen substance. \\
\APIMethod{da\_insert\_subst()}	& Insert new substance. \\
\APIMethod{da\_get\_subst\_det()}	& Load and ... \\
\APIMethod{da\_insert\_subst\_det()} 
			& ... copy substance details. \\
\APIMethod{da\_update\_sess()}	& Update session record.\\
\APIMethod{da\_db\_commit()}	& Commit changes.\\
\APIMethod{da\_get\_subst()}	& Get substance for insert in ZSDC\\
\APIMethod{da\_get\_catch()}	& Get catchment for insert in ZSDC\\
\multicolumn{2}{l}{If catchment has been selected and not loaded before,
load new map:}\\\hline
\APIMethod{da\_get\_bin\_obj()}	& Load geographic data. \\
\APIMethod{da\_get\_backgrd()}	& Load information about background data. \\
\APIMethod{da\_get\_bin\_obj()}	& Load background data. \\
\end{tabular}
\medskip

\subsection{Save Session}
\label{subsec:savesession}

This feature is only available for the privileged user.

The current session is saved in the database.

\subsubsection{DB API Method Calls}

\medskip

\begin{tabular}{p{6cm}|p{7.5cm}}
API Method 	& Description \\ \hline
\APIMethod{da\_get\_sess()} 		& Load contents of old session. \\
\APIMethod{da\_make\_temp\_sess\_permanent()} & Make temporary session 
						permanent. \\
\APIMethod{da\_create\_temp\_sess()} 	& Create new temporary session. \\
\APIMethod{da\_db\_commit()} 		& Commit save action. \\
\APIMethod{da\_get\_sess()} 		& Load contents of new session. \\
\end{tabular}

\subsection{Save Session As}
\label{subsec:savesessionas}

This feature is only available for the privileged user.

It allows to store the current session separate from the
original session.

The new session will be the working session after a 'Save Session As'.

A dialog is is displayed allowing to change name and comment of the session
so that it can be distinguished from the original one.


\subsubsection{DB API Method Calls}

In difference to 'Save Session' the new session is made permanent by
dereferencing it from the former permanent session.
\medskip

\begin{tabular}{p{6cm}|p{7.5cm}}
API Method 	& Description \\ \hline
\APIMethod{da\_get\_sess()} 		& Load record of old session. \\
\APIMethod{da\_update\_sess()} 		& Save the session as permanent. \\
\APIMethod{da\_create\_temp\_sess()}& Create new temporary session. \\
\APIMethod{da\_get\_sess()} 		& Load contents of new session. \\
\APIMethod{da\_db\_commit()} 		& Commit save action. \\
\end{tabular}

\subsection{Close Session}
\label{subsec:closesession}

If the current session is modified and if the user is privileged, the user
is offered the option to save the changes before actually closing the
session. Otherwise the session will be closed without comment.

After closing the session the map-frame will be updated to be a blank frame.

\subsubsection{DB API Method Calls}

\begin{tabular}{p{6cm}|p{7.5cm}}
API Method 	& Description \\ \hline
\APIMethod{da\_delete\_sess()} & Delete the current temporary session. \\
\APIMethod{da\_db\_commit()}   & Commit changes. \\
\end{tabular}


\subsection{Delete Session}
\label{subsec:deletesession}

This feature is only available for the privileged user.

A dialog similar as for 'Open Session' (see \ref{subsec:opensession})
is displayed allowing to select the session that should be removed 
from the database. The user can only remove sessions for which he has
appropriate user privileges (i.e. his own sessions, sessions where his
group has editing rights and sessions where all have editing rights).

After selection, the user is required to confirm the action.

If the current session has been deleted, the map-frame will be updated to be a blank frame.


\subsubsection{DB API Method Calls}

\begin{tabular}{p{6cm}|p{7.5cm}}
API Method 	& Description \\ \hline
\multicolumn{2}{l}{Delete session dialog functionality:} \\ \hline
\APIMethod{da\_get\_sess()} 	& Load list of sessions.  \\
\APIMethod{da\_get\_user()} 	& Get user to check privileges.  \\
\APIMethod{da\_get\_subst()} 	& Load substance for info dialog. \\
\APIMethod{da\_get\_catch()}    & Load catchment for info dialog. \\
\APIMethod{da\_get\_group()}    & Load group for info dialog. \\

\multicolumn{2}{l}{If a session has been selected:}\\ \hline
\APIMethod{da\_delete\_sess()}  & Delete selected session (and according data).\\
\APIMethod{da\_db\_commit()}  	& Commit changes. \\
\end{tabular}

%
%------------------------------------------------
%
\clearpage
\section{Substance Management}
\label{sec:substance}

\subsection{New Substance}
\label{subsec:newsubstance}

As identified above, the substance parameters needed for a mode 1 simulation
are clear. A screen provides access on the data including also parameters for
substance identification. The dialogs do not provide the scientific parameter 
functionality as provided by the stand-alone client. Distributed parameters
will be either not distributed or normal distributed.


\subsubsection{DB API Method Calls}

\begin{tabular}{p{6cm}|p{7.5cm}}
API Method 	& Description \\ \hline
\multicolumn{2}{l}{New substance dialog functionality:} \\ \hline
\APIMethod{da\_get\_para\_tree()} 	& Get parameter information. \\
\multicolumn{2}{l}{If a new substance has been specified:}\\ \hline
\APIMethod{da\_insert\_subst()} 	& Insert substance. \\
\APIMethod{da\_insert\_subst\_det()} 	& Insert substance details.\\
\APIMethod{da\_get\_sess()} 	& Insert substance. \\
\APIMethod{da\_update\_sess()} 	& Insert substance. \\
\APIMethod{da\_db\_commit()}		& Commit changes.
\end{tabular}

\subsection{Open Substance}
\label{subsec:opensubstance}

The user is displayed a list of available substances. 

On selection the new substance replaces the former data set. Emission data
and simulation results related to this former substance are removed for the
(temporary) session.


\subsubsection{DB API Method Calls}

\begin{tabular}{p{6cm}|p{7.5cm}}
API Method 	& Description \\ \hline
\multicolumn{2}{l}{Open substance dialog functionality:} \\ \hline
\APIMethod{da\_get\_subst()} 	& Load list of substances. \\

\multicolumn{2}{l}{If a substance has been selected:}\\ \hline
\APIMethod{da\_get\_sess()} 	& Load session record. \\
\APIMethod{da\_get\_subst()} 	& Load substance data. \\
\APIMethod{da\_insert\_subst()} 	& Create new substance and ...\\
\APIMethod{da\_get\_subst\_det()} 	& ... copy the details ...\\
\APIMethod{da\_insert\_subst\_det()} 	& ... for the new substance.\\
\APIMethod{da\_update\_sess()}		& Relate the new substance to the 
						session.\\
\APIMethod{da\_delete\_subst()}		& Delete the old substance data. \\

\multicolumn{2}{l}{If the current session contains emission or result data:}\\
									\hline
\APIMethod{da\_delete\_res()}		& Delete the old result data. \\
\APIMethod{da\_get\_market()}		& Load market record. \\
\APIMethod{da\_delete\_market()}	& Delete the old market data. \\
\APIMethod{da\_get\_sess\_disch()}		& Load discharge record. \\
\APIMethod{da\_delete\_sess\_disch()}		& Delete the old discharge data. \\

\multicolumn{2}{l}{Finally:}\\ \hline
\APIMethod{da\_db\_commit()}		& Commit changes.
\end{tabular}


\subsection{Edit Substance}
\label{subsec:editsubstance}

As identified above, the substance parameters needed for a mode 1
simulation are clear. A screen provides access on the data including also
parameters for substance identification. The dialogs do not provide the
scientific parameter functionality as provided by the stand-alone client.
\\

If a parameter is distributed this will be shown by a specific notification
of the current value:
$<param1;param2/distribution>$ represents  a two-parameter distribution and
the distribution type. $<mean/None>$ specifies a parameter which can be
distributed but where only a mean value has been provided so far. If the
user wants to change the distribution type or parameter, he can use this
notification.

\subsubsection{DB API Method Calls}

\begin{tabular}{p{6cm}|p{7.5cm}}
API Method 	& Description \\ \hline
\multicolumn{2}{l}{Edit substance dialog functionality:} \\ \hline
\APIMethod{da\_get\_para\_tree()} 	& Get parameter information. \\
\APIMethod{da\_get\_subst\_det()} 	& Get detailed substance information. \\
\multicolumn{2}{l}{If changes have been made to the substance:}\\ \hline
\APIMethod{da\_get\_subst()} 		& Load substance record. \\
\APIMethod{da\_update\_subst()} 	& Save substance. \\
\APIMethod{da\_get\_subst\_det()} 	& Load substance details records. \\
\APIMethod{da\_update\_subst\_det()}& Save substance details.\\
\APIMethod{da\_get\_sess()} 		& Load session record. \\
\APIMethod{da\_update\_sess()} 		& Save session with new substance. \\
\APIMethod{da\_db\_commit()}		& Commit changes.
\end{tabular}

\subsection{Save Substance}
\label{subsec:savesubstance}

This feature is only available for privileged users.
In addition to the system wide template data sets users can save private
substance templates. The contents of the current substance data set are
stored into a new data set.

A save substance dialog is displayed allowing to change name and comment of
the substance so that it can be distinguished from the original one.

\subsubsection{DB API Method Calls}

\begin{tabular}{p{6cm}|p{7.5cm}}
API Method 	& Description \\ \hline

\APIMethod{da\_get\_subst\_det} 	& Get substance details... \\
\APIMethod{da\_update\_subst\_det} 	& ...to update the attribute NAME. \\
\APIMethod{da\_get\_subst} 			& Get substance ... \\
\APIMethod{da\_update\_subst} 		& ...to update the attribute NAME 
										and COMMENT. \\
\APIMethod{da\_get\_subst()} 		& Get new record. \\
\APIMethod{da\_insert\_subst()} 	& Save substance. \\
\APIMethod{da\_get\_subst\_det} 	& Get new substance details... \\
\APIMethod{da\_insert\_subst\_det()}& Save substance details.\\
\APIMethod{da\_get\_sess} 			& Get session record... \\
\APIMethod{da\_update\_sess()}		& Save session with new substance.\\
\APIMethod{da\_db\_commit()}		& Commit changes.
\end{tabular}

\subsection{Delete Substance}
\label{subsec:deletesubstance}

This feature is only available for privileged users.
Substances from the private template collection can be deleted.

After selection, the user is required to confirm the action.


\subsubsection{DB API Method Calls}

\begin{tabular}{p{6cm}|p{7.5cm}}
API Method 	& Description \\ \hline
\multicolumn{2}{l}{Delete substance dialog functionality:} \\ \hline
\APIMethod{da\_get\_subst()} & Load list of substances.  \\
\APIMethod{da\_get\_user()}  & Load user of each substance to identify
								privileges.  \\
\APIMethod{da\_get\_user()}  & Get user of substance (for details of
								substance).\\
\APIMethod{da\_get\_group()} & Get group of substance (for details of
								substance).\\

\multicolumn{2}{l}{If a substance has been selected:}\\ \hline
\APIMethod{da\_get\_subst()} 	& Load substance record for confirmation
									dialog.  \\
\APIMethod{da\_delete\_subst()} & Delete selected substance.\\
\APIMethod{da\_db\_commit()}  	& Commit changes. \\
\end{tabular}

\clearpage
\section{Catchment Management}
\label{sec:catchment}

\subsection{Open Catchment}
\label{subsec:opencatchment}

The user is displayed a list of available catchment. 
On selection the new catchment replaces the former data set. The map frame
will be updated afterward.


\subsubsection{DB API Method Calls}

\begin{tabular}{p{6cm}|p{7.5cm}}
API Method 	& Description \\ \hline
\multicolumn{2}{l}{Open catchment dialog functionality:} \\ \hline
\APIMethod{da\_get\_catch()} 	& Load list of catchments.  \\

\multicolumn{2}{l}{If a new catchment has been selected:}\\ \hline
\APIMethod{da\_get\_sess()} 	& Load session record. \\
\APIMethod{da\_update\_sess()} 	& Save session changes. \\
\multicolumn{2}{l}{If catchment has been selected and not loaded before,
load new map:}\\\hline
\APIMethod{da\_get\_bin\_obj()}	& Load geographic data. \\
\APIMethod{da\_get\_backgrd()}	& Load information about background data. \\
\APIMethod{da\_get\_bin\_obj()}	& Load background data. \\

\multicolumn{2}{l}{If the current session contains emission or result data:}\\
									\hline
\APIMethod{da\_delete\_res()}		& Delete the old result data. \\
\APIMethod{da\_get\_market()}		& Load market record. \\
\APIMethod{da\_delete\_market()}	& Delete the old market data. \\
\APIMethod{da\_get\_sess\_disch()}		& Load discharge record. \\
\APIMethod{da\_delete\_sess\_disch()}		& Delete the old discharge data. \\

\multicolumn{2}{l}{Finally:}\\ \hline
\APIMethod{da\_db\_commit()}	& Commit changes.
\end{tabular}

\subsection{Edit Emission}
\label{subsec:editemission}

The 'Edit Emission' feature will be implemented as a tool in the maps
toolbar.

It allows selection of a local emission point and access on site specific
consumption and additional inputs.


\subsubsection{DB API Method Calls}

\begin{tabular}{p{6cm}|p{7.5cm}}
API Method 	& Description \\ \hline

\multicolumn{2}{l}{Edit emission dialog functionality:} \\ \hline
\APIMethod{da\_get\_disch()} 	& Get discharge data.\\
\APIMethod{da\_get\_market()} 	& Get market data of discharge if
									existent.\\
\APIMethod{da\_get\_para\_tree()} & Get parameter data.\\

\multicolumn{2}{l}{If the session has already local market data:}\\ \hline
\APIMethod{da\_get\_market()  }& Get local market record\\

\multicolumn{2}{l}{If the emission point has no market data:}\\ \hline
\APIMethod{da\_insert\_market()  } & Insert new market record.\\

\multicolumn{2}{l}{If the emission point has already market data:}\\ \hline
\APIMethod{da\_update\_market() } & Update the record.\\

\multicolumn{2}{l}{Finally:}\\ \hline
\APIMethod{da\_get\_sess()}	& Load new session data.\\
\APIMethod{da\_db\_commit()}& Commit changes.
\end{tabular}


\clearpage

\subsection{Edit Discharge}
\label{subsec:editdischarge}

The 'Edit Discharge' feature will be implemented as a tool in the map
toolbar.

It allows selection of a discharge point and access on site specific 
discharge data as identified above (see \ref{sec:general}).


\subsubsection{DB API Method Calls}

\begin{tabular}{p{6cm}|p{7.5cm}}
API Method 	& Description \\ \hline
\multicolumn{2}{l}{Edit discharge dialog functionality:} \\ \hline
\APIMethod{da\_get\_disch()  } 		& Get discharge data.\\
\APIMethod{da\_get\_sess\_disch()  }& Get local discharge data of discharge
site if existent.\\
\APIMethod{da\_get\_para\_tree()  } & Get parameter data.\\

\multicolumn{2}{l}{If the session has already local discharge data:}\\ \hline
\APIMethod{da\_get\_sess\_disch()  }& Get local discharge record\\

\multicolumn{2}{l}{If the discharge has no site specific data:}\\ \hline
\APIMethod{da\_insert\_disch()  } & Insert new site specific discharge record.\\

\multicolumn{2}{l}{If the discharge has already site specific data:}\\ \hline
\APIMethod{da\_update\_disch() } & Update the record.\\

\multicolumn{2}{l}{Finally:}\\ \hline
\APIMethod{da\_get\_sess()}	& Load new session data.\\
\APIMethod{da\_db\_commit()}& Commit changes.
\end{tabular}

\clearpage
\section{Model}
\label{sec:model}

\subsection{Edit Model Parameters}
\label{subsec:editmodelparameters}

The functionality of GREAT-ER Web is concentrated on the model mode 1 for
the compartments considered, with an including of sewer in comparison with 
GREAT-ER 1.0. Therewith the only required model parameter is the number of
Monte-Carlo-Shots.


\subsubsection{DB API Method Calls}

\begin{tabular}{p{6cm}|p{7.5cm}}
API Method 	& Description \\ \hline
\APIMethod{da\_get\_mod\_det() } 	& Load the record.\\
\APIMethod{da\_update\_mod\_det() } & Update the record.\\
\APIMethod{da\_db\_commit() } 		& Commit changes.\\
\end{tabular}

\subsection{Run Simulation}
\label{subsec:runsimulation}

Since all changes in the current sessions are synchronized immediately with
the database no action has to be done before starting the simulation.  When
the simulation finished properly, the results are loaded.

GREAT-ERWeb only manages GREAT-ER simulations in model mode 1. If
the current session has model modes different from mode 1 the user will be
asked to either change all modes of the current session to mode 1 or to
cancel the request. The model mode changes will be made permanent when the
user is saving the session.


All API methods used by the simulation server are already defined by 
the implementation of the GREAT-ER 1.0 simulator wrapper in
GREAT-ER II phase 1.


\subsubsection{DB API Method Calls}

\begin{tabular}{p{6cm}|p{7.5cm}}
API Method 	& Description \\ \hline
\APIMethod{da\_get\_sess()} 		& Reload session 
						(now contains results ID).\\
\APIMethod{da\_get\_bin\_obj()}	& Load stretch results. \\
\APIMethod{da\_get\_res()} 		& Load results. \\
\end{tabular}

\clearpage

\section{Analysis}

GREAT-ER Web provides the core analysis tools of GREAT-ER to demonstrate and
explain the GREAT-ER approach: The two PEC concepts and the sampling of a
concentration profile. 

\subsection{PEC Initial}

The PEC$_{Initial}$ is the spatial aggregation of concentrations in the  
river directly after emission. This is similar to
the PEC$_{local}$ as defined in the EU Technical Guidance Documents, 
although its calculation is different.
Based on the C$_{sim, start}$ mean values, the mean is calculated for 
all stretches receiving treated or untreated discharges.

\subsubsection{DB API Method Calls}

\begin{tabular}{p{6cm}|p{7.5cm}}
API Method 	& Description \\ \hline
\APIMethod{da\_get\_disch() } 	& Load discharge data.\\
\APIMethod{da\_get\_res() } 	& Load result record.\\
\APIMethod{da\_update\_res() } 	& Insert pec\_initial information.\\
\end{tabular}

\subsection{PEC Catchment}

The PEC$_{Catchment}$ is the average of representative concentrations 
over the entire catchment. This is a concept
for  geo-referenced  exposure  assessment published with GREAT-ER 1.0,  
although  there  is  some  analogy  with  the  PEC$_{regional}$  
in  the EU Technical Guidance Documents. 

The calculation of PEC$_{Catchment}$ can be based on any of the 
previously derived percentiles of the model results. 

Three different results are calculated based on the different 
weighting methods:
\begin{enumerate}
	\item weighting  by  volume  based  on  the  subset  of  
		loaded  stretches  and  on  all  stretches  within  the
		catchment;
	\item weighting by stretch length based on the subset of 
		loaded stretches and on all stretches within the
		catchment;
	\item weighting by flow increment based on all stretches 
		within the catchment.
\end{enumerate}

\subsubsection{DB API Method Calls}

\begin{tabular}{p{6cm}|p{7.5cm}}
API Method 	& Description \\ \hline
\APIMethod{da\_get\_res() } 	& Load result record.\\
\APIMethod{da\_get\_stretch() } & Load stretch data.\\
\APIMethod{da\_update\_res() } 	& Insert pec\_initial string.\\
\end{tabular}

\subsection{Concentration Profile}

The 'Concentration Profile' feature is implemented as a tool of the map
toolbar: After selecting a river stretch C$_{sim, internal}$ mean values are
sampled for all stretches downstream to the catchment outlet. 

The profile is displayed in a diagram.

\subsubsection{DB API Method Calls}

\begin{tabular}{p{6cm}|p{7.5cm}}
API Method 	& Description \\ \hline
\APIMethod{da\_get\_stretch() } 	& Load stretch data.\\
\APIMethod{da\_get\_res() } 		& Load result record.\\
\APIMethod{da\_get\_res\_stretch() }& Load results of stretches.\\
\end{tabular}

\begin{appendix}

\include{gnufdl}

\end{appendix}

\end{document}



