Skip to content

GitLab

Commit 94cbd6d9 authored by Uwe Schulzweida's avatar Uwe Schulzweida
Browse files

Docu update

parent 6b717d9e
Hide whitespace changes
Inline Side-by-side
doc/tex/c_examples.tex
View file @ 94cbd6d9
\appendix
\chapter{\label{example}Examples}
\chapter{\label{appendixa}Examples}
This appendix contains complete examples to write, read
and copy a dataset with the CDI library.
\section{Write a dataset}
\section{\label{example_write}Write a dataset}
Here is an example using CDI to write a netCDF dataset with
2 variables on 3 time steps. The first variable is a 2D field
on surface level and the second variable is a 3D field on 5 pressure
levels. Both variables are on the same lon/lat grid.
\lstinputlisting[language=C, frame=single, backgroundcolor=\color{zebg}, basicstyle=\footnotesize]
{../../examples/cdi_write.c}
\subsection{Result}
This is the {\tt ncdump -h} output of the resulting netCDF file {\tt example.nc}.
\begin{lstlisting}[frame=single, backgroundcolor=\color{zebg}, basicstyle=\footnotesize]
netcdf example {
dimensions:
......@@ -48,11 +57,17 @@ data:
\section{Read a dataset}
This example reads the netCDF file {\tt example.nc} from \htmlref{Appendix B.1}{example_write}.
\lstinputlisting[language=C, frame=single, backgroundcolor=\color{zebg}, basicstyle=\footnotesize]
{../../examples/cdi_read.c}
\section{Copy a dataset}
This example reads the netCDF file {\tt example.nc} from \htmlref{Appendix B.1}{example_write}
and writes the result to a GRIB dataset by simple setting the output file type
to {\tt FILETYPE\_GRB}.
\lstinputlisting[language=C, frame=single, backgroundcolor=\color{zebg}, basicstyle=\footnotesize]
{../../examples/cdi_copy.c}
doc/tex/c_grid.tex
View file @ 94cbd6d9
\section{Create a horizontal Grid: {\tt gridCreate}}
\subsection{Create a horizontal Grid: {\tt gridCreate}}
\index{gridCreate}
\label{gridCreate}
The function {\tt gridCreate} creates a horizontal Grid.
\subsection*{Usage}
\subsubsection*{Usage}
\begin{verbatim}
int gridCreate(int gridtype, int size);
......@@ -25,12 +25,12 @@ Number of gridpoints.
\end{deflist}
\end{minipage}
\subsection*{Result}
\subsubsection*{Result}
{\tt gridCreate} returns an identifier to the Grid.
\subsection*{Example}
\subsubsection*{Example}
Here is an example using {\tt gridCreate} to create a regular lon/lat Grid:
......@@ -54,10 +54,10 @@ Here is an example using {\tt gridCreate} to create a regular lon/lat Grid:
\end{lstlisting}
\section{Destroy a horizontal Grid: {\tt gridDestroy}}
\subsection{Destroy a horizontal Grid: {\tt gridDestroy}}
\index{gridDestroy}
\label{gridDestroy}
\subsection*{Usage}
\subsubsection*{Usage}
\begin{verbatim}
void gridDestroy(int gridID);
......@@ -72,13 +72,13 @@ Grid ID, from a previous call to {\htmlref{\tt gridCreate}{gridCreate}}
\end{minipage}
\section{Duplicate a horizontal Grid: {\tt gridDuplicate}}
\subsection{Duplicate a horizontal Grid: {\tt gridDuplicate}}
\index{gridDuplicate}
\label{gridDuplicate}
The function {\tt gridDuplicate} duplicates a horizontal Grid.
\subsection*{Usage}
\subsubsection*{Usage}
\begin{verbatim}
int gridDuplicate(int gridID);
......@@ -93,19 +93,19 @@ Grid ID, from a previous call to {\htmlref{\tt gridCreate}{gridCreate}},
\end{deflist}
\end{minipage}
\subsection*{Result}
\subsubsection*{Result}
{\tt gridDuplicate} returns an identifier to the duplicated Grid.
\section{Get the type of a Grid: {\tt gridInqType}}
\subsection{Get the type of a Grid: {\tt gridInqType}}
\index{gridInqType}
\label{gridInqType}
The function {\tt gridInqType} returns the type of a Grid.
\subsection*{Usage}
\subsubsection*{Usage}
\begin{verbatim}
int gridInqType(int gridID);
......@@ -119,7 +119,7 @@ Grid ID, from a previous call to {\htmlref{\tt gridCreate}{gridCreate}}
\end{deflist}
\end{minipage}
\subsection*{Result}
\subsubsection*{Result}
{\tt gridInqType} returns the type of the grid,
one of the set of predefined CDI grid types.
......@@ -129,13 +129,13 @@ and {\tt GRID\_CELL}.
\section{Get the size of a Grid: {\tt gridInqSize}}
\subsection{Get the size of a Grid: {\tt gridInqSize}}
\index{gridInqSize}
\label{gridInqSize}
The function {\tt gridInqSize} returns the size of a Grid.
\subsection*{Usage}
\subsubsection*{Usage}
\begin{verbatim}
int gridInqSize(int gridID);
......@@ -149,19 +149,19 @@ Grid ID, from a previous call to {\htmlref{\tt gridCreate}{gridCreate}}
\end{deflist}
\end{minipage}
\subsection*{Result}
\subsubsection*{Result}
{\tt gridInqSize} returns the number of grid points of a Grid.
\section{Define the number of values of a X-axis: {\tt gridDefXsize}}
\subsection{Define the number of values of a X-axis: {\tt gridDefXsize}}
\index{gridDefXsize}
\label{gridDefXsize}
The function {\tt gridDefXsize} defines the number of values of a X-axis.
\subsection*{Usage}
\subsubsection*{Usage}
\begin{verbatim}
void gridDefXsize(int gridID, int xsize);
......@@ -178,13 +178,13 @@ Number of values of a X-axis
\end{minipage}
\section{Get the number of values of a X-axis: {\tt gridInqXsize}}
\subsection{Get the number of values of a X-axis: {\tt gridInqXsize}}
\index{gridInqXsize}
\label{gridInqXsize}
The function {\tt gridInqXsize} returns the number of values of a X-axis.
\subsection*{Usage}
\subsubsection*{Usage}
\begin{verbatim}
void gridInqXsize(int gridID);
......@@ -198,19 +198,19 @@ Grid ID, from a previous call to {\htmlref{\tt gridCreate}{gridCreate}}
\end{deflist}
\end{minipage}
\subsection*{Result}
\subsubsection*{Result}
{\tt gridInqXsize} returns the number of values of a X-axis.
\section{Define the number of values of a Y-axis: {\tt gridDefYsize}}
\subsection{Define the number of values of a Y-axis: {\tt gridDefYsize}}
\index{gridDefYsize}
\label{gridDefYsize}
The function {\tt gridDefYsize} defines the number of values of a Y-axis.
\subsection*{Usage}
\subsubsection*{Usage}
\begin{verbatim}
void gridDefYsize(int gridID, int ysize);
......@@ -227,13 +227,13 @@ Number of values of a Y-axis
\end{minipage}
\section{Get the number of values of a Y-axis: {\tt gridInqYsize}}
\subsection{Get the number of values of a Y-axis: {\tt gridInqYsize}}
\index{gridInqYsize}
\label{gridInqYsize}
The function {\tt gridInqYsize} returns the number of values of a Y-axis.
\subsection*{Usage}
\subsubsection*{Usage}
\begin{verbatim}
void gridInqYsize(int gridID);
......@@ -247,19 +247,19 @@ Grid ID, from a previous call to {\htmlref{\tt gridCreate}{gridCreate}}
\end{deflist}
\end{minipage}
\subsection*{Result}
\subsubsection*{Result}
{\tt gridInqYsize} returns the number of values of a Y-axis.
\section{Define the values of a X-axis: {\tt gridDefXvals}}
\subsection{Define the values of a X-axis: {\tt gridDefXvals}}
\index{gridDefXvals}
\label{gridDefXvals}
The function {\tt gridDefXvals} defines all values of the X-axis.
\subsection*{Usage}
\subsubsection*{Usage}
\begin{verbatim}
void gridDefXvals(int gridID, double *xvals);
......@@ -276,13 +276,13 @@ X-values of the grid
\end{minipage}
\section{Get all values of a X-axis: {\tt gridInqXvals}}
\subsection{Get all values of a X-axis: {\tt gridInqXvals}}
\index{gridInqXvals}
\label{gridInqXvals}
The function {\tt gridInqXvals} returns all values of the X-axis.
\subsection*{Usage}
\subsubsection*{Usage}
\begin{verbatim}
int gridInqXvals(int gridID, double *xvals);
......@@ -298,7 +298,7 @@ X-values of the grid
\end{deflist}
\end{minipage}
\subsection*{Result}
\subsubsection*{Result}
Upon successful completion {\tt gridInqXvals} returns the number of values and
the values are stored in {\tt xvals}.
......@@ -306,13 +306,13 @@ Otherwise, 0 is returned and {\tt xvals} is empty.
\section{Define the values of a Y-axis: {\tt gridDefYvals}}
\subsection{Define the values of a Y-axis: {\tt gridDefYvals}}
\index{gridDefYvals}
\label{gridDefYvals}
The function {\tt gridDefYvals} defines all values of the Y-axis.
\subsection*{Usage}
\subsubsection*{Usage}
\begin{verbatim}
void gridDefYvals(int gridID, double *yvals);
......@@ -329,13 +329,13 @@ Y-values of the grid
\end{minipage}
\section{Get all values of a Y-axis: {\tt gridInqYvals}}
\subsection{Get all values of a Y-axis: {\tt gridInqYvals}}
\index{gridInqYvals}
\label{gridInqYvals}
The function {\tt gridInqYvals} returns all values of the Y-axis.
\subsection*{Usage}
\subsubsection*{Usage}
\begin{verbatim}
int gridInqYvals(int gridID, double *yvals);
......@@ -351,7 +351,7 @@ Y-values of the grid
\end{deflist}
\end{minipage}
\subsection*{Result}
\subsubsection*{Result}
Upon successful completion {\tt gridInqYvals} returns the number of values and
the values are stored in {\tt yvals}.
......@@ -359,13 +359,13 @@ Otherwise, 0 is returned and {\tt yvals} is empty.
\section{Define the bounds of a X-axis: {\tt gridDefXbounds}}
\subsection{Define the bounds of a X-axis: {\tt gridDefXbounds}}
\index{gridDefXbounds}
\label{gridDefXbounds}
The function {\tt gridDefXbounds} defines all bounds of the X-axis.
\subsection*{Usage}
\subsubsection*{Usage}
\begin{verbatim}
void gridDefXbounds(int gridID, double *xbounds);
......@@ -382,13 +382,13 @@ X-bounds of the grid
\end{minipage}
\section{Get the bounds of a X-axis: {\tt gridInqXbounds}}
\subsection{Get the bounds of a X-axis: {\tt gridInqXbounds}}
\index{gridInqXbounds}
\label{gridInqXbounds}
The function {\tt gridInqXbounds} returns the bounds of the X-axis.
\subsection*{Usage}
\subsubsection*{Usage}
\begin{verbatim}
int gridInqXbounds(int gridID, double *xbounds);
......@@ -404,7 +404,7 @@ X-bounds of the grid
\end{deflist}
\end{minipage}
\subsection*{Result}
\subsubsection*{Result}
Upon successful completion {\tt gridInqXbounds} returns the number of bounds and
the bounds are stored in {\tt xbounds}.
......@@ -412,13 +412,13 @@ Otherwise, 0 is returned and {\tt xbounds} is empty.
\section{Define the bounds of a Y-axis: {\tt gridDefYbounds}}
\subsection{Define the bounds of a Y-axis: {\tt gridDefYbounds}}
\index{gridDefYbounds}
\label{gridDefYbounds}
The function {\tt gridDefYbounds} defines all bounds of the Y-axis.
\subsection*{Usage}
\subsubsection*{Usage}
\begin{verbatim}
void gridDefYbounds(int gridID, double *ybounds);
......@@ -435,13 +435,13 @@ Y-bounds of the grid
\end{minipage}
\section{Get the bounds of a Y-axis: {\tt gridInqYbounds}}
\subsection{Get the bounds of a Y-axis: {\tt gridInqYbounds}}
\index{gridInqYbounds}
\label{gridInqYbounds}
The function {\tt gridInqYbounds} returns the bounds of the Y-axis.
\subsection*{Usage}
\subsubsection*{Usage}
\begin{verbatim}
int gridInqYbounds(int gridID, double *ybounds);
......@@ -457,7 +457,7 @@ Y-bounds of the grid
\end{deflist}
\end{minipage}
\subsection*{Result}
\subsubsection*{Result}
Upon successful completion {\tt gridInqYbounds} returns the number of bounds and
the bounds are stored in {\tt ybounds}.
......@@ -465,13 +465,13 @@ Otherwise, 0 is returned and {\tt ybounds} is empty.
\section{Define the name of a X-axis: {\tt gridDefXname}}
\subsection{Define the name of a X-axis: {\tt gridDefXname}}
\index{gridDefXname}
\label{gridDefXname}
The function {\tt gridDefXname} defines the name of a X-axis.
\subsection*{Usage}
\subsubsection*{Usage}
\begin{verbatim}
void gridDefXname(int gridID, const char *name);
......@@ -488,13 +488,13 @@ Name of the X-axis
\end{minipage}
\section{Get the name of a X-axis: {\tt gridInqXname}}
\subsection{Get the name of a X-axis: {\tt gridInqXname}}
\index{gridInqXname}
\label{gridInqXname}
The function {\tt gridInqXname} returns the name of a X-axis.
\subsection*{Usage}
\subsubsection*{Usage}
\begin{verbatim}
void gridInqXname(int gridID, const char *name);
......@@ -510,19 +510,19 @@ Name of the X-axis
\end{deflist}
\end{minipage}
\subsection*{Result}
\subsubsection*{Result}
{\tt gridInqXname} returns the name of the X-axis to the parameter name.
\section{Define the longname of a X-axis: {\tt gridDefXlongname}}
\subsection{Define the longname of a X-axis: {\tt gridDefXlongname}}
\index{gridDefXlongname}
\label{gridDefXlongname}
The function {\tt gridDefXlongname} defines the longname of a X-axis.
\subsection*{Usage}
\subsubsection*{Usage}
\begin{verbatim}
void gridDefXlongname(int gridID, const char *longname);
......@@ -539,13 +539,13 @@ Longname of the X-axis
\end{minipage}
\section{Get the longname of a X-axis: {\tt gridInqXlongname}}
\subsection{Get the longname of a X-axis: {\tt gridInqXlongname}}
\index{gridInqXlongname}
\label{gridInqXlongname}
The function {\tt gridInqXlongname} returns the longname of a X-axis.
\subsection*{Usage}
\subsubsection*{Usage}
\begin{verbatim}
void gridInqXlongname(int gridID, const char *longname);
......@@ -561,19 +561,19 @@ Longname of the X-axis
\end{deflist}
\end{minipage}
\subsection*{Result}
\subsubsection*{Result}
{\tt gridInqXlongname} returns the longname of the X-axis to the parameter longname.
\section{Define the units of a X-axis: {\tt gridDefXunits}}
\subsection{Define the units of a X-axis: {\tt gridDefXunits}}
\index{gridDefXunits}
\label{gridDefXunits}
The function {\tt gridDefXunits} defines the units of a X-axis.
\subsection*{Usage}
\subsubsection*{Usage}
\begin{verbatim}
void gridDefXunits(int gridID, const char *units);
......@@ -590,13 +590,13 @@ Units of the X-axis
\end{minipage}
\section{Get the units of a X-axis: {\tt gridInqXunits}}
\subsection{Get the units of a X-axis: {\tt gridInqXunits}}
\index{gridInqXunits}
\label{gridInqXunits}
The function {\tt gridInqXunits} returns the units of a X-axis.
\subsection*{Usage}
\subsubsection*{Usage}
\begin{verbatim}
void gridInqXunits(int gridID, const char *units);
......@@ -612,19 +612,19 @@ Units of the X-axis
\end{deflist}
\end{minipage}
\subsection*{Result}
\subsubsection*{Result}
{\tt gridInqXunits} returns the units of the X-axis to the parameter units.
\section{Define the name of a Y-axis: {\tt gridDefYname}}
\subsection{Define the name of a Y-axis: {\tt gridDefYname}}
\index{gridDefYname}
\label{gridDefYname}
The function {\tt gridDefYname} defines the name of a Y-axis.
\subsection*{Usage}
\subsubsection*{Usage}
\begin{verbatim}
void gridDefYname(int gridID, const char *name);
......@@ -641,13 +641,13 @@ Name of the Y-axis
\end{minipage}
\section{Get the name of a Y-axis: {\tt gridInqYname}}
\subsection{Get the name of a Y-axis: {\tt gridInqYname}}
\index{gridInqYname}
\label{gridInqYname}
The function {\tt gridInqYname} returns the name of a Y-axis.
\subsection*{Usage}
\subsubsection*{Usage}
\begin{verbatim}
void gridInqYname(int gridID, const char *name);
......@@ -663,19 +663,19 @@ Name of the Y-axis
\end{deflist}
\end{minipage}
\subsection*{Result}
\subsubsection*{Result}
{\tt gridInqYname} returns the name of the Y-axis to the parameter name.
\section{Define the longname of a Y-axis: {\tt gridDefYlongname}}
\subsection{Define the longname of a Y-axis: {\tt gridDefYlongname}}
\index{gridDefYlongname}
\label{gridDefYlongname}
The function {\tt gridDefYlongname} defines the longname of a Y-axis.
\subsection*{Usage}
\subsubsection*{Usage}
\begin{verbatim}
void gridDefYlongname(int gridID, const char *longname);
......@@ -692,13 +692,13 @@ Longname of the Y-axis
\end{minipage}
\section{Get the longname of a Y-axis: {\tt gridInqYlongname}}
\subsection{Get the longname of a Y-axis: {\tt gridInqYlongname}}
\index{gridInqYlongname}
\label{gridInqYlongname}
The function {\tt gridInqYlongname} returns the longname of a Y-axis.
\subsection*{Usage}
\subsubsection*{Usage}
\begin{verbatim}
void gridInqXlongname(int gridID, const char *longname);
......@@ -714,19 +714,19 @@ Longname of the Y-axis
\end{deflist}
\end{minipage}
\subsection*{Result}
\subsubsection*{Result}
{\tt gridInqYlongname} returns the longname of the Y-axis to the parameter longname.
\section{Define the units of a Y-axis: {\tt gridDefYunits}}
\subsection{Define the units of a Y-axis: {\tt gridDefYunits}}
\index{gridDefYunits}
\label{gridDefYunits}
The function {\tt gridDefYunits} defines the units of a Y-axis.
\subsection*{Usage}
\subsubsection*{Usage}
\begin{verbatim}
void gridDefYunits(int gridID, const char *units);
......@@ -743,13 +743,13 @@ Units of the Y-axis
\end{minipage}
\section{Get the units of a Y-axis: {\tt gridInqYunits}}
\subsection{Get the units of a Y-axis: {\tt gridInqYunits}}
\index{gridInqYunits}
\label{gridInqYunits}
The function {\tt gridInqYunits} returns the units of a Y-axis.
\subsection*{Usage}
\subsubsection*{Usage}
\begin{verbatim}
void gridInqYunits(int gridID, const char *units);
......@@ -765,7 +765,7 @@ Units of the Y-axis
\end{deflist}
\end{minipage}
\subsection*{Result}
\subsubsection*{Result}
{\tt gridInqYunits} returns the units of the Y-axis to the parameter units.
doc/tex/c_stream.tex
View file @ 94cbd6d9
\section{Create a new dataset: {\tt streamOpenWrite}}
\subsection{Create a new dataset: {\tt streamOpenWrite}}
\index{streamOpenWrite}
\label{streamOpenWrite}
The function {\tt streamOpenWrite} creates a new datset.
\subsection*{Usage}
\subsubsection*{Usage}
\begin{verbatim}
int streamOpenWrite(const char *path, int filetype);
......@@ -23,13 +23,13 @@ The type of the file format, one of the set of predefined CDI file format types.
\end{deflist}
\end{minipage}
\subsection*{Result}
\subsubsection*{Result}
Upon successful completion {\tt streamOpenWrite} returns an identifier to the
open stream. Otherwise, a negative number with the error status is returned.
\subsection*{Errors}
\subsubsection*{Errors}
\hspace*{4mm}\begin{minipage}[]{15cm}
......@@ -46,7 +46,7 @@ Library not available
\end{minipage}
\subsection*{Example}
\subsubsection*{Example}
Here is an example using {\tt streamOpenWrite} to create a new netCDF file
named {\tt foo.nc} for writing:
......@@ -63,13 +63,13 @@ named {\tt foo.nc} for writing:
\end{lstlisting}
\section{Open a dataset for reading: {\tt streamOpenRead}}