\renewcommand{\documentID}{\$Id: howto.tex,v 1.7 2003-07-17 11:18:37 jan Exp $ $}

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


\section{Software Requirements}
\begin{itemize}
	\item Python $\ge$ 2.0
	\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}

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.

With the GREAT-ER II Administration Tool:
\begin{itemize}
	\item Create a new catchment entry (CATCH\_TAB)
	\item Upload all geographic data into the data base (BIN\_OBJ\_TAB)
	\item Relate available background data in the database to the 
		new catchment (BACKGRD\_JOIN\_TAB) 
\end{itemize}

Prepare the discharge and stretch attributes by running the scripts
\verb+insert-disch_att.py+ and \verb+insert-stretch_att.py+.
The scripts generate sequences of SQL-statements. These can be 
executed by the database SQL shell to upload the attributes.

