A DataWindow control's Error event is triggered whenever an error occurs in a data or property expression at runtime. These expressions that refer to data and properties of a DataWindow object may be valid under some runtime conditions but not others. The Error event allows you to respond with error recovery logic when an expression is not valid.
When you use a data or property expression, the PowerScript compiler checks the syntax only as far as the Object property. Everything following the Object property is evaluated at runtime. For example, in the following expression, the column name emp_name and the property Visible are not checked until runtime:
dw_1.Object.emp_name.Visible = "0"
If the emp_name column did not exist in the DataWindow, or if you had misspelled the property name, the compiler would not detect the error. However, at runtime, PocketBuilder would trigger the DataWindow control’s Error event.
The Error event is triggered even if you have surrounded an error-producing data or property expression in a try-catch block. The catch statement is executed after the Error event is triggered, but only if you do not code the Error event or do not change the default Error event action from ExceptionFail!. The following example shows a property expression in a try-catch block:
TRY
dw_1.Object.emp_name.Visible = "0"
CATCH (dwruntimeerror dw_e)
MessageBox ("DWRuntimeError", dw_e.text)
END TRY
The Error event has several arguments that provide information about the error condition. You can check the values of the arguments to determine the cause of the error. For example, you can obtain the internal error number and error text, the name of the object whose script caused the error, and the full text of the script where the error occurred. The information provided by the Error event’s arguments can be helpful in debugging expressions that are not checked by the compiler.
If you catch a DWRuntimeError error, you can use the properties of that class instead of the Error event arguments to provide information about the error condition. The following table displays the correspondences between the Error event arguments and the DWRuntimeError properties.
Error event argument |
DWRuntimeError property |
|---|---|
errornumber |
number |
errorline |
line |
errortext |
text |
errorwindowmenu |
objectname |
errorobject |
class |
errorscript |
routinename |
When the Error event is triggered, you can have the application ignore the error and continue processing, substitute a different return value, or escalate the error by triggering the SystemError event. In the Error event, you can set two arguments passed by reference to control the outcome of the event.
Argument |
Description |
|---|---|
Action |
A value you specify to control the application's course of action as a result of the error. Values are:
|
ReturnValue |
A value whose datatype matches the expected value that the DataWindow would have returned. This value is used when the value of action is ExceptionSubstituteReturnValue!. |
For a complete description of the arguments of the Error event, see the online Help.
When to substitute a return value
The ExceptionSubstituteReturnValue! action allows you to substitute
a return value when the last element of an expression causes an
error. Do not use ExceptionSubstituteReturnValue! to substitute
a return value when an element in the middle of an expression causes
an error.
The ExceptionSubstituteReturnValue! action is most useful for handling errors in data expressions.
