<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
<TITLE> S-Lang Run-Time Library Reference: Version 1.4.0: Debugging Functions</TITLE>
<LINK HREF="slangfun-18.html" REL=next>
<LINK HREF="slangfun-16.html" REL=previous>
<LINK HREF="slangfun.html#toc17" REL=contents>
</HEAD>
<BODY>
<A HREF="slangfun-18.html">Next</A>
<A HREF="slangfun-16.html">Previous</A>
<A HREF="slangfun.html#toc17">Contents</A>
<HR>
<H2><A NAME="s17">17. Debugging Functions</A></H2>
<P>
<H2><A NAME="_clear_error"></A> <A NAME="ss17.1">17.1 <B>_clear_error</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Clear an error condition
<DT><B> Usage </B><DD><P><CODE>_clear_error ()</CODE>
<DT><B> Description </B><DD><P>This function may be used in error-blocks to clear the error that
triggered execution of the error block. Execution resumes following
the statement, in the scope of the error-block, that triggered the
error.
<DT><B> Example </B><DD><P>Consider the following wrapper around the <CODE>putenv</CODE> function:
<BLOCKQUOTE><CODE>
<PRE>
define try_putenv (name, value)
{
variable status;
ERROR_BLOCK
{
_clear_error ();
status = -1;
}
status = 0;
putenv (sprintf ("%s=%s", name, value);
return status;
}
</PRE>
</CODE></BLOCKQUOTE>
If <CODE>putenv</CODE> fails, it generates an error condition, which the
<CODE>try_putenv</CODE> function catches and clears. Thus <CODE>try_putenv</CODE>
is a function that returns <CODE>-1</CODE> upon failure and <CODE>0</CODE> upon
success.
<DT><B> See Also </B><DD><P><CODE>_trace_function, _slangtrace, _traceback</CODE>
</DL>
<P>
<P>
<H2><A NAME="_debug_info"></A> <A NAME="ss17.2">17.2 <B>_debug_info</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Configure debugging information
<DT><B> Usage </B><DD><P><CODE>Integer_Type _debug_info</CODE>
<DT><B> Description </B><DD><P>The <CODE>_debug_info</CODE> variable controls whether or not extra code
should be generated for additional debugging and traceback
information. Currently, if <CODE>_debug_info</CODE> is zero, no extra code
will be generated; otherwise extra code will be inserted into the
compiled bytecode for additional debugging data.
<P>The value of this variable is is local to each compilation unit and
setting its value in one unit has no effect upon its value in other
units.
<DT><B> Example </B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
_debug_info = 1; % Enable debugging information
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> Notes </B><DD><P>Setting this variable to a non-zero value may slow down the
interpreter somewhat.
<DT><B> See Also </B><DD><P><CODE>_traceback, _slangtrace</CODE>
</DL>
<P>
<P>
<H2><A NAME="_slangtrace"></A> <A NAME="ss17.3">17.3 <B>_slangtrace</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Turn function tracing on or off.
<DT><B> Usage </B><DD><P><CODE>Integer_Type _slangtrace</CODE>
<DT><B> Description </B><DD><P>The <CODE>_slangtrace</CODE> variable is a debugging aid that when set to a
non-zero value enables tracing when function declared by
<CODE>_trace_function</CODE> is entered. If the value is greater than
zero, both intrinsic and user defined functions will get traced.
However, if set to a value less than zero, intrinsic functions will
not get traced.
<DT><B> See Also </B><DD><P><CODE>_trace_function, _traceback, _print_stack</CODE>
</DL>
<P>
<P>
<H2><A NAME="_trace_function"></A> <A NAME="ss17.4">17.4 <B>_trace_function</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Set the function to trace
<DT><B> Usage </B><DD><P><CODE>_trace_function (String_Type f)</CODE>
<DT><B> Description </B><DD><P><CODE>_trace_function</CODE> declares that the <B>S-lang</B> function with name
<CODE>f</CODE> is to be traced when it is called. Calling
<CODE>_trace_function</CODE> does not in itself turn tracing on. Tracing
is turned on only when the variable <CODE>_slangtrace</CODE> is non-zero.
<DT><B> See Also </B><DD><P><CODE>_slangtrace, _traceback</CODE>
</DL>
<P>
<P>
<H2><A NAME="_traceback"></A> <A NAME="ss17.5">17.5 <B>_traceback</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Generate a traceback upon error
<DT><B> Usage </B><DD><P><CODE>Integer_Type _traceback</CODE>
<DT><B> Description </B><DD><P><CODE>_traceback</CODE> is an intrinsic integer variable whose value
controls whether or not a traceback of the call stack is to be
generated upon error. If <CODE>_traceback</CODE> is greater than zero, a
full traceback will be generated, which includes the values of local
variables. If the value is less than zero, a traceback will be
generated without local variable information, and if
<CODE>_traceback</CODE> is zero the traceback will not be generated.
<P>Local variables are represented in the form <CODE>$n</CODE> where <CODE>n</CODE> is an
integer numbered from zero. More explicitly, <CODE>$0</CODE> represents the
first local variable, <CODE>$1</CODE> represents the second, and so on.
Please note that function parameters are local variables and that the
first parameter corresponds to <CODE>$0</CODE>.
<DT><B> See Also </B><DD><P><CODE>_slangtrace, error</CODE>
</DL>
<P>
<P>
<P>
<HR>
<A HREF="slangfun-18.html">Next</A>
<A HREF="slangfun-16.html">Previous</A>
<A HREF="slangfun.html#toc17">Contents</A>
</BODY>
</HTML>
