Handling communications errors

What the client can do

Whenever an error occurs during client/server communications,
the client application can trap the error and respond to the situation.
In the event of an error, PowerBuilder records information about
the error in the built-in Error object. The client application can
access the Error object to determine what caused the error and then
respond accordingly.

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 doesn’t 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.

Connecting to a different server

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.

Writing scripts to handle errors

To process errors in a client application, you write scripts
for the following events:

• Error event of the
  Connection object
• SystemError event of the Application object

PowerBuilder triggers these events in this order. If the Error
event of the Connection object does not have a script associated
with it, PowerBuilder will execute the script for the SystemError
event, if one is available.

System exception handler

PowerBuilder
has a system exception handler that tries to catch fatal system errors.
It helps prevent the server from terminating due to 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.

CORBA exceptions

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

• System exceptions
• User exceptions

A system exception is one of a standard
set of errors raised by the server.

A user 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.

If a PowerBuilder client to a Jaguar component receives a
system exception, the exception is displayed by default as a runtime
error. The error-handling mechanism from the client’s perspective
is the same as it is for a distributed PowerBuilder client. The
exception triggers the Error event of the Connection object, thereby
allowing the developer to override the default display of the runtime
error.

The user exception for PowerBuilder components is described
in IDL so that non-PowerBuilder clients can use the information
passed by a PowerBuilder runtime error. This runtime error exception
is named PBUserException. If a PowerBuilder
client to a Jaguar component receives a PBUserException, the PowerBuilder
virtual machine will retrieve the data and reconstitute the error as
a normal runtime error.

Scripting the Error event of the Connection object

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 Connection
object. Once you have created the custom Connection object, you
can refer to it anywhere in your scripts where you use a Connection
object.

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:

---