<!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: 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>