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 programming error is an erroneous sequence of calls to the 4GL–JMS API or the calling of the API with invalid parameters. Typically, programming errors should not occur in a deployed application.
An example of a programming error is an attempt by the application to make a TextMessage call in a StreamMessage. Programming errors should be tracked down and fixed at development time. The primary source of information for that phase is the 4GL–JMS API. (See "4GL–JMS API Reference.")
- A run-time condition is an event that disturbs the normal flow of the application and might happen in a deployed application. The 4GL programmer should try to handle it programmatically.
Examples of run-time conditions include attempting to connect to a JMS server that is not currently running and trying to subscribe to a topic without the proper authorization. The primary source for understanding and programmatically handling run-time conditions is the Progress SonicMQ JavaDoc (in
\docs\api
under the SonicMQ installation directory).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 problem is reported synchronously if it occurs and is detected while the 4GL application is executing a 4GL–JMS API call.
- A problem is reported asynchronously when it comes from the asynchronous error reporting system of the JMS server (OnException Events) or from the 4GL–JMS mechanism that delivers messages asynchronously to the 4GL client.
A synchronous problem is reported by an API internal procedure by returning:
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:
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:
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:
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:
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:
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:
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:
- Message handlers should handle ERROR, STOP, and QUIT conditions and not propagate them. An unhandled condition is considered a programming error.
- Since the message handler returns control to the 4GL–JMS implementation and the message handler cannot raise a condition, there must to be a mechanism to allow the message handler to communicate problems to the rest of the 4GL application. This can be done by passing a 4GL procedure handle to the messageConsumer object using the setApplicationContext call. The message-handler procedure can obtain the procedure handle by calling the getApplicationContext procedure in the messageConsumer object and then making internal procedure calls in it.
- As mentioned in the "Message Acknowledgment and Recovery" section, the message handler can call the setNoAcknowledge method of the message consumer to prevent the message from being acknowledged in a session that is not transacted for receiving.
- Calling WAIT–FOR is allowed inside a message handler, but no further messages from that Session object are received until the message handler returns.
- The following recursive calls from the message handler into the 4GL–JMS API of the same Session object are considered a programming error: deleteSession, deleteConsumer, and recover. There are no restrictions on calling these API entries of another Session object.
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 |