\section{Usage}

This section descibes how to use {\CDO}.
The syntax is:
\begin{verbatim}
   cdo  [ Options ] Operator1 [ --Operator2 [ --OperatorN ] ]
\end{verbatim}


\subsection{Options}

All options have to be placed before the first operator.
The following options are available for all operators:

\begin{tabbing}
\makebox[1.5in][l]{\hspace*{1cm}\sl -a}
         \= Convert from a relative to an absolute time axis. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -b $<$nbits$>$}
         \> Set the number of bits for output precision. The valid precisions depend \\
         \> on the file format:\\
         \> \parbox[r]{3in}{
              \vspace*{1mm}
              \hspace*{0cm}\begin{tabular}{|l|l|}
              \hline
              \rowcolor[gray]{.9}
                \sl $<$format$>$ & \sl $<$nbits$>$ \\
                {\tt grb}                         & {\tt 1 - 32} \\
                {\tt nc, nc2, nc4, srv, ext, ieg} & {\tt 32/64}   \\
              \hline
              \end{tabular}
              \vspace*{1mm}
            } \\
         \> For {\tt srv}, {\tt ext} and {\tt ieg} format an {\tt L} or {\tt B} can be added to set the byteorder \\
         \> to Little or Big endian. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -f $<$format$>$}
         \> Set the output file format. The valid file formats are: \\
         \> \parbox[r]{3in}{
              \vspace*{1mm}
              \hspace*{0cm}\begin{tabular}{|l|l|}
              \hline
              \rowcolor[gray]{.9}
              {\bf File format}          & \sl $<$format$>$ \\
               GRIB version 1            & {\tt grb} \\
               netCDF                    & {\tt nc}  \\
               netCDF version 2 (64-bit) & {\tt nc2} \\
               netCDF-4 classic (HDF5)   & {\tt nc4} \\
               SERVICE                   & {\tt srv} \\
               EXTRA                     & {\tt ext} \\
               IEG                       & {\tt ieg} \\
              \hline
              \end{tabular}
              \vspace*{1mm}
            } \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -g $<$grid$>$}
         \> Define the default grid description by name or from file. \\
         \> Available grid names are: {\tt t}$<$RES$>${\tt grid}, {\tt r}$<$NX$>${\tt x}$<$NY$>$, {\tt gme}$<$NI$>$ \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -h}
         \> Help information for the operators. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -m $<$missval$>$}
         \> Set the default missing value (default: {\tt-9e+33}). \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -R}
         \> Convert GRIB data from reduced to regular grid. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -r}
         \> Convert from an absolute to a relative time axis. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -s}
         \> Silent mode. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -t $<$partab$>$}
         \> Set the default parameter table name or file.\\
         \> Predefined tables are:  {\tt echam4 echam5 mpiom1}\\
\makebox[1.5in][l]{\hspace*{1cm}\sl -V}
         \> Print the version number. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -v}
         \> Print extra details for some operators. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -z szip}
         \> Compress GRIB records with szip. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl \ \ zip}
         \> Deflate compression of netCDF4 variables. \\
\end{tabbing}
%\footnotemark
%\footnotetext{Needs szip support compiled in}

\subsection{Operators}

There are more than 400 operators available.
% See section {\bf \htmlref{Operator catalog}{opercat}} for a short overview of all operators.
A detailed description of all operators can be found in the
{\bf \htmlref{Reference Manual}{refman}} section.


\subsection{Combining operators}

All operators with a fixed number of input streams and one output stream
can pipe the result directly to an other operator.
The operator must begin with "--", in order to combine it with others.
This can improve the performance by:
\begin{itemize}
\item reducing unnecessary disk I/O
\item parallel processing
\end{itemize}
Use
\begin{verbatim}
   cdo sub -dayavg ifile2 -timavg ifile1 ofile
\end{verbatim}
instead of
\begin{verbatim}
   cdo timavg ifile1 tmp1
   cdo dayavg ifile2 tmp2
   cdo sub tmp2 tmp1 ofile
   rm tmp1 tmp2
\end{verbatim}

All operators with an unlimited number of input streams ({\tt ifiles})
can't be combined with other operators. Here is an incomplete list
of those operators:
{\bf \htmlref{copy}{copy}},
{\bf \htmlref{cat}{cat}},
{\bf \htmlref{merge}{merge}},
{\bf \htmlref{mergetime}{mergetime}},
{\bf \htmlref{ens$<\!STAT\!>$}{ENSSTAT}}

Combining of operators is implemented over POSIX Threads (pthread).
Therefore this {\CDO} feature is not available on operating systems 
without POSIX Threads.

\subsection{Operator parameter}

Some operators need one or more parameter.

\begin{itemize}
\item STRING

Unquoted characters without blanks and tabs.
The following command select the variables with the names {\tt pressure} and {\tt tsurf}:
\begin{verbatim}
   cdo selvar,pressure,tsurf ifile ofile
\end{verbatim}

\item FLOAT

Floating point number in any representation.
The following command sets the range between {\tt 0} and {\tt 273.15}
of all fields to missing value:
\begin{verbatim}
   cdo setrtomiss,0,273.15 ifile ofile
\end{verbatim}

\item INTEGER

A list of integers can be specified by {\it first/last[/inc]}.
To select the days 5, 6, 7, 8 and 9 use:
\begin{verbatim}
   cdo selday,5/9 ifile ofile
\end{verbatim}
This is the same as:
\begin{verbatim}
   cdo selday,5,6,7,8,9 ifile ofile
\end{verbatim}
\end{itemize}
