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 and Macros
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.
Error Manager Data Structures
ErrExceptionType Struct
Purpose
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.
Prototype
typedef struct ErrExceptionType { struct ErrExceptionType *nextP; ErrJumpBuf state; Int32 err; } ErrExceptionType;
typedef ErrExceptionType *ErrExceptionPtr;
Fields
-
nextP - Next
ErrExceptionTypestructure in the linked list. -
state - Storage for setjmp/longjmp.
-
err - Error code.
Error Manager Functions and Macros
ErrAlert Macro
Purpose
Displays an alert dialog for runtime errors.
Declared In
ErrorBase.h Prototype
#define ErrAlert ( err )
Parameters
Returns
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 Macro
Purpose
Marks the end of an ErrTry() block and the beginning of an ErrCatch block.
Declared In
ErrorBase.h Prototype
#define 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 thisErrCatchblock.
Returns
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 Macro
Purpose
Displays an error alert if error checking is set to partial or full.
Declared In
ErrorMgr.h Prototype
#define ErrDisplay ( msg )
Parameters
Returns
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 Function
Purpose
Display a dialog with an error message. Do not allow the user to exit the dialog or continue.
Declared In
ErrorBase.h 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.
Returns
Comments
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 Macro
Purpose
Marks the end of an ErrCatch() block.
Declared In
ErrorBase.h Prototype
#define ErrEndCatch
Parameters
Returns
Comments
ErrEndCatch can only be used in conjunction with ErrTry() and ErrCatch. See the comments under ErrTry for usage instructions.
ErrExceptionList Function
Purpose
Return the address of the pointer to the first ErrExceptionType structure in the linked list of exception structures.
Declared In
ErrorBase.h Prototype
MemPtr *ErrExceptionList ( void )
Parameters
Returns
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 Macro
Purpose
Displays an error alert dialog if condition is true and error checking is set to partial or full.
Declared In
ErrorMgr.h Prototype
#define ErrFatalDisplayIf ( condition, msg )
Parameters
Returns
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 Macro
Purpose
Displays an error alert dialog if condition is true and error checking is set to full.
Declared In
ErrorMgr.h Prototype
#define ErrNonFatalDisplayIf ( condition, msg )
Parameters
Returns
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 Function
Purpose
Cause a jump to the nearest Catch block.
Declared In
ErrorBase.h Prototype
void ErrThrow ( Int32 err )
Parameters
Returns
Comments
Use the macros ErrTry, ErrCatch, and ErrEndCatch in conjunction with this function.
See Also
ErrFatalDisplayIf(), ErrNonFatalDisplayIf(), ErrDisplay()
ErrTry Macro
Purpose
Marks the beginning of a try/catch block.
Declared In
ErrorBase.h Prototype
#define ErrTry
Parameters
Returns
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