\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}
         \= Generate an absolute time axis. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -b $<$nbits$>$}
         \> Set the number of bits for the output precision. The valid precisions depend \\
         \> on the file format:\\
         \> \parbox[r]{3in}{
              \vspace*{1mm}
              \hspace*{0cm}\begin{tabular}{|l|l|}
              \hline
              \rowcolor{pcolor2}
                \sl $<$format$>$ & \sl $<$nbits$>$ \\
                {\tt grb, grb2}           & {\tt P1 - P24}              \\
                {\tt nc, nc2, nc4, nc4c}  & {\tt I8/I16/I32/F32/F64}  \\
                {\tt grb2, srv, ext, ieg}       & {\tt F32/F64}             \\
              \hline
              \end{tabular}
              \vspace*{1mm}
            } \\
         \> For {\tt srv}, {\tt ext} and {\tt ieg} format the letter {\tt L} or {\tt B} can be added to set the byteorder \\
         \> to {\tt L}ittle or {\tt B}ig 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{pcolor2}
              {\bf File format}          & \sl $<$format$>$ \\
               GRIB version 1            & {\tt grb}  \\
               GRIB version 2            & {\tt grb2} \\
               netCDF                    & {\tt nc}   \\
               netCDF version 2 (64-bit) & {\tt nc2}  \\
               netCDF-4 (HDF5)           & {\tt nc4}  \\
               netCDF-4 classic          & {\tt nc4c} \\
               SERVICE                   & {\tt srv}  \\
               EXTRA                     & {\tt ext}  \\
               IEG                       & {\tt ieg}  \\
              \hline
              \end{tabular}
              \vspace*{1mm}
            } \\
         \> GRIB2 is only available if {\CDO} was compiled with GRIB\_API support and all \\
         \> netCDF file types are only available if {\CDO} was compiled with netCDF support! \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -g $<$grid$>$}
         \> Define the default grid description by name or from file (see chapter 1.3 on page \pageref{GRID_DESCRIPTION}). \\
         \> Available grid names are: {\tt r<NX>x<NY>}, {\tt lon=<LON>/lat=<LAT>}, {\tt n<N>}, {\tt gme<NI>} \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -h}
         \> Help information for the operators. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -M}
         \> Switch to indicate that the I/O streams have missing values. \\
\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 -O}
         \> Overwrite existing output file, if checked. \\
         \> Existing output file is checked only for: {\tt ens<STAT>}, {\tt merge}, {\tt mergetime} \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -P $<$nthreads$>$}
         \> Set number of OpenMP threads. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -Q}
         \> Alphanumeric sorting of netCDF parameter names. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -R}
         \> Convert GRIB1 data from reduced to regular grid (only with cgribex lib). \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -r}
         \> Generate 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 (see chapter 1.6 on page \pageref{PARAMETER_TABLE}).\\
         \> Predefined tables are:  {\tt echam4 echam5 echam6 mpiom1 ecmwf remo}\\
\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}
         \> SZIP compression of GRIB1 records. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl \ \ jpeg}
         \> JPEG compression of GRIB2 records. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl \ \ zip[\_1-9]}
         \> 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{Operator chaining}

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 arbitrary number of input streams ({\tt ifiles})
can't be combined with other operators if these operators are used
with more than one input stream. Here is an incomplete list of
these operators:
{\bf \htmlref{copy}{copy}},
{\bf \htmlref{cat}{cat}},
{\bf \htmlref{merge}{merge}},
{\bf \htmlref{mergetime}{mergetime}},
{\bf \htmlref{select}{select}},
{\bf \htmlref{ens$<\!STAT\!>$}{ENSSTAT}} \\
Use single quotes if the input stream names are generated with
wildcards. In this case CDO will do the pattern matching and the
output can be combined with other operators. Here is an example for
this feature:
\begin{verbatim}
   cdo timavg -select,name=temperature 'ifile?' ofile
\end{verbatim}

The CDO internal wildcard expansion is using the {\it glob()} function. 
Therefore internal wildcard expansion is not available on operating systems without the {\it glob()} function!

{\bf Note:}
Operator chaining is implemented over POSIX Threads (pthreads).
Therefore this {\CDO} feature is not available on operating systems without POSIX Threads support!

\subsection{Operator parameter}

Some operators need one or more parameter. A list of parameter is indicated by the seperator ','.

\begin{itemize}
\item STRING

Unquoted characters without blanks and tabs.
The following command select variables with the name {\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 range of integer parameter can be specified by {\it first}/{\it last}[/{\it inc}].
To select the days 5, 6, 7, 8 and 9 use:
\begin{verbatim}
   cdo selday,5/9 ifile ofile
\end{verbatim}
The result is the same as:
\begin{verbatim}
   cdo selday,5,6,7,8,9 ifile ofile
\end{verbatim}
\end{itemize}
