Introduction

---

Opening tables can be accomplished through the Open method of the TDBISAMTable component, or by setting the Active property to True. Before opening a table, however, you must first specify the location of the table and the table name itself. The location of the table is specified in the DatabaseName property of the TDBISAMTable component, and the table name is specified in the TableName property.
Setting the DatabaseName Property

---

You may specify the DatabaseName property using two different methods:

1) The first method is to set the DatabaseName property of the TDBISAMTable component to the DatabaseName property of an existing TDBISAMDatabase component within the application. In this case the database location will come from either the Directory property or the RemoteDatabase property depending upon whether the TDBISAMDatabase has its SessionName property set to a local or remote session. Please see the Starting Sessions and Opening Databases topics for more information. The following example shows how to use the DatabaseName property to point to an existing TDBISAMDatabase component for the database location:

begin
   with MyDatabase do
      begin
      DatabaseName:='AccountingDB';
      Directory:='c:\acctdata';
      Connected:=True;
      end;
   with MyTable do
      begin
      DatabaseName:='AccountingDB';
      TableName:='ledger';
      Active:=True;
      end;
end;

Another useful feature is using the BeforeConnect event of the TDBISAMDatabase component to dynamically set the Directory or RemoteDatabase property before the TDBISAMDatabase component attempts to connect to the database. This is especially important when you have the Connected property for the TDBISAMDatabase component set to True at design-time during application development and wish to change the Directory or RemoteDatabase property before the connection is attempted when the application is run.

2) The second method is to enter the name of a local directory, if the TDBISAMTable component's SessionName property is set to a local session, or remote database, if the TDBISAMTable component's SessionName property is set to a remote session, directly into the DatabaseName property. In this case a temporary database component will be automatically created, if needed, for the database specified and automatically destroyed when no longer needed. The following example shows how to use the DatabaseName property to point directly to the desired database location without referring to a TDBISAMDatabase component:

begin
   with MySession do
      begin
      SessionName:='Remote';
      SessionType:=stRemote;
      RemoteAddress:='192.168.0.2';
      Active:=True;           
      end;
   with MyTable do
      begin
      SessionName:='Remote';
      DatabaseName:='AccountingDB';
      TableName:='ledger';
      Active:=True;
      end;
end;

Exclusive and ReadOnly Open Modes

---

In the above two examples we have left the Exclusive and ReadOnly properties of the TDBISAMTable component at their default value of False. However, you can use these two properties to control how the table is opened and how that open affects the ability of other sessions and users to open the same table.

When the Exclusive property is set to True, the table specified in the TableName property will be opened exclusively when the Open method is called or the Active property is set to True. This means that neither the current session nor any other session or user may open this table again without causing an EDBISAMEngineError exception. It also means that the table open will fail if anyone else has the table opened either shared (Exclusive=False) or exclusively (Exclusive=True). The error code given when a table open fails due to access problems is 11013 and 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 using a try..except block (Delphi) or try..catch block (C++) and display an appropriate error message to the user:

begin
   with MySession do
      begin
      SessionName:='Remote';
      SessionType:=stRemote;
      RemoteAddress:='192.168.0.2';
      Active:=True;           
      end;
   with MyDatabase do
      begin
      SessionName:='Remote';
      DatabaseName:='AccountingData';
      RemoteDatabase:='AccountingDB';
      Connected:=True;
      end;
   with MyTable do
      begin
      SessionName:='Remote';
      { We're using a database component for the database
        location, so we use the same value as the DatabaseName
        property for the TDBISAMDatabase component above, not
        the same value as the RemoteDatabase property, which
        is the name of the database as defined on the DBISAM
        database server }
      DatabaseName:='AccountingData';
      TableName:='ledger';
      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;

When the ReadOnly property is set to True, the table specified in the TableName property will be opened read-only when the Open method is called or the Active property is set to True. This means that the TDBISAMTable component will not be able to modify the contents of the table until the table is closed and re-opened with write access (ReadOnly=False). If any of the physical files that make up the table are marked read-only at the operating system level (such as is the case with CD-ROMs) then DBISAM automatically detects this condition and sets the ReadOnly property to True. DBISAM is also able to do extensive read buffering on any table that is marked read-only at the operating system level, so if your application is only requiring read-only access then it would provide a big performance boost to mark the tables as read-only at the operating system level. Finally, if security permissions for any of the physical files that make up the table prevent DBISAM from opening the table with write access, then DBISAM will also automatically detect this condition and set the ReadOnly property to True.

Table Locale Support

---

It is possible that a table was created using a specific LocaleID that is not available or installed in the operating system currently in use. In such a case this will cause an EDBISAMEngineError exception to be raised when the table is opened. The error code given when a table open fails due to locale support problems is 15878 and is defined as DBISAM_CANNOTLOADLDDRV in the dbisamcn unit (Delphi) or dbisamcn header file (C++). The table cannot be opened until the locale support is installed or the table locale is altered using an operating system with the proper local support.

Opening In-Memory Tables

---

Opening in-memory tables is the same as opening disk-based tables except for one slight difference. In-memory tables, regardless of whether they are used in a local or remote session, use a special "Memory" database name instead of a normal database name. This special database is always present and the current session always has all rights to the database.


Opening Encrypted Tables

---

When a table is marked as encrypted and given a password, its contents are then encrypted using this password and any subsequent attempts to open the table only succeed if this password (in this order):

1) Is present in the in-memory list of passwords for the current TDBISAMSession component. You can use the AddPassword, RemovePassword, and RemoveAllPasswords methods to add and remove passwords for the current session.

2) Is provided on-demand through the OnPassword event of the current session.

3) Is provided on-demand through a visual password dialog that will be displayed if the OnPassword event is not assigned an event handler.


The TDBISAMTable Encrypted property will indicate whether a given table is encrypted with a password. This property does not require that the table be open before accessing it. DBISAM will automatically attempt to open the table, read the encrypted status, and return the value of this property. The Password property will indicate the password for the table in the same manner provided that the table can be opened automatically with the correct password for the current session, as indicated above.

Please see the Creating and Altering Tables topics for more information on creating encrypted tables.