Handling errors

PowerBuilder provides three layers of error handling that can be used by clients connecting to EAServer:

• A mechanism, using try/catch/finally blocks, for handling exceptions thrown by components running in EAServer

  All system and runtime errors are converted into objects that descend from the type RuntimeError.

• The Error event on the Connection and JaguarORB objects to handle errors that occur in the context of an EAServer connection

• The SystemError event on the Application object to handle errors that have not been trapped by any other mechanism

PowerBuilder records information about errors in a built-in Error structure. This structure is used by the Error and SystemError events.

A client application can handle communications errors in a number of ways. For example, if a client connects to a server and tries to invoke a method for an object that does not exist, the client can disconnect from the server, connect to a different server, and retry the operation. Alternatively, the client can display a message to the user and give the user the opportunity to control what happens next.

When an error occurs, if the client connects to a new server to retry the operation, it must instantiate the remote object on the new server before invoking a method of the remote object.

This is the sequence in which PowerBuilder executes error-handling code in an EAServer client:

1. If an error occurs in the context of the Connection or JaguarORB object, and the Error event of that object has a script associated with it, PowerBuilder executes the event script, if any.

2. If any one of the following is true, any active exception handler for a RuntimeError or its descendants is invoked:

   • The Error event is not scripted

   • The action argument of the Error event is set to ExceptionFail!

   • The error does not occur in the context of the Connection or JaguarORB object

3. If no exception handler exists, or if the existing exception handlers do not handle the exception, the SystemError event on the Application object is executed. If the SystemError event has no script, an application error occurs and the application is terminated.

PowerBuilder has a system exception handler that tries to catch fatal system errors. It helps prevent the server from terminating because of problems with individual client connections. Whenever a fatal error occurs in a client connection, PowerBuilder tries to terminate the client connection without bringing down the server or interfering with other client connections. Once the problem has been detected, the system exception handler triggers a SystemError event in the Application object, just as it would for any other runtime error on the client.

Using the try/catch mechanism lets you handle errors where they occur, making it less likely that an error thrown by a component results in a fatal error in the client application. Scripting the Error event of the Connection object is less precise and, unless the action argument of the Error event is set to ExceptionFail!, bypasses any try/catch exception handlers.

You should therefore leave the Error event unscripted and add try/catch blocks to your code to achieve the most effective error handling. You can use the GetMessage function to retrieve the exception’s error message.