28 Error Manager

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 Functions
  

For more information on the error manager, see the chapter "Debugging Strategies" in the Palm OS Programmer's Companion.

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

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 nonexitable dialog with an error message. Do not allow the user to 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

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