Introduction

---

As already discussed in the DBISAM Architecture topic, the TDBISAMSession component represents a session in DBISAM. The following information will show how to start a session in an application.

Preparing a Local Session for Startup

---

If a TDBISAMSession component has its SessionType property set to stLocal, then it is considered a local session as opposed to a remote session. There is nothing extra that must be done to prepare a local session for startup.

Preparing a Remote Session for Startup

---

If a TDBISAMSession component has its SessionType property set to stRemote, then it is considered a remote session as opposed to a local session. Starting a remote session will cause DBISAM to attempt a connection to the database server specified by the RemoteAddress or RemoteHost and RemotePort or RemoteService properties. In addition, the RemoteEncryption property indicates whether the session's connection to the database server will be encrypted using the RemoteEncryptionPassword property. You must set these properties properly before trying to open the remote session or an exception will be raised.

The RemoteAddress and RemoteHost properties are normally mutually exclusive. They can both be specified, but the RemoteHost property will take precedence. The host name used for the server can be specified via the "hosts" text file available from the operating system. In Windows 98, for example, it's located in the Windows directory and is called "hosts.sam". Renaming this file to just "hosts" and adding an entry in it for the database server will allow you to refer to the database server by host name instead of IP address. The following is an example of an entry for a database server running on a LAN:

192.168.0.1     DBISAMLANServer

This is sometimes more convenient than remembering several IP addresses for different database servers. It also allows the IP address to change without having to modify your application.

The RemotePort and RemoteService properties are also normally mutually exclusive. They can both be specified, but the RemoteService property will take precedence. By default the ports that DBISAM database servers use are:


These ports can be changed, however, so check with your administrator or person in charge of the database server configuration to verify that these are the ports being used.

The service name used for the database server can be specified via the "services" text file available from the operating system. In Windows 98, for example, it's located in the \Windows directory and is called "services". Adding an entry in it for the database server's port will allow you to refer to the server's port by service name instead of port number. The following is an example of an entry for both the normal server port and the administrative port:

DBISAMServer     12005/tcp
DBISAMAdmin     12006/tcp

This is sometimes more convenient than remembering the port numbers for different database servers. It also allows the port number to change without having to modify your application.

The RemoteEncryption property can be set to either True or False and determines whether the session's connection to the server will be encrypted or not. If this property is set to True, the RemoteEncryptionPassword property is used to encrypt and decrypt all data transmitted to and from the database server. This property must match the same encryption password that the database server is using or else an exception will be raised when a request is attempted on the server.


If for any reason DBISAM cannot connect to a database server an exception will be raised. The error code that is returned when a connection fails is 11280 and is defined as DBISAM_REMOTECONNECT in the dbisamcn unit (Delphi) or dbisamcn header file (C++). It's also possible for DBISAM to be able to connect to the server, but the connection will be rejected due to the database server's maximum connection setting being reached (11282 and defined as DBISAM_REMOTEMAXCONNECT), the database server not accepting any new logins (11281 and defined as DBISAM_REMOTENOLOGIN), the database server blocking the client workstation's IP address from accessing the server (11283 and defined as DBISAM_REMOTEADDRESSBLOCK), or an encrypted connection being required by the database server (11277 and defined as DBISAM_REMOTEENCRYPTREQ).

The RemoteUser and RemotePassword properties can be used to automate the login to a database server. Every DBISAM database server uses the following default user ID and password if the database server is being started for the first time, or if it is being started with an empty or missing configuration file:

User ID: Admin (case-insensitive)
Password: DBAdmin (case-sensitive)

Starting a Session

---

To start a session you must set the TDBISAMSession Active property to True or call its Open method. For a local session (SessionType property is set to stLocal), the session will be opened immediately. As discussed above, for a remote session (SessionType property is set to stRemote), performing this operation will cause the session to attempt a connection to the database server specified by the RemoteAddress or RemoteHost and RemotePort or RemoteService properties. If the RemoteUser and RemotePassword properties are specified and are valid, then neither the OnRemoteLogin event nor the interactive login dialog will be triggered. If these properties are not specified or are not valid, the OnRemoteLogin event will be triggered if there is an event handler assigned to it. If an event handler is not assigned to the OnRemoteLogin event, DBISAM will display an interactive login dialog that will prompt for a user ID and password. All database servers require a user ID and password in order to connect and login. DBISAM will allow for up to 3 login attempts before issuing an exception. The error code that is returned when a connection fails due invalid login attempts is 11287 and is defined as DBISAM_REMOTEINVLOGIN in the dbisamcn unit (Delphi) or dbisamcn header file (C++).


The OnStartup event is useful for handling the setting of any pertinent properties for the session before the session is started. This event is called right before the session is started, so it is useful for situations where you need to change the session properties from values that were used at design-time to values that are valid for the environment in which the application is now running. The following is an example of using an OnStartup event handler to set the remote connection properties for a session:

void __fastcall TMyForm::MySessionStartup(TObject *Sender)
{
   TRegistry *Registry = new TRegistry;
   try
      {
      Registry->RootKey=HKEY_LOCAL_MACHINE;
      if (Registry->OpenKey("SOFTWARE/My Application",false)
         {
         if (Registry->ReadBool("IsRemote"))
            {
            MySession->SessionType=stRemote;
            MySession->RemoteAddress=Registry->ReadString("RemoteAddress");
            MySession->RemotePort=Registry->ReadString("RemotePort");
            }
         else
            {            
            MySession->SessionType=stLocal;
            }
         }
      else
         {
         ShowMessage("Error reading connection information "+
                     "from the registry");
         }
      }
   __finally
      {
      delete Registry;
      }
}

The OnShutdown event can be used for taking specific actions after a session has been stopped. As is the case with the OnStartup event, the above warning regarding the Open method or Active property also applies for the OnShutDown event.

More Session Properties

---

After a session is started, it can also be used to control certain global settings for all TDBISAMDatabase, TDBISAMQuery, and TDBISAMTable components that link to the session via their SessionName properties. The properties that represent these global settings are detailed below: