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.

What the client can do

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.

Where errors are handled

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.

System exception handler

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.

Context-sensitive error handling

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.

For more information about exceptions, see “Exception handling in PowerBuilder”.

Because your error-handling code may not trap all the errors
that occur, you should always script the SystemError event of the
Application object.

Handling CORBA exceptions

CORBA provides a standard way for components to indicate errors
or warnings. CORBA supports two types of exceptions:

• System exceptions
• User-defined exceptions

A system exception is one of a standard
set of errors raised by the server. These exceptions are defined
in the CORBA specification.

A user-defined exception is an error
or warning defined in the component’s IDL. A user exception
is a new data type that describes a set of data elements that are
returned to the client when the exception is raised.

System exceptions

In PowerBuilder, CORBA system exceptions are mapped to a set
of objects that inherit from the RuntimeError object. To see a list
of these exceptions, select CORBASystemException on the System tab
in the PowerBuilder Browser, select ShowHierarchy from the popup
menu, and expand the Treeview item.

The names of the CORBASystemException objects in PowerBuilder
map to the names of CORBA system exceptions as defined in the CORBA/IIOP Specification
with underscore characters omitted. For example, the PowerBuilder
CORBACommFailure exception maps to the CORBA_COMM_FAILURE
exception. For detailed information about CORBA exceptions, see
the CORBA/IIOP Specification, which can be downloaded from
the OMG Web site at http://www.omg.org.

You might want to provide error-handling for the following
exceptions when you invoke methods on a component:

User-defined exceptions

User-defined exceptions are mapped to the CORBAUserException
object, which inherits from the Exception object. PowerBuilder clients
can handle exceptions thrown by any component type.

If an EAServer component has a method on it that is defined
to throw an exception, that method on the PowerBuilder proxy object
is also declared to throw a user defined exception. The definition
of the user defined exception is created when you create the component
proxy.

All Create, Remove, and FindByPrimaryKey methods on EJB components throw
the EJB CreateException, RemoveException, and FinderException exceptions.
These exceptions are represented by IDL exceptions with the same name
in the CtsComponents package in EAServer.

Scripting the Error event

What you do

To handle errors in the Error event of the Connection object,
you create a user object that customizes the definition of the object.
Once you have created the custom Connection object, you can refer
to it anywhere in your scripts where you use a Connection object. If you
use the JaguarORB event, you can script its Error event in the same
way.

The Connection Object wizard creates a custom Connection object
for you. See “Using the wizard to create
a Connection object”.

Arguments to the Error event

The Error event of the custom Connection object has several
arguments that provide information about the condition that caused
the error. For example, these arguments provide the error number
and error text, as well as the name of the object that caused the
error and the full text of the script where the error occurred.

In addition to the arguments that provide error information,
the Error event has an argument that lets you specify what action
to take. To specify the action, you assign one of four enumerated
values (ExceptionFail!, ExceptionRetry!, ExceptionIgnore!, or ExceptionSubstituteReturnValue!)
to the Action argument of the Error event.

Example

In this example, the Error event script informs the user of
the condition that caused the communications error and gives the
user the opportunity to control what happens next. Depending on
the user’s input, the client application fails, retries
the operation, or ignores the error and continues processing:

Scripting the SystemError event

What you do

In the SystemError event of the Application object, you can
write a script to tell PowerBuilder to halt application execution
or ignore the error.

Example

In this example, the SystemError event script displays a message
informing the user of the condition that caused the communications
error and gives the user the opportunity to control what happens
next. Depending on the user’s input, the client application
halts execution or ignores the error and continues processing:

---