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.
|
ExceptionAction value |
Effect |
|---|---|
|
ExceptionFail! |
Fail as if the event had no script. Failing |
|
ExceptionIgnore! |
Ignore the error and return as if no error Caution If you are getting a |
|
ExceptionRetry! |
Send the command to the OLE server again (useful if Caution If you keep retrying and |
|
ExceptionSubstituteReturnValue! |
Use the value specified in the ReturnValue argument You can set up an With a valid |
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:
|
1 2 3 |
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:
|
1 2 3 4 5 6 7 8 9 10 |
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
PowerScript Reference.