\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 -H}
         \> Do not append to netCDF {\it history} global attribute. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -k}
         \> NetCDF4 chunk type: auto, grid or lines. \\
\makebox[1.5in][l]{\hspace*{1cm}\sl -L}
         \> Lock I/O (sequential access). \\
\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 (Only available if OpenMP support was compiled in). \\
\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}
         \> Create an extra output stream for the module TIMSTAT. This stream contains  \\
         \> the number of non missing values for each output period. \\
\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 -W}
         \> Print extra warning messages. \\
\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{Environment variables}

There are some environment variables which influence the behavior of {\CDO}. 
An incomplete list can be found in \htmlref{Appendix A}{environment}.

Here is an example to set the envrionment variable CDO\_RESET\_HISTORY for different shells:

\begin{tabular}[b]{ll}
Bourne shell (sh): & CDO\_RESET\_HISTORY=1 ; export CDO\_RESET\_HISTORY \\
Korn shell (ksh):   & export CDO\_RESET\_HISTORY=1 \\
C shell (csh):        & setenv CDO\_RESET\_HISTORY 1 \\
\end{tabular}


\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{Parallelized operators}

Some of the {\CDO} operators are shared memory parallelized with OpenMP.
An OpenMP-enabled C compiler is needed to use this feature.
Users may request a specific number of OpenMP threads {\tt nthreads} with the '{\tt -P}' switch.

Here is an example to distribute the bilinear interpolation on 8 OpenMP threads:
\begin{lstlisting}[frame=single, backgroundcolor=\color{pcolor2}, basicstyle=\ttfamily, columns=flexible]
   cdo -P 8  remapbil,targetgrid  ifile  ofile
\end{lstlisting}

Many {\CDO} operators are I/O-bound. This means most of the time is spend in reading and writing the data. 
Only compute intensive {\CDO} operators are parallelized. 
An incomplete list of OpenMP parallelized operators can be found in \htmlref{Appendix B}{openmp}.

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