timemgmt_usage.tex

CCSM Research Tools: Community Atmosphere Model (CAM)

% $Id: TimeMgmt_usage.tex,v 1.1.6.1 2002/04/24 03:25:50 erik Exp $
\section{Usage}

The library includes both C and F90 bindings.  C methods and 
parameters begin with {\tt MF\_} (Modeling Framework) and F90 
methods and parameters begin with {\tt MFM\_} (Modeling Framework 
Modules).

\noindent {\bf Constraints}

The library design imposes some constraints on the user:

\begin{itemize}
\item {\it No direct access of Fortran derived types.}  Attributes
of Fortran derived types are private.

\item{\it All types should be initialized.} In order to provide consistent
argument checking and to inrease the overall robustness of the library,
a user should call one of the {\tt ``Init''} routines before using the
library's Fortran derived types, or a {\tt ``Construct''} routine before 
using its C classes.

\end{itemize}

\noindent {\bf Error Handling}

All C ({\tt MF\_*}) operations return an integer error code.  
All F90 ({\tt MFM\_*}) operations have an optional integer return code 
argument.  Return codes are translated into error descriptions using the 
methods: 

\begin{verbatim}
    void MF_ErrPrint(int rc)

    subroutine MFM_ErrPrint(rc)  
    integer, intent(in) :: rc
\end{verbatim}

A return code of {\tt MF[M]\_SUCCESS} indicates that an 
operation executed without errors.

The user can currently choose from two different error handlers.
{\tt MF[M]\_ERR\_RETURN} will simply return from a routine in which an error 
is identified, without printing an error description.
{\tt MF[M]\_ERR\_EXIT} will print a detailed error description including
file, function name, and line number, and will then terminate execution
(this is a simple exit, not an {\tt MPI\_ABORT}).  These handlers are set 
using the methods: 
\begin{verbatim}
    void MF_ErrHandlerSetType(MF_ErrHandlerType type)

    subroutine MFM_ErrHandlerSetType(type)
    integer, intent(in) :: type
\end{verbatim}

The intent is to develop an MPI-like error handling system in which
users can choose from a variety of handlers or supply their own.