esmf_usage.tex

CCSM Research Tools: Community Atmosphere Model (CAM)

% $Id: ESMF_usage.tex,v 1.1.6.1 2002/04/24 03:26:02 erik Exp $

\section{Basic Usage and Conventions}

\subsection{Bindings}

The library includes both C/C++ and F90 bindings.  The C/C++ prefix for
procedures and parameters is {\tt ESMC\_} and the F90 prefix is {\tt ESMF\_}.

\subsection{Object Function Conventions}

A large portion of the library is built using objects.  To standardize the
creation, use and destruction of these objects the library uses certain
common function for each object.  

\begin{itemize}
\item{\bf ESM[F/C]\_<Class>New}
Allocates a {\it deep} object.  This function will allocate space from the heap and may
create other resources which must be free'd or deallocated.  All items created with
{\bf New} must be deleted with {\bf Delete} below.  {\tt e.g. ESMF\_LogNew}

\item{\bf ESM[F/C]\_<Class>Delete}
De-Allocates an object created with New.  Any transient resources that were created will
be cleaned up. {\tt e.g. ESMF\_LogDelete}

\item{\bf ESM[F/C]\_<Class>Init}
Initializes a {\it shallow} object.  This class of objects does not need to be destructed and
is guaranteed not to allocate any resources that must be cleaned up.  {\tt e.g. ESMF\_TimeInit}

\item{\bf ESM[F/C]\_<Class>Set<Value>}
Sets a given value with the class.  The {\bf Value} parameter is decided by the class. 
{\tt e.g. ESMF\_LogSetState}

\item{\bf ESM[F/C]\_<Class>Get<Value>}
Gets a given value with the class.  The {\bf Value} parameter is decided by the class.  
{\tt e.g. ESMF\_LogGetState}

\item{\bf ESM[F/C]\_<Class>SetConfig}
This function takes a list of resorces as defined in the resource section the class.  Some class
may not have resources and this function has no meaning.  The function allows a user to set multiple
resources with one function call.  {\tt e.g. ESMF\_LogSetConfig}

\item{\bf ESM[F/C]\_<Class>GetConfig}
This function takes a list of resorces as defined in the resource section the class.  Some class
may not have resources and this function has no meaning.  The function allows a user to get multiple
resources with one function call.  {\tt ESMF\_LogGetConfig}

\item{\bf ESM[C]\_<Class>Construct}
This function fills initializes an object with valid data.  This function is called by both the
{\bf Init} and {\bf New} functions.  Depending on the type of object this function may or may not 
allocate resources that need to be freed.

\item{\bf ESM[C]\_<Class>Destruct}
This function cleans up any resources that were created in the {\bf Construct} method.

\end{itemize}

\subsection{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 increase 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 the {\tt ``Construct''} routine before 
using its C/C++ classes.  A {\tt ``New''} routine is provided for C/C++ if
dynamic memory allocation is desired.

\end{itemize}

\subsection{Error Handling}

All C/C++ procedures return an integer error code.  All F90 procedures have 
an optional integer return code argument (with the exception of a select few
functions that use {\tt stdargs}).  Return codes are translated 
into error descriptions using the methods: 

\begin{verbatim}
    void ESMC_ErrPrint(int rc)

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

A return code of {\tt ESM[F/C]\_SUCCESS} indicates that an 
operation executed without errors.

The user can currently choose from two different error handlers.
{\tt ESM[F/C]\_ERR\_RETURN} will simply return from a routine in which an error 
is identified, without printing an error description.
{\tt ESM[F/C]\_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 _ErrHandlerSetType(ESM[F/C]_ErrHandlerType type)

    subroutine ESM[F/C]_ErrHandlerSetType(type)
    integer, intent(in) :: type
\end{verbatim}

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