Commit 9a0af948 authored by Uwe Schulzweida's avatar Uwe Schulzweida
Browse files

Docu update.

parent afbdc216
......@@ -70,6 +70,17 @@ Function catalog:
vlistInqVarDatatype Get the data type of a Variable
vlistDefVarMissval Define the missing value of a Variable
vlistInqVarMissval Get the missing value of a Variable
-------------------------------------------------------------
cdi_key
-------------------------------------------------------------
cdiDefKeyString Define a string from a key
cdiInqKeyString Get a string from a key
cdiDefKeyInt Define an integer value from a key
cdiInqKeyInt Get an integer value from a key
cdiDefKeyFloat Define a floating point value from a key
cdiInqKeyFloat Get a floating point value from a key
cdiDefKeyBytes Define a byte array from a key
cdiInqKeyBytes Get a byte array from a key
-------------------------------------------------------------
cdi_att
-------------------------------------------------------------
......
......@@ -50,6 +50,14 @@ vlistDefVarDatatype vlist_var
vlistInqVarDatatype vlist_var
vlistDefVarMissval vlist_var
vlistInqVarMissval vlist_var
cdiDefKeyString cdi_key
cdiInqKeyString cdi_key
cdiDefKeyInt cdi_key
cdiInqKeyInt cdi_key
cdiDefKeyFloat cdi_key
cdiInqKeyFloat cdi_key
cdiDefKeyBytes cdi_key
cdiInqKeyBytes cdi_key
cdiInqNatts cdi_att
cdiInqAtt cdi_att
cdiDelAtt cdi_att
......
......@@ -2,11 +2,11 @@ Attributes may be associated with each variable to specify non
CDI standard properties. CDI standard properties as code, name,
units, and missing value are directly associated with each variable by
the corresponding CDI function (e.g. {\htmlref{\texttt{vlistDefVarName}}{vlistDefVarName}}).
An attribute has a variable to which it is assigned, a name, a type,
A user defined attribute has a variable to which it is assigned, a name, a type,
a length, and a sequence of one or more values.
The attributes have to be defined after the variable is created and
before the variable list is associated with a stream.
Attributes are only used for NetCDF datasets.
User defined attributes are only used for NetCDF datasets.
It is also possible to have attributes that are not associated with any variable.
These are called global attributes and are identified by using CDI\_GLOBAL as a
......
\subsection{Define a string from a key: \texttt{cdiDefKeyString}}
\index{cdiDefKeyString}
\label{cdiDefKeyString}
The function {\texttt{cdiDefKeyString}} defines a text string from a key.
\subsubsection*{Usage}
\begin{verbatim}
int cdiDefKeyString(int cdiID, int varID, int key, const char *string);
\end{verbatim}
\hspace*{4mm}\begin{minipage}[]{15cm}
\begin{deflist}{\texttt{string}\ }
\item[\texttt{cdiID}]
CDI object ID (vlistID, gridID, zaxisID).
\item[\texttt{varID}]
Variable identifier or CDI\_GLOBAL.
\item[\texttt{key}]
The key to be searched.
\item[\texttt{string}]
The address of a string where the data will be read.
\end{deflist}
\end{minipage}
\subsubsection*{Result}
{\texttt{cdiDefKeyString}} returns CDI\_NOERR if OK.
\subsubsection*{Example}
Here is an example using {\texttt{cdiDefKeyString}} to define the name of a variable:
\begin{lstlisting}[language=C, backgroundcolor=\color{pyellow}, basicstyle=\small, columns=flexible]
#include "cdi.h"
...
int vlistID, varID, status;
...
vlistID = vlistCreate();
varID = vlistDefVar(vlistID, gridID, zaxisID, TIME_VARYING);
...
status = cdiDefKeyString(vlistID, varID, CDI_KEY_NAME, "temperature");
...
\end{lstlisting}
\subsection{Get a string from a key: \texttt{cdiInqKeyString}}
\index{cdiInqKeyString}
\label{cdiInqKeyString}
The function {\texttt{cdiInqKeyString}} gets a text string from a key.
\subsubsection*{Usage}
\begin{verbatim}
int cdiInqKeyString(int cdiID, int varID, int key, char *string, int *length);
\end{verbatim}
\hspace*{4mm}\begin{minipage}[]{15cm}
\begin{deflist}{\texttt{string}\ }
\item[\texttt{cdiID}]
CDI object ID (vlistID, gridID, zaxisID).
\item[\texttt{varID}]
Variable identifier or CDI\_GLOBAL.
\item[\texttt{key}]
The key to be searched.
\item[\texttt{string}]
The address of a string where the data will be retrieved.
The caller must allocate space for the returned string.
\item[\texttt{length}]
The allocated length of the string on input.
\end{deflist}
\end{minipage}
\subsubsection*{Result}
{\texttt{cdiInqKeyString}} returns CDI\_NOERR if key is available.
\subsubsection*{Example}
Here is an example using {\texttt{cdiInqKeyString}} to get the name of the first variable:
\begin{lstlisting}[language=C, backgroundcolor=\color{pyellow}, basicstyle=\small, columns=flexible]
#include "cdi.h"
...
#define STRLEN 256
...
int streamID, vlistID, varID, status;
int length = STRLEN;
char name[STRLEN];
...
streamID = streamOpenRead(...);
vlistID = streamInqVlist(streamID);
...
varID = 0;
status = cdiInqKeyString(vlistID, varID, CDI_KEY_NAME, name, &length);
...
\end{lstlisting}
\subsection{Define an integer value from a key: \texttt{cdiDefKeyInt}}
\index{cdiDefKeyInt}
\label{cdiDefKeyInt}
The function {\texttt{cdiDefKeyInt}} defines an integer value from a key.
\subsubsection*{Usage}
\begin{verbatim}
int cdiDefKeyInt(int cdiID, int varID, int key, int value);
\end{verbatim}
\hspace*{4mm}\begin{minipage}[]{15cm}
\begin{deflist}{\texttt{cdiID}\ }
\item[\texttt{cdiID}]
CDI object ID (vlistID, gridID, zaxisID).
\item[\texttt{varID}]
Variable identifier or CDI\_GLOBAL.
\item[\texttt{key}]
The key to be searched.
\item[\texttt{value}]
An integer where the data will be read.
\end{deflist}
\end{minipage}
\subsubsection*{Result}
{\texttt{cdiDefKeyInt}} returns CDI\_NOERR if OK.
\subsection{Get an integer value from a key: \texttt{cdiInqKeyInt}}
\index{cdiInqKeyInt}
\label{cdiInqKeyInt}
The function {\texttt{cdiInqKeyInt}} gets an integer value from a key.
\subsubsection*{Usage}
\begin{verbatim}
int cdiInqKeyInt(int cdiID, int varID, int key, int *value);
\end{verbatim}
\hspace*{4mm}\begin{minipage}[]{15cm}
\begin{deflist}{\texttt{cdiID}\ }
\item[\texttt{cdiID}]
CDI object ID (vlistID, gridID, zaxisID).
\item[\texttt{varID}]
Variable identifier or CDI\_GLOBAL.
\item[\texttt{key}]
The key to be searched..
\item[\texttt{value}]
The address of an integer where the data will be retrieved.
\end{deflist}
\end{minipage}
\subsubsection*{Result}
{\texttt{cdiInqKeyInt}} returns CDI\_NOERR if key is available.
\subsection{Define a floating point value from a key: \texttt{cdiDefKeyFloat}}
\index{cdiDefKeyFloat}
\label{cdiDefKeyFloat}
The function {\texttt{cdiDefKeyFloat}} defines a {\CDI} floating point value from a key.
\subsubsection*{Usage}
\begin{verbatim}
int cdiDefKeyFloat(int cdiID, int varID, int key, double value);
\end{verbatim}
\hspace*{4mm}\begin{minipage}[]{15cm}
\begin{deflist}{\texttt{cdiID}\ }
\item[\texttt{cdiID}]
CDI object ID (vlistID, gridID, zaxisID).
\item[\texttt{varID}]
Variable identifier or CDI\_GLOBAL.
\item[\texttt{key}]
The key to be searched
\item[\texttt{value}]
A double where the data will be read
\end{deflist}
\end{minipage}
\subsubsection*{Result}
{\texttt{cdiDefKeyFloat}} returns CDI\_NOERR if OK.
\subsection{Get a floating point value from a key: \texttt{cdiInqKeyFloat}}
\index{cdiInqKeyFloat}
\label{cdiInqKeyFloat}
The function {\texttt{cdiInqKeyFloat}} gets a floating point value from a key.
\subsubsection*{Usage}
\begin{verbatim}
int cdiInqKeyFloat(int cdiID, int varID, int key, double *value);
\end{verbatim}
\hspace*{4mm}\begin{minipage}[]{15cm}
\begin{deflist}{\texttt{cdiID}\ }
\item[\texttt{cdiID}]
CDI object ID (vlistID, gridID, zaxisID).
\item[\texttt{varID}]
Variable identifier or CDI\_GLOBAL.
\item[\texttt{key}]
The key to be searched.
\item[\texttt{value}]
The address of a double where the data will be retrieved.
\end{deflist}
\end{minipage}
\subsubsection*{Result}
{\texttt{cdiInqKeyFloat}} returns CDI\_NOERR if key is available.
\subsection{Define a byte array from a key: \texttt{cdiDefKeyBytes}}
\index{cdiDefKeyBytes}
\label{cdiDefKeyBytes}
The function {\texttt{cdiDefKeyBytes}} defines a byte array from a key.
\subsubsection*{Usage}
\begin{verbatim}
int cdiDefKeyBytes(int cdiID, int varID, int key, const unsigned char *bytes,
int length);
\end{verbatim}
\hspace*{4mm}\begin{minipage}[]{15cm}
\begin{deflist}{\texttt{length}\ }
\item[\texttt{cdiID}]
CDI object ID (vlistID, gridID, zaxisID).
\item[\texttt{varID}]
Variable identifier or CDI\_GLOBAL.
\item[\texttt{key}]
The key to be searched.
\item[\texttt{bytes}]
The address of a byte array where the data will be read.
\item[\texttt{length}]
Length of the byte array
\end{deflist}
\end{minipage}
\subsubsection*{Result}
{\texttt{cdiDefKeyBytes}} returns CDI\_NOERR if OK.
\subsection{Get a byte array from a key: \texttt{cdiInqKeyBytes}}
\index{cdiInqKeyBytes}
\label{cdiInqKeyBytes}
The function {\texttt{cdiInqKeyBytes}} gets a byte array from a key.
\subsubsection*{Usage}
\begin{verbatim}
int cdiInqKeyBytes(int cdiID, int varID, int key, unsigned char *bytes, int *length);
\end{verbatim}
\hspace*{4mm}\begin{minipage}[]{15cm}
\begin{deflist}{\texttt{length}\ }
\item[\texttt{cdiID}]
CDI object ID (vlistID, gridID, zaxisID).
\item[\texttt{varID}]
Variable identifier or CDI\_GLOBAL.
\item[\texttt{key}]
The key to be searched.
\item[\texttt{bytes}]
The address of a byte array where the data will be retrieved.
The caller must allocate space for the returned byte array.
\item[\texttt{length}]
The allocated length of the byte array on input.
\end{deflist}
\end{minipage}
\subsubsection*{Result}
{\texttt{cdiInqKeyBytes}} returns CDI\_NOERR if key is available.
......@@ -47,6 +47,67 @@ Define a text attribute
\ifpdfoutput{}{(\ref{cdiDefAttTxt})}
\section*{\texttt{
\ifpdf
\hyperref[cdiDefKeyBytes]{cdiDefKeyBytes}
\else
cdiDefKeyBytes
\fi
}}
\begin{verbatim}
int cdiDefKeyBytes(int cdiID, int varID, int key, const unsigned char *bytes,
int length);
\end{verbatim}
Define a byte array from a key
\ifpdfoutput{}{(\ref{cdiDefKeyBytes})}
\section*{\texttt{
\ifpdf
\hyperref[cdiDefKeyFloat]{cdiDefKeyFloat}
\else
cdiDefKeyFloat
\fi
}}
\begin{verbatim}
int cdiDefKeyFloat(int cdiID, int varID, int key, double value);
\end{verbatim}
Define a floating point value from a key
\ifpdfoutput{}{(\ref{cdiDefKeyFloat})}
\section*{\texttt{
\ifpdf
\hyperref[cdiDefKeyInt]{cdiDefKeyInt}
\else
cdiDefKeyInt
\fi
}}
\begin{verbatim}
int cdiDefKeyInt(int cdiID, int varID, int key, int value);
\end{verbatim}
Define an integer value from a key
\ifpdfoutput{}{(\ref{cdiDefKeyInt})}
\section*{\texttt{
\ifpdf
\hyperref[cdiDefKeyString]{cdiDefKeyString}
\else
cdiDefKeyString
\fi
}}
\begin{verbatim}
int cdiDefKeyString(int cdiID, int varID, int key, const char *string);
\end{verbatim}
Define a string from a key
\ifpdfoutput{}{(\ref{cdiDefKeyString})}
\section*{\texttt{
\ifpdf
\hyperref[cdiInqAtt]{cdiInqAtt}
......@@ -107,6 +168,66 @@ Get the value(s) of a text attribute
\ifpdfoutput{}{(\ref{cdiInqAttTxt})}
\section*{\texttt{
\ifpdf
\hyperref[cdiInqKeyBytes]{cdiInqKeyBytes}
\else
cdiInqKeyBytes
\fi
}}
\begin{verbatim}
int cdiInqKeyBytes(int cdiID, int varID, int key, unsigned char *bytes, int *length);
\end{verbatim}
Get a byte array from a key
\ifpdfoutput{}{(\ref{cdiInqKeyBytes})}
\section*{\texttt{
\ifpdf
\hyperref[cdiInqKeyFloat]{cdiInqKeyFloat}
\else
cdiInqKeyFloat
\fi
}}
\begin{verbatim}
int cdiInqKeyFloat(int cdiID, int varID, int key, double *value);
\end{verbatim}
Get a floating point value from a key
\ifpdfoutput{}{(\ref{cdiInqKeyFloat})}
\section*{\texttt{
\ifpdf
\hyperref[cdiInqKeyInt]{cdiInqKeyInt}
\else
cdiInqKeyInt
\fi
}}
\begin{verbatim}
int cdiInqKeyInt(int cdiID, int varID, int key, int *value);
\end{verbatim}
Get an integer value from a key
\ifpdfoutput{}{(\ref{cdiInqKeyInt})}
\section*{\texttt{
\ifpdf
\hyperref[cdiInqKeyString]{cdiInqKeyString}
\else
cdiInqKeyString
\fi
}}
\begin{verbatim}
int cdiInqKeyString(int cdiID, int varID, int key, char *string, int *length);
\end{verbatim}
Get a string from a key
\ifpdfoutput{}{(\ref{cdiInqKeyString})}
\section*{\texttt{
\ifpdf
\hyperref[cdiInqNatts]{cdiInqNatts}
......
......@@ -191,7 +191,13 @@
\newpage
\section{Attributes}
\section{Key attributes}
\input{keys}
\input{c_cdi_key}
\newpage
\section{User attributes}
\input{attribute}
\input{c_cdi_att}
......
......@@ -188,7 +188,13 @@
\newpage
\section{Attributes}
\section{Key attributes}
\input{keys}
\input{f_cdi_key}
\newpage
\section{User attributes}
\input{attribute}
\input{f_cdi_att}
......
\subsection{Define a string from a key: \texttt{cdiDefKeyString}}
\index{cdiDefKeyString}
\label{cdiDefKeyString}
The function {\texttt{cdiDefKeyString}} defines a text string from a key.
\subsubsection*{Usage}
\begin{verbatim}
INTEGER FUNCTION cdiDefKeyString(INTEGER cdiID, INTEGER varID, INTEGER key,
CHARACTER*(*) string)
\end{verbatim}
\hspace*{4mm}\begin{minipage}[]{15cm}
\begin{deflist}{\texttt{string}\ }
\item[\texttt{cdiID}]
CDI object ID (vlistID, gridID, zaxisID).
\item[\texttt{varID}]
Variable identifier or CDI\_GLOBAL.
\item[\texttt{key}]
The key to be searched.
\item[\texttt{string}]
The address of a string where the data will be read.
\end{deflist}
\end{minipage}
\subsubsection*{Result}
{\texttt{cdiDefKeyString}} returns CDI\_NOERR if OK.
\subsubsection*{Example}
Here is an example using {\texttt{cdiDefKeyString}} to define the name of a variable:
\begin{lstlisting}[language=Fortran, backgroundcolor=\color{pyellow}, basicstyle=\small, columns=flexible]
INCLUDE 'cdi.h'
...
INTEGER vlistID, varID, status
...
vlistID = vlistCreate()
varID = vlistDefVar(vlistID, gridID, zaxisID, TIME_VARYING)
...
status = cdiDefKeyString(vlistID, varID, CDI_KEY_NAME, "temperature")
...
\end{lstlisting}
\subsection{Get a string from a key: \texttt{cdiInqKeyString}}
\index{cdiInqKeyString}
\label{cdiInqKeyString}
The function {\texttt{cdiInqKeyString}} gets a text string from a key.
\subsubsection*{Usage}
\begin{verbatim}
INTEGER FUNCTION cdiInqKeyString(INTEGER cdiID, INTEGER varID, INTEGER key,
CHARACTER*(*) string, INTEGER length)
\end{verbatim}
\hspace*{4mm}\begin{minipage}[]{15cm}
\begin{deflist}{\texttt{string}\ }
\item[\texttt{cdiID}]
CDI object ID (vlistID, gridID, zaxisID).
\item[\texttt{varID}]
Variable identifier or CDI\_GLOBAL.
\item[\texttt{key}]
The key to be searched.
\item[\texttt{string}]
The address of a string where the data will be retrieved.
The caller must allocate space for the returned string.
\item[\texttt{length}]
The allocated length of the string on input.
\end{deflist}
\end{minipage}
\subsubsection*{Result}
{\texttt{cdiInqKeyString}} returns CDI\_NOERR if key is available.
\subsubsection*{Example}
Here is an example using {\texttt{cdiInqKeyString}} to get the name of the first variable:
\begin{lstlisting}[language=Fortran, backgroundcolor=\color{pyellow}, basicstyle=\small, columns=flexible]
INCLUDE 'cdi.h'
...
#define STRLEN 256
...
INTEGER streamID, vlistID, varID, status
INTEGER length = STRLEN
CHARACTER name[STRLEN]
...
streamID = streamOpenRead(...)
vlistID = streamInqVlist(streamID)
...
varID = 0
status = cdiInqKeyString(vlistID, varID, CDI_KEY_NAME, name, length)
...
\end{lstlisting}
\subsection{Define an integer value from a key: \texttt{cdiDefKeyInt}}
\index{cdiDefKeyInt}
\label{cdiDefKeyInt}
The function {\texttt{cdiDefKeyInt}} defines an integer value from a key.
\subsubsection*{Usage}
\begin{verbatim}
INTEGER FUNCTION cdiDefKeyInt(INTEGER cdiID, INTEGER varID, INTEGER key,
INTEGER value)
\end{verbatim}
\hspace*{4mm}\begin{minipage}[]{15cm}
\begin{deflist}{\texttt{cdiID}\ }
\item[\texttt{cdiID}]
CDI object ID (vlistID, gridID, zaxisID).
\item[\texttt{varID}]
Variable identifier or CDI\_GLOBAL.
\item[\texttt{key}]
The key to be searched.