c_stream.tex

\subsection{Create a new dataset: \texttt{streamOpenWrite}}
\index{streamOpenWrite}
\label{streamOpenWrite}

The function {\texttt{streamOpenWrite}} creates a new datset.
\subsubsection*{Usage}

\begin{verbatim}
    int streamOpenWrite(const char *path, int filetype);
\end{verbatim}

\hspace*{4mm}\begin{minipage}[]{15cm}
\begin{deflist}{\texttt{filetype}\ }
\item[\texttt{path}]
The name of the new dataset.
\item[\texttt{filetype}]
The type of the file format, one of the set of predefined {\CDI} file format types.
                     The valid {\CDI} file format types are {\texttt{CDI\_FILETYPE\_GRB}}, {\texttt{CDI\_FILETYPE\_GRB2}}, {\texttt{CDI\_FILETYPE\_NC}},
                     {\texttt{CDI\_FILETYPE\_NC2}}, {\texttt{CDI\_FILETYPE\_NC4}}, {\texttt{CDI\_FILETYPE\_NC4C}}, {\texttt{CDI\_FILETYPE\_NC5}},
                     {\texttt{CDI\_FILETYPE\_NCZARR}}, {\texttt{CDI\_FILETYPE\_SRV}}, {\texttt{CDI\_FILETYPE\_EXT}} and {\texttt{CDI\_FILETYPE\_IEG}}.

\end{deflist}
\end{minipage}

\subsubsection*{Result}

Upon successful completion {\texttt{streamOpenWrite}} returns an identifier to the
open stream. Otherwise, a negative number with the error status is returned.


\subsubsection*{Errors}


\hspace*{4mm}\begin{minipage}[]{15cm}
\begin{deflist}{\texttt{CDI\_EUFILETYPE}\ }
\item[\texttt{CDI\_ESYSTEM}]
Operating system error.
\item[\texttt{CDI\_EINVAL}]
Invalid argument.
\item[\texttt{CDI\_EUFILETYPE}]
Unsupported file type.
\item[\texttt{CDI\_ELIBNAVAIL}]
Library support not compiled in.
\end{deflist}
\end{minipage}


\subsubsection*{Example}

Here is an example using {\texttt{streamOpenWrite}} to create a new NetCDF file named {\texttt{foo.nc}} for writing:

\begin{lstlisting}[language=C, backgroundcolor=\color{pyellow}, basicstyle=\small, columns=flexible]

    #include "cdi.h"
       ...
    int streamID;
       ...
    streamID = streamOpenWrite("foo.nc", CDI_FILETYPE_NC);
    if ( streamID < 0 ) handle_error(streamID);
       ...
\end{lstlisting}


\subsection{Open a dataset for reading: \texttt{streamOpenRead}}
\index{streamOpenRead}
\label{streamOpenRead}

The function {\texttt{streamOpenRead}} opens an existing dataset for reading.

\subsubsection*{Usage}

\begin{verbatim}
    int streamOpenRead(const char *path);
\end{verbatim}

\hspace*{4mm}\begin{minipage}[]{15cm}
\begin{deflist}{\texttt{path}\ }
\item[\texttt{path}]
The name of the dataset to be read.

\end{deflist}
\end{minipage}

\subsubsection*{Result}

Upon successful completion {\texttt{streamOpenRead}} returns an identifier to the
open stream. Otherwise, a negative number with the error status is returned.


\subsubsection*{Errors}


\hspace*{4mm}\begin{minipage}[]{15cm}
\begin{deflist}{\texttt{CDI\_EUFILETYPE}\ }
\item[\texttt{CDI\_ESYSTEM}]
Operating system error.
\item[\texttt{CDI\_EINVAL}]
Invalid argument.
\item[\texttt{CDI\_EUFILETYPE}]
Unsupported file type.
\item[\texttt{CDI\_ELIBNAVAIL}]
Library support not compiled in.
\end{deflist}
\end{minipage}


\subsubsection*{Example}

Here is an example using {\texttt{streamOpenRead}} to open an existing NetCDF
file named {\texttt{foo.nc}} for reading:

\begin{lstlisting}[language=C, backgroundcolor=\color{pyellow}, basicstyle=\small, columns=flexible]

    #include "cdi.h"
       ...
    int streamID;
       ...
    streamID = streamOpenRead("foo.nc");
    if ( streamID < 0 ) handle_error(streamID);
       ...
\end{lstlisting}


\subsection{Close an open dataset: \texttt{streamClose}}
\index{streamClose}
\label{streamClose}

The function {\texttt{streamClose}} closes an open dataset.

\subsubsection*{Usage}

\begin{verbatim}
    void streamClose(int streamID);
\end{verbatim}

\hspace*{4mm}\begin{minipage}[]{15cm}
\begin{deflist}{\texttt{streamID}\ }
\item[\texttt{streamID}]
Stream ID, from a previous call to {\htmlref{\texttt{streamOpenRead}}{streamOpenRead}} or {\htmlref{\texttt{streamOpenWrite}}{streamOpenWrite}}.

\end{deflist}
\end{minipage}


\subsection{Get the filetype: \texttt{streamInqFiletype}}
\index{streamInqFiletype}
\label{streamInqFiletype}

The function {\texttt{streamInqFiletype}} returns the filetype of a stream.

\subsubsection*{Usage}

\begin{verbatim}
    int streamInqFiletype(int streamID);
\end{verbatim}

\hspace*{4mm}\begin{minipage}[]{15cm}
\begin{deflist}{\texttt{streamID}\ }
\item[\texttt{streamID}]
Stream ID, from a previous call to {\htmlref{\texttt{streamOpenRead}}{streamOpenRead}} or {\htmlref{\texttt{streamOpenWrite}}{streamOpenWrite}}.

\end{deflist}
\end{minipage}

\subsubsection*{Result}

{\texttt{streamInqFiletype}} returns the type of the file format,
one of the set of predefined {\CDI} file format types.
The valid {\CDI} file format types are {\texttt{CDI\_FILETYPE\_GRB}}, {\texttt{CDI\_FILETYPE\_GRB2}}, {\texttt{CDI\_FILETYPE\_NC}},
{\texttt{CDI\_FILETYPE\_NC2}}, {\texttt{CDI\_FILETYPE\_NC4}}, {\texttt{CDI\_FILETYPE\_NC4C}}, {\texttt{CDI\_FILETYPE\_NC5}},
{\texttt{CDI\_FILETYPE\_NCZARR}}, {\texttt{CDI\_FILETYPE\_SRV}}, {\texttt{CDI\_FILETYPE\_EXT}} and {\texttt{CDI\_FILETYPE\_IEG}}.


\subsection{Define the byte order: \texttt{streamDefByteorder}}
\index{streamDefByteorder}
\label{streamDefByteorder}

The function {\texttt{streamDefByteorder}} defines the byte order of a binary dataset
with the file format type {\texttt{CDI\_FILETYPE\_SRV}}, {\texttt{CDI\_FILETYPE\_EXT}} or {\texttt{CDI\_FILETYPE\_IEG}}.

\subsubsection*{Usage}

\begin{verbatim}
    void streamDefByteorder(int streamID, int byteorder);
\end{verbatim}

\hspace*{4mm}\begin{minipage}[]{15cm}
\begin{deflist}{\texttt{byteorder}\ }
\item[\texttt{streamID}]
Stream ID, from a previous call to {\htmlref{\texttt{streamOpenWrite}}{streamOpenWrite}}.
\item[\texttt{byteorder}]
The byte order of a dataset, one of the {\CDI} constants {\texttt{CDI\_BIGENDIAN}} and
                     {\texttt{CDI\_LITTLEENDIAN}}.

\end{deflist}
\end{minipage}


\subsection{Get the byte order: \texttt{streamInqByteorder}}
\index{streamInqByteorder}
\label{streamInqByteorder}

The function {\texttt{streamInqByteorder}} returns the byte order of a binary dataset
with the file format type {\texttt{CDI\_FILETYPE\_SRV}}, {\texttt{CDI\_FILETYPE\_EXT}} or {\texttt{CDI\_FILETYPE\_IEG}}.

\subsubsection*{Usage}

\begin{verbatim}
    int streamInqByteorder(int streamID);
\end{verbatim}

\hspace*{4mm}\begin{minipage}[]{15cm}
\begin{deflist}{\texttt{streamID}\ }
\item[\texttt{streamID}]
Stream ID, from a previous call to {\htmlref{\texttt{streamOpenRead}}{streamOpenRead}} or {\htmlref{\texttt{streamOpenWrite}}{streamOpenWrite}}.

\end{deflist}
\end{minipage}

\subsubsection*{Result}

{\texttt{streamInqByteorder}} returns the type of the byte order.
The valid {\CDI} byte order types are {\texttt{CDI\_BIGENDIAN}} and {\texttt{CDI\_LITTLEENDIAN}}



\subsection{Define the variable list: \texttt{streamDefVlist}}
\index{streamDefVlist}
\label{streamDefVlist}

The function {\texttt{streamDefVlist}} defines the variable list of a stream.

To safeguard against errors by modifying the wrong vlist object,
this function makes the passed vlist object immutable.
All further vlist changes have to use the vlist object returned by streamInqVlist().

\subsubsection*{Usage}

\begin{verbatim}
    void streamDefVlist(int streamID, int vlistID);
\end{verbatim}

\hspace*{4mm}\begin{minipage}[]{15cm}
\begin{deflist}{\texttt{streamID}\ }
\item[\texttt{streamID}]
Stream ID, from a previous call to {\htmlref{\texttt{streamOpenWrite}}{streamOpenWrite}}.
\item[\texttt{vlistID}]
Variable list ID, from a previous call to {\htmlref{\texttt{vlistCreate}}{vlistCreate}}.

\end{deflist}
\end{minipage}


\subsection{Get the variable list: \texttt{streamInqVlist}}
\index{streamInqVlist}
\label{streamInqVlist}

The function {\texttt{streamInqVlist}} returns the variable list of a stream.

\subsubsection*{Usage}

\begin{verbatim}
    int streamInqVlist(int streamID);
\end{verbatim}

\hspace*{4mm}\begin{minipage}[]{15cm}
\begin{deflist}{\texttt{streamID}\ }
\item[\texttt{streamID}]
Stream ID, from a previous call to {\htmlref{\texttt{streamOpenRead}}{streamOpenRead}} or {\htmlref{\texttt{streamOpenWrite}}{streamOpenWrite}}.

\end{deflist}
\end{minipage}

\subsubsection*{Result}

{\texttt{streamInqVlist}} returns an identifier to the variable list.



\subsection{Define a timestep: \texttt{streamDefTimestep}}
\index{streamDefTimestep}
\label{streamDefTimestep}

The function {\texttt{streamDefTimestep}} defines a timestep of a stream by the identifier tsID.
The identifier tsID is the timestep index starting at 0 for the first timestep.
Before calling this function the functions {\texttt{taxisDefVdate}} and {\texttt{taxisDefVtime}} should be used
to define the timestamp for this timestep. All calls to write the data refer to this timestep.

\subsubsection*{Usage}

\begin{verbatim}
    int streamDefTimestep(int streamID, int tsID);
\end{verbatim}

\hspace*{4mm}\begin{minipage}[]{15cm}
\begin{deflist}{\texttt{streamID}\ }
\item[\texttt{streamID}]
Stream ID, from a previous call to {\htmlref{\texttt{streamOpenWrite}}{streamOpenWrite}}.
\item[\texttt{tsID}]
Timestep identifier.

\end{deflist}
\end{minipage}

\subsubsection*{Result}

{\texttt{streamDefTimestep}} returns the number of expected records of the timestep.



\subsection{Get timestep information: \texttt{streamInqTimestep}}
\index{streamInqTimestep}
\label{streamInqTimestep}

The function {\texttt{streamInqTimestep}} sets the next timestep to the identifier tsID.
The identifier tsID is the timestep index starting at 0 for the first timestep.
After a call to this function the functions {\texttt{taxisInqVdate}} and {\texttt{taxisInqVtime}} can be used
to read the timestamp for this timestep. All calls to read the data refer to this timestep.

\subsubsection*{Usage}

\begin{verbatim}
    int streamInqTimestep(int streamID, int tsID);
\end{verbatim}

\hspace*{4mm}\begin{minipage}[]{15cm}
\begin{deflist}{\texttt{streamID}\ }
\item[\texttt{streamID}]
Stream ID, from a previous call to {\htmlref{\texttt{streamOpenRead}}{streamOpenRead}} or {\htmlref{\texttt{streamOpenWrite}}{streamOpenWrite}}.
\item[\texttt{tsID}]
Timestep identifier.

\end{deflist}
\end{minipage}

\subsubsection*{Result}

{\texttt{streamInqTimestep}} returns the number of records of the timestep or 0, if the end of the file is reached.