Developing a Database Application:
The dBASE Plus Tutorial
Ken Mayer, Senior SQA Engineer, dBASE Inc.
Michael Nuwer, dBASE user
|
Developing a Database Application:
|
|
Building and Deploying the Executable |
The goals of Phase IX of the tutorial project are:
Talk about coming into the home stretch! The next part of any application is building the executable (.EXE) that the user will actually be running.
dBASE Plus supports a functionality that is called Dynamic External Objects (DEO). This is a really spiffy technology. DEO provides the ability to run an application from a collection of external object files. In other words, the object code that is created when a program's source file is compiled no longer have to reside in an executable file in order to run.
This architecture has a number of advantages. First, the executable is now very small, perhaps as small as 50k. This kind of tiny executable loads very quickly and uses less memory than an executable that includes all the compiled code. Under DEO, only the pieces of an application that are in use get loaded into memory. And they are unloaded when no longer needed. For this reason DEO uses much less memory and hence, runs faster.
Another advantage of DEO is that it provides the ability to update an application by replacing the object file (a WFO or a REO etc.), rather then an entire executable. Perhaps you need to fix a bug in an application that is already running at your client's office, or your client want's some additional data displayed in a report. After you update your code, you will only need to drop the one recompiled file onto your client's system and the application is updated. Moreover, if your application is running in a networked environment, all the workstations will be updated with this single act.
The executable that we will create for running the Tutorial application is going to contain one line. It's purpose is to run the Start.prg program. This should be easy to do. Open a new program file and enter the following line:
do start.prg
Save this file as "Tutorial.prg".
To compile this program file, switch to the command window and type the following:
compile tutorial.prg
Next we need to build the new object file into an executable file. The Build command is used to link a compiled program into a Windows executable. In addition to linking the compiled program, we will include an icon to identify our application in the windows environment and a splash file that will display while our program loads.
We need to, first, be sure that the icon file and the splash file are in the dBASEtutorial folder. Use the Navigator (the Images tab), or the Windows Explorer and look for Mugs.ico and MugsLogo.bmp in the dBASEtutorial folder. If either file is missing, get it from the dBASEtutorial.zip archive. These two files were distributed along with the other setup files.
Back in the Command Window. We are now ready to build the executable. Enter the following command:
build tutorial.pro icon mugs.ico splash mugslogo.bmp
Note: The application icon file is going to be deployed along with the application. The splash file is stored in the executable when it is created, and unless you also want to use this image in your application somewhere (on a form, a report, whatever), then you do not need to deploy it.
It can't get much easier. We now have an executable program file (tutorial.exe) that will launch our application. The next thing we need is the application's .INI file.
The Initialization File
Before we actually get to the deployment of our application, we need to create
a .INI file for the application. This file is very important to insure that
your application works the same when deployed as it does when developing it.
This file contains setup information that can be quite useful, but it must be the exact same name (except for the extension) as the name of the executable. So in our case we created an executable named Tutorial.exe, and need an initialization file named Tutorial.ini.
The following information should be contained in this file (and based on aspects of any real-world projects you create, you may need other settings in the .INI as well). One way to create a .INI file is to simply type, in the command window:
modi comm Tutorial.ini
This will put you in the dBASE Plus source editor. You should have the following in your .INI (the EPOCH setting is up to you, but 1950 is a good date for it.):
[CommandSettings] EPOCH=1950 [OnOffCommandSettings] CENTURY=ON LDCHECK=OFF BELL=OFF TALK=OFF [CommandWindow] Open=1 Maximized=0 Minimized=1 [Toolbars] Standard=0 Format=0 [ComponentTypes] ComponentTypeNumeric=1 ComponentTypeDate=1 ComponentTypeLogical=0 ComponentTypeMemo=0 ComponentTypeBinary=0 ComponentTypeOLE=0 ComponentTypeNumericForTables=1 ComponentTypeDateForTables=1 ComponentTypeLogicalForTables=0 ComponentTypeMemoForTables=0 ComponentTypeBinaryForTables=0 ComponentTypeOLEForTables=0 [Desktop] Maximized=1 [ObjectPath] objpath0="\dBASEtutorial\deploy\objects" [ErrorHandling] ErrorAction=5 ErrorLogFile=TutorialError.log ErrorLogMaxSize=100
(The Object Path is added here for testing purposes. It will be changed when the application is deployed. The Error Handling section will send any error message to both the screen and a log file. This way if your users report an error, you can view the error file for the exact details -- something the user typically doesn't remember.)
Save this file and exit the Source Editor.
The tutorial application is now ready to run outside the dBASE Plus development environment. So, the next thing we need to do is deploy our application to another computer. In order to do this, however, we must first collect all the files that need to be deployed and place them in a common location.
We are going to use the folder called "Deploy" which is a subfolder of c:\dBASEtutorial. The Deploy folder was created back in Phase I when you unzipped the tutorial files onto your computer. In that folder there are a few utilities that we will be using.
But first you should create three new folder under the Deploy folder. You can use Windows Explorer to do this. Name the first new folder "Root", the second "Objects" and the third "Tables". We need to copy our deployable files to these folders.
First we need to copy three files to the folder named "Root". With the Windows Explorer still running find "Tutorial.exe", "Tutorial.ini", and "Statements.sql" and drag (or otherwise copy) them to the Root folder. (You can select multiple files in Windows Explorer by holding down the Ctrl key when you click the mouse.) These files will be deployed to the main application folder on the client computer.
Next we will copy the object files. The Objects folder is where we will place all our application's object files. These files can be deployed to a subfolder on the client's PC or they can be stored on a file server.
One easy way to copy the object files is to arrange the Windows Explorer icons by "type". Select the "View" Menu item, then select "Arrange Icons | by Type". All the dBASE Plus object files are now grouped together. You can begin by selecting CutomReportControls.co and the other custom classes. Coping these files to the Objects folder:
Next are the Datamodules. There should be seven of these:
Next are the Form objects. Select and copy these files. (Do not deploy CustomControls.wfo. This form was used to help us make the custom components and is not needed in the application.)
Following the form files are the Customer Labels, Tutorial Menu, and four Report fields. These should also be copied.
The final four object files are compiled PRGs. We do not need to deploy Configure.pro nor tutorial.pro, but we do need setup.pro and start.pro. So copy these last two files to the Objects folder.
There is one additional files in \dBASEtutorial that must be copied to the Objects folder. That file is mugs.ico which is the icon file used on our forms.
NOTE: If you are really paying attention, when you run the "working version" of the application you will note that each form uses the same icon as the one we assigned to the .EXE. This was done by setting the icon property in the BASE.CFM file ... just in case you were wondering ... For this to work, you must deploy the icon file.
At this point the Objects folder should have 35 files.
The last two files that must be included with a deployed application are report.co and seeker.co. These files are part of the dBASE Plus core product and will be found in the the "dBLClasses" folder of the dBASE Plus root folder. The location of this root folder depends on were you installed dBASE Plus. On my system it is: "D:\dBASE\Plus\dBLClasses." Locate this folder on your system.
You will find report.co in "ReportControls" and seeker.co in "FormControls". Copy these two files to the Object folder.
Now you should have 37 files in the Objects folder.
Test The Executable
Of course, in a normal situation you don't have a tutorial reminding you to
put each file in the Objects folder, so you should always test the executable
to make sure that everything works.
You can do this from where you are right now by double clicking "Tutorial.exe".
Notice that when you do that you should see the splash screen come up and then the application framework with your menu, your application title, and the icon we selected in the title bar.
Try each menu option and make sure it works properly.
Once you have tested everything, and if something is missing the error message is pretty straightforward, it is time to deploy the application.
Copy the Tables
Your executable is using the database that you created for developing this application.
When we deploy the application we must remember to include the tables. At this
point you can copy the tables from c:\dBASEtutorial\tables to c:\dBASEtutorial\deploy\tables.
You should include the following files in the database folder:
The data tables:
The index files:
The memo/binary files:
(If you drag and drop the files in Windows Explorer be sure to hold down the Ctrl key so that you copy, rather than move, the files.)
The files that we are collecting for deployment contain data. When you deploy your own application to your clients, you may want the tables empty. To do this, take a look at c:\dBASEtutorial\tables\CopyData.prg. That program file has code to empty the tables and reset the Autoincrement numbers.
We are now ready to Deploy our application. I recommend trying, if you can, to deploy onto a machine that does not have dBASE Plus on it, or any dBASE Plus applications. If you don't have a spare machine to deploy the tutorial application we can simulate the deployment on your development machine.
The first thing we need to do is to get the deployment files to the computer where the application will be installed. You can copy all of them to a writable CD or a zip disk; or you can make then accessible over a network; or you can put them on floppy disks and copy them to a tempory location on the client machine.
The folder structure on your "install disk" should be as follows:
<ParentFolder>\Root\
<ParentFolder>\Object\
<ParentFolder>\Tables\
The ParentFolder can be the root of a disk (like a CD) or it can be a subfolder (like a network drive).
At this point you can copy all the files in \dBASEtutorial\Deploy and its subfolders to the ParentFolder on the "install disk". The exact procedure will vary depending on the medium you use.
There is one more file that you will need for the deployment. On your dBASE Plus CD there is a folder named "Runtime". This folder contains a set of runtime installers that will do everything we need. The following files are in the Runtime folder.
dBASEPlusRuntimeEngine.exe dBASEPlusRuntimeEngine_ES.exe dBASEPlusRuntimeEngine_EN.exe dBASEPlusRuntimeEngine_DE.exe dBASEPlusRuntimeEngine_IT.exe dBASEPlusRuntimeEngine_JA.exe
Each of these files will install the dBASE Plus runtime files and the BDE. The differences are related to the language support files. The first file in the above list will install support files for all the languages supported by dBASE Plus. The other five files will install support files for only one language. For example, dBASE PlusRuntimeEngine_DE.exe installs the dBASE Plus runtime files, the BDE, and language drivers for German.
You should use the runtime installer that supports the language you are working with or use the installer that supports all the languages.
Copy the runtime installer to your "install disk". (If the file is too large for the medium that you are using, you can run the runtime installer directly from the dBASE Plus CD.)
Now we are ready to move all the files to the client computer and proceed with the installation. There are two steps to our deployment.
First we need to install the dBASE Plus runtime files and the BDE. Double-click the dBASEPlusRuntimeEngine file and an installation will begin. Proceed through the intallation steps to install the dBASE Plus runtime files and the BDE.
The second step to our deployment is coping the tutorial application files to the client computer. This can be done manually or it can be done using a Tutorial setup utility. We are going to use a utility and explain each of the tasks it performs.
Use Windows Explore and, on the "install disk," navigate to the parent folder. In this folder you should find a file called "setup.exe." Double click this file to run the setup utility.
Default information is already filled in on this form. The Tutorial Application's executable file will be installed to c:\dBASEtutorialApp. The object files will be installed to a folder called "Custom" under "dBASEtutorialApp" and the Tables will be installed to a folder called "Tables" which is also under "dBASEtutorialApp". The database alias that will be created is called "dBASEtutorial".
If you are satisfied with these setting, you can click the "Install" button and the files on the "install disk" will be installed to the appropriate folder on the client computer.
Make the appropriate change if you want to use an alternate location. One common setup is to put the tables and the object files on a network file server. Then install the Program files to a location on the local hard drive. (In all cases the runtime and BDE files must be installed on the client. Ultimatly, it is the client's CPU that will run the application.)
The source code for this install form can be found in \dBASEtutorial\Deploy and you are welcome to modiy it to suite your own needs.
The "Install" buttons will execute the following tasks:
We are storing the object files in a location other than the application's root directory, therefore we must declare the object path in Tutorial.ini. Otherwise the EXE will not be able to find it's object files. The object path will look something like the following:
[ObjectPath]
objpath1="C:\dBASEtutorialApp\Custom"
objpath2="C:\dBASEtutorialApp\"
(It is perfectly valid for the object files to sit on a file server share and the exe to sit on a local workstation. You can even use a UNC path to the objects, i.e., \\server\share\folder.)
The last thing you should do to complete the installation is create a Windows short-cut on the desktop.
Test the deployement and you're done!
Last Modified: November 11, 2002
The Legal Stuff: This document is part of the dBASE Plus Tutorial created by Ken Mayer. This material is copyright © 2001, by Ken Mayer. dBASE Plus is copyrighted, trademarked, etc., by dBASE, Inc., the BDE (Borland Database Engine) and BDE Administrator are copyrighted, trademarked and all that by Borland, International. This document may not be posted elsewhere without the explicit permission of the author, who retains all rights to the document.