Class: cWebErrorHandler

Properties  Events  Methods    Index of Classes

The Web Framework error handler

Hierarchy

cObject
---cWebErrorHandler

Library: Web Application Class Library

Package: cWebErrorHandler.pkg

Description

The web framework error handler is used to intercept and collect all errors that are raised during any client request (via the web framework CallAction interface), thus preventing the error from stopping execution of the server application with an error dialog. The error handler diverts errors from the built-in DataFlex error handler (ErrorSystem). The collected errors are returned to the client in the response structure and processed on the client in a way appropriate for each error.

You web application's main object (cWebApp) automatically declares an error handler and saves a reference to this object in the global object handle ghoWebErrorHandler.

You would replace this default error handler object with an application-specific error handler when you need to append or modify the errors are collected and categorized, for example you may wish to save certain application errors in one of the windows error logs on the server or use your own error logging system.

Whatever error handling system you use, it should never show an error message dialog on the server or wait for user input (on the server). This will effectively lock one instance of your web application to every client session connecting to it. You should also ensure that your error handler object sets the global variable ghoWebErrorHandler below the first line in your cWebApp object declaration.

The easiest way to replace the default error handler is to create a new cWebErrorHandler object inside your application's cWebApp object and augment the behavior of this object (or create a subclass).

Sample

Object oWebApp is a cWebApp
    Set psTheme to "Df_Web_Creme"

    Object oErrorHandler is a cWebErrorHandler
        // Add your custom error handling code here.
    End_Object

    // Web Application command bar objects can go here.
    
    // Web Views are included here
End_Object

The above sample declares a main web application object (cWebApp) and a custom error handler (cWebErrorHandler). Note that it is not necessary to manually set ghoWebErrorHandler as this is performed for you by the cWebErrorHandler class.

Raising Errors

To raise an error in your web application, simply call the Error command in the usual way.

Example

If (bSessionExpired = True) Begin
    Error 1000 "Your session key has expired"
End
Else Begin
    Send ProcessRequest
End


The Error_Report even is triggered for each error that is raised. You can augment this event to modify the behavior of the error handler for each error. Never call Error_Report directly to generate an error.

User Errors and Unhandled Errors

DataFlex distinguishes between two types of errors - user errors and unhandled errors.
- User Errors: User Errors (handled errors) are the errors that you expect your users will make. When a handled error occurs, you want to present the user with useful information that will help solve their problem. You also want your user to know that nothing is wrong with your application and that they've simply done something wrong.
- Unhandled Errors: These are errors that indicate that something has gone wrong with your application (i.e., a bug). These are usually programming errors and when they occur, you want the user to contact you. In addition, you'd like to be provided with as much useful debugging information as possible.

User Errors

The error handler maintains a set of all error numbers that are considered as user errors. Send AddUserError to add a new error number to this set, send RemoveUserError to remove a particular error number from the set and send RemoveAllUserErrors to clear the set of user errors entirely.

When a handled error occurs, a message box is presented on the client with the error text (and no technical information). The appearance of the message dialog is determined by the web application's CSS theme (psTheme).

Set psUserErrorCaption to change the default caption of the error message box.

Unhandled Errors

When an unhandled error occurs, a different message box is presented on the client. This dialog provides more technical information, including the error number, line number of your application that raised the error and any additional system information.

The appearance of the client unhandled error message dialog is determined by the web application's CSS theme (psTheme). Set psUnhandledErrorCaption to change the default caption of the error message box.

In addition to the client-side error report, the error is logged to the application event log. The logged error contains the complete set of error information including a stack dump. This can be browsed in the WebApp Administrator. Set LogErrorToEvent to false of your global web application object (cWebApp) to disable error logging.

When you are running a web application in the debugger then a server-side error dialog is displayed containing all of the error information including a stack dump. This is equivalent to the error dialog you would see when debugging a windows application and can be used in the same way to pause the application and jump to the line of code that raised the error.

Ignoring Errors

The error handler supports an interface for ignoring errors (regardless of whether they are considered user errors or unhandled errors). Use the IgnoreError, TrapError and TrapAllErrors messages to manipulate the set of trapped errors. By default, every error belongs to the set of trapped errors.

The set of trapped errors is a global set that is used both by the web framework error handler (i.e. this class) while processing call actions, and the default global error system that handles errors at all other times.

There is a single error that will never be passed to the error object, Error 10 (Out of memory). Since the message-passing mechanism uses dynamically allocated memory, this would most-certainly cause a system failure.