Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

32    Error Manager

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

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

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

ErrExceptionType Struct ^TOP^

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 ErrExceptionType structure in the linked list.
state
Storage for setjmp/longjmp.
err
Error code.

Error Manager Functions and Macros ^TOP^

ErrAlert Macro ^TOP^

Purpose

Displays an alert dialog for runtime errors.

Declared In

ErrorBase.h

Prototype

#define ErrAlert (
   err
)

Parameters

err
An error code (as type Err).

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

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 this ErrCatch block.

Returns

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 Macro ^TOP^

Purpose

Displays an error alert if error checking is set to partial or full.

Declared In

ErrorMgr.h

Prototype

#define ErrDisplay (
   msg
)

Parameters

msg
Error message text as a string.

Returns

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 Function ^TOP^

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(
   constChar*constfilename,
   UInt16lineNo,
   constChar*constmsg
)

Parameters

filename
Source code filename.
lineno
Line number in the source code file.
msg
Message to display.

Returns

Never 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 ^TOP^

Purpose

Marks the end of an ErrCatch() block.

Declared In

ErrorBase.h

Prototype

#define ErrEndCatch

Parameters

None.

Returns

Returns nothing.

Comments

ErrEndCatch can only be used in conjunction with ErrTry() and ErrCatch. See the comments under ErrTry for usage instructions.

ErrExceptionList Function ^TOP^

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

None.

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

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

condition
A boolean value. If true, display the error.
msg
Error message text as a string.

Returns

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 Macro ^TOP^

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

condition
A boolean value. If true, display the error.
msg
Error message text as a string.

Returns

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 Function ^TOP^

Purpose

Cause a jump to the nearest Catch block.

Declared In

ErrorBase.h

Prototype

void ErrThrow (
   Int32err
)

Parameters

err
Error code.

Returns

Never returns.

Comments

Use the macros ErrTry, ErrCatch, and ErrEndCatch in conjunction with this function.

See Also

ErrFatalDisplayIf(), ErrNonFatalDisplayIf(), ErrDisplay()

ErrTry Macro ^TOP^

Purpose

Marks the beginning of a try/catch block.

Declared In

ErrorBase.h

Prototype

#define ErrTry

Parameters

None.

Returns

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