error.html | searchcode

/trunk/tigcc/doc/System/WebFiles/error.html

http://github.com/debrouxl/gcc4ti
HTML | 417 lines | 358 code | 43 blank | 16 comment | 0 complexity | ac5a5899c2134b7a7fa1236fe3970ac2 MD5 | raw file
Possible License(s): GPL-2.0, AGPL-1.0

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<HTML>

<HEAD>

<TITLE>error.h</TITLE>

<STYLE TYPE="TEXT/CSS">

<!--

.IE3-DUMMY { CONT-SIZE: 100%; }

BODY { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; BACKGROUND-COLOR: #E0E0E0; }

P { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }

H1 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }

H2 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }

H3 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }

H4 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }

H5 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }

H6 { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }

UL { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; }

TD { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; BACKGROUND-COLOR: #FFFFFF; }

.NOBORDER { BACKGROUND-COLOR: #E0E0E0; PADDING: 0pt; }

.NOBORDER TD { FONT-FAMILY: Verdana,Arial,Helvetica,Sans-Serif; BACKGROUND-COLOR: #E0E0E0; PADDING: 0pt; }

.CODE { FONT-FAMILY: Courier New; }

-->

</STYLE>

</HEAD>

<BODY TEXT="#000000" BGCOLOR="#E0E0E0">

<FONT SIZE="5"><B>The &lt;error.h&gt; Header File</B></FONT>

<HR>

<P><B>Routines for error handling</B></P>



<H3><U>Language Extensions</U></H3>

<DL INDENT="20"><DT><B><A HREF="#ENDFINAL">ENDFINAL</A></B><DD>Terminates a TRY...FINALLY...ENDFINAL block.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#ENDTRY">ENDTRY</A></B><DD>Terminates a TRY...ONERR...ENDTRY block.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#FINALLY">FINALLY</A></B><DD>Begins the termination handler in a TRY...FINALLY...ENDFINAL block.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#ONERR">ONERR</A></B><DD>Begins the error handler in a TRY...ONERR...ENDTRY block.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#PASS">PASS</A></B><DD>Passes on unhandled errors to a higher level.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#TRY">TRY</A></B><DD>Starts a protected block of code.</DL>

<H3><U>Functions</U></H3>

<DL INDENT="20"><DT><B><A HREF="#ER_catch">ER_catch</A></B><DD>Catches an error.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#ER_success">ER_success</A></B><DD>Pops the state from the error stack.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#ER_throw">ER_throw</A></B><DD>Throws an error with a constant number.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#ER_throwVar">ER_throwVar</A></B><DD>Throws an error.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#ERD_dialog">ERD_dialog</A></B><DD>Displays an error dialog box.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#ERD_dismissNotice">ERD_dismissNotice</A></B><DD>Removes the error notice displayed by a prior call to <A HREF="#ERD_notice">ERD_notice</A>.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#ERD_notice">ERD_notice</A></B><DD>Displays an error notice.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#ERD_process">ERD_process</A></B><DD>Processes an error.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#find_error_message">find_error_message</A></B><DD>Returns a TI-Basic error message string.</DL>

<H3><U>Global Variables</U></H3>

<DL INDENT="20"><DT><B><A HREF="#errCode">errCode</A></B><DD>Contains the error number in a TRY...ONERR...ENDTRY block.</DL>

<H3><U>Predefined Types</U></H3>

<DL INDENT="20"><DT><B><A HREF="alloc.html#Bool">Bool</A></B><DD>An enumeration to describe true or false values.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#ERROR_FRAME">ERROR_FRAME</A></B><DD>A type designed for capturing a task state.<IMG WIDTH="1" HEIGHT="20" ALIGN="TOP"><DT><B><A HREF="#ErrorCodes">ErrorCodes</A></B><DD>An enumeration containing all error codes.</DL>

<HR>

<H3><A NAME="ENDFINAL"><U>ENDFINAL</U></A></H3>

<P><B>Terminates a TRY...FINALLY...ENDFINAL block.</B></P>



<P>The macro ENDFINAL terminates a <A HREF="#TRY">TRY</A>...<A HREF="#FINALLY">FINALLY</A>...ENDFINAL block.

See <A HREF="#TRY">TRY</A> for more info.</P>



<HR>

<H3><A NAME="ENDTRY"><U>ENDTRY</U></A></H3>

<P><B>Terminates a TRY...ONERR...ENDTRY block.</B></P>



<P>The macro ENDTRY terminates a <A HREF="#TRY">TRY</A>...<A HREF="#ONERR">ONERR</A>...ENDTRY block.

See <A HREF="#TRY">TRY</A> for more info.</P>



<HR>

<H3><A NAME="FINALLY"><U>FINALLY</U></A></H3>

<P><B>Begins the termination handler in a TRY...FINALLY...ENDFINAL block.</B></P>



<P>The macro FINALLY ends the protected block and begins the handler for code

which always has to be executed (see <A HREF="#TRY">TRY</A> for more info).

The variable <A HREF="#errCode">errCode</A> is

automatically created in the error handler, and it contains the error number to allow

the program to check what caused the error, or 0 if there was no error.

This variable is destroyed after the <A HREF="#ENDFINAL">ENDFINAL</A> statement.

<BR><BR>

<B>Note:</B> The macro FINALLY uses the <A HREF="#ER_success">ER_success</A> function to end the protected

block, and <A HREF="#ENDFINAL">ENDFINAL</A> uses <A HREF="#PASS">PASS</A> to throw the

error signaled by <A HREF="#errCode">errCode</A> a second time.

<BR><BR>

Here is an example (called "Memory Error"), which demonstrates the use of this

macro:</P>

<PRE>// Allocate memory as long as possible, then throw an error
// All allocated memory will be freed again!

#define USE_TI89              // Compile for TI-89
#define USE_TI92PLUS          // Compile for TI-92 Plus
#define USE_V200              // Compile for V200

#define MIN_AMS 100           // Compile for AMS 1.00 or higher
#define ENABLE_ERROR_RETURN   // Enable Returning Errors to TIOS

#include &lt;tigcclib.h&gt;         // Include All Header Files

#define BLOCK_SIZE 1024

void AllocRecursively(void)
{
  void *ptr = malloc_throw (BLOCK_SIZE);
  TRY
    // Could do something with ptr here...
    AllocRecursively ();
    // Could still do something with ptr...
  FINALLY
    free (ptr);
  ENDFINAL
}

// Main Function
void _main(void)
{
  AllocRecursively ();
}

</PRE>



<HR>

<H3><A NAME="ONERR"><U>ONERR</U></A></H3>

<P><B>Begins the error handler in a TRY...ONERR...ENDTRY block.</B></P>



<P>The macro ONERR ends the protected block and begins the error handler (see

<A HREF="#TRY">TRY</A> for more info). The variable <A HREF="#errCode">errCode</A> is

automatically created in the error handler, and it contains the error number to allow

the program to check what caused the error. This variable

is destroyed after the <A HREF="#ENDTRY">ENDTRY</A> statement.

<BR><BR>

<B>Note:</B> The macro ONERR uses the <A HREF="#ER_success">ER_success</A> function to end the protected

block.</P>



<HR>

<H3><A NAME="PASS"><U>PASS</U></A></H3>

<P><B>Passes on unhandled errors to a higher level.</B></P>



<P>The macro PASS passes on any unhandled errors to a higher level error handler (see

<A HREF="#TRY">TRY</A> for more info). In fact, it executes <A HREF="#ER_throwVar">ER_throwVar</A>

with <A HREF="#errCode">errCode</A> as an argument.</P>



<HR>

<H3><A NAME="TRY"><U>TRY</U></A></H3>

<P><B>Starts a protected block of code.</B></P>



<P>TRY,

<A HREF="#ONERR">ONERR</A>,

<A HREF="#ENDTRY">ENDTRY</A>,

<A HREF="#FINALLY">FINALLY</A>,

<A HREF="#ENDFINAL">ENDFINAL</A>, and

<A HREF="#PASS">PASS</A>

are macros which extend the C language to implement an error handling mechanism which is

almost identical to the commonly-used exception handling as well as error handling in TI-Basic.

<BR><BR>

TRY begins the protected block. It is a macro which is implemented using the

<A HREF="#ER_catch">ER_catch</A> function. If an error occurs in the protected block, program

execution transfers to the block after the <A HREF="#ONERR">ONERR</A> or

<A HREF="#FINALLY">FINALLY</A> statement.

<BR><BR>

However, <A HREF="#ONERR">ONERR</A> and <A HREF="#FINALLY">FINALLY</A>

are entirely different. The <A HREF="#ONERR">ONERR</A> block will not

be executed if there was no error, and it is assumed to either handle the

error or call <A HREF="#PASS">PASS</A>. The error is cleared, so if

<A HREF="#PASS">PASS</A> is not called, the execution continues

normally after the <A HREF="#ENDTRY">ENDTRY</A> statement.

<BR><BR>

<A HREF="#FINALLY">FINALLY</A>, on the other hand, is not implemented

to handle errors, but instead to create a block of code which will always be

executed, regardless of whether there was an error or not. It does not clear

the error (or more precisely, <A HREF="#ENDFINAL">ENDFINAL</A> throws

it again). This can be used in a function which allocates memory, destroys

the contents of the screen, or does something else which always needs cleaning up.

If the function throws an error in a protected block, the memory should

always be freed again, the screen should be restored, etc. But the error

should not be handled at the same time; instead, it must be handled on a

higher level (often even in the calling function).

<BR><BR>

The usage of <A HREF="#ONERR">ONERR</A> is illustrated in the following example:</P>

<PRE>TRY

  // <I>&lt;protected code&gt;</I>

ONERR

  if (errCode == <I>some_specific_code</I>)

    // <I>&lt;error handler&gt;</I>

  else

    // <I>pass on any unhandled errors to a higher level</I>

    PASS;

ENDTRY

</PRE>

<P>The usage of <A HREF="#FINALLY">FINALLY</A> is illustrated in the following example:</P>

<PRE>TRY

  ...

  // <I>&lt;allocate memory&gt;</I>

  TRY

    // <I>&lt;protected code&gt;</I>

  FINALLY

    // <I>&lt;free the allocated memory&gt;</I>

  ENDFINAL

  ...

ONERR

  // <I>&lt;error handler&gt;</I>

ENDTRY

</PRE>

<P>The variable <A HREF="#errCode">errCode</A> is automatically created in the error handler, and

it contains the error number to allow the program to check what caused the error. This variable

will be destroyed after the <A HREF="#ENDTRY">ENDTRY</A>/<A HREF="#ENDFINAL">ENDFINAL</A> statement.

<BR><BR>

It is important to say that you must not exit the protected block using

<A HREF="keywords.html#goto">goto</A> or <A HREF="keywords.html#return">return</A> statements, else the error frame will not

be removed, so the further behavior of the program will be unpredictable.

If you really want to exit from the protected block before its natural end

(i.e. before the <A HREF="#ONERR">ONERR</A> or <A HREF="#FINALLY">FINALLY</A> statement),

call <A HREF="#ER_success">ER_success</A> explicitely to remove the error frame

before exiting, i.e. do something like</P>

<PRE>TRY

  ...

  if (<I>I_really_must_exit_from_here</I>)

  {

    ER_success ();

    return;

  }

  ...

ONERR

  ...

ENDTRY

</PRE>

<P>But in general this is a very bad practice and should be avoided even if it

requires some extra code. For example, you can rewrite the code like this:</P>

<PRE>TRY

  ...

  if (!<I>I_really_must_exit_from_here</I>)

  {

    ...

  }

ONERR

  ...

ENDTRY

if (<I>I_really_must_exit_from_here</I>)

  return;

</PRE>

<P>There is also another possible caveat related to error handling. The TRY macro (or

<A HREF="#ER_catch">ER_catch</A>, more precisely) saves many of

the registers on its execution context stack, since <A HREF="#ER_catch">ER_catch</A> needs to

simulate a return identical to the return of any normal function. Consequently, when an error is thrown, all

variables which reside in registers are reset to their contents before the TRY macro was

called. If code in an <A HREF="#ONERR">ONERR</A> or <A HREF="#FINALLY">FINALLY</A>

block needs the value of a variable set in the TRY block, the code must arrange to make sure

the C code optimizer does not put that variable in a register. This can be

accomplished by declaring such variables to be <A HREF="keywords.html#volatile">volatile</A>.

So, remember this rule: Variables changed in a TRY block must be declared volatile if they

are referenced in an <A HREF="#ONERR">ONERR</A> or <A HREF="#FINALLY">FINALLY</A> block!

<BR><BR>

If you want to protect the whole program, passing all unhandled errors to the operating system,

you can define <CODE>ENABLE_ERROR_RETURN</CODE> instead of using a

TRY...<A HREF="#ONERR">ONERR</A>...<A HREF="#ENDTRY">ENDTRY</A> block.

See the section <A HREF="htretval.html#reterr">Returning Errors</A>

for more information.</P>



<HR>

<H3><A NAME="ER_catch"><U>ER_catch</U></A></H3>

<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#short">short</A></B> ER_catch (<B><A HREF="keywords.html#void">void</A></B> *ErrorFrame);</TD></TR></TABLE></P>

<P><B>Catches an error.</B></P>



<P>ER_catch sets up an error handler. It saves the task state in

<I>ErrorFrame</I>, which is usually a buffer

of type <A HREF="#ERROR_FRAME">ERROR_FRAME</A>, and returns 0. The state consists of the values of A2-A7,

D3-D7, and PC. It also records a pointer to the previously saved state, which

makes it a linked list/stack, and yet another two system pointers.

<BR><BR>

If <A HREF="#ER_throwVar">ER_throwVar</A> is called later on (note that some TIOS routines may perform

<A HREF="#ER_throwVar">ER_throwVar</A> in a case of error), it simulates a return from the

previously called ER_catch, and the error code passed into <A HREF="#ER_throwVar">ER_throwVar</A>

will become the result of ER_catch. The processor must be in User mode for this

to work properly.

<BR><BR>

<B>Note:</B> Usually you should not call

this function explicitely. Use the <A HREF="#TRY">TRY</A> macro instead.</P>



<P>See also: <A HREF="#TRY">TRY</A>, <A HREF="#ONERR">ONERR</A>, <A HREF="#ENDTRY">ENDTRY</A>, <A HREF="#FINALLY">FINALLY</A>, <A HREF="#ENDFINAL">ENDFINAL</A>, <A HREF="#ER_throwVar">ER_throwVar</A>, <A HREF="#ER_throw">ER_throw</A>, <A HREF="#ER_success">ER_success</A></P>

<HR>

<H3><A NAME="ER_success"><U>ER_success</U></A></H3>

<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#void">void</A></B> ER_success (<B><A HREF="keywords.html#void">void</A></B>);</TD></TR></TABLE></P>

<P><B>Pops the state from the error stack.</B></P>



<P>ER_success pops the state previously saved by <A HREF="#ER_catch">ER_catch</A> off the stack,

i.e. removes the error frame from the linked list. You usually will not call this function

explicitely: the macro <A HREF="#ONERR">ONERR</A> will do this for you.</P>



<HR>

<H3><A NAME="ER_throw"><U>ER_throw</U></A></H3>

<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#void">void</A></B> ER_throw (<B><A HREF="keywords.html#short">short</A></B> err_no);</TD></TR></TABLE></P>

<P><B>Throws an error with a constant number.</B></P>



<P>ER_throw works like <A HREF="#ER_throwVar">ER_throwVar</A>, but it

produces much shorter code (only 2 bytes). This is done through the Line 1010

(A-Line) emulator, which emulates an assembly opcode for each error number.

As a consequence, <I>err_no</I> must be constant.</P>



<P>See also: <A HREF="#ER_throwVar">ER_throwVar</A>, <A HREF="#ErrorCodes">ErrorCodes</A></P>

<HR>

<H3><A NAME="ER_throwVar"><U>ER_throwVar</U></A></H3>

<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#void">void</A></B> ER_throwVar (<B><A HREF="keywords.html#short">short</A></B> err_no);</TD></TR></TABLE></P>

<P><B>Throws an error.</B></P>



<P>ER_throwVar restores the state previously saved by <A HREF="#ER_catch">ER_catch</A>.

It then returns in such a way that <A HREF="#ER_catch">ER_catch</A> appears to have

returned with the value <I>err_no</I>.

See the TI-Basic manual for a meaning of the various error codes. ER_throwVar

should not be called with a value 0 as <I>err_no</I>. Think of ER_throwVar as a long

jump rather than a subroutine call. Execution does not return from the ER_throwVar call.

<BR><BR>

<B>Note:</B> If you want to use ER_throwVar to bail out to the TIOS from an arbitrary

place, you need to define <CODE>ENABLE_ERROR_RETURN</CODE>.

See the section <A HREF="htretval.html#reterr">Returning Errors</A>

for more information.</P>



<P>See also: <A HREF="#ER_throw">ER_throw</A>, <A HREF="#ErrorCodes">ErrorCodes</A>, <A HREF="#PASS">PASS</A></P>

<HR>

<H3><A NAME="ERD_dialog"><U>ERD_dialog</U></A></H3>

<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#short">short</A></B> ERD_dialog (<B><A HREF="keywords.html#short">short</A></B> err_no, <B><A HREF="keywords.html#short">short</A></B> prog_flag);</TD></TR></TABLE></P>

<P><B>Displays an error dialog box.</B></P>



<P>ERD_dialog displays an error dialog box with a message corresponding to the

error code <I>err_no</I>. See the TI manual for a meaning of the various

error codes. ERD_dialog returns <A HREF="alloc.html#Bool">TRUE</A> or

<A HREF="alloc.html#Bool">FALSE</A>, depending of whether the user

exits the dialog box by pressing ENTER or ESC key. This routine may cause

heap compression.

<BR><BR>

<I>prog_flag</I> is a flag which may be <A HREF="alloc.html#Bool">FALSE</A> or

<A HREF="alloc.html#Bool">TRUE</A>. Normally, it needs to be <A HREF="alloc.html#Bool">FALSE</A>,

but when it is <A HREF="alloc.html#Bool">TRUE</A>, in addition to the standard button

whith message "Esc=CANCEL", another button with message "Enter=GOTO" will be

added in the error dialog box. This is mostly useless, but

error dialog boxes have this option (TIOS uses this when you break a BASIC program).

Note, however, that pressing Enter will not perform the actual transfer to the program

editor.</P>



<HR>

<H3><A NAME="ERD_dismissNotice"><U>ERD_dismissNotice</U></A></H3>

<P><A HREF="httigcc.html#minams">AMS 2.00 or higher</A></P>

<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#void">void</A></B> ERD_dismissNotice (<B><A HREF="keywords.html#void">void</A></B>);</TD></TR></TABLE></P>

<P><B>Removes the error notice displayed by a prior call to <A HREF="#ERD_notice">ERD_notice</A>.</B></P>



<P>This function causes the screen to be repainted, because it calls

<A HREF="wingraph.html#WinClose">WinClose</A>.<BR>

<B>CAUTION:</B> calling this function without a prior call to

<A HREF="#ERD_notice">ERD_notice</A>, or calling ERD_dismissNotice twice,

can leave the calculator in an unstable state !</P>



<HR>

<H3><A NAME="ERD_notice"><U>ERD_notice</U></A></H3>

<P><A HREF="httigcc.html#minams">AMS 2.00 or higher</A></P>

<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#short">short</A></B> ERD_notice (<B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#int">char</A></B> <B><A HREF="keywords.html#const">const</A></B> *title, <B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#int">char</A></B> <B><A HREF="keywords.html#const">const</A></B> *message);</TD></TR></TABLE></P>

<P><B>Displays an error notice.</B></P>



<P>ERD_notice displays a dialog-looking window with title <I>title</I>, message <I>message</I>

(word-wrapped if necessary), without buttons, that will stay on the screen until

<A HREF="#ERD_dismissNotice">ERD_dismissNotice</A> is called.<BR>

ERD_notice returns TRUE if the window was actually displayed, FALSE otherwise.<BR>

ERD_notice <B>must</B> be paired correctly with <A HREF="#ERD_dismissNotice">ERD_dismissNotice</A>.</P>



<HR>

<H3><A NAME="ERD_process"><U>ERD_process</U></A></H3>

<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#void">void</A></B> ERD_process (<B><A HREF="keywords.html#short">short</A></B> err_no);</TD></TR></TABLE></P>

<P><B>Processes an error.</B></P>



<P>ERD_process processes the error with error code <I>err_no</I> by calling

<A HREF="#ERD_dialog">ERD_dialog</A> appropriately. Button "Enter=GOTO" will

be displayed only if the routine concludes from some system flags that the

routine is called from the TI-Basic interpreter (which will not be the case

if you called it from a C or ASM program). Then, ERD_process responds by

starting the appropriate application (for example the text editor if the TI-Basic

interpreter was active and if the user pressed the button "Enter=GOTO").

Principally, there is no difference between ERD_process and

<A HREF="#ERD_dialog">ERD_dialog</A>, except in event-driven applications

(see the <A HREF="events.html">events.h</A> header file).</P>



<HR>

<H3><A NAME="find_error_message"><U>find_error_message</U></A></H3>

<P><A HREF="httigcc.html#minams">AMS 1.01 or higher</A></P>

<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#const">const</A></B> <B><A HREF="keywords.html#int">char</A></B> *find_error_message (<B><A HREF="keywords.html#short">short</A></B> err_no);</TD></TR></TABLE></P>

<P><B>Returns a TI-Basic error message string.</B></P>



<P>find_error_message returns a pointer to the text of the TI-Basic error message string

with the code <I>err_no</I>. See the TI-Basic manual for a list of various error codes. If

<I>err_no</I> is not a valid error code, the routine returns a pointer to the string

"Unknown ERROR code", or its localized version if a language localization is active (on 

AMS 2.xx).

<BR><BR>

find_error_message may return <A HREF="alloc.html#NULL">NULL</A>.</P>



<HR>

<H3><A NAME="errCode"><U>errCode</U></A></H3>

<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">short</A></B> errCode;</TD></TR></TABLE></P>

<P><B>Contains the error number in a TRY...ONERR...ENDTRY block.</B></P>



<P>errCode is an automatic (local) variable which is automatically created in the error handler, and it

contains the error number to allow the program to check what caused the error. This variable

is automatically destroyed after <A HREF="#ENDTRY">ENDTRY</A> statement, i.e. after execution

of the error handler. Variable errCode, because it is local to the <A HREF="#ONERR">ONERR</A>

block, cannot be referenced outside the <A HREF="#ONERR">ONERR</A> block.</P>



<P>See also: <A HREF="#ErrorCodes">ErrorCodes</A></P>

<HR>

<H3><A NAME="ERROR_FRAME"><U>ERROR_FRAME</U></A></H3>

<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#typedef">typedef</A></B> <B><A HREF="keywords.html#struct">struct</A></B> ErrorFrameStruct {

<TABLE><TR><TD WIDTH="12"></TD><TD CLASS="CODE">

<B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">long</A></B> A2, A3, A4, A5, A6, A7;<BR>

<B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">long</A></B> D3, D4, D5, D6, D7;<BR>

<B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">long</A></B> NG_control;<BR>

<B><A HREF="keywords.html#int">char</A></B> *RetIndex;<BR>

<B><A HREF="keywords.html#short">unsigned</A></B> <B><A HREF="keywords.html#short">long</A></B> PC;<BR>

<B><A HREF="keywords.html#struct">struct</A></B> ErrorFrameStruct *Link;<BR>

</TD></TR></TABLE>

} ERROR_FRAME [1];</TD></TR></TABLE></P>

<P><B>A type designed for capturing a task state.</B></P>



<P>ERROR_FRAME is a type designed for capturing a task state needed for

catching errors using the <A HREF="#ER_catch">ER_catch</A> command.</P>



<HR>

<H3><A NAME="ErrorCodes"><U>ErrorCodes</U></A></H3>

<P><TABLE BORDER="1" CELLPADDING="2"><TR><TD CLASS="CODE"><B><A HREF="keywords.html#enum">enum</A></B> ErrorCodes {ER_OK = 0, ER_OKAY = 0, ER_EXIT = 1, ER_STOP = 2, ER_OFF = 3, ER_PRGM_STOP = 4, ER_NO_MSG = 9, ER_FUNC_DID_NOT_RETURN_VALUE = 10, ER_TEST_NOT_TRUE_OR_FALSE = 20, ER_ARG_CANNOT_BE_FOLDER = 30, ER_ARGUMENT = 40, ER_ARG_MISMATCH = 50, ER_EXPECTED_BOOL_OR_AGG = 60, ER_ARG_MUST_BE_DECIMAL = 70, ER_ARG_MUST_BE_LABEL = 80, ER_ARGUMENT_MUST_BE_LIST = 90, ER_ARG_MUST_BE_MATRIX = 100, ER_ARG_MUST_BE_PIC = 110, ER_ARG_MUST_BE_PIC_OR_STR = 120, ER_ARG_MUST_BE_STRING = 130, ER_EXPECTED_VAR = 140, ER_ARG_MUST_BE_EMPTY_FOLDER = 150, ER_EXPECTED_ALGEBRAIC = 160, ER_ASAP_TOO_LONG = 161, ER_ATTRIBUTE_NOT_FOUND = 163, ER_BATT_LOW = 165, ER_BOUND = 170, ER_BREAK = 180, ER_CHECKSUM = 185, ER_CIRCULAR_DEFINITION = 190, ER_INVALID_SUCH_THAT = 200, ER_DATATYPE = 210, ER_DEPENDENT_LIMIT = 220, ER_DIFF_EQ_SETUP = 225, ER_DIMENSION = 230, ER_NOT_ENOUGH_ELEMENTS = 230, ER_NON_CONFORMING_LISTS = 240, ER_DIVBY0 = 250, ER_DOMAIN = 260, ER_DUPLICATE_VAR_NAME = 270, ER_ELSEIF_WITHOUT_IF = 280, ER_ELSE_WITHOUT_IF = 280, ER_ENDTRY_WITHOUT_ELSE = 290, ER_EXCESSIVE_ITERATION = 295, ER_EXPECTED_2OR3_ELEMENTS = 300, ER_EXPIRED = 305, ER_APP_EXT_NOT_FOUND = 307, ER_APP_NOT_FOUND = 308, ER_INVALID_NSOLVE_ARG1 = 310, ER_INVALID_SOLVE_ARG1 = 320, ER_FOLDER = 330, ER_FUNCS_IN_DIFF_EQ = 335, ER_INCONSISTENT_UNITS = 345, ER_INVALID_SUBSCRIPT = 350, ER_INVALID_INDIR_STRING = 360, ER_INDIR_STRING_NOT_VARNAME = 360, ER_INDIR_STRING_NOT_FUNNAME = 360, ER_INVALID_ANS = 380, ER_ILLEGAL_ASSIGNMENT = 390, ER_ILLEGAL_ASSIGNMENT_VALUE = 400, ER_INVALID_AXES = 405, ER_ILLEGAL_COMMAND = 410, ER_INVALID_FOLDER_NAME = 420, ER_GRAPH_MODE = 430, ER_INVALID_GUESS = 435, ER_INVALID_IMPLIED_MULT = 440, ER_ILLEGAL_IN_FUNC = 450, ER_ILLEGAL_IN_CUSTOM = 460, ER_ILLEGAL_IN_DIALOG = 470, ER_ILLEGAL_IN_TOOLBAR = 480, ER_CANNOT_EXIT_FROM_TRY = 490, ER_CANNOT_CYCLE_FROM_TRY = 490, ER_CANNOT_GOTO_FROM_TRY = 490, ER_CANNOT_GOTO_INTO_TRY = 490, ER_INVALID_LABEL = 500, ER_INVALID_LIST_OR_MATRIX = 510, ER_INVAL_OUTSIDE_TB_CM = 520, ER_INVAL_OUTSIDE_DG_TB_CM = 530, ER_INVALID_OUTSIDE_DIALOG = 540, ER_MUST_BE_IN_PRGM_OR_FUNC = 550, ER_CYCLE_NOT_IN_LOOP = 560, ER_EXIT_NOT_IN_LOOP = 560, ER_INVALID_PATHNAME = 570, ER_INVALID_POLAR_COMPLEX = 575, ER_ILLEGAL_PRGM_REF = 580, ER_INVALID_SYNTAX_BLOCK = 590, ER_INVALID_TABLE = 600, ER_INVALID_USE_OF_UNITS = 605, ER_INVALID_LOCAL_DECLARATION = 610, ER_EXPECTED_VAR_OR_FUNC = 620, ER_INVALID_VAR_REF = 630, ER_INVALID_VECTOR_SYNTAX = 640, ER_LINK_IO = 650, ER_MAT_NOT_DIAGONALIZABLE = 665, ER_MEMORY = 670, ER_MEMORY_EXHAUSTION = 670, ER_ESTACK_OVERFLOW = 670, ER_STACK_VIO = 673, ER_EXPECTED_LPAR = 680, ER_EXPECTED_RPAR = 690, ER_EXPECTED_DOUBLE_QUOTE = 700, ER_EXPECTED_RIGHT_BRACKET = 710, ER_EXPECTED_RIGHT_BRACE = 720, ER_INVALID_BLOCK_STRUCTURE = 730, ER_MISSING_THEN = 740, ER_NOT_FUNC_OR_PRGM = 750, ER_NO_FUNCS_SEL = 765, ER_NO_SOLUTION = 780, ER_NON_ALGEBRAIC_VARIABLE = 790, ER_UNREAL_RESULT = 800, ER_EXPECTED_REAL = 800, ER_MEMORY_DML = 810, ER_RATIONAL_NUMERIC_OVERFLOW = 830, ER_OVERFLOW = 830, ER_STAT_PLOT = 840, ER_PRGM_NOT_FOUND = 850, ER_RECURSION_TOO_DEEP = 860, ER_RESERVED = 870, ER_SYS_FUNC = 870, ER_ROM_ROUTINE_NOT_AVAILABLE = 875, ER_SEQUENCE_SETUP = 880, ER_SIGNATURE_ERR = 885, ER_SINGULARMAT = 890, ER_SLOPE_FIELD_FUNCS = 895, ER_WEIGHTS_SUM_NOT_POS = 900, ER_LISTS_CONTAIN_NEG = 900, ER_LISTS_NOT2DISCREET = 900, ER_EMPTY_GROUP_NOT_VALID = 900, ER_SYNTAX = 910, ER_UNEXPECTED_CHARACTER = 910, ER_EXPECTED_EQUAL = 910, ER_EXPECTED_FACTOR = 910, ER_TOO_FEW_ARGS = 930, ER_TOO_MANY_ARGS = 940, ER_TOO_MANY_SUBSCRIPTS = 950, ER_TOO_MANY_UNDEFINED = 955, ER_UNDEFINED_VAR = 960, ER_UNLICENSED = 965, ER_GRAPH_FUNC_IN_USE = 970, ER_PROG_OR_FUNC_IN_USE = 970, ER_VAR_IN_USE = 970, ER_LOCKED = 980, ER_PROTECTED = 980, ER_NAME_TOO_LONG = 990, ER_RANGE = 1000, ER_ZOOM = 1010, ER_ILLEGAL_TAG = 1020, ER_UNKNOWN_TAG = 1020, ER_DIVISION_BUG = 1020, ER_MEM_VIO = 1030, ER_FP_TEST_FAIL = 4094, EXPECTED_BOOL_OR_AGG_ERROR = 60, EXPECTED_VAR_ERROR = 140, EXPECTED_ALGEBRAIC_ERROR = 160, INVALID_SUCH_THAT_ERROR = 200, NON_CONFORMING_LISTS_ERROR = 240, EXPECTED_2OR3_ELEMENTS_ERROR = 300, INVALID_NSOLVE_ARG1_ERROR = 310, INVALID_SOLVE_ARG1_ERROR = 320, INVALID_PATHNAME_ERROR = 570, EXPECTED_VAR_OR_FUNC_ERROR = 620, MEMORY_EXHAUSTION_ERROR = 670, ESTACK_OVERFLOW_ERROR = 670, EXPECTED_LPAR_ERROR = 680, EXPECTED_RPAR_ERROR = 690, EXPECTED_DOUBLE_QUOTE_ERROR = 700, EXPECTED_RIGHT_BRACKET_ERROR = 710, EXPECTED_RIGHT_BRACE_ERROR = 720, UNREAL_RESULT_ERROR = 800, EXPECTED_REAL_ERROR = 800, RATIONAL_NUMERIC_OVERFLOW_ERROR = 830, RECURSION_TOO_DEEP_ERROR = 860, SYNTAX_ERROR = 910, UNEXPECTED_CHARACTER_ERROR = 910, EXPECTED_EQUAL_ERROR = 910, EXPECTED_FACTOR_ERROR = 910, TOO_FEW_ARGS_ERROR = 930, TOO_MANY_ARGS_ERROR = 940, TOO_MANY_SUBSCRIPTS_ERROR = 950, TOO_MANY_UNDEFINED_ERROR = 955, GRAPH_FUNC_IN_USE_ERROR = 970, NAME_TOO_LONG_ERROR = 990, ILLEGAL_TAG_ERROR = 1020, UNKNOWN_TAG_ERROR = 1020, DIVISION_BUG_ERROR = 1020};</TD></TR></TABLE></P>

<P><B>An enumeration containing all error codes.</B></P>



<P>This enumeration contains all error codes used by the TIOS. Error names not

starting with <CODE>'ER_'</CODE> are deprecated and introduced only for

compatibility. All of these errors can be

<A HREF="htretval.html#reterr">passed on to the operating system</A>.

You can use your own numbers for errors which you handle in your program, if

you want to use the error-handling system to write more stable programs.</P>



<P>See also: <A HREF="#ER_throw">ER_throw</A>, <A HREF="#ER_throwVar">ER_throwVar</A>, <A HREF="#errCode">errCode</A></P>

<HR>

<H3><A HREF="index.html">Return to the main index</A></H3>

</BODY>

</HTML>