Commit 7c711ada authored by Uwe Schulzweida's avatar Uwe Schulzweida
Browse files

Docu update

parent 94cbd6d9
......@@ -34,6 +34,7 @@ doc/tex/c_zaxis.tex -text
doc/tex/cdi_cman.tex -text
doc/tex/cdi_fman.tex -text
doc/tex/cleanup -text
doc/tex/dataset.tex -text
doc/tex/f_examples.tex -text
doc/tex/f_grid.tex -text
doc/tex/f_link.tex -text
......@@ -46,6 +47,7 @@ doc/tex/f_vlist_var.tex -text
doc/tex/f_zaxis.tex -text
doc/tex/formats.tex -text
doc/tex/grid.tex -text
doc/tex/install.tex -text
doc/tex/intro.tex -text
doc/tex/makedoc -text
doc/tex/makehtml -text
......@@ -53,9 +55,12 @@ doc/tex/makepdf_c -text
doc/tex/makepdf_f -text
doc/tex/makeps_c -text
doc/tex/makeps_f -text
doc/tex/modules.tex -text
doc/tex/taxis.tex -text
doc/tex/test.tex -text
doc/tex/usage.tex -text
doc/tex/variable.tex -text
doc/tex/vlist.tex -text
doc/tex/zaxis.tex -text
examples/Makefile.am -text
examples/Makefile.in -text
......
......@@ -48,7 +48,7 @@ Function catalog:
vlistDefVarUnits Define the units of a Variable
vlistInqVarUnits Get the units of a Variable
vlistDefVarDatatype Define the data type of a Variable
vlistInqVarDatatype Get the datatype of a Variable
vlistInqVarDatatype Get the data type of a Variable
vlistDefVarMissval Define the missing value of a Variable
vlistInqVarMissval Get the missing value of a Variable
-------------------------------------------------------------
......
......@@ -647,7 +647,7 @@ Get the Code number of a Variable
int vlistInqVarDatatype(int vlistID, int varID);
\end{verbatim}
Get the datatype of a Variable
Get the data type of a Variable
\section*{\tt \htmlref{vlistInqVarLongname}{vlistInqVarLongname}}
......
......@@ -9,6 +9,26 @@
int vlistCreate(void);
\end{verbatim}
\subsubsection*{Example}
Here is an example using {\tt vlistCreate} to create a variable list
and add a variable with {\tt vlistDefVar}.
\begin{lstlisting}[language=C, backgroundcolor=\color{zebg}, basicstyle=\footnotesize]
#include "cdi.h"
...
int vlistID, varID;
...
vlistID = vlistCreate();
varID = vlistDefVar(vlistID, gridID, zaxisID, TIME_VARIABLE);
...
streamDefVlist(streamID, vlistID);
...
vlistDestroy(vlistID);
...
\end{lstlisting}
\subsection{Destroy a variable list: {\tt vlistDestroy}}
\index{vlistDestroy}
......
......@@ -22,7 +22,7 @@ Grid ID, from a previous call to {\htmlref{\tt gridCreate}{gridCreate}}
Z-axis ID, from a previous call to {\htmlref{\tt zaxisCreate}{zaxisCreate}}
\item[{\tt timeID}]
One of the set of predefined CDI time identifiers.
The valid CDI time identifiers are TIME\_CONSTANT and TIME\_VARIABLE.
The valid CDI time identifiers are {\tt TIME\_CONSTANT} and {\tt TIME\_VARIABLE}.
\end{deflist}
\end{minipage}
......@@ -32,6 +32,26 @@ One of the set of predefined CDI time identifiers.
{\tt vlistDefVar} returns an identifier to the new variable.
\subsubsection*{Example}
Here is an example using {\tt vlistCreate} to create a variable list
and add a variable with {\tt vlistDefVar}.
\begin{lstlisting}[language=C, backgroundcolor=\color{zebg}, basicstyle=\footnotesize]
#include "cdi.h"
...
int vlistID, varID;
...
vlistID = vlistCreate();
varID = vlistDefVar(vlistID, gridID, zaxisID, TIME_VARIABLE);
...
streamDefVlist(streamID, vlistID);
...
vlistDestroy(vlistID);
...
\end{lstlisting}
\subsection{Define the code number of a Variable: {\tt vlistDefVarCode}}
\index{vlistDefVarCode}
......@@ -270,17 +290,20 @@ Variable list ID, from a previous call to {\htmlref{\tt vlistCreate}{vlistCreate
\item[{\tt varID}]
Variable identifier
\item[{\tt datatype}]
Data type identifier
The data type identifier.
The valid CDI data types are {\tt DATATYPE\_PACK1}, {\tt DATATYPE\_PACK2},
{\tt DATATYPE\_PACK3}, {\tt DATATYPE\_REAL4} and {\tt DATATYPE\_REAL8}.
\end{deflist}
\end{minipage}
\subsection{Get the datatype of a Variable: {\tt vlistInqVarDatatype}}
\subsection{Get the data type of a Variable: {\tt vlistInqVarDatatype}}
\index{vlistInqVarDatatype}
\label{vlistInqVarDatatype}
The function {\tt vlistInqVarDatatype} returns the datatype of a variable.
The function {\tt vlistInqVarDatatype} returns the data type of a variable.
\subsubsection*{Usage}
......@@ -300,7 +323,9 @@ Variable identifier
\subsubsection*{Result}
{\tt vlistInqVarDatatype} returns an identifier to the datatype of the variable.
{\tt vlistInqVarDatatype} returns an identifier to the data type of the variable.
The valid CDI data types are {\tt DATATYPE\_PACK1}, {\tt DATATYPE\_PACK2}, {\tt DATATYPE\_PACK3},
{\tt DATATYPE\_REAL4} and {\tt DATATYPE\_REAL8}.
......
......@@ -167,11 +167,13 @@
\newpage
\section{Variable list functions}
\input{vlist}
\input{c_vlist}
\newpage
\section{Variable functions}
\input{variable}
\input{c_vlist_var}
......
......@@ -166,11 +166,13 @@
\newpage
\section{Variable list functions}
\input{vlist}
\input{f_vlist}
\newpage
\section{Variable functions}
\input{variable}
\input{f_vlist_var}
......
This module contains functions to read and write the data.
To create a new dataset the output format must be specified
with one of the following predefined file types:
\vspace*{3mm}
\hspace*{8mm}\begin{minipage}{15cm}
\begin{deflist}{{\large\tt FILETYPE\_GRB \ \ }}
\item[{\large\tt FILETYPE\_GRB}] File type GRIB version 1
\item[{\large\tt FILETYPE\_NC }] File type netCDF
\item[{\large\tt FILETYPE\_NC2}] File type netCDF version 2
\item[{\large\tt FILETYPE\_SRV}] File type SERVICE
\item[{\large\tt FILETYPE\_EXT}] File type EXTRA
\item[{\large\tt FILETYPE\_IEG}] File type IEG
\end{deflist}
\end{minipage}
\vspace*{3mm}
To set the byte order of a binary dataset with the file format
type {\tt FILETYPE\_SRV}, {\tt FILETYPE\_EXT} or {\tt FILETYPE\_IEG} use one of the
following constants in the call to {\htmlref{\tt streamDefByteorder}{streamDefByteorder}}:
\vspace*{3mm}
\hspace*{8mm}\begin{minipage}{15cm}
\begin{deflist}{{\large\tt CDI\_LITTLEENDIAN \ \ }}
\item[{\large\tt CDI\_BIGENDIAN }] Byte order big endian
\item[{\large\tt CDI\_LITTLEENDIAN}] Byte order little endian
\end{deflist}
\end{minipage}
\vspace*{3mm}
......@@ -651,7 +651,7 @@ Get the Code number of a Variable
INTEGER FUNCTION vlistInqVarDatatype(INTEGER vlistID, INTEGER varID)
\end{verbatim}
Get the datatype of a Variable
Get the data type of a Variable
\section*{\tt \htmlref{vlistInqVarLongname}{vlistInqVarLongname}}
......
......@@ -9,6 +9,26 @@
INTEGER FUNCTION vlistCreate()
\end{verbatim}
\subsubsection*{Example}
Here is an example using {\tt vlistCreate} to create a variable list
and add a variable with {\tt vlistDefVar}.
\begin{lstlisting}[language=Fortran, backgroundcolor=\color{zebg}, basicstyle=\footnotesize]
INCLUDE 'cdi.h'
...
INTEGER vlistID, varID
...
vlistID = vlistCreate()
varID = vlistDefVar(vlistID, gridID, zaxisID, TIME_VARIABLE)
...
streamDefVlist(streamID, vlistID)
...
vlistDestroy(vlistID)
...
\end{lstlisting}
\subsection{Destroy a variable list: {\tt vlistDestroy}}
\index{vlistDestroy}
......
......@@ -23,7 +23,7 @@ Grid ID, from a previous call to {\htmlref{\tt gridCreate}{gridCreate}}
Z-axis ID, from a previous call to {\htmlref{\tt zaxisCreate}{zaxisCreate}}
\item[{\tt timeID}]
One of the set of predefined CDI time identifiers.
The valid CDI time identifiers are TIME\_CONSTANT and TIME\_VARIABLE.
The valid CDI time identifiers are {\tt TIME\_CONSTANT} and {\tt TIME\_VARIABLE}.
\end{deflist}
\end{minipage}
......@@ -33,6 +33,26 @@ One of the set of predefined CDI time identifiers.
{\tt vlistDefVar} returns an identifier to the new variable.
\subsubsection*{Example}
Here is an example using {\tt vlistCreate} to create a variable list
and add a variable with {\tt vlistDefVar}.
\begin{lstlisting}[language=Fortran, backgroundcolor=\color{zebg}, basicstyle=\footnotesize]
INCLUDE 'cdi.h'
...
INTEGER vlistID, varID
...
vlistID = vlistCreate()
varID = vlistDefVar(vlistID, gridID, zaxisID, TIME_VARIABLE)
...
streamDefVlist(streamID, vlistID)
...
vlistDestroy(vlistID)
...
\end{lstlisting}
\subsection{Define the code number of a Variable: {\tt vlistDefVarCode}}
\index{vlistDefVarCode}
......@@ -273,17 +293,20 @@ Variable list ID, from a previous call to {\htmlref{\tt vlistCreate}{vlistCreate
\item[{\tt varID}]
Variable identifier
\item[{\tt datatype}]
Data type identifier
The data type identifier.
The valid CDI data types are {\tt DATATYPE\_PACK1}, {\tt DATATYPE\_PACK2},
{\tt DATATYPE\_PACK3}, {\tt DATATYPE\_REAL4} and {\tt DATATYPE\_REAL8}.
\end{deflist}
\end{minipage}
\subsection{Get the datatype of a Variable: {\tt vlistInqVarDatatype}}
\subsection{Get the data type of a Variable: {\tt vlistInqVarDatatype}}
\index{vlistInqVarDatatype}
\label{vlistInqVarDatatype}
The function {\tt vlistInqVarDatatype} returns the datatype of a variable.
The function {\tt vlistInqVarDatatype} returns the data type of a variable.
\subsubsection*{Usage}
......@@ -303,7 +326,9 @@ Variable identifier
\subsubsection*{Result}
{\tt vlistInqVarDatatype} returns an identifier to the datatype of the variable.
{\tt vlistInqVarDatatype} returns an identifier to the data type of the variable.
The valid CDI data types are {\tt DATATYPE\_PACK1}, {\tt DATATYPE\_PACK2}, {\tt DATATYPE\_PACK3},
{\tt DATATYPE\_REAL4} and {\tt DATATYPE\_REAL8}.
......
This section contains functions to define a horizontal Grid.
This module contains functions to define a new horizontal Grid
and to get information from an existing Grid.
A Grid object is necessary to define a variable.
The following different Grid types are available:
......
\section{\label{build}Building from sources}
This section describes how to build the \CDI library from the sources on a UNIX system.
\CDI is using the GNU configure and build system to compile the source code.
The only requirement is a working ANSI C compiler.
%First go to the \href{http://www.mpimet.mpg.de/~cdo/download.html}{\tt download} page
%({\tt http://www.mpimet.mpg.de/\~\,cdo/download.html}) to get the latest distribution,
First go to the \href{http://www.mpimet.mpg.de/sw/cdi}{\tt download} page
({\tt http://www.mpimet.mpg.de/sw/cdi}) to get the latest distribution,
if you did not have it already.
To take full advantage of \CDI's features the following additional
library should be installed.
\begin{itemize}
\item Unidata \href{http://www.unidata.ucar.edu/packages/netcdf/index.html}{netCDF} library
({\tt http://www.unidata.ucar.edu/packages/netcdf/index.html})
version 3 or higher.
This is needed to read/write netCDF files with \CDI.
\end{itemize}
%This section is divided into the following sections:
%<ul>
%<li>\ref install_src_unix "Compiling from source on Unix"
%<li>\ref install_bin_unix "Installing the binaries on Unix"
%<li>\ref build_tools "Tools used to develop CDO"
%</ul>
\subsection{Compilation}
Compilation is now done by performing the following steps:
\begin{enumerate}
\item Unpack the archive, unless you already have done that:
\begin{verbatim}
gunzip cdi-$VERSION.tar.gz # uncompress the archive
tar xf cdi-$VERSION.tar # unpack it
cd cdi-$VERSION
\end{verbatim}
\item Run the configure script:
\begin{verbatim}
./configure
\end{verbatim}
Or with netCDF support:
\begin{verbatim}
./configure --with-netcdf=<netCDF root directory>
\end{verbatim}
For an overview of other configuration options use
\begin{verbatim}
./configure --help
\end{verbatim}
\item Compile the program by running make:
\begin{verbatim}
make
\end{verbatim}
\end{enumerate}
The software should compile without problems and the library ({\tt libcdi.a})
should be available in the {\tt src} directory of the distribution.
\subsection{Installation}
After the compilation of the source code do a {\tt make install},
possibly as root if the destination permissions require that.
\begin{verbatim}
make install
\end{verbatim}
The library is installed into the directory {\tt $<$prefix$>$/lib}.
The C and Fortran include files are installed into the directory {\tt $<$prefix$>$/include}.
{\tt $<$prefix$>$} defaults to {\tt /usr/local} but can be changed with
the {\tt --prefix} option of the configure script.
%Alternatively, you can also copy the library from the {\tt src} directory
%manually to some {\tt lib} directory in your search path.
Complete examples for write, read and copy a dataset with CDI
can be found in \htmlref{Appendix B}{example}.
This section contains functions to define a Time axis.
This section contains functions to define a new Time axis
and to get information from an existing T-axis.
A T-axis object is necessary to define the time axis of a dataset.
The following different Time axis types are available:
......
This module contains functions to add new variables to a
variable list and to get information about variables from
a variable list. To add new variables to a variables list
one of the following time types must be specified:
\vspace*{3mm}
\hspace*{8mm}\begin{minipage}{15cm}
\begin{deflist}{{\large\tt TIME\_CONSTANT \ \ }}
\item[{\large\tt TIME\_CONSTANT }] For time constant variables
\item[{\large\tt TIME\_VARIABLE }] For time varying variables
\end{deflist}
\end{minipage}
\vspace*{3mm}
\vspace*{3mm}
\hspace*{8mm}\begin{minipage}{15cm}
\begin{deflist}{{\large\tt DATATYPE\_PACK1 \ \ }}
\item[{\large\tt DATATYPE\_PACK1}] 1 packed byte (only for GRIB)
\item[{\large\tt DATATYPE\_PACK2}] 2 packed byte (only for GRIB)
\item[{\large\tt DATATYPE\_PACK3}] 3 packed byte (only for GRIB)
\item[{\large\tt DATATYPE\_REAL4}] 4 byte floating point
\item[{\large\tt DATATYPE\_REAL8}] 8 byte floating point
\end{deflist}
\end{minipage}
This module contains functions to handle a list of variables.
A variable list is a collection of all variables of a dataset.
This section contains functions to define a vertical Z-axis.
This section contains functions to define a new vertical Z-axis
and to get information from an existing Z-axis.
A Z-axis object is necessary to define a variable.
The following different Z-axis types are available:
......
......@@ -257,11 +257,13 @@ int vlistInqVarTime(int vlistID, int varID);
/* vlistDefVarCode: Define the code number of a Variable */
void vlistDefVarCode(int vlistID, int varID, int code);
/* vlistInqVarCode: Get the code number of a Variable */
int vlistInqVarCode(int vlistID, int varID);
/* vlistDefVarDatatype: Define the data type of a Variable */
void vlistDefVarDatatype(int vlistID, int varID, int datatype);
/* vlistInqVarDatatype: Get the data type of a Variable */
int vlistInqVarDatatype(int vlistID, int varID);
void vlistDefVarInstitut(int vlistID, int varID, int instID);
......
......@@ -237,6 +237,23 @@ static void vlist_check_ptr(const char *func, VLIST *vlistptr)
@Prototype int vlistCreate(void)
@Example
Here is an example using @func{vlistCreate} to create a variable list
and add a variable with @func{vlistDefVar}.
@Source
#include "cdi.h"
...
int vlistID, varID;
...
vlistID = vlistCreate();
varID = vlistDefVar(vlistID, gridID, zaxisID, TIME_VARIABLE);
...
streamDefVlist(streamID, vlistID);
...
vlistDestroy(vlistID);
...
@EndSource
@EndFunction
*/
int vlistCreate(void)
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment