/error.html
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 <error.h> 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 <tigcclib.h> // 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><protected code></I>
- ONERR
- if (errCode == <I>some_specific_code</I>)
- // <I><error handler></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><allocate memory></I>
- TRY
- // <I><protected code></I>
- FINALLY
- // <I><free the allocated memory></I>
- ENDFINAL
- ...
- ONERR
- // <I><error handler></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>