Occurs when an OLE automation command caused an exception on the OLE server.
Improved error-handling capability in PowerBuilder
The ExternalException event is maintained for backward compatibility.
If you do not script this event or change its action argument, information
from this event is passed to RuntimeError objects, such as OLERuntimeError.
You can handle these errors in a try-catch block.
Event ID |
Objects |
|---|---|
None |
OLE, OLEObject, OLETxnObject |
Argument |
Description |
|---|---|
resultcode |
UnsignedLong by value (a PowerBuilder number identifying the exception that occurred on the server). |
exceptioncode |
UnsignedLong by value (a number identifying the error that occurred on the server. For the meaning of the code, see the server documentation). |
source |
String by value (the name of the server, which the server provides). |
description |
String by value (a description of the exception, which the server provides). |
helpfile |
String by value (the name of a Help file containing information about the exception, which the server provides). |
helpcontext |
UnsignedLong by value (the context ID of a Help topic in helpfile containing information about the exception, which the server provides). |
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 would have returned. This value is used when the value of action is ExceptionSubstituteReturnValue!. |
None. (Do not use a RETURN statement.)
OLE objects are dynamic. Expressions that refer to data and properties of these objects might be valid under some runtime conditions but not others. If the expression causes an exception on the server, PowerBuilder triggers the ExternalException event. The ExternalException event gives you information about the error that occurred on the OLE server.
The server defines what it considers exceptions. Some errors, such as mismatched datatypes, generally do not cause an exception but do trigger the Error event. In some cases you might not consider the cause of the exception to be an error. To determine the reason for the exception, see the documentation for the server.
When an exception occurs because of a call to an OLE server, error handling occurs like this:
The ExternalException event occurs.
If the ExternalException event has no script or its action argument is set to ExceptionFail!, the Error event occurs.
If the Error event has no script or its action argument is set to ExceptionFail!, any active exception handler for an OLERuntimeError 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.
Suppose your window has two instance variables: one for specifying the exception action, and another of type Any for storing a potential substitute value. Before accessing the OLE property, a script sets the instance variables to appropriate values:
ie_action = ExceptionSubstituteReturnValue!
ia_substitute = 0
li_currentsetting = ole_1.Object.Value
If the command fails, a script for the ExternalException event displays the Help topic named by the OLE server, if any. It substitutes the return value you prepared and returns control to the calling script. The assignment of the substitute value to li_currentsetting works correctly because their datatypes are compatible:
string ls_context
// Command line switch for WinHelp numeric context ID
ls_context = "-n " + String(helpcontext)
If Len(HelpFile) > 0 THEN
Run("winhelp.exe " + ls_context + " " + helpfile)
END IF
action = ie_action
returnvalue = ia_substitute
Because the event script must serve for every automation command for the control, you need to set the instance variables to appropriate values before each automation command.
