<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<TITLE> S-Lang Run-Time Library Reference: Version 1.4.0: Message and Error Functions</TITLE>
<LINK HREF="slangfun-8.html" REL=next>
<LINK HREF="slangfun-6.html" REL=previous>
<LINK HREF="slangfun.html#toc7" REL=contents>
</HEAD>
<BODY>
<A HREF="slangfun-8.html">Next</A>
<A HREF="slangfun-6.html">Previous</A>
<A HREF="slangfun.html#toc7">Contents</A>
<HR>
<H2><A NAME="s7">7. Message and Error Functions</A></H2>

<P>
<H2><A NAME="error"></A> <A NAME="ss7.1">7.1 <B>error</B></A>
</H2>

<P>
<DL>
<DT><B> Synopsis </B><DD><P>Generate an error condition
<DT><B> Usage </B><DD><P><CODE>error (String_Type msg</CODE>
<DT><B> Description </B><DD><P>The <CODE>error</CODE> function generates a <B>S-lang</B> error condition causing
the interpreter to start unwinding to top-level.  It takes a single
string parameter which is displayed on the stderr output device.
The error condition may be cleared via an <CODE>ERROR_BLOCK</CODE> with the
<CODE>_clear_error</CODE> function.  Consult <B>A Guide to the S-Lang Language</B> for more
information.
<DT><B> Example </B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
    define add_txt_extension (file)
    {
       if (typeof (file) != String_Type)
         error ("add_extension: parameter must be a string");
       file += ".txt";
       return file;
    }
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> See Also </B><DD><P><CODE>verror, _clear_error, message</CODE>
</DL>
<P>
<P>
<H2><A NAME="message"></A> <A NAME="ss7.2">7.2 <B>message</B></A>
</H2>

<P>
<DL>
<DT><B> Synopsis </B><DD><P>Print a string onto the message device
<DT><B> Usage </B><DD><P><CODE>message (String_Type s</CODE>
<DT><B> Description </B><DD><P>The <CODE>message</CODE> function will print the string specified by
<CODE>s</CODE> onto the message device.
<DT><B> Example </B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
     define print_current_time ()
     {
       message (time ());
     }
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> Notes </B><DD><P>The message device will depend upon the application.  For example,
the output message device for the <CODE>jed</CODE> editor correspond to the
line at the bottom of the display window.  The default message
device is the standard output device.
<DT><B> See Also </B><DD><P><CODE>vmessage, sprintf, error</CODE>
</DL>
<P>
<P>
<H2><A NAME="usage"></A> <A NAME="ss7.3">7.3 <B>usage</B></A>
</H2>

<P>
<DL>
<DT><B> Synopsis </B><DD><P>Generate a usage error
<DT><B> Usage </B><DD><P><CODE>usage (String_Type msg)</CODE>
<DT><B> Description </B><DD><P>The <CODE>usage</CODE> function generates a usage exception and displays
<CODE>msg</CODE> to the message device.
<DT><B> Example </B><DD><P>Suppose that some function <CODE>plot</CODE> plots an array of <CODE>x</CODE> and
<CODE>y</CODE> values.  The such a function could be written to issue a
usage message if the wrong number of arguments were passed:
<BLOCKQUOTE><CODE>
<PRE>
    define plot ()
    { 
       variable x, y;

       if (_NARGS != 2)
         usage ("plot (x, y)");
       
       (x, y) = ();
       % Now do the hard part
          .
          .
    }
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> See Also </B><DD><P><CODE>error, message</CODE>
</DL>
<P>
<P>
<H2><A NAME="verror"></A> <A NAME="ss7.4">7.4 <B>verror</B></A>
</H2>

<P>
<DL>
<DT><B> Synopsis </B><DD><P>Generate an error condition
<DT><B> Usage </B><DD><P><CODE>verror (String_Type fmt, ...)</CODE>
<DT><B> Description </B><DD><P>The <CODE>verror</CODE> function performs the same role as the <CODE>error</CODE>
function.  The only difference is that instead of a single string
argument, <CODE>verror</CODE> takes a sprintf style argument list.
<DT><B> Example </B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
    define open_file (file)
    {
       variable fp;

       fp = fopen (file, "r");
       if (fp == NULL) verror ("Unable to open %s", file);
       return fp;
    }
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> Notes </B><DD><P>In the current implementation, strictly speaking, the <CODE>verror</CODE>
function is not an intrinsic function.  Rather it is a predefined
<B>S-lang</B> function using a combination of <CODE>Sprintf</CODE> and
<CODE>error</CODE>.
<DT><B> See Also </B><DD><P><CODE>error, Sprintf, vmessage</CODE>
</DL>
<P>
<P>
<H2><A NAME="vmessage"></A> <A NAME="ss7.5">7.5 <B>vmessage</B></A>
</H2>

<P>
<DL>
<DT><B> Synopsis </B><DD><P>Print a formatted string onto the message device
<DT><B> Usage </B><DD><P><CODE>vmessage (String_Type fmt, ...)</CODE>
<DT><B> Description </B><DD><P>The <CODE>vmessage</CODE> function formats a sprintf style argument list
and displays the resulting string onto the message device.
<DT><B> Notes </B><DD><P>In the current implementation, strictly speaking, the <CODE>vmessage</CODE>
function is not an intrinsic function.  Rather it is a predefined
<B>S-lang</B> function using a combination of <CODE>Sprintf</CODE> and
<CODE>message</CODE>.
<DT><B> See Also </B><DD><P><CODE>message, Sprintf, verror</CODE>
</DL>
<P>
<P>
<P>
<HR>
<A HREF="slangfun-8.html">Next</A>
<A HREF="slangfun-6.html">Previous</A>
<A HREF="slangfun.html#toc7">Contents</A>
</BODY>
</HTML>
