\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}
         \> 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 (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}
