Introduction

---

One of the first items to address in any application, and especially a database application, is how to anticipate and gracefully handle exceptions. This is true as well with DBISAM. Fortunately, Delphi and C++ both provide elegant exception types and handling. DBISAM uses this exception handling architecture and also expands upon it in several important ways. In certain situations DBISAM will intercept exceptions and trigger events in order to allow for the continuation of a process without the interruption that would occur if the exception were allowed to propagate through the call stack.

DBISAM Exception Types

---

DBISAM primarily uses the EDBISAMEngineError object as its exception object for all engine errors. This object descends from the EDatabaseError exception object defined in the common DB unit, which itself descends from the common Exception object. This hierarchy is important since it allows you to isolate the type of error that is occurring according to the type of exception object that has been raised, as you will see below when we demonstrate some exception handling.


The EDBISAMEngineError object contains several important properties that can be accessed to discover specific information on the nature of the exception. The ErrorCode property is always populated with a value which indicates the error code for the current exception. Other properties may or may not be populated according to the error code being raised, and a list of all of the error codes raised by the DBISAM engine along with this information can be found in Appendix B - Error Codes and Messages.

Exception Handling

---

The most basic form of exception handling is to use the try..except block (Delphi) or try..catch (C++) to locally trap for specific error conditions. The error code that is returned when an open fails due to access problem is 11013, which is defined as DBISAM_OSEACCES in the dbisamcn unit (Delphi) or dbisamcn header file (C++). The following example shows how to trap for such an exception on open and display an appropriate error message to the user:

begin
   with MyDBISAMTable do
      begin
      DatabaseName:='c:\testdata';
      TableName:='customer';
      Exclusive:=True;
      ReadOnly:=False;
      try
         Open;
      except
         on E: Exception do
            begin
            if (E is EDatabaseError) and (E is EDBISAMEngineError) then
               begin
               if (EDBISAMEngineError(E).ErrorCode=DBISAM_OSEACCES) then
                  ShowMessage('Cannot open table '+TableName+
                    ', another user has the table open already')
               else
                  ShowMessage('Unknown or unexpected '+
                    'database engine error # '+
                    IntToStr(EDBISAMEngineError(E).ErrorCode));
               end
            else
               ShowMessage('Unknown or unexpected '+
                    'error has occurred');
            end;
      end;
      end;
end;

Exception Events

---

Besides trapping exceptions with a try..except or try..catch block, you may also use a global TApplication.OnException event handler to trap database exceptions. However, doing so will eliminate the ability to locally recover from the exception and possibly retry the operation or take some other course of action. There are several events in DBISAM components that allow you to code event handlers that remove the necessity of coding try..except or try..catch blocks while still providing for local recovery. These events are as follows:


The above events are all based in the TDBISAMTable or TDBISAMQuery components, and are mainly geared toward application-level exception handling. There is a lower level of exception handling available also in the following TDBISAMEngine events: