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
ErrDlgResultType Enum
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
DbgOnlyFatalError Macro
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
Returns
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
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
Returns
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
Purpose
Displays an alert dialog for runtime errors.
Declared In
Form.h
Prototype
uint16_t ErrAlert ( DmOpenRefappDbRef
, status_terrCode
)
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
ErrDisplay Macro
Purpose
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.
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
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
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.
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
Purpose
Display an error alert dialog.
Declared In
ErrorMgr.h
Prototype
#define ErrFatalDisplay (
msg
)
Parameters
Returns
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
Purpose
Display an error alert dialog if the specified condition is true.
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.
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
Purpose
Display an error alert dialog.
Declared In
ErrorMgr.h
Prototype
#define ErrFatalError (
errMsg
)
Parameters
Returns
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
Purpose
Display an error alert dialog if the specified condition is true.
Declared In
ErrorMgr.h
Prototype
#define ErrFatalErrorIf (condition
,errMsg
)
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.
See Also
DbgOnlyFatalErrorIf()
, ErrFatalError()
ErrFatalErrorInContext Function
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_tlineNum
, const char*errMsg
)
Parameters
-
→ fileName
- Source code filename.
-
→ lineNum
- Line number in the source code file.
-
→ errMsg
- Message to display.
Returns
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
Purpose
Looks up the error message for the specified error code.
Declared In
Form.h
Prototype
status_t ErrGetErrorMsg ( DmOpenRefappDbRef
, status_terrCode
, char*errMsgP
, int32_terrMsgLen
)
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:
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
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
Returns
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
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
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).
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.