ExternalException event

Description

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

Event ID	Objects
None	OLE, OLEObject, OLETxnObject

Parameters

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: ExceptionFail! – fail as if this script were not implemented. The error condition triggers 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. 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 would have returned. This value is used when the value of action is ExceptionSubstituteReturnValue!.

Return Values

None. (Do not use a RETURN statement.)

Usage

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.

Examples

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!

1	ie_action = ExceptionSubstituteReturnValue!

ia_substitute = 0

1	ia_substitute = 0

li_currentsetting = ole_1.Object.Value

1	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

1	string ls_context

// Command line switch for WinHelp numeric context ID

1	// Command line switch for WinHelp numeric context ID

ls_context = "-n " + String(helpcontext)

1	ls_context = "-n " + String(helpcontext)

If Len(HelpFile) &gt; 0 THEN

1	If Len(HelpFile) > 0 THEN

&#160;&#160;&#160;Run("winhelp.exe " + ls_context + " " + helpfile)

1	Run("winhelp.exe " + ls_context + " " + helpfile)

END IF

END IF

action = ie_action

1	action = ie_action

returnvalue = ia_substitute

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

Connection Information

ExternalException – PB Docs 125