% $Id: Log_iface.tex,v 1.1.6.1 2002/04/24 03:25:36 erik Exp $\subsection{F90 Interface}\subsubsection{Types}{\bf MFM\_LogHandle}This log handle is returned from the initialization call.  It is used toidentify which log a given command is to use.  This type may only contain aninteger handle, but is cast as a Fortran type for {\tt type } safety.\subsubsection{Log Levels}Each message that is output via the log will have an associated logginglevel.  This level is used to categorize what type of message is being outputand what the priority/category of the message is.The logging levels will be defined as a list of integer parameters:\begin{itemize}\item{\bf MFM\_LOGLEVEL\_INFO}Marks a message that would be useful for someone debugging the code to have.\item{\bf MFM\_LOGLEVEL\_ERROR}Reports an error condition.\item{\bf MFM\_LOGLEVEL\_TIMER}Used to write information related to code profiling or timing.\end{itemize}\subsubsection{Log States}The program may be run at several different logging states.  Each state willallow the messages at various logging levels to be output. \begin{itemize}\item{\bf MFM\_LOGSTATE\_QUIET}Suppresses the output of all message types.  All calls to the log willreturn immediately after verifying this flag.  This will be the fastest mode ofoperation, the only faster being to turn the library off via the compile flags.\item{\bf MFM\_LOGSTATE\_NORMAL}This option will print only the types of messages that you would want to haveunder normal operations.\item{\bf MFM\_LOGSTATE\_TIMER}Prints out only profiling/timing information.\item{\bf MFM\_LOGSTATE\_VERBOSE}Outputs every type of message.\end{itemize}\subsubsection{Output Matrix}A matrix will determine which types of messages are output in each state.\begin{tabular}{|p{1.5in}|p{3.33in}|} \hline  & {\bf Log Level} \\ \hline\end{tabular}\begin{tabular}{|p{1.5in}|p{1.0in}|p{1.0in}|p{1.0in}|} \hline{\bf Log State}   & {\bf INFO }& {\bf ERROR } & {\bf TIMER} \\ \hline{\bf QUIET}       & off & off & off \\ \hline{\bf NORMAL}      & on & on & off \\ \hline{\bf TIMER}       & off & off & on \\ \hline{\bf VERBOSE}     & on & on  & on  \\ \hline\end{tabular}\subsubsection{Functions}\begin{itemize}\item{\bf MFM\_LogInit}This function initializes the log and should be called in a non-threadedcode section.\begin{verbatim}        function MFM_LogInit(name, logstate, labelio)        character *(*) :: name              ! The name of the logfiles.        integer :: logstate                 ! Beginning state of the log.        logical :: labelio                  ! Separate or same file for MPI.        type(MFM_LogHandle) :: MFM_LogInit  ! Returns a handle for this log\end{verbatim}This call will set up whatever data structures are necessary for logging, andwill open the logfiles as necessary.  The name parameter will be used to createthe log files.  If {\tt labelio} is {\tt .false.} then there will be onelogfile and the name will be exactly as specified.  If {\tt labelio} is {\tt.true.}, then there will be one file per process with the name ``{\tt name}.{\it \{MPI process number\}}''[ .\end{itemize}\subsubsection{Subroutines}\begin{itemize}\item{\bf MFM\_LogSetState}Sets the log state.  The state is set at initialization, but this provides amethod to change the setting at any time.\begin{verbatim}        subroutine MFM_LogSetState(log, state)        type(MFM_LogHandle) :: log      ! The log to set state in.        integer :: state                   ! The new state.\end{verbatim} \item{\bf MFM\_LogSelect}Chooses the log to make active.  This log is used for subsequent calls to {\tt MFM\_LogPrint}.\begin{verbatim}        subroutine MFM_LogSelect(log)        type(MFM_LogHandle) :: log      ! The log to use.\end{verbatim} \item{\bf MFM\_LogPrint}Outputs the desired message.\begin{verbatim}                subroutine MFM_LogPrint(LogLevel, format, ...)        integer :: LogLevel      ! Logging level for this data.        character(*) :: format   ! A C-Style format string        \end{verbatim}Example:\begin{verbatim}        real(8) :: eps        real :: thet        int :: i                call MFM_LogPrint(MFM_LOGLEVEL_INFO, "In Euler Transform, eps = %-10.3f, thet =     &   %10.3lf, iteration:%d \n", eps, thet, i)\end{verbatim}The call will work exactly like {\tt printf} does in C.  This call will notactually exist in this module since it accepts a variable argument list, andthis can only be done in C.  The function will appear to be included in thismodule, however.The log levels are defined above.\item{\bf MFM\_LogFlush}        This function will not return until the log has flushed the output throughthe output mechanism.\end{itemize}