\section{Print Control}
\label{sec:print}

All modules should use the same print control mechanism, to provide
both uniformity and flexibility.  The routines in \verb+util_print+ do
this.  Using these routines ensures that

\begin{enumerate}
\item All modules understand the print levels
\begin{itemize}
\item \verb+none+ (i.e., no output except for catastrophic errors, such as 
inconsistent data, or failure to converge)
\item \verb+low+
\item \verb+medium+ = \verb+default+
\item \verb+high+
\item \verb+debug+
\end{itemize}
\item Printing of specific quantities can be directly enabled or
  disabled from the input using already existing input routines
\item Modules operate independently and printing is
   controllable via context
\end{enumerate}

The following example shows how it works. Inside the SCF input,
 include the directive
\begin{verbatim}
  print low basis "final eigenvectors"
  noprint title
\end{verbatim}
This sets the overall SCF print level to low, forces printing of the
final eigenvectors and basis, and disables printing of the title.

The implementation is very simple.  Each module defines (using
provided input routines) one or two entries in the database which
enable/disable printing

\begin{itemize}
\item \verb+<module>:print+ --- list of names to enable print
\item \verb+<module>:noprint+ --- list of names to disable print
\end{itemize}

The special values ({\tt none}, {\tt low}, \ldots) are recognized in
the list of print keywords and are used to adjust the print level.
The parsing of this list is encapsulated in the routine
\verb+util_print_rtdb_load()+.  To support multiply nested modules, a
stack of print options is maintained.

\sloppy
The coding needed in a module using print control is then simply:
\begin{itemize}
\item In the input routine, upon detecting a line with either the print
  or noprint directive, insert the call to {\tt util\_print\_input};
\begin{verbatim}
     call util_print_input(rtdb, 'module_name')
\end{verbatim}
\item Set the default print level for a new module at the beginning of a module
\begin{verbatim}
     call util_print_push 
     call util_print_rtdb_load(rtdb, 'module_name')
\end{verbatim}
\end{itemize}

The routine \verb+util_print_push()+ sets the default print level for a new
  module. The routine \verb+util_print_rtdb_load+  then
 reads in any input parameters.

To control printing within a module, the following commands must be specified.

\begin{verbatim}
     #include "util.fh"

     if (util_print("name", level)) then
       write out data associated with "name"
     endif
\end{verbatim}


Level is one of the prespecified print levels (\verb+print_none+,
  \verb+print_low+, \ldots; see \verb+util/printlevels.fh+ for
  actual values).

At the end of a module, the output file can be invoked by the call,
\begin{verbatim}
     call util_print_pop
\end{verbatim}

\fussy

 An example of this usage is as follows;
\begin{verbatim}
#include "util.fh"

      call util_print_push
      call util_print_rtdb_load('scf')
      if (util_print('information', print_low)) then
         write(6,*) ...
      endif
      ...
      call util_print_pop
\end{verbatim}

 If an application wants more direct control over printing there are
routines to explicitly control the print level and to enable/disable
printing of named items.

The required integers have been declared in {\tt util.fh} and 
\verb+util_print+ has been declared an external logical valued function.
The required integers are
\begin{itemize}
\item \verb+print_none+ (warning: paradoxical as it may seem, this argument for
  \verb+util_print+ will force printing even if none is asked for!)
\item \verb+print_low+
\item \verb+print_medium+
\item \verb+print_high+
\item \verb+print_debug+
\item \verb+print_never+
\item \verb+print_default+ = \verb+print_medium+
\end{itemize}
and to declare \verb+util_print+ as an external logical valued function.

\subsection{Other Relevant Routines}

\subsubsection{{\tt util\_print}}
\sloppy
\begin{verbatim}
  logical function util_print(name, level)
  character*(*) name   [input]
  integer level        [input]
\end{verbatim}
The value \TRUE is returned if \verb+level+ is less than or equal to the current print level
or the printing of \verb+name+ was
explicitly enabled and the printing of \verb+name+ has not been
explicitly disabled.  Otherwise
\FALSE is returned.
The current print level is set by either \verb+util_print_rtdb_load+ or
\verb+util_print_set_level+.

\fussy

\subsubsection{{\tt util\_print\_input}}
\begin{verbatim}
    subroutine util_print_input(rtdb, prefix)
    integer rtdb         [input]
    character*(*) prefix [input]
\end{verbatim}
The input routine of a module should call this routine upon detecting
either the {\tt print} or {\tt noprint} directives.  It should pass
the name of the module in the character string {\tt prefix}.  This is
prepended to actual entries made in the database.

\subsubsection{{\tt util\_print\_push}}
\begin{verbatim}
    subroutine util_print_push
\end{verbatim}
Call this routine on entry to a module to push the print stack down.
A call to this routine is usually immediately followed by a call to
\verb+util_print_rtdb_load+. 

\subsubsection{{\tt util\_print\_pop}}
\begin{verbatim}
    subroutine util_print_pop
\end{verbatim}
Call this routine immediately before exit from a module to pop the
print stack to the previous context.

\subsubsection{{\tt util\_print\_rtdb\_load}}
\begin{verbatim}
    subroutine util_print_rtdb_load(rtdb, prefix)
    integer rtdb         [input]
    character*(*) prefix [input]
\end{verbatim}
This routine loads the print information from the database for a
module with name provided in \verb+prefix+.  The value of
\verb+prefix+ must match that provided in the corresponding call to
\verb+util_print_input+.

This routine is usually called at the start of a module immediately
following a call to \verb+util_print_push+.

\subsubsection{{\tt util\_print\_set\_level}}
\begin{verbatim}
    subroutine util_print_set_level(level)
    integer level        [input]
\end{verbatim}
Set the print level to {\tt level}.  This routine is rarely called
from applications.

