Icon Opening Databases

Introduction
As already discussed in the DBISAM Architecture topic, the TDBISAMDatabase component represents a database in DBISAM. The following information will show how to open a database in an application.

Preparing a Database for Opening
Before you can open a database using the TDBISAMDatabase component, you must set a couple of properties. The TDBISAMDatabase DatabaseName property is the name given to the database within the application and is required for naming purposes only. For a local database the Directory property should contain a directory name, either in UNC format or using logical drive mapping notation. For a remote database, the RemoteDatabase property will contain the name of a logical database set up on the database server that you are connecting to.

Information Setting the Directory property for a local database so that it points to an invalid directory and then opening the database will not cause an error. However, an exception will be raised if a TDBISAMTable or TDBISAMQuery component that is linked to the TDBISAMDatabase via its DatabaseName property tries to open a table. The error code that is returned when a table open fails due to the directory or table files not being present is 11010 and is defined as DBISAM_OSENOENT in the dbisamcn unit (Delphi) or dbisamcn header file (C++).

Opening a Database
To open a database you must set the TDBISAMDatabase Connected property to True or call its Open method. For a local TDBISAMDatabase component whose SessionName property is linked to a local TDBISAMSession component, the database will cause the local TDBISAMSession to be opened if it is not already, and then the database will be opened. For a remote database whose SessionName property is linked to a remote TDBISAMSession component, performing this operation will cause the remote session to attempt a connection to the database server if it is not already connected. If the connection is successful, the database will then be opened.

The BeforeConnect event is useful for handling the setting of any pertinent properties for the TDBISAMDatabase component before it is opened. This event is triggered right before the database is opened, so it's useful for situations where you need to change the database information from that which was used at design-time to something that is valid for the environment in which the application is now running. The following is an example of a BeforeConnect event handler that is used to set the properties for a TDBISAMDatabase component before it is opened:

procedure TMyForm.MyDatabaseBeforeConnect(Sender: TObject);
var
   Registry: TRegistry;
begin
   Registry:=TRegistry.Create;
   try
      with MyDatabase do
         begin
         { Make sure that the DatabaseName is set }
         DatabaseName:='MyDatabase';
         { Now set the Directory property to the value
           from the registry }
         Registry.RootKey:=HKEY_LOCAL_MACHINE;
         if Registry.OpenKey('SOFTWARE/My Application',False) then
            Directory:=Registry.ReadString('Directory')
         else
            ShowMessage('Error reading database information '+
                        'from registry');
         end;
   finally
      Registry.Free;
   end;
end;

Information You should not call the TDBISAMDatabase Open method or modify the Connected property from within this event handler. Doing so can cause infinite recursion.

More Database Properties
A TDBISAMDatabase component has one other property of importance that is detailed below:

PropertyDescription
KeepConnectionControls whether the database connection is kept active even after it is no longer needed. This property has no effect upon a local session, but can result in tremendous performance improvements for a remote session, therefore it defaults to True and should be left as such in most cases.
KeepTablesOpenControls whether the physical tables opened with the database connection are kept open even after they are closed by the application. Setting this property to True can dramatically improve the performance of large SQL scripts and any other operations that involve constantly opening and closing the same tables over and over.
Image