Basic usage example Professional

The ADSDBE is basically used like any other Xbase++ DatabaseEngine (DBE). It must be loaded with the DbeLoad() function and can be defined with DbeSetDefault() as the default DBE. Once the ADSDBE is loaded, all commands and functions of the DML (Data Manipulation Language) are directed via the ADSDBE to the ADS and executed on the server station. The result of a DML command is then returned to the Xbase++ application, or client station.

Loading the DatabaseEngine

Although the ADSDBE usage is quite similar to other Xbase++ DBEs, there are some differences which must be taken into account. The basic difference is that the ADSDBE consists of a data component and a built in order component, Dictionary and Session component as well. Therefore there is no need to useDbeBuild() to build a DatabaseEngine with order/index management capabilitites.

01: PROCEDURE DbeSys 
02: 
03:    IF ! DbeLoad( "ADSDBE" ) 
04:       Alert( "Unable to load ADSDBE", {"Ok"} ) 
05:    ENDIF 
06:  
07:    DbeSetDefault( "ADSDBE" ) 
08: RETURN 
09: 
10: 

Procedure DbeSys() is used in this example, just as in any Xbase++ application, to load the required DBE. Since the ADSDBE has an order component, the function DbeBuild() is not called. Instead, the ADSDBE must be defined with DbeSetDefault() as the default DBE (line #7), although it is the only DBE loaded in the example.

Connecting to the Server

The next important difference is that the ADSDBE allows to access files via a database server (ADS) which runs on a remote site. This requires the client station to establish a connection to the Server before any file can be used. This, again, is accomplished by the DacSession()class whose objects have the functionality to build a server connection and maintain a session while the client station is connected (note: the prefix DAC stands for Data Access Chain). Therefore, the following steps are required for sucessfully using a database and index file with the ADSDBE:

01: PROCEDURE DbeSys 
02: 
03:    IF ! DbeLoad( "ADSDBE" ) 
04:       Alert( "Unable to load ADSDBE", {"Ok"} ) 
05:    ENDIF 
06:  
07:    DbeSetDefault( "ADSDBE" ) 
08: RETURN 
09: 
10: 
11: PROCEDURE Main 
12:   LOCAL cConnect := "DBE=ADSDBE;SERVER=\\ALASKA\VOL1" 
13:   LOCAL oSession := DacSession():New( cConnect ) 
14: 
15:    IF .NOT. oSession:isConnected() 
16:       Alert( "Unable to establish connection to ADS", {"Quit"} ) 
17:       QUIT 
18:    ENDIF 
19: 
20:    SET DEFAULT TO "\\ALASKA\VOL1" 
21: 
22:    USE CUSTOMER EXCLUSIVE 
23:    INDEX ON Upper( LastName+FirstName ) TAG Name TO Cust 
24: 
25:    USE CUSTOMER SHARED INDEX Cust 
26:    Browse() 
27: 
28:    oSession:disconnect() 
29: RETURN 

Line #12 is executed after the ADSDBE is available. It defines the connection string to be used by the DacSession object created in line #13. The connection string contains all information required for establishing a connection to the server. It contains the name of the database engine ("ADSDBE") and the name of the server or a drive letter. If the application uses a server name as the parameter, it must include the share name for Windows NT and Windows 95, or volume name for Novell NetWare as well. For example, use "\\server\share" or "\\server\volume".

A DacSession object establishes a connection on instantiation already, so that a successful connection can be tested in line #15 using the :isConnected() method. The sample program then either quits when the connection fails, or opens a database, creates an index and browses the data. When the user quits browsing, the DacSession object disconnects from the server and the program terminates.

The only difference in using the ADSDBE compared to the DBFNTX DBE, is that the ADSDBE requires the DacSession object to establish a connection to the ADS and to disconnect from the server. The code for database and index handling, or data manipulation, is the same. In line #22, for instance, the Customer database file is opened and line #23 creates an index file. Both files, however, are located on the server and accessed via the ADS.