Example: porting the MastApp application from the BDE to InstantBDExpress

(C) 2005-2024 Ethea

Premise

The MastApp application is one of the demo programs supplied with Delphi in the Demos folder. The application uses the BDE to access two different databases, one in Paradox format and the other in InterBase format. This documents describes the steps needed to port the application to the dbExpress technology, by means of InstantBDExpress. Converting real applications is usually more complex, yet this example will give you an idea of the process.

Details in the examples below may vary slightly depending on which version of Delphi you use.

Prerequisites

First we need to ensure that we have installed the InstantBDExpress components in the Delphi IDE, and that we have correctly configured the MASTSQL data access alias through InstantBDExpress Administrator. The alias should be already in IBDXConnections.ini, with these default values:

[MASTSQL]
GetDriverFunc=getSQLDriverINTERBASE
LibraryName=dbexpint.dll
VendorLib=gds32.dll
Database=C:\Program Files (x86)\Common Files\Borland Shared\Data\MASTSQL.GDB
RoleName=RoleName
User_Name=sysdba
Password=masterkey
ServerCharSet=
SQLDialect=1
BlobSize=-1
CommitRetain=False
WaitOnLocks=True
ErrorResourceFile=
LocaleCode=0000
Interbase TransIsolation=ReadCommited
Trim Char=False
DriverName=Interbase

Check and modify the database path as required, then try to connect to it.

Source cleanup and removal of Paradox support

Before we can start converting the application, we need to do a little cleanup and remove the application's support for Paradox tables. If you are using Delphi 2006 or later,some of these changes are already done.

In Main.pas:

• Delete the menu items ViewLocal and ViewRemote and their event handlers ViewLocalClick and ViewRemoteClick, which allow the user to choose between the two alternatives.

• Delete the event handler ViewMenuClick, that verifies if the remote database is available.
• Delete the methods UpdateRSConnect e InitRSRUN, which are very old leftovers from the ReportSmith times; delete the call to InitRSRUN in TMainForm.FormCreate.

In DataMod.pas:

• Delete these routines: DataDirectory, SetDatabaseAlias, UseLocalData, UseRemoteData.

• Make sure Database.AliasName is set to MASTSQL, or MASTSQL30 if you are using Delphi 2006.

• If you are starting from the version of MastApp distributed with Delphi 2006, you need to move the code found in OrdersBeforePost to an event handler for Orders.BeforeInsert. It was a wrong change made in Delphi 2006 by Borland. The version provided with InstantBDExpress already incorporates the fix.

Remove the unit DbTables from the uses clause of every unit except DataMod: it's not really used anyway in any other unit. You'll have to remove it from these units: Main, BRPARTS, EDPARTS, BrCstOrd, EDCUST, EDORDER, SrchDlg. Depending on the technique you choose to apply, this is not strictly required, but removing unused units from uses clauses is good practice anyway.

Now we have a "clean" BDE application that uses TTable and TQuery components for data access and a TDatabase for database connection. If you want to try the interposer technique, go on with the next section, otherwise skip it and continue with the instructions for component substitution explained in the subsequent section.

Note: beginning with Delphi 2009, you need to use a special unit for each chosen DBExpress driver. In this case, just add DBXInterbase to the DataMod's unit uses clause. Beginning from Delphi 2010, you also have the choice of DBXFirebird, depending on how you have defined the MastSQL connection in DBExpress' configuration file.

Using the interposer technique

As you have seen in the Conversion strategies document, you have several alternative options for applying this technique.

1. Add a new unit to the project; locate the IBDXInterposer.pas unit in IBDX's samples folder. You can leave it where it is or, after you have added it to the project, save it under a different name of your choice. Add the name of this new unit to the interface uses clause of the DataMod unit, after DbTables, and you're done.
2. Add the same unit and save it under the name DbTables, preferrably in the project folder. No need to do anything else.
3. Add the same unit, save it under a name of your choice and define a unit alias "DbTables=<interposer unit name>" in the Project Options.

Option 1 is what will work best with this particular application. In order for options 2 and 3 to work, all units that refer to DbTables need to be recompiled. In this case (at least in Delphi 7) the units DBLookup and QuickRpt. You can simply remove the former from the uses clauses in which it appears, as it's just a remnant from past times, but you usually don't have the source for the latter (which is the main unit of Quick Reports).

So, go for option 1 and that's it. The application is still using the BDE at design time, but will be using dbExpress at run time. Run the application and test it to verify that everything is still working correctly.

Using the component substitution technique

With this technique, you replace all BDE components with equivalent InstantBDExpress components. This is the longest path, with manual changes that we are showing so that you can see exactly what's going on.

1) Using TIBDXDatabase instead of TDatabase:

• Open the DataMod unit, disconnect the database component (which will automatically close all tables and queries) and trigger the data module's View as Text command.

• Replace TDatabase with TIBDXDatabase

• Remove the property Params.Strings

• Select the View as Form command, set LoginPrompt to True through the Object Inspector and try connecting the database component

• Save and confirm that the class name should be changed in the source file as well. Delphi will do that automatically.

2) Using TIBDXQuery and TIBDXTable

• With the DataMod data module open, select the View as Text command

• Search & Replace TTable with TIBDXTable

• Search & Replace TQuery with TIBDXQuery (pay attention not to accidentally rename the CustQuery component: do a case-sensitive S&R)

• Search & Replace TFloatField with TIBDXFloatField

• Search & Replace TStringField con TIBDXStringField

• Search & Replace TBooleanField with TIBDXBooleanField

• Search & Replace TCurrencyField with TIBDXCurrencyField

• Search & Replace TDateTimeField with TIBDXDateTimeField

• Search & Replace TIntegerField with TIBDXIntegerField

• Select View as Form, save and confirm that the class names should be changed in the source file as well. Again, Delphi will do that automatically

• Search & Replace TDBDataSet with TIBDXDBDataSet

Nota: changing all field class names is not really needed for this application; the only truly required change is using TIBDXDateTimeField, which adapts a dbExpress timestamp to Delphi's TDateTime type. The steps above outline what you will generally need to do in more complex applications. Furthermore, TIBDXQuery and TIBDXTable will create TIBDX...Field instances when you select their Add All Fields command, so it's best to rename everything also for consistency.

It's usually quicker to perform the Search & Replace operations through GReplace, although in this simple case you can do it by hand as described above.

Removing BDE support completely

It is now time to clean up all BDE-related remnants from the DataMod unit:

• Delete the DbTables unit from the uses clause

• Build All: check thata everything is compiled without errors.

Testing the converted application

It is desirable to add a command to explicitly connect to the database to the program's main form. Now you can run the application and test it.

Troubleshooting

If for some reason you can't follow these steps, you can find pre-converted MastApp applications in the demos folder of InstantBDExpress' installation directory: the MastAppInterposer unit is converted using the interposer unit technique, while MastAppIBDX contains the application converted through the component substitution technique. These will help you to double-check your work and find what went wrong.