% $Id: ERROR.TEX 1.1 2000/01/24 10:18:52 ska Exp ska $
\section{\label{ssError}\subsys{error}}

\subsection{Design}

\subsys{error} is a mainly mixture of wrappers of functions of other
subsystems that issue the particular function and terminate the
application with an appropriate error message on failure.

Therefore, there is no header file for this subsystem, the prototypes
are located within the header file specific for the wrapped function
instead.

The error messages issued on failure can be customized, though, when
the native \suppl  implementation is used, the user can decide which
language to include and hard-code within \suppl. The adjustments
have to be made within the include file {\tt MSGS.LNG}. In conjunction,
the subdirectory {\tt NLS} contains all necessary resources to adjust
the \suppl  internal settings, mostly to set up the strings displayed.

\paragraphe{The error codes} returned by the functions of \suppl can be also 
considered as a part of \subsys{error}. All functions that return
a non-zero integer number to indicate a failure do use the
symbolic error codes defined in the header file {\tt ERRCODES.H}.
That way the user can easily create a general error detection and
error handling system, e.g. attach appropriate error messages (strings)
with the numbers.

\paragraphe{The error messages} issued by functions of \suppl  are
generated by functions in order to be overridden by other message
issuing facilites, such as \msglib. All those function are named
\fct{Esuppl\_*()}, where the \tok{*} part is derived from the
issued message, for instance \fct{Esuppl\_noMem()} prints the string
\quote{Out of memory.} and \fct{Esuppl\_writeFile(fnam)} prints
\quote{Cannot write file: <<fnam>>}.

The include file \fnam{MSGS.H} enumerates all error reporting
functions of \suppl.

The actual strings can be choosen at compile-time, e.g.\ to
prepare \suppl  to speak another language. Though, there is no
special help to tweak the messages themselves, like to change
the order of the embedded arguments -- the \tok{%s} and \tok{%d}
tokens in the \fct{printf()}-style format strings. The include
file \fnam{MSGS.LNG} defines what message file to use, thus, it
is recommended to create one file per supported language and
derive the filename from the name of the language. The names of the
identifiers must not be modified, though.

After issuing the error message the program is terminated by these
error reporting functions.

\subsection{Implementation}

\subsubsection{Functions of \subsys{dynstr}}

All these functions return a pointer of a newly dynamically allocated
chunk of memory of the heap. They terminate the program with the
error message \quote{\sc Out of memory.}, if the chunk of memory
could not be allocated, thus, if the arguments passed to the functions
are valid themselves, e.g. \tok{Estrdup(NULL)} is {\em not} valid,
these function {\em never} return \tok{NULL}.

The word {\em buffer} shall apply to a dynamically allocated chunk of
memory below. A {\em dynstring} is an indirect pointer to a buffer,
for more details refer to capitel \ref{ssDynstr} on page \refPage{ssDynstr}.

\begin{tabTS}
\fct{Emalloc} & Allocates a specified amount of bytes. \\
\fct{Ecalloc} & Allocates a specified amount of bytes and
	fills it with \tok{0} (zeroes). \\
\fct{Erealloc} & Resizes a buffer. The former contents of it is retained. \\
\fct{Esetsize} & Resizes a dynstring. The contents may change. \\
\fct{Eresize} & Resizes a dynstring. The contents is retained. \\
\fct{Estrdup} & Duplicates a string into a buffer. \\
\fct{Estrchg} & Duplicates a string into a dynstring. \\
\fct{Estrdupe} & Duplicates a portion of string into a buffer. \\
\end{tabTS}


\subsubsection{Error Reporting Functions}

The names of all such functions begins with \fct{Esuppl\_}.
The functions themselves are automatically created by the perl script
\fnam{MKERRFUNC.PL} from the header file \fnam{MSGS.H}.

One prototype may look like this:\newline\noindent
\verb*|void Esuppl_nonArgOption(char ch);|\newline\noindent
The perl script creates the following function body:\newline\noindent
\begin{verbatim*}
void Esuppl_nonArgOption(char ch)
{
	error(E_nonArgOption, ch);

}
\end{verbatim*}

The general way to construct the body is this:
\begin{itemize}
\item The function header is the same as the prototype.
\item The function body consists of exactly one line.
\item The function calls the macro \fct{error\#()}, where the hash sign
(\#) is replaced by the number of arguments of the prototype, if this
number is unequal to one (1); otherwise just the function \fct{error()}
is called.
\item The first argument to \fct{error()} is a \fct{printf()}-style
format string, which name is derived by replacing the portion
\fct{Esuppl\_} by just \fct{E\_}.
\item The remaining arguments to \fct{error()}, if any, are the same
as form the prototype, in the same order, too.
\end{itemize}

The format string is taken from \subsys{nls}, part localized messages.

\fct{error()} also terminates the program with exit code \tok{125}.

\paragraphe{To add new error reporting functions} one has to:
\begin{enumerate}
\item add a prototype of the function to the header file \fnam{MSGS.H},
\item add a format string to the localized message files in directory
	\fnam{NLS}, files \fnam{*.LNG}. The name of the message string
	must be the one constructed by replace the \fct{Esuppl\_} part of
	the function by \fct{E\_},
\item re-compile \suppl.
\end{itemize}

Note: Adding a new error reporting function changes one header file
included into most of the files of \suppl, that means that when \suppl
is re-compiled nearly all source files are compiled.
