< Home < Developers < Development Support < Documentation

## 29 Error Manager

Table of Contents | < Previous | Next > | Index

| Title - Palm OS® Programmer's API Reference Part II: System Management 29 Error Manager ERROR_CHECK_LEVEL Define Error Manager Data Structures ErrExceptionType Error Manager Functions ErrAlert ErrCatch ErrDisplay ErrDisplayFileLineMsg ErrEndCatch ErrExceptionList ErrFatalDisplayIf ErrNonFatalDisplayIf ErrThrow ErrTry |  |  |  | This chapter provides reference material for the error manager. The error manager API is declared in the header files ErrorMgr.h and ErrorBase.h. This chapter covers: ERROR_CHECK_LEVEL Define Error Manager Data Structures Error Manager Functions For more information on the error manager, see the chapter "Debugging Strategies" in the Palm OS Programmer's Companion, vol. I. ## ERROR_CHECK_LEVEL Define The error manager uses the compiler define ERROR_CHECK_LEVEL to control the level of error messages displayed. You can set the value of the compiler define to control which level of error checking and display is compiled into the application. Three levels of error checking are supported: none, partial, and full. #####
If you set ERR_CHECK_LEVEL to... | The compiler...
--- | ---
ERROR_CHECK_NONE (0) | Doesn't compile in any error calls.
ERROR_CHECK_PARTIAL (1) | Compiles in only ErrDisplay and ErrFatalDisplayIf calls.
ERROR_CHECK_FULL (2) | Compiles in all three calls.
## Error Manager Data Structures ## ErrExceptionType An ErrExceptionType structure is created for each ErrTry and ErrCatch block. At any point in the program, there is a linked list of these structures. An ErrExceptionType structure stores information about the state of the machine (register values) at the start of the ErrTry block.
    typedef struct ErrExceptionType {
      struct ErrExceptionType *nextP;
      ErrJumpBuf state;
      Int32 err;
    } ErrExceptionType;
    typedef ErrExceptionType *ErrExceptionPtr;
#### Field Descriptions #####
nextP | Next ErrExceptionType structure in the linked list.
state | Storage for setjmp/longjmp.
err | Error code.
## Error Manager Functions ## ErrAlert #### Purpose Macro that displays an alert dialog for runtime errors. #### Prototype ErrAlert (err) #### Parameters #####
-> err | An error code (as type Err).
#### Result Returns 0, which indicates that the OK button has been clicked to dismiss the dialog. #### Comments This macro is intended for use by applications that are likely to receive runtime errors when the application itself is not at fault. For example, a networking application might use it to display an alert if the remote server cannot be found. The error message displayed on the dialog is stored in a 'tSTL' resource. A 'tSTL' resource contains a list of strings that can be looked up by index. The err parameter is used as the index into this list. To use application-defined error codes in ErrAlert, make sure that all of your error codes are greater than or equal to appErrorClass. This way, the error manager looks up the code in the application's 'tSTL' resource number 0. All other error codes are taken from 'tSTL' resource stored in the system. #### Compatibility Implemented only if 3.2 New Feature Set is present. ## ErrCatch #### Purpose Macro that marks the end of an ErrTry block and the beginning of an ErrCatch block. #### Prototype ErrCatch (theErr) #### Parameters #####
-> theErr | An exception code identifying the reason for the failure. This is the value supplied to the ErrThrow call that caused the jump to this ErrCatch block.
#### Result Returns nothing. #### Comments ErrCatch can only be used in conjunction with ErrTry and ErrEndCatch. See the comments under ErrTry for usage instructions. ErrTry, ErrCatch and ErrThrow are based on setjmp and longjmp. At the beginning of an ErrTry block, setjmp saves the machine registers. ErrThrow calls longjmp, which restores the registers and jumps to the beginning of the ErrCatch block. Therefore, any changes in the ErrTry block to variables stored in registers aren't retained when entering the ErrCatch block. The solution is to declare variables that you want to use in both the ErrTry and ErrCatch blocks as "volatile". For example:
    volatile long x = 1;  // Declare volatile local variable
    ErrTry {
       x = 100;    // Set local variable in Try
       ErrThrow(-1);
    }
    ErrCatch(inErr) {
       if (x > 1) {    // Use local variable in Catch
          SysBeep(1);
       }
    } ErrEndCatch
If you have many local variables after the ErrCatch you may want to put the ErrTry and ErrCatch in a separate enclosing function. ## ErrDisplay #### Purpose Macro that displays an error alert if error checking is set to partial or full. #### Prototype ErrDisplay (msg) #### Parameters #####
-> msg | Error message text as a string.
#### Result No return value. #### Comments Call this macro to display an error message, source code filename, and line number. This macro is compiled into the code only if the compiler define ERROR_CHECK_LEVEL is set to 1 or 2 (ERROR_CHECK_PARTIAL or ERROR_CHECK_FULL). #### See Also ErrFatalDisplayIf, ErrNonFatalDisplayIf ## ErrDisplayFileLineMsg #### Purpose Display a dialog with an error message. Do not allow the user to exit the dialog or continue. #### Prototype void ErrDisplayFileLineMsg (const Char *const filename, UInt16 lineNo, const Char *const msg) #### Parameters #####
-> filename | Source code filename.
#####
-> lineno | Line number in the source code file.
#####
-> msg | Message to display.
#### Result Never returns. #### Comment Called by ErrFatalDisplayIf and ErrNonFatalDisplayIf. This function is useful when the application is already on the device and being tested by users. On Japanese systems, the system displays a generic message indicating that an error has occurred instead of displaying the English message. #### See Also ErrFatalDisplayIf, ErrNonFatalDisplayIf, ErrDisplay ## ErrEndCatch #### Purpose Macro that marks the end of an ErrCatch block. #### Prototype ErrEndCatch #### Parameters #####
None.
#### Result Returns nothing. #### Comments ErrEndCatch can only be used in conjunction with ErrTry and ErrCatch. See the comments under ErrTry for usage instructions. ## ErrExceptionList #### Purpose Return the address of the pointer to the first ErrExceptionType structure in the linked list of exception structures. #### Prototype MemPtr *ErrExceptionList (void) #### Parameters #####
None.
#### Result Returns the address of the pointer to the first ErrExceptionType structure linked into the exception list. #### Comments This function is used by the ErrTry and ErrCatch macros as well as the ErrThrow function in order to find the exception list. When called from an application, this routine returns the application's exception list. ## ErrFatalDisplayIf #### Purpose Macro that displays an error alert dialog if condition is true and error checking is set to partial or full. #### Prototype ErrFatalDisplayIf (condition, msg) #### Parameters #####
-> condition | A boolean value. If true, display the error.
#####
-> msg | Error message text as a string.
#### Result No return value. #### Comments Call this macro to display a fatal error message, source code filename, and line number. The alert is displayed only if condition is true. The dialog is cleared only when the user resets the system by responding to the dialog. This macro is compiled into the code if the compiler define ERROR_CHECK_LEVEL is set to 1 or 2 (ERROR_CHECK_PARTIAL or ERROR_CHECK_FULL). #### See Also ErrNonFatalDisplayIf, ErrDisplay, ## ErrNonFatalDisplayIf #### Purpose Macro that displays an error alert dialog if condition is true and error checking is set to full. #### Prototype ErrNonFatalDisplayIf (condition, msg) #### Parameters #####
-> condition | A boolean value. If true, display the error.
#####
-> msg | Error message text as a string.
#### Result No return value. #### Comments Call this macro to display a nonfatal error message, source code filename, and line number. The alert is displayed only if condition is true. The alert dialog is cleared when the user selects to continue (or resets the system). This macro is compiled into the code only if the compiler define ERROR_CHECK_LEVEL is set to 2 (ERROR_CHECK_FULL). #### See Also ErrFatalDisplayIf, ErrDisplay ## ErrThrow #### Purpose Cause a jump to the nearest Catch block. #### Prototype void ErrThrow (Int32 err) #### Parameters #####
-> err | Error code.
#### Result Never returns. #### Comments Use the macros ErrTry, ErrCatch, and ErrEndCatch in conjunction with this function. #### See Also ErrFatalDisplayIf, ErrNonFatalDisplayIf, ErrDisplay ## ErrTry #### Purpose Macro that marks the beginning of a try/catch block. #### Prototype ErrTry #### Parameters #####
None.
#### Result Returns nothing. #### Comments An exception raised by a call to ErrThrow-even from within a nested subroutine-causes program execution to switch to the beginning of the ErrCatch block. If the end of the block enclosed by ErrTry is encountered without a call to ErrThrow, execution jumps to the line of code following the ErrEndCatch macro. See "The Try-and-Catch Mechanism" of the Palm OS Programmer's Companion, vol. I for a more thorough description of how this mechanism works. #### Example You must structure your code exactly as shown here. You can't use ErrTry without ErrCatch and ErrEndCatch, or vice versa.
    ErrTry {
       // Do something which may fail. Call ErrThrow to signal
       // failure and force a jump to the following ErrCatch
       // block.
    }
    ErrCatch(inErr) {
       // Recover or cleanup after a failure in the above ErrTry
       // block. "inErr" is an exception code identifying the
       // reason for the failure.

       // Call ErrThrow if you want to jump out to the next
       // ErrCatch block.

       // The code in this block doen't execute if the above
       // ErrTry block completes without a call to ErrThrow.
    } ErrEndCatch