\renewcommand{\documentID}{\$Id: howto.tex,v 1.9 2007-06-06 16:30:05 frank Exp $ $}

\chapter{How-To}
\label{chap:HowTo}


\section{Software Requirements}
\begin{itemize}
	\item Python $\ge$ 2.2.1
	\item GNU Awk $\ge$ 3.1.0
	\item gen2shp $\ge$ 0.3.0 \newline
		  (\verb"http://intevation.de/~jan/gen2shp/")
	\item txt2dbf $\ge$ 1.0.2
	\item dbf2txt $\ge$ 0.5.2 \newline
		  (\verb"http://www.usf.uos.de/~fkoorman/software/dbftools.en.html")
	\item GNU textutils (sort, join, cut, paste) $\ge$ 2.0
	\item GNU fileutils (rm) $\ge$ 4.1
	\item GNU sed version $\ge$ 3.02
	\item GNU sh-utils (echo) $\ge$ 2.0.11
\end{itemize}

(all the programs must be somewhere in your search path)

\section{Prerequisites}
\label{sec:prerequisites}

As a first step you have to copy greater-pre-processing.py somewhere
into you PATH or extend the PATH to where you have installed
the greater-pre-processing package:

  \verb+cp greater-pre-processing.py /some/where/in/your/search/path+

  OR

  \verb+export PATH=$PATH:/some/where/greater-pre-processing+

Next, set this environment variable that points to where you have
installed the greater-pre-processing package:

  \verb+export GREATER_PRE_PROC=/some/where/greater-pre-processing+

You then are able to execute

  \verb+greater-pre-processing.py+

in a directory with the pre-defined files for your catchment
(you will be given further info on how to use the program).

\section{Running the Data Preprocessing}

{\footnotesize
\begin{verbatim}
$ greater-pre-processing.py help
greater-pre-processing 1.2.0

Found 'catchment.desc':
 ID                    = aire
 Name                  = Catchment of River Aire including River Calder
 Description           = The Aire catchment is in Yorkshire, UK
 Format version src    = 1.0
 Format version result = 2.0
description complete.

greater-pre-processing [check|help|run|run-without-cleanup|clean]
 help  print this text
 check test for completeness and correct syntax of source files
 run   execute catchment pre-processing
 run-without-cleanup execute catchment pre-processing not removing
                     temporary files
 clean remove all temporary and all results files
\end{verbatim}
}

\section{Integrate a catchment into GREAT-ER 1.0}

First, make sure, that OUT-VERSION in catchment.desc
is set to 1.0, then process the data.

Now copy all files *.shp, *.shx, *.dbf into \%GHOME\%/catchments/ID
where ID is the name of the new catchment.
Finally, add the new catchment to \%GHOME\%/catchments.dbf,
see http://great-er.intevation.org/catchments\_dbf.html for how to
do this.

\section{Integrate a catchment into GREAT-ER 2.0}

First, make sure, that OUT-VERSION in catchment.desc
is set to 2.0, then process the data.

Before uploading the data make sure that relevant values 
(GISFILELIST, STRETCH\_TAB, DISCH\_TAB) are set in catchment.desc
(see section \ref{sec:catchment.desc} and \ref{sec:gisfilelist} for details).

The upload process will perform the following steps:
\begin{itemize}
\item Create a new Catchment entry in the CATCH\_TAB.
\item Upload all stretch data into STRETCH\_TAB (including appropriate
      conversion).
\item Upload all discharge data into DISCH\_TAB (including appropriate
      conversion).
\item Upload all GIS data (shapefiles) and additional binary files.
\end{itemize}

Change to the directory of the data to be uploaded. If path values are set
according to the prerequisites (section \ref{sec:prerequisites}), run:

  \verb+upload-catchment.py+

If running the upload under MicroSoft Windows it might be necessary to include
the Python binary, e.g.:

  \verb+..\..\Python22\python.exe ..\..\upload\upload-catchment.py+
\\

A wizard guides you through the upload:
\begin{itemize}
\item Upload information screen
\item Parameters for database connection
\item Upload confirmation. Selecting {\em Next} the upload is started!
\item After displaying the progress the status of the upload is reported.
\end{itemize}  

