Progress
External Program
Interfaces


Error and Condition Handling

This section provides information about error and condition handling with the 4GL–JMS API.

Categories Of Errors and Conditions

From the point of view of the 4GL programmer, there are two types of errors and conditions, programming errors and run-time conditions.

A second category for classifying errors and conditions is whether or not the problem is reported by the 4GL–JMS implementation synchronously or asynchronously:

A synchronous problem is reported by an API internal procedure by returning:

RETURN ERROR <error message>.  

A 4GL API function reports a synchronous problem by returning an UNKNOWN value. These problems could be either programming errors or runtime conditions.

NOTE: Some synchronous programming errors are not detected by the 4GL–JMS but rather by the 4GL interpreter. For example, an attempt to call setText in a StreamMessage causes error 6456:

Procedure message.p has no entry point for setText. (6456) 

An asynchronous problem is reported as a TextMessage and handled by the error-handler procedure. The error-handler procedure is set by the application using the setErrorHandler procedure in the Session object.

Programming errors are usually reported synchronously. Run-time conditions are reported either synchronously or asynchronously.

Asynchronous Conditions

Typically, problems reported asynchronously are run-time conditions. An example of an asynchronous problem is the failure of the SonicMQ broker or the failure of communication between the SonicMQ Adapter and the SonicMQ broker. (See the "Installing an Error Handler To Handle an Asynchronous Error" section in Using the SonicMQ Adapter.") Another example of an asynchronous condition is the failure to send an automatic reply. (The message handler is set with a reply message, but the SonicMQ server fails to send the reply.)

Asynchronous conditions should be handled programmatically by creating a messageConsumer object and passing it to the setErrorHandler procedure in the Session object. Asynchronous conditions are always reported in a TextMessage with several possible CHAR message properties in the message header: exception, errorCode, linkedException–1, linkedException–2… linkedException–N (where N is a number of additional exceptions linked to the main exception). Use the getPropertyNames function to get a list of properties in the error message header. (See the example in the "Installing an Error Handler To Handle an Asynchronous Error" section in Using the SonicMQ Adapter.")

If an application does not set an error handler, a default error handler displays the error message and the properties in alert boxes.

NOTE: An application must call beginSession before creating the error-handling messageConsumer object and calling setErrorHandler.

Synchronous Errors and Conditions

Errors are reported synchronously when something goes wrong at a method call; a 4GL ERROR condition is raised. Examples include trying to publish to an unauthorized topic or trying to receive from a nonexistent queue.

To report a problem synchronously, the 4GL–JMS API internal procedure calls:

RETURN ERROR <error message> 

That call raises an error condition at the caller. The caller can use regular 4GL techniques to handle the error: a NO–ERROR phrase or an ON ERROR block, coupled with checking the RETURN–VALUE value to obtain the error message. If an application uses the NO–ERROR phrase, it must check the STATUS–ERROR:error flag to determine whether a problem has occurred.

By default, every synchronous error or condition is displayed by the 4GL–JMS API, which calls:

MESSAGE <error-message> VIEW-AS ALERT-BOX.  

This allows a quick analysis and resolution of the problem at development time.

At deployment time, however, the application developer might want to handle problems programmatically and prevent the message from being displayed on the screen. This can be achieved by calling the setNoErrorDisplay(true) procedure in the Session object. Both setNoErrorDisplay(true) and setNoErrorDisplay(false) can be called several times during the life of a session.

NOTE: Message objects inherit the display/noDisplay property from the session that created them. However, after a message is created, it is independent from the session. The setNoErrorDisplay procedure must be called in the Message object itself to change this property.

Run-time Conditions

The typical run-time condition is generated by the Java–JMS code on the server. In that case, the format of the error message obtained from the RETURN–VALUE is:

 <java-exception>:<error-message>. 

The 4GL programmer can look up the type of exceptions thrown by SonicMQ and handle some of those programmatically. The most typical run-time conditions are connection and authorization failures.

Connection and Communication Failures

The most common run-time condition is a connection failure. A connection to the SonicMQ Adapter and the JMS server is created by the beginSession call. A connection failure is always reported synchronously by beginSession, which calls:

RETURN ERROR <error message>.  

The connection can fail because of a failure to connect to the SonicMQ Adapter or a failure to connect to the JMS server. If the connection fails because of failing to connect to the JMS server, the format of the error message is:

<java-exception>:<error-message>. 

A communication failure after establishing a successful connection might be detected:

In some cases, it takes a long time for the underlying communication system to detect that there is a problem (possibly several minutes until the timeout mechanism triggers a communication failure event). Use the setPingInterval (N) session method to instruct the SonicMQ Adapter to actively ping the SonicMQ broker every N seconds to detect a communication failure more quickly. The setPingInterval functionality is a SonicMQ extension. A pingInterval value can also be specified in the srvrStartupParam property of the SonicMQ Adapter as a default for all clients.

Message Handler Errors and Conditions

A message handling procedure is an arbitrary 4GL program, and the 4GL programmer is free to handle problems that occur during the processing of a message using any 4GL technique.

However, the following issues and limitations must be considered:

Interrupts

An interrupt (CTRL-C on UNIX and CTRL-BREAK on Microsoft platforms) while a 4GL–JMS call is executing can cause either a 4GL STOP condition or an ERROR condition returned from the call, depending on the exact timing. The 4GL–JMS implementation guarantees that partial messages will not be sent or received as a result of an interrupt.

SonicMQ Adapter Failure

If communication with the SonicMQ Adapter is lost, or if the SonicMQ Adapter shuts down while the 4GL client is performing a WAIT–FOR (or waitForMessages) statement, a 4GL STOP condition is raised.

If communication with the SonicMQ Adapter is lost, or if the SonicMQ Adapter shuts down while the 4GL–JMS implementation is actively trying to communicate to it (for example, when the 4GL application calls publish or subscribe), an ERROR or STOP condition is raised, depending on the exact point where the failure was discovered.


Copyright © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095