

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

The function {\tt 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}{\tt filetype\ }
\item[{\tt path}]
The name of the new dataset.
\item[{\tt filetype}]
The type of the file format, one of the set of predefined {\CDI} file format types.
                     The valid {\CDI} file format types are {\tt FILETYPE\_GRB}, {\tt FILETYPE\_GRB2}, {\tt FILETYPE\_NC},
                     {\tt FILETYPE\_NC2}, {\tt FILETYPE\_NC4}, {\tt FILETYPE\_NC4C}, {\tt FILETYPE\_SRV},
                     {\tt FILETYPE\_EXT} and {\tt FILETYPE\_IEG}.

\end{deflist}
\end{minipage}

\subsubsection*{Result}

Upon successful completion {\tt 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}{\tt CDI\_EUFILETYPE\ }
\item[{\tt CDI\_ESYSTEM}]
Operating system error.
\item[{\tt CDI\_EINVAL}]
Invalid argument.
\item[{\tt CDI\_EUFILETYPE}]
Unsupported file type.
\item[{\tt CDI\_ELIBNAVAIL}]
Library support not compiled in.
\end{deflist}
\end{minipage}


\subsubsection*{Example}

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

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

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


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

The function {\tt 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}{\tt path\ }
\item[{\tt path}]
The name of the dataset to be read.

\end{deflist}
\end{minipage}

\subsubsection*{Result}

Upon successful completion {\tt 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}{\tt CDI\_EUFILETYPE\ }
\item[{\tt CDI\_ESYSTEM}]
Operating system error.
\item[{\tt CDI\_EINVAL}]
Invalid argument.
\item[{\tt CDI\_EUFILETYPE}]
Unsupported file type.
\item[{\tt CDI\_ELIBNAVAIL}]
Library support not compiled in.
\end{deflist}
\end{minipage}


\subsubsection*{Example}

Here is an example using {\tt streamOpenRead} to open an existing netCDF
file named {\tt 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: {\tt streamClose}}
\index{streamClose}
\label{streamClose}

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

\subsubsection*{Usage}

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

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

\end{deflist}
\end{minipage}


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

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

\subsubsection*{Usage}

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

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

\end{deflist}
\end{minipage}

\subsubsection*{Result}

{\tt 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 {\tt FILETYPE\_GRB}, {\tt FILETYPE\_GRB2}, {\tt FILETYPE\_NC}, {\tt FILETYPE\_NC2},
{\tt FILETYPE\_NC4}, {\tt FILETYPE\_NC4C}, {\tt FILETYPE\_SRV}, {\tt FILETYPE\_EXT} and {\tt FILETYPE\_IEG}.



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

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

\subsubsection*{Usage}

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

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

\end{deflist}
\end{minipage}


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

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

\subsubsection*{Usage}

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

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

\end{deflist}
\end{minipage}

\subsubsection*{Result}

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



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

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

\subsubsection*{Usage}

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

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

\end{deflist}
\end{minipage}


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

The function {\tt 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}{\tt streamID\ }
\item[{\tt streamID}]
Stream ID, from a previous call to {\htmlref{\tt streamOpenRead}{streamOpenRead}} or {\htmlref{\tt streamOpenWrite}{streamOpenWrite}}.

\end{deflist}
\end{minipage}

\subsubsection*{Result}

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



\subsection{Define time step: {\tt streamDefTimestep}}
\index{streamDefTimestep}
\label{streamDefTimestep}

The function {\tt streamDefTimestep} defines the time step of a stream.

\subsubsection*{Usage}

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

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

\end{deflist}
\end{minipage}

\subsubsection*{Result}

{\tt streamDefTimestep} returns the number of records of the time step.



\subsection{Get time step: {\tt streamInqTimestep}}
\index{streamInqTimestep}
\label{streamInqTimestep}

The function {\tt streamInqTimestep} returns the time step of a stream.

\subsubsection*{Usage}

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

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

\end{deflist}
\end{minipage}

\subsubsection*{Result}

{\tt streamInqTimestep} returns the number of records of the time step.



\subsection{Write a variable: {\tt streamWriteVar}}
\index{streamWriteVar}
\label{streamWriteVar}

The function streamWriteVar writes the values of one time step of a variable 
to an open dataset.
\subsubsection*{Usage}

\begin{verbatim}
    void streamWriteVar(int streamID, int varID, const double *data, int nmiss);
\end{verbatim}

\hspace*{4mm}\begin{minipage}[]{15cm}
\begin{deflist}{\tt streamID\ }
\item[{\tt streamID}]
Stream ID, from a previous call to {\htmlref{\tt streamOpenRead}{streamOpenRead}} or {\htmlref{\tt streamOpenWrite}{streamOpenWrite}}.
\item[{\tt varID}]
Variable identifier.
\item[{\tt data}]
Pointer to a block of data values to be written.
\item[{\tt nmiss}]
Number of missing values.

\end{deflist}
\end{minipage}


\subsection{Read a variable: {\tt streamReadVar}}
\index{streamReadVar}
\label{streamReadVar}

The function streamReadVar reads all the values of one time step of a variable
from an open dataset.
\subsubsection*{Usage}

\begin{verbatim}
    void streamReadVar(int streamID, int varID, double *data, int *nmiss);
\end{verbatim}

\hspace*{4mm}\begin{minipage}[]{15cm}
\begin{deflist}{\tt streamID\ }
\item[{\tt streamID}]
Stream ID, from a previous call to {\htmlref{\tt streamOpenRead}{streamOpenRead}} or {\htmlref{\tt streamOpenWrite}{streamOpenWrite}}.
\item[{\tt varID}]
Variable identifier.
\item[{\tt data}]
Pointer to the location into which the data values are read.
                     The caller must allocate space for the returned values.
\item[{\tt nmiss}]
Number of missing values.

\end{deflist}
\end{minipage}


\subsection{Write a horizontal slice of a variable: {\tt streamWriteVarSlice}}
\index{streamWriteVarSlice}
\label{streamWriteVarSlice}

The function streamWriteVarSlice writes the values of a horizontal slice of a 
variable to an open dataset.
\subsubsection*{Usage}

\begin{verbatim}
    void streamWriteVarSlice(int streamID, int varID, int levelID, const double *data, 
                             int nmiss);
\end{verbatim}

\hspace*{4mm}\begin{minipage}[]{15cm}
\begin{deflist}{\tt streamID\ }
\item[{\tt streamID}]
Stream ID, from a previous call to {\htmlref{\tt streamOpenRead}{streamOpenRead}} or {\htmlref{\tt streamOpenWrite}{streamOpenWrite}}.
\item[{\tt varID}]
Variable identifier.
\item[{\tt levelID}]
Level identifier.
\item[{\tt data}]
Pointer to a block of data values to be written.
\item[{\tt nmiss}]
Number of missing values.

\end{deflist}
\end{minipage}


\subsection{Read a horizontal slice of a variable: {\tt streamReadVarSlice}}
\index{streamReadVarSlice}
\label{streamReadVarSlice}

The function streamReadVar reads all the values of a horizontal slice of a variable
from an open dataset.
\subsubsection*{Usage}

\begin{verbatim}
    void streamReadVarSlice(int streamID, int varID, int levelID, double *data, 
                            int *nmiss);
\end{verbatim}

\hspace*{4mm}\begin{minipage}[]{15cm}
\begin{deflist}{\tt streamID\ }
\item[{\tt streamID}]
Stream ID, from a previous call to {\htmlref{\tt streamOpenRead}{streamOpenRead}} or {\htmlref{\tt streamOpenWrite}{streamOpenWrite}}.
\item[{\tt varID}]
Variable identifier.
\item[{\tt levelID}]
Level identifier.
\item[{\tt data}]
Pointer to the location into which the data values are read.
                     The caller must allocate space for the returned values.
\item[{\tt nmiss}]
Number of missing values.

\end{deflist}
\end{minipage}
