Error event

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

Parameters

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!.

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 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

This example displays information about the error
that occurred and allows the script to continue:

MessageBox("Error Number " + string(errornumber)&amp;<br>&#160;&#160;&#160;+ " Occurred", "Errortext: " + String(errortext))<br>action = ExceptionIgnore!

1	MessageBox("Error Number " + string(errornumber)&<br>   + " Occurred", "Errortext: " + String(errortext))<br>action = ExceptionIgnore!

Connection Information

Error – PB Docs 125