\documentclass[dvips]{report}
\usepackage{makeidx}
\usepackage{a4}
\usepackage{graphicx}
\usepackage{html,htmllist}
% \usepackage{times}
\scrollmode
% use %sort -f -u manual.idx > manual.index for a primitive index
%
%  NOTE:  You must use LaTeX2e in order to process this document
%	If you do not have LaTeX2e, a PostScript version
%	(manual.ps) is included with this distribution.
%
%%%%%%%%%%%%%%%%%%% No changes beyond this point %%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\makeindex
\sloppy
% Transforms the \indexentry generated by \makeindex in the concepts.idx
% file into a form understood by the theindex environment.
% See below on how to produce an index.
%
\newcommand{\latextohtml}{\LaTeX 2\texttt{HTML}}
\newcommand{\fn}[1]{{\ttfamily #1}}	% file names
\newcommand{\Email}[1]{{\ttfamily <#1>}}% file names
\newcommand{\HTML}[1]{{\ttfamily <#1>}}%  HTML tag
\newcommand{\Meta}[1]{\texttt{<\emph{#1}>}}%  Meta string
\newcommand{\indexentry}[2]{\item #1 #2}
\def\contrat{contrat numero N de l'ESA}
\newcommand{\onlinedoc}{http://www-dsed.llnl.gov/files/programs/unix/latex2html/manual/}
\newcommand{\patches}{http://www-dsed.llnl.gov/files/programs/unix/latex2html}
\newcommand{\sourceA}{ftp://www-dsed.llnl.gov/files/programs/unix/latex2html/sources/latex2html-96.1.tar.gz}
\newcommand{\sourceB}{ftp://ftp.mpn.com/pub/nikos/latex2html-96.1.tar.gz}
\newcommand{\sourceC}{ftp://ftp.rzg.mpg.de/outgoing/latex2html-96.1.tar.gz}
\newcommand{\CTAN}{tex-archive/support/latex2html}

%\setlength{\textwidth}{5.5in}
%\setlength{\textwidth}{16cm}
%\setlength{\changebarwidth}{1pt}
%\addtolength{\oddsidemargin}{-1in}
%\addtolength{\oddsidemargin}{-2cm}
%\addtolength{\evensidemargin}{-1in}
%\addtolength{\evensidemargin}{-2cm}
\begin{document}
\bibliographystyle{abbrv}

%\input{def}
\sloppy
\title{Documentation et manuel d'utilisation\\
du\\
serveur WWW\\
de l'Atmosphère de Mars
\author{Christophe Hourdin}
\date{\today}}

\maketitle 

\begin{htmlonly}
Ce document est également disponible sous forme
\htmladdnormallink{postscript}{doc.ps}.
\index{postscript version}
\end{htmlonly}


\begin{abstract} 
\end{abstract}

\tableofcontents

\part{La documentation du GCM Martien}

\part{La serveur Martien - Base de données}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%	DEFINITIONS
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\def\repgd{{\it /dg/chourdin/gd1.2}}
\def\reppzf{{\it WWW/ferret/pzf}}
\def\rephtml{{\it WWW/ferret/pcgi\_htmls\_v2.0}}
\def\repworld-small{{\it WWW/ferret/world-small}}
\def\repsrc{{\it WWW/live\_access/src}}
\def\repp{{\it WWW/ferret/p}}
\def\repdata{{\it WWW/mars\_data}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\chapter{Généralitées sur le serveur}

\section{Attention chaine de caractère des axes!}
Dans {\it present\_data.c}, La chaine de caractère de chacun des axes
est initialisée en blanc par:
\begin{verbatim}
char *axString[4]={"         ", "          ",
             "               ", "             "};
\end{verbatim}
Surtout avec l'altitude donnée en "sigma\_level", il est nécessaire
d'élargir cette chaîne de caractères.\\
Si cette chaine est trop courte, le serveur renvoie un message d'erreur
indiquant des arguments abhérents pour les GO scripts ferret en ce
qui concerne les valeurs de temps, level... des axes.

\section{Attention dans {\it initialize.h}!}
La première variable dans {\it initialize.h} (variable 0) doit
être doublée. Pour la faire apparaitre sur le menu de la page
html, il faut la référencer par {\bf !1} (variable 1) et non par
{\bf !0} (variable 0) dans {\it select-by-dataset.html.template.frames}
 au risque de ne pas voir apparaitre de page
lorsqu'on clique sur le bouton "Change data set" de la main page (et pas
de message d'erreur ce qui permet de se poser à peu près 300.000
questions).

\section{Test Modifications}
Lorsqu'on effectue des modifications dans les scripts ferret (.jnl)
appellés par le serveur, il faut, pour tester ces changements quitter
et relancer netscape. Un reload ne suffit pas. Il faut également,
comme à chaque test, aller détruire dans \repp \ l'image
correspondante, afin de forcer le serveur à la recréer (avec
le nouveau script par exemple).\\

On peut aussi, quand on ne comprend plus rien! (modifications sans
effets) , detruire tous les .o et recompiler.

\section{Les GO scripts ferret (.jnl)}
Les seuls scripts appellés directement par le serveur sont:\\
"setup\_region.jnl"\\
"std\_gif\_*.jnl"\\
"refmap.jnl"\\
"std\_list.jnl"\\
Ils sont appellés par le programme {\it live\_access.c} (répertoire \repsrc).\\

Afin de savoir quelles sont les commandes passées par le serveur à
ferret pour créer les images et ainsi pouvoir les modifier, on a
créé une sortie de toutes ces commandes (fichier {\it MOMO} dans
\repp).

\section{Les cannevas (template et frames)}
Le serveur va lire les fichiers .template et .frames stockés dans le répertoire \rephtml \ et
remplace le numéro rencontré après un "{\bf !}" dans ces
fichiers par le nom correspondant dans le fichier {\it
initialize.h} (\repsrc).

\section{Format image gd}
Le format {\it gd} est un format image qui permet d'afficher rapidement
une image sous HTML (librairie et démo dans \repgd).

Les fonctions correspondantes utilisées par le serveur sont dans le
fichier {\it gd.c} (répertoire \repsrc).

\chapter{Pour modifier le serveur}

\section{Changement de l'image en première page}
Cette image est stockée en format {\it gd} dans le répèrtoire
\reppzf \  sous le nom de {\it world-small.gd}\\

Attention: cette image doit etre en coordonnees 0:360 -90:90\\

Afin de créer cette image, on peut générer par n'importe quel
utilitaire une image au format GIF et la convertir ensuite avec {\it
giftogd} (répertoire \repgd).

Si on veut créer une image à partir de {\it ferret}, ferret ne pouvant
générer que du metafile (GKSM format), il est nécessaire ensuite de
convertir ce format au format gd. Le shell script {\it Meta2gif} s'en charge
(répertoire \repworld-small). Il passe du format GKSM au format ps
par gksm2ps ou par la fonction Fprint de ferret, puis du format ps au
format ppm par ghostscript, et enfin du format ppm au format gif par
ppmtogif. Il faut ensuite bien sur lancer la commande "giftogd  out.gif
out.gd". 

\section{3 bugs pour le zoom en (-180:180)}
remet la valeur a 180 au lieu de -180 au 2eme appel du zoom.\\

Dans {\it pzf.c}, le calcul de la largeur du cadre du zoom donne 0 
pour x1 = x2 (cas de -180 a 180 ou -180 est ramene a 180 par addition
de 360). Il faut donc rajouter le cas d'egalité dans $if ( x1 >= x2
) then width =(sx-x1)+x2$ sinon $width=x2-x1=0$, et on obtient alors un
trait vertiavl sur la map à 180 degrés.\\

Quand on demande un zoom sur une région en -180: 180, de retour sur
la page principal, le serveur indique 180:180 au lieu de 180e:180w. Le
traitement de la chaine de caractère pour la longitude est fait dans
{\it test\_axis\_entries.c}. Il faut retirer le cas de la fin du
traitement qui fixe à 180 tout ce qui est en 180 (180e ou 180w).\\
Il faut donc remplacer:

\verb+if (rval == 180.0 || rval == 360.0 || rval == 0.0)+\\
par

\verb+if (rval == 360.0 || rval == 0.0)+\\

\noindent
Il faut également remplacer:

\verb+if (kar == 'w' && rval >= 180.0)+\\
par 

\verb+if (kar == 'w' && rval > 180.0)+\\

\noindent
et

\verb+else if (kar == 'e' && rval >= 180.0)+\\
par

\verb+else if (kar == 'e' && rval > 180.0)+



\section{Changement des régions prédéfinies pour le Zoom}
Indiquer les coordonnées du zoom dans le fichier
{\it process\_xy\_zoom\_menu.c} ainsi qu'un nom correspondant à cette
région.\\
Reporter ce nom dans les fichiers {\it zoom.html.template} et
{\it second\_zoom.html.template} du répertoire \rephtml.

\section{Changement de la couleur du cadre pour le zoom}
Dans le fichier {\it pzf.c} (répertoire \repsrc), changer les valeurs
pour rouge, vert et bleu de la fonction {\it gdImageColorAllocate}.

trait\_couleur = gdImageColorAllocate(imo, ROUGE, VERT, BLEU);\\
Chacune des couleur allant de 0 à 256.

exemple pour un trait bleu:

trait\_couleur = gdImageColorAllocate(imo, 0, 0, 255);

\section{Changement des données}
Pour donner l'acces à des données, il faut qu'elles soient au format Netcdf et placées dans un des
répertoires désignés par la variable FER\_DATA (variable définie dans le fichier
{\it site\_specific\_references.h} \ du répertoire \repsrc). A priori on les place dans \repdata{\it/data}.\\

On spécifie ensuite les nouvelles données dans le fichier {\it initialize.h} de \repsrc.\\

Puis, pour voir ces nouvelles données apparaitre dans le menu "Change Data Set", on indique dans le
fichier {\it select-by-dataset.html.template.frames} (\rephtml),
derriere un point d'exclamation "{\bf !}", l'index correspondant au nouveau jeu
de données (index fixé dans {\it initialize.h}).\\

\section{Changement des valeurs par défaut}
Pour sélectionner le fichier de données, et la variable choisie
par défaut au moment de la connexion, , changer la valeur de "MOMO\_default"
 dans {\it get\_current\_status.c} par l'index correspondant à la variable
souhaitée (index fixé dans {\it initialize.h}).\\

La vue par défault choisie est celle fixée dans la définition
de la variable dans {\it initialize.h}.\\

\section{Gestion de l'axe temps}
\subsection{Cas une variable un fichier Netcdf}
Le serveur est initialement prévu pour 2 cas:\\
La date sous forme jour et mois (ex: 16-dec) avec le cas ONE\_WIDGET, \\
La date sous forme jour,mois et année (ex: 15-dec-1988) avec le cas
MONTH\_YEAR.\\
Les dates définies à la fin du fichier {\it initialize.h} correspondent
chacune à une valeur, qui correspond dans le fichier Netcdf à une
valeur  de temps en "hour" ou "day" ou... Ferret prend cette valeur
comme un offset par rapport à la date de réference du fichier
Netcdf:\\
exemple d'entête d'un fichier Netcdf:\\
 {\it time:units = "days since 1984-01-01"}).

\subsection{Cas une variable plusieurs fichiers Netcdf (stats)}
\subsubsection{Cohérence en temps des différents fichiers} 

Lorsqu'on a un fichier Netcdf par jour par exemple, on peut
créer un fichier ferret de description ({\it .des}) qui appelle les
différents fichiers Netcdf. L'appel des différent fichiers est
basé sur la chronologie de l'axe des temps. Les fichiers peuvent ne
pas être régulièrement espacés, (Time INDEPENDANT), mais
doivent avoir la même unité de temps et des temps qui se
succèdent.\\
Par exemple:\\
Le fichier "simulation.des" appelle\\
fichier "simulation.001" time(in days)  7000 7001 7002\\
fichier "simulation.002" time(in days)  7053 7055 7089\\
fichier "simulation.003" time(in days)  8427 8428 8429\\
On indique dans le fichier .des une date de référence et la valeur
du jour qui correspond.\\
exemple:\\
D\_T0TIME = '14-JAN-1984 00:00:00',\\
S\_START = 7000.0,


\subsubsection{Pas de cohérence en temps des différents fichiers} 

Voir cahier au Mercredi 19 Mars 1997.\\

Dans le cas des fichiers "stats", il n'y a pas de cohérence en temps,
puisque les fichiers contiennent des moyennes diurne sur la période
de simulation. On dispose donc de 12 valeurs de temps (toutes les 2
heures) par mois de simulation. On ne peut donc pas créer un fichier
.des.\\
On a modifié le programme, pour avoir une date sous la forme:\\
"A2m1-h20", ou A2m1 est récupéré et ajouté comme extension au
nom du fichier de données, et h20 est identifiée par le 'h' comme
l'heure 20, la valeur de time du fichier Netcdf.\\

Le fichier {\it present\_data.c} récupère les
informations pour ferret, les met en forme, puis appelle le programme
{\it live\_access} qui se charge de lancer les GO.\\

3 cas sont possibles pour le temps dans {\it present\_data.c}:\\
1/ les valeurs de temps ont étées affectées à l'exterieur
dans TLO et THI. On détecte donc la première lettre de ces valeurs
et on traite en fonction. \\
2/ une valeur de temps est affectée dans la variable "value" par 
{\it validate\_custom\_location}. On détecte donc la première lettre de
value.\\
3/ une valeur de temps est affectée dans la variable "value" par 
{\it get\_axis\_location}. On détecte également la première lettre de
value.\\
On modifie également la fonction  {\it get\_axis\_location}. On
rajoute le cas LS\_STATS (en plus de ONE\_WIDGET et MONTH\_YEAR).\\

On récupère dans chacun de ces trois cas, le début (A2m12 par
exemple) pour affecter la variable "DSET\_ext". Cette variable est
définie dans {\it tmap\_cgi.h}. Cette variable est l'extension qu'on
concatène au nom du fichier netcdf avant l'appel à {\it live\_acces}.\\
Il faut également l'intégrer dans le nom du fichier gif
créé, sinon un même nom de fichier correspondra à plusieurs
cas (ex: {\it viking\_year\_xy\_ps-180.0:180.0\_-90.0:90.0\_12.gif}) pour 
tous les mois. Il faut donc avoir un nom différent par saison ({\it
viking\_year\_a2m3\_xy\_ps...} et {\it viking\_year\_a3m7\_xy\_ps...}).\\

La récupération du temps se fait par 
la fonction {\it parse\_date} du fichier {\it
test\_axis\_entries.c}. On a rajouté dans cette fonction {\it
parse\_date} les cas HOUR\_SOLO et HOUR\_STATS.\\
HOUR\_SOLO pour une date en heure de la forme "h01"\\
HOUR\_STATS pour une date de la forme "A2m1-h20".\\

Il faut également modifier la fonction {\it express\_error\_sadness} du
fichier {\it test\_axis\_entries.c} pour avoir un message d'erreur sur le
temps approprié au cas LS\_STATS.

\section{Messages d'erreur}
Voir la fonction {\it express\_error\_sadness} dans {\it
test\_axis\_entries.c}. A l'appel de cette fonction, une page HTML est
créée avec le message d'erreur.\\
On peut en créer autant qu'on veut sur le même modèle.
(exemple {\it momo\_error\_sadness} dans le même fichier.

\section{Palette fonction de la variable}
la subroutine {\it live\_access.c} envoie à ferret la commande "GO
std\_gif\_..." 
Ce script a pour argument 7 le nom de la palette. {\it live\_access.c}
donne comme valeur pour l'argument 7 soit "light\_centered" (palettte
light\_centered.spk) soit " " (la palette par defaut "rainbow.spk?")
A la place, on lui passe comme argument 7 "var" le nom de la variable.
On place dans {\it WWW/mars\_data/palette} la palette voulue nommée
"var.spk". On remplace pour cela:

\verb+center ? "\"light_centered\"" : "\" \"");+\\
par

\verb+var);+

\section{Reglage Timeout pour ferret}

Si le temps d'execution des scripts GO de ferret est trop long, passé
un certain temps, le serveur stop ferret et redonne la main après un
message d'erreur. Ce temps est fixé dans {\it live\_access.c}: {\bf int
timeout}. Cet entier est passé en argument à la subroutine {\it
ferret\_synch}.

\section{Fond de carte: Map terrestre - relief martien}

Pour les cartes en Longitude-Latitude, au lieu d'utiliser en fond de
carte les continents
terrestres définis dans etopo30 etopo60...
(numero = différentes résolutions), on utilise le relief martien
de surface.cdf (variable zcon).\\
On effectue les remplacements ad'hoc dans les scripts {\it std\_gif\_xyref.jnl}
 et {\it std\_gif\_xyref.jnl}.

\section{Carte de référence: Map terrestre - relief martien}

Pour toutes les cartes (scripts {\it std\_gif\_*}), on souhaite avoir
comme carte de référence, si il y a lieu, le relief martien. Cette
carte est créée par {\it refmap.jnl}. On effectue dans {\it
refmap.jnl} les changements necessaires pour remplacer les continents
terrestres par le relief martien. Afin que refmap fonctionne comme cela
avait été prévu initialement, on a  besoin de rendre
périodique  en longitude le fichier surface.cdf qui contient le
relief martien par l'instruction:\\

\verb+ set axis/modulo longitude+ \\

\noindent
Un problème se pose dans la mesure ou en fonction de l'ordre
d'ouverture des différents fichiers par ferret, le nom de la
longitude est longitude ou longitude1 ou longitude2...
Pour régler ce problème, on ouvre en premier dans tous les
scripts {\it std\_gif\_*} le fichier surface.cdf. On sait alors qu'a
n'importe quel niveau des scripts, la longitude pour le fichier surface
se nomme "longitude".




%\chapter{Arborescence du serveur}

%\input{TREE_process.cgi}

\end{document}
