# CHAPTER 9: Errors and Messages

## 9.1 Introduction

If something goes wrong, the Toolkit will return error messages from the various parts of the connection to the database. These can be HTML Form errors, HTTP Server or Connectivity Server errors, SQL errors, or database access errors. They normally display in a default format. This is not always wanted. A Toolkit error generally doesn't mean a system crash or a bug, most often it will be something like a message stating the application can't connect to the Connectivity Server, or the user doesn't have privileges to perform an attempted database operation.

The default page for displaying error messages is located at `$MSHYPERPATH/resources/html/error.html`.

## 9.2 User Formatted Error Reports

To maintain the feel of an application during messages and errors, the report can be sent to an HTML file of your own devising.

Every page in an application can have its own error file. This file is named the same as the page it handles errors for, except the filename is prefixed with an `err_`. For instance `err_xxx.ehtml` would handle errors for a file `xxx.ehtml` in the same directory.

For example, suppose a page in your application is called `report.ehtml`. Create a file in the same directory called `err_report.ehtml`. This document can contain any HTML markup, as well as the tag `<ERRORMESSAGE>`. When an error occurs in `report.ehtml`, the file `err_report.ehtml` will automatically display. There is no need to place any hyperlinks or toolkit calls to `err_report.ehtml` within `report.ehtml`. The generated error will display wherever the `<ERRORMESSAGE>` tag was placed in `err_report.ehtml`. The `<ERRORMESSAGE>` tag can appear only once per error file.

If each page in a directory doesn't require its own error page, a general error page can be created for all pages in a directory. This file must be named `err_gen.html`. There can be a different one in each directory, if desired. Finally, an `err_gen.html` file can be put in the Toolkit CGI-bin directory, and all pages using the tools in that bin will bring up that error file.

When an error occurs in a given page `x.y`, the Toolkit first checks for an error file in the same directory named `err_x.y`. Finding none it checks the directory for a file named `err_gen.html`. Finding neither it checks the `bin` directory of the calling Toolkit program for an `err_gen.html` file. If no error files are found, the default display is used.

## 9.3 Suppressing Particular Connectivity Server Errors

A second type of error file specifically handles Connectivity Server errors. The error files associated with these errors are located in the `$MSHYPERPATH/resources/messages` directory.

Files located in this directory having the exactly the same name as the Connectivity Server error code are used to display errors. When these Connectivity Server errors are generated anywhere in the application, the content of those files will display rather than the actual Connectivity Server error.

One thing this can be used for is to suppress unwanted Connectivity Server messages. Two such options come with the deafult installation:

- 01S03 - no rows updated
- 01S04 - more than one row updated or deleted

It is often the case that an `UPDATE` may be desired which may change less or more than exactly one record, so warnings and errors popping up can be confusing to the user.

When an Connectivity Server error is handled this way, it overrides the `err_` file mechanism.

## 9.4 Log Files

By default the Toolkit sends all systems to `stderr` on some servers such as Apache this results in the error being logged in the server error log file, in others such as the Netscape Suite of servers, this results in the error being transmitted to the client application.

If you wish to keep errors generated by the Toolkit separate from the HTTP system then you can simply create a directory called `logs` directly under the location of the on-line Toolkit CGIs. This will automatically reroute the errors into:

- `logs/ehsql.log` - for `ehsql.cgi`
- `logs/ehlink.log` - for `ehlink.cgi`
- `logs/ehdbi.log` - for the database interface running underneath `ehlink.cgi`

Note that if you create these logs, remember to clean them out occasionally.

## 9.5 Tracing SQL Commands

During application development it is useful to create the log directory specified above and set the resource variable `EH_SQLTRACE` in the `ehtml.ini file`. This will then cause the SQL commands sent by the last browser interaction to be recorded in `logs/sql.log`, along with the time the command was sent to the database, and the time the database completed the request. This can be useful both to monitor the content of the commands, and to look for slow queries to allow the developer to optimize the database.