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