Developing a Database Application:
The dB2K Tutorial
Ken Mayer, Senior SQA Engineer, dBASE Inc.
Michael Nuwer, dB2K user
Last Modified: October 13, 2001
Version 2.2.0
|
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.
With dB2K a new functionality is added 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 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 a 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 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 dB2Ktutorial directory. Use the Navigator (the Images tab), or the Windows Explorer and look for Mugs.ico and Skyline.bmp in the dB2Ktutorial directory/folder. If either file is missing, get it from the dB2KTutorial.exe archive file. 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 skyline.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 in the previous step of this tutorial the file Tutorial.exe, we need a 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 dB2K 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="\dB2KTutorial\deploy\objects"
Save this file and exit the Source Editor.
The tutorial application is now ready to run outside the dB2K 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 needed 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:\dB2KTutorial. 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 dB2K object files are now grouped together. You can begin by selecting genericMDIapp.co and the datamodule objects. Coping these files to the Objects folder:
Next are the Form objects. Select and copy these files.
Following the form files is 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 \dB2KTutorial 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 27 files.
But wait, there are more needed files in \dB2KTutorial\MyCustom. Select that folder with Windows Explorer and copy the following files:
(CustomControls.wfo is not included in our application and does not need to be deployed with the other object 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 dB2K core product and will be found in the the "Classes" folder in the dB2K root folder. The location of the dB2K root folder depends on were you installed dB2K. On my system it is: "<dB2K_Home>\Classes."
Locate this folder on your system and copy report.co and seeker.co 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:\dB2KTutorial\tables to c:\dB2KTutorial\deploy\tables. You should include all the files in the database folder except the .ZIP file. (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 tables 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:\db2ktutorial\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 dB2K on it, or any dB2K 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 a 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 \dB2KTutorial\Deploy and its subfolders to the ParentFolder on the "install disk". The exact procedure will vary depending on the medium you.
There is one more file that you will need for the deployment. On your dB2K 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.
dB2KRuntimeEngine.exe dB2KRuntimeEngine_ES.exe dB2KRuntimeEngine_EN.exe dB2KRuntimeEngine_DE.exe dB2KRuntimeEngine_IT.exe dB2KRuntimeEngine_JA.exe
Each of these files will install the dB2K 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 dB2K. The other five files will install support files for only one language. For example, dB2KRuntimeEngine_DE.exe installs the dB2K 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 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 dB2K 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 dB2K runtime files and the BDE. Double-click the dB2KRuntimeEngine file and an Install Shield installation will begin. Proceed through the intallation steps to install the dB2K 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 dB2K 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:\dB2KTutorialApp. The object files will be installed to a folder called "Custom" under "dB2KTutorialApp" and the Tables will be installed to a folder called "Tables" which is also under "dB2KTutorialApp". The database alias that will be created is called "dB2KTutorial".
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.
The source code for this form can be found in \dB2KTutorial\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:\dB2KTutorialApp\Custom"
objpath2="C:\dB2KTutorialApp\"
(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!
The Legal Stuff: This document is part of the dB2K Tutorial created by Ken Mayer. This material is copyright © 2001, by Ken Mayer. dB2K 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.