Handling errors – PB Docs 125

Chain of error events

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

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

2. Otherwise, the ExternalException event for the OLE
   object occurs.

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

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

5. If no exception handler exists, or if the existing
   exception handlers do not handle the exception, the SystemError
   event for the Application object occurs.

6. 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:

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:

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.