Error Handling Approach
check for an error (no warning) check for an error and warn return if result is an error
jump to an error handler if result is an error check that the result is not an error
Macro
StsChk StsFailed StsRet StsJmp StsOK
The Class Manager defines similar macros for checking the status values returned when sending a message.
Each status value checker works with any expression that evaluates toa STATUS.
Each takes the expression and a variable to assign the status to. All of these macros (except StsChk) call StsWarn, so that they print out a warning message if you set the DEBUG preprocessor variable during compilation.
Since often one function calls another which also returns STATUS, using these macros consistently will give a "stack trace" indicating the site of the error and the nested set of functions which produced the error.
The examples below assume that MyFuncO returns STATUS.
Description
Example
StsChk(se, s)
Checks for an error.
Sets the STATUS s to the result of evaluating se. If s is less than stsOK, returns true, otherwise returns false. Does not print out a warning message.
STATUS Si
if (StsChk(MyFunc(paraml, param2), s)) ( II MyFunc() failed
Description
Example
Remarks
Description
CHAPTER 5: DEVELOPING AN APPLICATION 83 PenPoint Types and Macros
StsFaiied(se, s)
Checks for an error.
Sets the STATUS s to the result of evaluating se. If s is anything other than stsOK, returns true and prints an error if DEBUG is set. If sis stsOK, returns false.
STATUS Si
if (StsFailed(MyFunc(param1, param2), s)) (
II MyFunc() returned other than stsOK, so check status switch (Cls(s)) {
else (
II MyFunc() did the expected thing, so continue
This is analogous to StsOK, but it reverses the sense of the test in order to be more consistent with other checking macros.
StsJmp(se, s, labe/)
Jump to label on error.
Sets the STATUS s to se. If s is less than stsOK, it prints an error if DEBUG is set and does a goto to label. This is useful when you have a sequence of operations, any of which can fail, each having its own clean-up code.
STATUS Si
pMem1 = allocate some memorYi
StsJmp (MyFunc (param1, param2), s, Error1)i pMem2 = allocate some more memorYi
StsJmp (MyFunc (param1, param2), s, Error2)i return stsOKi
Error2:
II Handle error. 2.
OSHeapBlockFree(pMem2)i Error1:
II Handle error 1.
OSHeapBlockFree(pMem1)i return Si
z o
!i
u:::i A. A. C(
Z
C(
"
~
... ~9 ...
~ o11'1
StsOK(se, s)
Checks that things are OK.
Description Sets the STATUS s to the result of evaluating se. If s is greater than stsOK, returns true. Otherwise, prints an error if DEBUG is set and returns.
Example STATUS s;
if (StsOK(MyFunc(paraml, param2), s)) II MyFunc() succeeded, continue.
else (
II MyFunc() failed, check status.
switch (Cls(s)) (
Remarks This is analogous to StsFailed, but reverses the sense of the test and returns true for any status value that is not an error. In other words, this could return true but the status might be some other value than stsOK, such as stsNoMatch.
StsRet(se, s)
Returns status on error.
Description Sets the STATUS s to se. If s is less than stsOK, prints an error if DEBUG is set and returns s. This is useful if one function calls another and should immediately fail if the second function fails.
Example S'.!'ATUS s;
II If MyFunc has problems, return.
StsRet(MyFunc(paraml, param2), s);
". Debugging Assistance
GO has developed a set of useful functions and macros to assist in debugging PenPoint applications. They are no substitute for. DB, the PenPoint Source-level debugger, or the Pen Point mini-debugger (both these debuggers are documented in PenPoint Developement Tools). However, they help you trace the operation of a program without using a debugger. They are an elaboration of the time-honored technique of inserting printfs in your code.
",. Printing Debugging Strings
DPrintf and Debugf print text to the debugger stream. They take a formatting string and optional parameters to display, in the same manner as as the standard C function printf. The only difference between DPrintf and Debugf is that Debugf supplies a trailing newline (if you want a newline at the end ofDPrintf.
output, end it with \n).
Debugf("Entering init method for clsApp");
Debugf(IImain: process count = %d", processCount);
5.9
5.9.1
CHAPTER 5: DEVELOPING AN APPLICATION 85 Debugging Assistance
Debugge&' $1M'i'e~m
The debugger stream is a pseudo device to which programs (including PenPoint) can write debugging information. There are several ways to view the debugger stream.
• If you have a single screen, you can see the most recent lines written to the debugger stream when you press
I
PauseI.
• If you have a second (monochrome) monitor, serial terminal, or PC running communications software, you can constantly watch the debugger stream on this monitor while you run PenPoint on the main (VGA) monitor.
• You can send the debugger stream to a log file, by setting the D debugger flag to the hexadecimal value 8000. Usually you do this in the
ENVIRON.INI file, but you can also do it from the PenPoint symbolic debugger, or from the mini-debugger.
DebugSet=/DD8000
DebugLog=\\boot\tmp\run3.1og
• You can use the System Log application to view the debugger stream while running a PenPoint appliction.
None of these destinations are mutually exclusive.
Assertions
Often when working on functions called by other functions, you assume that the software is in a certain state. The ASSERT macro lets you state these assumptions, and if DEBUG is set, it checks to see that they are in fact the case. If they are not satisfied, it will print an error. For example, a square root function might rely on never being called with a negative number:
void MySqRoot(int num)
(
ASSERT(num >= 0, "MySqRoot: input parameter is negative!");
II Calculate square root ...
The test is only performed if DEBUG is defined.