Phase I: Introduction
The database application that we will be creating in this tutorial is a step-by-step type project. The project will progress from designing the tables to the forms through to the reports, before getting into the application's startup program and its deployment. Not all developers follow this path, so if it is not one you are used to, don't sweat it -- it's just one method of accomplishing the task.
Please do not skip a step. There will be a combination of hands-on work, and explanations of why you are doing these things. After you have performed some steps at least once the directions may not repeat the next time you need to do those same steps -- the idea is to get you used to doing them without hand-holding, and to also get you used to the idea that when all-else-fails, you can look things up.
When done with each section there is a link back to the menu, or you can continue to the next section directly (links to the next section are included at the bottom of the different html documents).
There are a lot of notes (indented text with lines on the top and bottom) -- you should read these. They are attempts to explain the whys and wherefores, or to explain bugs and bug workarounds (if it's a bug, we call it a bug in the tutorial -- there's no reason to "Beat around the bush" here). Many of these were added during the initial "beta" cycle of this tutorial, where a group of developers ran through the tutorial and pointed things out to the authors -- these notes expand on the rest of the tutorial. Don't skip them!
Keep in mind that this is just one way to create an application. We can pretty much guarantee that no two applications are going to be exactly the same -- each client you have will have different requirements, and the more you learn about the software, the more your own development techniques are likely to change.
There are many documents in the dBASE Knowledgebase -- and a note where to find the same information in Ken's The dBASE Book, that you should review as supplemental reading for this tutorial. It is strongly suggested that you read these documents or chapters of The dBASE Book. The material in them would take too long to cover in detail here, so it is a good idea that you read them along with this tutorial. They cover many of the same issues but in greater detail. (Ken wrote a good portion of the cited articles, and they were the foundation for The dBASE Book, just to put this into perspective. The material in the book will be more up-to-date than the Knowledgebase articles which have not been updated since they were written.)
|Knowledgebase||The dBASE Books|
|Using the Designers in dB2K||The dBASE Book, Chapter 12|
|Beginning Data Objects in Visual dBASE 7||The dBASE Book, Chapters 3-5|
|Working with the Form Controls in Visual dBASE 7.01 up to dB2K||The dBASE Book, Chapter 14-16|
|Working with Custom Classes in dB2K||The dBASE Book, Chapter 17|
|Beginning Forms||The dBASE Book, Chapter 13|
|Creating and Using Custom Forms in dB2K||The dBASE Book, Chapter 17|
|Multipage Forms||The dBASE Book, Chapter 13|
|Working with the Grid Control in dB2K||The dBASE Book, Chapter 15|
|Beginning Reports||The dBASE Book, Chapter 20, The dBASE Reports Book|
|Tricks With Reports and Labels||The dBASE Book, Chapter 20, The dBASE Reports Book|
|XBase DML to OODML||The dBASE Book, Chapter 8|
|Misc. Code, includes various tricks/tips.|
|Undocumented Database Classes and Other Undocumented Features||The dBASE Book, Chapter 7, Appendix 5|
You need to create a directory off the root of a hard drive on your computer called "dBASETutorial". (Well, it does say what it means, doesn't it?) The reason for this is so that everyone is working with as close to the same setup as possible. This will hopefully make more sense once we get into things like the database alias and such that we will be setting up.
You will want to download the file "tutorial.zip" (below), and unzip it to a folder for the tutorial. This file will include the starting data, a few files that you don't want to recreate, and a basic folder structure to work in.
The files you need to download for the tutorial are here:
The simplest way to do this is with Windows "File Explorer" in Windows 10. A "Folder" is the same as a "Directory" and throughout this tutorial we will use the terms interchangeably.
Unzip the file (above) "dBASETutorial.zip" to that folder. In Windows 10 in the Windows File Explorer, double-clicking the zip file will open it, you can then copy and paste the contents (<Ctrl>+A to select all, then <Ctrl>+C to copy; then navigate to the new folder "C:\dBASETutorial" or whatever you called it, and press <Ctrl>+V to paste the files and folders into it), which will give you your starting files and folders.
What you should see:
You will be creating everything else that you need, including the folders necessary for the project.
This project is going to be a fairly simple Customer Order and Invoice system. This will require several tables, several forms, at least a couple of reports. The tables will include a couple of lookup tables, relational tables (Invoice Inventory, etc.), and more. There are aspects of a "real-world" Inventory system that will not be included in this application. This is a learning application; consider it to be one with training wheels. Once we take the training wheels off, you can add whatever flourishes you need to.
To start we will create some tables, but ultimately we are going to copy some of the sample tables that ship with dBASE™. By copying them, we don't have to worry about modifying the original data.
If you follow along in the order shown in the tutorial menu (above), by the time it is complete you will have created an application from scratch, tested it, and deployed it. This should give you a good grounding to go out there and start building your own applications, which is the idea of this tutorial.
This is a very brief specification of the details for this project.
(If you are a professional developer and do a lot of contract work, you should be familiar with the specification process -- this is not going to come close to what you would need from your customers for a paying gig, it is just here to give you, the student, an idea of what we will be doing for this project.)
The application will be a multiple-document interface (MDI) application, with a menu (but no toolbars). This will allow the user to open multiple forms at once, including the same form multiple times.
There must be:
This is not a very complex application, but we will take advantage of a few special features of dBASE™ PLUS as we go. In order to make customization easier, we will be using custom forms, custom reports, custom datamodules, and custom controls.
We cannot emphasize enough that the techniques shown here are simply one way of coding an application, and that there are many more methods of doing the same things, and of course, no tutorial application can possibly cover every situation that every client you may have will need. This is a learning tool only, and as such cannot possibly cover every possible contingency. Have we put enough disclaimers into this project yet?
While it is a good idea for you to see this application working before creating your version, I have chosen in the rewrite for 2017 to not include a compiled version of the application. The reason for this is simple: every time there is a major update to dBASE™, the executable starts to fail because it was not compiled under that version. The amount of maintenance required to constantly update the executable (rebuild, recompile, upload, etc.) is enormous, with dBase, LLC putting out a major version of dBASE™ approximately every year, with minor updates in between. Hence, the "walkthrough" has been removed from the tutorial.
The dBASE™ PLUS IDE Environment
This project assumes that the Navigator and the Command windows are both on screen. If they are not, you should go to the "View" menu, and select the missing windows, so that both appear on screen. Their locations are not important -- you can move them and/or resize them as you like. (You may even want to use the "Window" menu to "Tile" these windows so that they are next to each other. Our personal preference is to have the navigator on top and the command window on bottom.) It is, however, important to have both available at all times.
You should also bring up the dBASE™ PLUS Desktop Properties dialog. Then with focus at the command or navigator windows, the menu "Properties" should be displayed -- select this, and then select "Desktop Properties". In this dialog, make sure that the following settings are done:
Now click the "Apply" button then the "OK" button.
The Navigator may have an entryfield titled "Also look in:" under the "Look in:" combobox. If this is the case, you should remove the combobox while working with the tutorial. This can be done from the Properties, Navigator Properties Menu. Un-check "Use Supplemental Search Path."
If you have not used a Supplemental Search Path they can, at times, be handy. The following is from Online Help: Use Supplemental Search Path - If checked, adds an additional search path text box (called "Also Look In:") to the Navigator. When a path name appears in both Look In boxes, dBASE™ PLUS displays files in all the directories specified in both Look In boxes.
Clearing Out Custom File References
This is important!! Before you start working on any new application, it is completely possible that you may have used custom Forms or Reports in the past. To avoid any complications in what we are doing for the tutorial, do the following (repeat as shown):
Repeat the steps above for the Reports tab. This will clear out references that may cause some frustration or grief later in the tutorial. Note: following the steps given above before starting any new project in dBASE™ PLUS is a good idea.
Navigate to the folder for the tutorial ("dBASETutorial" if you followed along earlier), using the Navigator in dBASE™ itself. If you have never done this, click on the "Folder" button in the Navigator window on the right, and select the folder:
To start out we are going to create a file called "configure.prg" to help configure the working environment in the IDE. This will have four commands to start, and as we move forward we will add more.
In the Command Window, type:
create command configure.prg
pressing the Enter key after the last character. This will open the Source Code Editor in dBASE™ PLUS. Type the following four statements:
_app.speedbar := true _app.statusBar := true _app.tabBar := true // only works in dBASE™ PLUS 8 or later set design on
When you have typed these, press <Ctrl>+W (save and exit the editor), and in the Navigator window, click "Programs". You should see this file. Double-click it to test it. If you get any errors, correct the typo, and try again.
While developing the tutorial application, your program will, from time to time, crash due to programming errors. At times our application will turn off the speedBar, statusBar, tabBar and design mode. If the application crashes after this, we can simply run configure.prg to turn them back on.
Later in the tutorial we will create some custom controls for use in our forms and reports. At that time we will add the appropriate lines of code. Then, when configure.prg is run, our custom controls will be available to the Form and Report designers.
This is a fairly lengthy project, and there is a lot of reading to do, especially if you follow the advice to read the KnowledgeBase documents as they are suggested.
In order to help out here are some hints that may make the whole thing a bit easier.
Printing the Tutorial
This thing is huge. You can, if you wish, print it out -- but be prepared for the fact that doing so will use a lot of paper! There is no simple way to "print it all in one shot" -- you will need to bring each document into your browser and print them one at a time.
Stopping And Picking Up Where You Left Off
As this is such a long project, you will need to take breaks. We don't expect that anyone is going to do the whole project in one sitting.
In addition, some folk may have projects that they are working on and need to switch over to those.
When you stop, note where you were in the tutorial.
Then, when you return to working on the tutorial project restart dBASE™ PLUS. If you had it up on screen, you may want to close it down and restart it, just to clear any resources that might have been in use. If you are using BDE Aliases in other projects, you may want to use the "CLOSE DATABASE" command to close any open BDE Aliases.
In the Navigator window, make sure you are pointing to the dBASETutorial folder (C:\dBASETutorial, or wherever you are working on it).
As you work through the tutorial there will be places where it will be necessary to add code to your forms or reports.
The code is laid out in the tutorial for you, it has comments embedded in it, and there is some extra commentary (in the tutorial text) outside the code explaining it. You have several options for entering the code:
When working in the form or report designer the "Source Code" window will stay open until you either explicitly close it yourself, or close the form (or report). If you look at the "Windows" menu you should see the form (or report), and the "Source Editor" window listed. You can select it at any time while working on a form (or report) unless, as noted, you close it.
Save Your Work Often
We cannot emphasize enough -- in any design surface, use the <Ctrl>+S key combination to save your work often. Any time you add code, save the form or report. Any time you have completed adding a series of controls, save your work; this can save you a lot of hassle later.
Wizard or Designer?
There are wizards built in to dBASE™ PLUS for the various designers. For our purposes, except when it comes to the mailing labels (in the reports part of this tutorial), we will only be using the designer.
When you double-click on a "[New <object>]" (where <object> is something like "Form", "Custom Form", "Report", etc.) icon in the navigator (as instructed throughout the tutorial), in many cases you may be asked if you wish to use the Wizard or the Designer. You should select "Designer" unless instructed otherwise.
You could go into the properties menu of dBASE™ PLUS and turn this question off for each of these -- the Properties menu has at least two options normally, one for "Desktop Properties" and one for whatever other tool is open. Select "Desktop" properties, and then find the "application" notebook tab -- select this. On the left are checkboxes for the design surfaces -- uncheck them, and you will not get the query about using the Wizards or the Designers.
This is a preference issue, however -- if you would rather be prompted, leave things as they are and make sure unless told otherwise in the tutorial to select the Designer.
Ok, some of the folk examining this tutorial may feel like they already understand how to create tables, or some other aspect of what is being discussed in the tutorial. For you smarty-pants types, you can copy files that are complete from \dBASETutorial\final_code.
For example, if you feel pretty comfortable with creating tables and indexes, you may want to simply copy all of the .DBF, .MDX and .DBT files from \dBASETutorial\final_code\tables into the \dBASETutorial\tables directory and then move on to the data modules section.
One caveat: in most places the file paths are not hard coded in the source code. However, if you wish to work with the Project file (tutorial.prj) or the Inno Setup Script (tutorial.iss) you would need to a) copy them to the main dBASETutorial folder, and then b) open them in the appropriate source code editors (for Inno Setup, double-click the file and it will open the appropriate screen), changing the hard coded paths that include the user name (in these files you will see "ken_000", which for whatever reason is the username on my development computer -- that would need changing, as well as any other paths ...).