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

23    Error Manager

System Management

Exploring Palm OS®

The Error Manager consists of a set of functions and macros that allow you to conditionally display debugging messages when working with debug ROMs.

ErrorManager Constants
Error Manager Functions and Macros

The header file ErrorMgr.h declares the API that this chapter describes.

For tips on using the Error Manager APIs, see Chapter 13, "Debugging Strategies."

ErrorManager Constants ^TOP^

ErrDlgResultType Enum ^TOP^

Purpose

Possible return types for ErrAlert().

Declared In

Form.h

Constants

errDlgResOK
The user tapped the OK button.
errDlgResCancel
The user tapped the Cancel button.
errDlgResRetry
The user tapped the Retry button.
errDlgResYes
The user tapped the Yes button.
errDlgResNo
The user tapped the No button.

Comments

In Palm OS Cobalt, ErrAlert() only displays an OK button.

Error Manager Functions and Macros ^TOP^

DbgOnlyFatalError Macro ^TOP^

Purpose

Display an error alert dialog if you are not doing a release build. For release builds, this macro does nothing.

Declared In

ErrorMgr.h

Prototype

#define DbgOnlyFatalError (
   errMsg
)

Parameters

errMsg
Error message text as a string.

Returns

Nothing.

Comments

This macro displays a fatal error message, source code filename, and line number in a dialog. The dialog is cleared only when the user resets the system by responding to the dialog.

This macro is compiled into the code only if the BUILD_TYPE compiler define is something other than BUILD_TYPE_RELEASE.

See Also

DbgOnlyFatalErrorIf(), ErrFatalError()

DbgOnlyFatalErrorIf Macro ^TOP^

Purpose

Display an error alert dialog if you are not doing a release build and the specified condition is true.

Declared In

ErrorMgr.h

Prototype

#define DbgOnlyFatalErrorIf (
   condition,
    errMsg
)

Parameters

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

Returns

Nothing.

Comments

This macro displays a fatal error message, source code filename, and line number in a dialog. 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 only if the BUILD_TYPE compiler define is something other than BUILD_TYPE_RELEASE.

See Also

DbgOnlyFatalError(), ErrFatalErrorIf()

ErrAlert Function ^TOP^

Purpose

Displays an alert dialog for runtime errors.

Declared In

Form.h

Prototype

uint16_t ErrAlert (
   DmOpenRef appDbRef,
   status_t errCode
)

Parameters

appDbRef
Open database containing the string list resource.
errCode
An error code. This is used as an index into a string list resource in a database. See Comments for more information.

Returns

Zero, which indicates that the OK button has been clicked to dismiss the dialog.

Comments

This function 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 string list resource. A string list resource contains strings that can be looked up by index. The errCode 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 string list resource number 0. All other error codes are taken from string list resources stored in the system.

See Also

ErrGetErrorMsg()

ErrDisplay Macro ^TOP^

Purpose

Display an error alert.

Declared In

ErrorMgr.h

Prototype

#define ErrDisplay (
   msg
)

Parameters

msg
Error message text as a string.

Returns

Nothing.

Comments

Call this macro to display an error message, source code filename, and line number.

Compatibility

This macro is provided for compatibility with applications ported from earlier releases of Palm OS; new applications are encouraged to use the (currently equivalent) ErrFatalError() macro instead.

ErrDisplayFileLineMsg Macro ^TOP^

Purpose

Display a dialog with an error message. Do not allow the user to exit the dialog or continue.

Declared In

ErrorMgr.h

Prototype

#define ErrDisplayFileLineMsg (
   a,
    b,
    c
)

Parameters

a
Source code filename.
b
Line number in the source code file.
c
Message to display.

Returns

Nothing.

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.

Compatibility

This macro is provided for compatibility with applications ported from earlier releases of Palm OS; new applications are encouraged to directly call the ErrFatalErrorInContext() function instead.

ErrFatalDisplay Macro ^TOP^

Purpose

Display an error alert dialog.

Declared In

ErrorMgr.h

Prototype

#define ErrFatalDisplay (
   msg
)

Parameters

msg
Error message text as a string.

Returns

Nothing.

Comments

Call this macro to display a fatal error message, source code filename, and line number. The dialog is cleared only when the user resets the system by responding to the dialog.

Compatibility

This macro is provided for compatibility with applications ported from earlier releases of Palm OS; new applications are encouraged to use the (currently equivalent) ErrFatalError() macro instead.

ErrFatalDisplayIf Macro ^TOP^

Purpose

Display an error alert dialog if the specified condition is true.

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

Nothing.

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.

Compatibility

This macro is provided for compatibility with applications ported from earlier releases of Palm OS; new applications are encouraged to use the (currently equivalent) ErrFatalErrorIf() macro instead.

ErrFatalError Macro ^TOP^

Purpose

Display an error alert dialog.

Declared In

ErrorMgr.h

Prototype

#define ErrFatalError (
   errMsg
)

Parameters

errMsg
Error message text as a string.

Returns

Nothing.

Comments

Call this macro to display a fatal error message, source code filename, and line number. The dialog is cleared only when the user resets the system by responding to the dialog.

See Also

DbgOnlyFatalError(), ErrFatalErrorIf()

ErrFatalErrorIf Macro ^TOP^

Purpose

Display an error alert dialog if the specified condition is true.

Declared In

ErrorMgr.h

Prototype

#define ErrFatalErrorIf (
   condition,
    errMsg
)

Parameters

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

Returns

Nothing.

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.

See Also

DbgOnlyFatalErrorIf(), ErrFatalError()

ErrFatalErrorInContext Function ^TOP^

Purpose

Display a dialog with an error message. Do not allow the user to exit the dialog or continue.

Declared In

ErrorMgr.h

Prototype

void ErrFatalErrorInContext (
   const char *fileName,
   uint32_t lineNum,
   const char *errMsg
)

Parameters

fileName
Source code filename.
lineNum
Line number in the source code file.
errMsg
Message to display.

Returns

Nothing.

Comments

Called by all of the macros documented in this chapter. 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.

ErrGetErrorMsg Function ^TOP^

Purpose

Looks up the error message for the specified error code.

Declared In

Form.h

Prototype

status_t ErrGetErrorMsg (
   DmOpenRef appDbRef,
   status_t errCode,
   char *errMsgP,
   int32_t errMsgLen
)

Parameters

appDbRef
Open database containing the string list resource.
errCode
An error code. This is used as an index into a string list resource in a database. See Comments for more information.
errMsgP
The error message corresponding to errCode.
errMsgLen
The size in bytes of the errMsgP parameter.

Returns

errNone upon success or one of the following:

sysErrParamErr
Invalid errMsgP or errMsgLen parameter.

Comments

This function is intended to be used under the same circumstances as ErrAlert(). You might use this function if you want to display the error message in a dialog of your own design.

The error message is stored in a string list resource. A string list resource contains strings that can be looked up by index. The errCode parameter is used as the index into this list.

To use application-defined error codes in ErrGetErrorMsg(), make sure that all of your error codes are greater than or equal to appErrorClass. Palm OS looks up application-specific codes in the application's string list resource number 0. All other error codes are taken from string list resources stored in the system.

Example

The following code looks up an error code in the system library's database and displays it in an alert.


DmOpenRef syslibdbP = DmOpenDatabaseByTypeCreator  
   (sysFileTLibrary, sysFileCSystem, dmModeReadOnly); 
int32_t errStringSize = 50; 
 
myErrString = (char *)MemPtrNew(50); 
ErrGetErrorMsg(syslibdbP, memErrNotEnoughSpace, myErrString,  
   errStringSize); 
FrmCustomAlert(myAppdbP, MyAlertResourceID, myErrString,  
   "", ""); 

ErrNonFatalDisplay Macro ^TOP^

Purpose

Display an error alert dialog if you are not doing a release build. For release builds, this macro does nothing.

Declared In

ErrorMgr.h

Prototype

#define ErrNonFatalDisplay (
   msg
)

Parameters

msg
Error message text as a string.

Returns

Nothing.

Comments

Call this macro to display a nonfatal error message, source code filename, and line number. The alert dialog is cleared when the user selects to continue (or resets the system).

Compatibility

This macro is provided for compatibility with applications ported from earlier releases of Palm OS; new applications are encouraged to use the (currently equivalent) DbgOnlyFatalError() macro instead.

ErrNonFatalDisplayIf Macro ^TOP^

Purpose

Display an error alert dialog if the specified condition is true and you are not doing a release build. For release builds, this macro does nothing.

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

Nothing.

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

Compatibility

This macro is provided for compatibility with applications ported from earlier releases of Palm OS; new applications are encouraged to use the (currently equivalent) DbgOnlyFatalErrorIf() macro instead.