As already discussed in the Architecture topic, the TEDBSession component represents a session in ElevateDB. The following information will show how to connect a session in an application.

Preparing a Local Session for Connection

---

If a TEDBSession component has its SessionType property set to stLocal, then it is considered a local session as opposed to a remote session. A local session must have values assigned to the LoginUser and LoginPassword properties if you do not wish to have ElevateDB display a login dialog when the session is connected.

The default Administrator user and password for an ElevateDB configuration is:

User: Administrator (case-insensitive)
Password: EDBDefault (case-sensitive)

Preparing a Remote Session for Connection

---

If a TEDBSession component has its SessionType property set to stRemote, then it is considered a remote session as opposed to a local session. In addition to the Login* properties detailed above that are required for a local or remote session, there are some additional properties for remote sessions that must be specified.

Connecting a remote session will cause ElevateDB to attempt a connection to the ElevateDB Server specified by the RemoteAddress or RemoteHost and RemotePort or RemoteService properties, and the RemoteConnectionTimeout property will indicate how long the remote session will wait for a successful connection attempt. In addition, the RemoteSignature property indicates the signature that the session's connection to the ElevateDB Server will be signed with, and the RemoteEncryption property indicates whether the session's connection to the ElevateDB Server will be encrypted using the RemoteEncryptionPassword property. You must set these properties properly before trying to connect 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, for example, it is located in the Windows\System32\Drivers\Etc directory. Adding an entry in this file for the ElevateDB Server will allow you to refer to the ElevateDB Server by host name instead of IP address. The following is an example of an entry for an ElevateDB Server running on a LAN:

192.168.0.1     ElevateDBServer

This is sometimes more convenient than remembering several IP addresses for different ElevateDB 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 port that ElevateDB Servers use is 12010. This port can be changed, however, so check with your administrator or person in charge of the ElevateDB Server configuration to verify that this is the port being used.

The service name used for the ElevateDB Server can be specified via the "services" text file available from the operating system. In Windows, for example, it's located in the \Windows\System32\Drivers\Etc directory. Adding an entry to this file for the ElevateDB 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 the server:

ElevateDBServer     12010/tcp

This is sometimes more convenient than remembering the port numbers for different ElevateDB 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 ElevateDB Server. This property must match the same encryption password that the ElevateDB Server is using for communications with remote sessions (TEDBEngine ServerEncryptionPassword property) or else an exception will be raised when a request is attempted on the server.

If for any reason the remote session cannot connect to an ElevateDB Server, an exception will be raised. The error that is raised when a connection fails is 1100 (EDB_ERROR_CLIENTCONN). It's also possible for ElevateDB to be able to connect to the server, but the connection will be rejected due to the ElevateDB Server blocking the client workstation's IP address from accessing the server (1104 and defined as EDB_ERROR_ADDRBLOCK), or an encrypted connection being required by the ElevateDB Server (1105 and defined as EDB_ERROR_ENCRYPTREQ).

Connecting a Session

---

To connect a session you must set the TEDBSession 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 ElevateDB Server specified by the RemoteAddress or RemoteHost and RemotePort or RemoteService properties. The connection attempt will wait the number of seconds specified by theRemoteConnectionTimeout property.

For both local and remote sessions, if the LoginUser and LoginPassword properties are specified and are valid, then neither the OnLogin event nor the interactive login dialog will be triggered. If these properties are not specified or are not valid, the OnLogin event will be triggered if there is an event handler assigned to it. If an event handler is not assigned to the OnLogin event, ElevateDB will display an interactive login dialog that will prompt for a user ID and password. All ElevateDB configurations require a user ID and password in order to connect and login. ElevateDB will allow for up to 3 login attempts before issuing an exception. The error that is raised when a connection fails due to invalid login attempts is 501 (EDB_ERROR_LOGIN).


The BeforeConnect event is useful for handling the setting of any properties for the session before the session is connected. This event is called right before the session is connected, 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 BeforeConnect event handler to set the remote connection properties for a session:

void __fastcall TMyForm::MySessionBeforeConnect(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 AfterDisconnect event can be used for taking specific actions after a session has been disconnected. As is the case with the BeforeConnect event, the above warning regarding the Open method or Active property also applies for the AfterDisconnect event.

More Session Properties

---

A session can also be configured to control several global settings for all TEDBDatabase, TEDBTable, TEDBQuery, TEDBStoredProc, and TEDBScript components that link to the session via their SessionName properties. The properties that represent these global settings are detailed below: