Handling errors

Statements in scripts that refer to the OLE server’s properties are not checked in the compiler because PowerBuilder does not know what syntax the server expects. Because the compiler cannot catch errors, runtime errors can occur when you specify property or function names and arguments the OLE server does not recognize.

Chain of error events

When an error occurs that is generated by a call to an OLE server, PowerBuilder follows this sequence of events:

If the error was generated by an ActiveX control that has defined a stock error event, the ocx_error event for the PowerBuilder OLE control is triggered.
Otherwise, the ExternalException event for the OLE object occurs.
If the ExternalException event has no script or its action argument is set to ExceptionFail! (the default), the Error event for the OLE object occurs.
If the Error event has no script or its action argument is set to ExceptionFail! (the default), any active exception handler for a RuntimeError or its descendants is invoked.
If no exception handler exists, or if the existing exception handlers do not handle the exception, the SystemError event for the Application object occurs.
If the SystemError has no script, an application runtime error occurs and the application is terminated.

You can handle the error in any of these events or in a script using a TRY-CATCH block. However, it is not a good idea to continue processing after the SystemError event occurs.

For more information about exception handling, see “Handling exceptions”.

Events for OLE errors

PowerBuilder OLE objects and controls all have two events for error handling:

ExternalException Triggered when the OLE server or control throws an exception or fires an error event (if there is no ocx_error event). Information provided by the server can help diagnose the error.
Error Triggered when the exception or error event is not handled. PowerBuilder error information is available in the script.

If the OLE control defines a stock error event, the PowerBuilder OLE control container has an additional event:

ocx_error Triggered when the OLE server fires an error event. Information provided by the server can help diagnose the error.

The creator of an OLE control can generate the stock error event for the control using the Microsoft Foundation Classes (MFC) Class Wizard. The arguments for the ocx_error event in PowerBuilder map to the arguments defined for the stock error event.

Responding to the error

If the PowerBuilder OLE control has an ocx_error event script, you can get information about the error from the event’s arguments and take appropriate action. One of the arguments of ocx_error is the boolean CancelDisplay. You can set CancelDisplay to TRUE to cancel the display of any MFC error message. You can also supply a different description for the error.

In either the ExternalException or Error event script, you set the Action argument to an ExceptionAction enumerated value. What you choose depends on what you know about the error and how well the application will handle missing information.

**Table 19-6: ExceptionAction enumerated values**
ExceptionAction value	Effect
ExceptionFail!	Fail as if the event had no script. Failing triggers the next error event in the order of event handling.
ExceptionIgnore!	Ignore the error and return as if no error occurred. Caution If you are getting a property value or expecting a return value from a function, a second error can occur during the assignment because of mismatched datatypes.
ExceptionRetry!	Send the command to the OLE server again (useful if the OLE server was not ready). Caution If you keep retrying and the failure is caused by an incorrect name or argument, you will set your program into an endless loop. You can set up a counter to limit the number of retries.
ExceptionSubstituteReturnValue!	Use the value specified in the ReturnValue argument instead of the value returned by the OLE server (if any) and ignore the error condition. You can set up an acceptable return value in an instance variable before you address the OLE server and assign it to the ReturnValue argument in the event script. The datatype of ReturnValue is Any, which accommodates all possible datatypes. With a valid substitute value, this choice is a safe one if you want to continue the application after the error occurs.

Example: ExternalException event

The ExternalException event, like the ocx_error event, provides error information from the OLE server that can be useful when you are debugging your application.

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. 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 = ExceptionSubstituteReturnValue!
ReturnValue = ia_substitute

Because the event script must serve for every automation command for the control, you would need to set the instance variables to appropriate values before each automation command.

Error event

The Error event provides information about the PowerBuilder context for the error. You can find out the PowerBuilder error number and message, as well as the object, script, and line number of the error. This information is useful when debugging your application.

The same principles discussed in the ExceptionAction value table for setting the Action and ReturnValue arguments apply to the Error event, as well as ExternalException.

For more information about the events for error handling, see the PowerScript Reference.