PowerBuilder Occurs when an error is found in a data or property expression for an external object or a DataWindow object. Also occurs when a communications error is found in a distributed application.
PowerBuilder event information Event ID: None
Argument |
Description |
|---|---|
errornumber |
Unsigned integer by value (PowerBuilder’s error number). |
errortext |
String, read-only (PowerBuilder’s error message). |
errorwindowmenu |
String, read-only. The name of the window or menu that is the parent of the object whose script caused the error. |
errorobject |
String, read-only. The name of the object whose script caused the error. |
errorscript |
String, read-only. The full text of the script in which the error occurred. |
errorline |
Unsigned integer by value. The line in the script where the error occurred. |
action |
ExceptionAction by reference. A value you specify to control the application’s course of action as a result of the error. Values are:
|
returnvalue |
Any by reference. A value whose datatype matches the expected value that the OLE server or DataWindow would have returned. This value is used when the value of action is ExceptionSubstituteReturnValue!. |
None. (Do not use a RETURN statement.)
DataWindow and OLE objects are dynamic. Expressions that use dot notation to refer to data and properties of these objects might be valid under some runtime conditions but not others. The Error event allows you to respond to this dynamic situation with error recovery logic.
The Error event also allows you to respond to communications errors in the client component of a distributed application. In the Error event for a custom connection object, you can tell PowerBuilder what action to take when an error occurs during communications between the client and the server.
The Error event gives you an opportunity to substitute a default value when the error is not critical to your application. Its arguments also provide information that is helpful in debugging. For example, the arguments can help you debug DataWindow data expressions that cannot be checked by the compiler—such expressions can only be evaluated at runtime.
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 substituted return value will not match the datatype
of the unresolved object reference and will cause a system error.
The ExceptionSubstituteReturnValue! action is most useful for handling errors in data expressions.
For DataWindows, if an error occurs while evaluating a data or property expression, error processing occurs like this:
The Error event occurs.
If you use a Try-Catch block, it is best not to script the Error event.
If the Error event has no script or its action argument is not changed from the default action (ExceptionFail!), either a catch statement is executed or the SystemError event occurs.
If you do not handle the error in a Try-Catch block and the SystemError event has no script, an application error occurs and the application is terminated.
The chapter on “Using DataWindow Objects” in the DataWindow Programmers Guide contains a table of correspondences between Error event arguments and DWRuntimeError properties. You can use the DWRuntimeError properties in a Try-Catch block to obtain the same information about an error condition that you would otherwise obtain from Error event arguments.
The error processing in the client component of a distributed application is the same as for DataWindows. For information about handling communications errors in a distributed application, see the discussion of distributed applications in Application Techniques.
For information about error processing in OLE controls, see the ExternalException event description in the PowerScript Reference.
For information about using data and property expressions for DataWindow objects, see Chapter 4, “Accessing Data in Code” and Chapter 5, “Accessing DataWindow Object Properties in Code.”
This example displays information about the error that occurred and allows the script to continue:
MessageBox("Error Number " + string(errornumber)&
+ " Occurred", "Errortext: " + String(errortext))
action = ExceptionIgnore!
