Error

Description

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 client connecting to EAServer.

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

Event ID	Objects
None	Connection, DataWindow, DataStore, JaguarORB, OLE, OLEObject, OLETxnObject

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: ExceptionFail! – fail as if this script were not implemented. The error condition triggers any active event handlers, or if none, the SystemError event. ExceptionIgnore! – ignore this error and return as if no error occurred (use this option with caution because the conditions that caused the error can cause another error). ExceptionRetry! – execute the function or evaluate the expression again in case the OLE server was not ready. This option is not valid for DataWindows. ExceptionSubstituteReturnValue! – use the value specified in the returnvalue argument instead of the value returned by the OLE server or DataWindow, and cancel the error condition.
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!.

Returns

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 DataWindow Reference or the online Help.

For information about handling communications errors in a multitier application, see the discussion of distributed applications in Application Techniques.

Examples

Example 1

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!