Description
Occurs when an error is found in a data or property expression for an external object or a DataWindow object.
Improved error-handling capability in PowerBuilder
The Error event is maintained for backward compatibility. If you do not script the Error event or change its action argument, information from this event is passed to RuntimeError objects, such as DWRuntimeError or OLERuntimeError. You can handle these errors in a try-catch block.
Event ID
Arguments
|
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!. |
Return Values
None. Do not use a RETURN statement.
Usage
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 it to substitute a return value when an element in the middle of an expression causes an error. The substituted return value does not match the datatype of the unresolved object reference and causes a system error.
The ExceptionSubstituteReturnValue! action can be useful for handling errors in data expressions.
For DataWindows, when an error occurs while evaluating a data or property expression, error processing occurs like this:
-
The Error event occurs.
-
If the Error event has no script or its action argument is set to ExceptionFail!, any active exception handler for a DWRuntimeError or its RuntimeError ancestor is invoked.
-
If no exception handler exists, or if the existing exception handlers do not handle the exception, the SystemError event is triggered.
-
If the SystemError event has no script, an application error occurs and the application is terminated.
The error processing in the client component of a distributed application is the same as for DataWindows.
For information about error processing in OLE controls, see the ExternalException event. For information about data and property expressions for DataWindow objects, see the section called “PowerBuilder: DataWindow property expressions” in DataWindow Reference.
For information about handling communications errors in a multitier application, see Developing Distributed Applications in Application Techniques.
Examples
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! See also
DBError in the section called “DBError” in DataWindow Reference
