psblas3/docs/src/error.tex

\section{Error handling}

The PSBLAS library error handling policy has been completely rewritten
in version 2.0. The idea behind the design of this new error handling
strategy is to keep error messages on a stack allowing the user to
trace back up to the point where the first error message has been
generated. Every routine in the PSBLAS-2.0 library has, as last
non-optional argument, an integer \verb|info| variable; whenever,
inside the routine, an error is detected, this variable is set to a
value corresponding to a specific error code. Then this error code is
also pushed on the error stack and then either control is returned to
the caller routine or the execution is aborted, depending on the users
choice. At the time when the execution is aborted, an error message is
printed on standard output with a level of verbosity than can be
chosen by the user. If the execution is not aborted, then, the caller
routine checks the value returned in the \verb|info| variable and, if
not zero, an error condition is raised. This process continues on all the
levels of nested calls until the level where the user decides to abort
the program execution.

Figure~\ref{fig:routerr} shows the layout of a generic \verb|psb_foo|
routine with respect to the PSBLAS-2.0 error handling policy. It is
possible to see how, whenever an error condition is detected, the
\verb|info| variable is set to the corresponding error code which is,
then, pushed on top of the stack by means of the
\verb|psb_errpush|. An error condition may be directly detected inside
a routine or indirectly checking the error code returned returned by a
called routine. Whenever an error is encountered, after it has been
pushed on stack, the program execution skips to a point where the
error condition is handled; the error condition is handled either by
returning control to the caller routine or by calling the
\verb|psb\_error| routine which prints the content of the error stack
and aborts the program execution, according to the choice made by the
user with \verb|psb_set_erraction|. The default is to print the error
and terminate the program, but the user may choose to handle the error
explicitly. 

\begin{figure}[h!]
  \begin{Sbox}
    \begin{minipage}[tl]{0.95\textwidth}
\small
\begin{lstlisting}
subroutine psb_foo(some args, info)
   ...
   if(error detected) then
      info=errcode1
      call psb_errpush('psb_foo', errcode1)
      goto 9999
   end if
   ...
   call psb_bar(some args, info)
   if(info .ne. zero) then
      info=errcode2
      call psb_errpush('psb_foo', errcode2)
      goto 9999
   end if
   ...
9999 continue
   if (err_act .eq. act_abort) then
     call psb_error(icontxt)
     return
   else
     return
   end if

end subroutine psb_foo
\end{lstlisting}
    \end{minipage}
  \end{Sbox}
  \setlength{\fboxsep}{8pt}
  \begin{center}
    \fbox{\TheSbox}
  \end{center}
  \caption{\label{fig:routerr}The layout of a generic \texttt{psb\_foo}
  routine with respect to PSBLAS-2.0 error handling policy.}
\end{figure}




Figure~\ref{fig:errormsg} reports a sample error message generated by
the PSBLAS-2.0 library. This error has been generated by the fact that
the user has chosen the invalid ``FOO'' storage format to represent
the sparse matrix. From this error message it is possible to see that
the error has been detected inside the \verb|psb_cest| subroutine
called by \verb|psb_spasb| ... by process 0 (i.e. the root process).


\begin{figure}[h!]
  \begin{Sbox}
    \begin{minipage}[tl]{0.95\textwidth}
\begin{verbatim}
==========================================================
Process: 0.  PSBLAS Error (4010) in subroutine: df_sample           
Error from call to subroutine mat dist            
==========================================================
Process: 0.  PSBLAS Error (4010) in subroutine: mat_distv           
Error from call to subroutine psb_spasb           
==========================================================
Process: 0.  PSBLAS Error (4010) in subroutine: psb_spasb           
Error from call to subroutine psb_cest            
==========================================================
Process: 0.  PSBLAS Error (136) in subroutine: psb_cest            
Format FOO is unknown
==========================================================
Aborting...
\end{verbatim}
    \end{minipage}
  \end{Sbox}
  \setlength{\fboxsep}{8pt}
  \begin{center}
    \fbox{\TheSbox}
  \end{center}
  \caption{\label{fig:errormsg}A sample PSBLAS-2.0 error
    message. Process 0 detected an error condition inside the {\textrm
    psb\_cest} subroutine}
\end{figure}


\clearpage\subroutine{psb\_errpush}{Pushes an error code onto the error
  stack}

\begin{lstlisting}
call psb_errpush(err_c, r_name, i_err, a_err)
\end{lstlisting}

\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Entry]
\item[err\_c] the error code\\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: an integer.
\item[r\_name] the soutine where the error has been caught.\\
Scope: {\bf local} \\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: a string.\\
\item[i\_err] addional info for error code\\
Scope: {\bf local} \\
Type: {\bf optional}\\
Specified as: an integer array\\
\item[a\_err] addional info for error code\\
Scope: {\bf local} \\
Type: {\bf optional}\\
Specified as: a string.\\
\end{description}

\clearpage\subroutine{psb\_error}{Prints the error stack content and aborts
  execution}

\begin{lstlisting}
call psb_error(icontxt)
\end{lstlisting}

\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Entry]
\item[icontxt] the communication context.\\
Scope: {\bf global} \\
Type: {\bf optional}\\
Intent: {\bf in}.\\
Specified as: an integer.
\end{description}



\clearpage\subroutine{psb\_set\_errverbosity}{Sets the verbosity of error
  messages.}

\begin{lstlisting}
call psb_set_errverbosity(v)
\end{lstlisting}

\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Entry]
\item[v] the verbosity level\\
Scope: {\bf global}\\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: an integer.
\end{description}

\clearpage\subroutine{psb\_set\_erraction}{Set the type of action to be
  taken  upon error condition.}


\begin{lstlisting}
call psb_set_erraction(err_act)
\end{lstlisting}

\begin{description}
\item[Type:] Asynchronous.
\item[\bf On Entry]
\item[err\_act] the type of action.\\
Scope: {\bf global} \\
Type: {\bf required}\\
Intent: {\bf in}.\\
Specified as: an integer. Possible values: \verb|psb_act_ret|,
\verb|psb_act_abort|. 
\end{description}



%% \clearpage\subroutine{psb\_errcomm}{Error communication routine}

%% \begin{lstlisting}
%% call psb_errcomm(icontxt, err)
%% \end{lstlisting}

%% \begin{description}
%% \item[\bf On Entry]
%% \item[icontxt] the communication context.\\
%% Scope: {\bf global} \\
%% Type: {\bf required}\\
%% Intent: {\bf in}.\\
%% Specified as: an integer.
%% \item[err] the error code to be communicated\\
%% Scope: {\bf global} \\
%% Type: {\bf required}\\
%% Intent: {\bf inout}.\\
%% Specified as: an integer.\\
%% \end{description}

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "userguide"
%%% End: