Beginners corner Part 1
The dBASE interface
an Integrated Development Environment (IDE)
by Jean-Pierre Martel, editor of the dBulletin

Introduction

This document is the first in a series of articles aimed at beginners who would like to use dBASE as a programming tool. This series will help you to realize what an outstanding technological work dBASE is, yet easy to use for database management. Moreover, dBASE allows you to create and to distribute Windows applications without having to pay royalties since you are the author.

This series will apply to the most recent versions of dBASE. The only big difference between these versions and the ones before is a new way to access data that respects object-oriented-programming. Since all Windows versions of dBASE look about the same, many of our chapters will also be valid for Visual dBASE 5.x users. As much as possible, we will try to indicate the differences between these versions.

Our goal is not to write the bible of dBASE, but rather to give you the essential notions the novice needs to know to use dBASE effectively.

The dBASE interface

First of all, dBL (the programming language used by the 32-bit software sold by dBASE, Inc.)  is a programming language on top of which an interface was grafted. The latter will help you to learn dBASE but, except for the Source editor, doesn't give you access to all the power dBL is capable of. On the other hand, as we will see in the chapter about forms,  it is possible to make simple Windows applications even if someone doesn't know much about dBL.

When dBASE opens, its interface consists of the followings parts:

The contextual menus

Exploring the menus is a good way to discover their richness and to learn their shortcuts. Yet dBASE will reserve some surprises for you since its menus differ according to the context. For example, when you use the Form designer, some floating palettes will appear and some new items will be found in the menus. So, when you have become a dBASE veteran, don't be surprised to discover items in the menus that you never noticed before.

Except for macros, ordinary Windows applications (word processor, spreadsheet, utility software, etc.) create few kinds of files. On the contrary, programming software creates a large number of file types. For example, dBASE can create tables, queries, programs, forms, and reports; in a nutshell, files that have very little in common. That variety explains the nineteen kinds of files that you have to choose among in the Type drop down list of the File Open dialog box, and the fourteen kinds of files among which you have to choose when you want to save a document in the Source editor.

The Toolbar

The meaning of symbols on the Toolbar buttons are obvious enough that I probably don't have to give details about them. However, if the meaning of one of them is not clear to you, point to it with the mouse cursor, leave it there for a few seconds, and a speed tip will appear and give you its purpose. Like the menus, the dBASE Toolbar is contextual. Different tools will appear according to the context.

To decide which tools will be available in the different dBASE modules, go to the menu item View|ToolWindows|Customize ToolWindows Under the Tool Windows tab of the toolbox that appears, various checkboxes allow you to configure your working environment as well as to decide the features of the tool buttons. You can access that dialog box directly when you right-click the Toolbar.

The Toolbar can be transformed into a floating palette. With the mouse, grab its right side, the separators, or the surface beneath the buttons, and drag it anywhere onto the desktop. Once it is a floating palette, you can put it back in place or close it by clicking on the 'x' in the upper-right corner. You can make the Toolbar appear or disappear at will through the menu item View|ToolWindows|Standard Toolbar (see the image above).

The Navigator

The dBASE Navigator has the same purpose as the Windows Explorer. And, as with Explorer, the user can change the size of the icons and their order through the View menu.

NavigatorIn the image on the left, some items in the Navigator have been numbered to facilitate comprehension of the text. Button allows you to change the working folder (whose name appears in ). When the user clicks on button , the combobox opens and displays previously accessed working folders (Tip: Just move your mouse cursor over the image  to the left to open the drop down list.) When you click on any item in that opened combobox , that item becomes the working folder. The tabs display certain types of files in the working folder and acts as a kind of filter that allows you to rapidly find the file you are looking for. The Other tab is the only one that offers you the opportunity to decide the file types to be displayed in the Navigator. When the cursor has been placed somewhere within the list of files in the working folder, just type the first letter of a file name to go immediately to the first file whose name begins with that letter.

The first item in the file list is always Untitled. It offers a practical means of creating a new item. You just have to double-click on it (or select it and push the Enter key) to open the Source editor (if it is a program) or to open a Wizard (in most other cases).

When you double-click on any item other than Untitled, you will execute that item. There are two exceptions to that rule: if you double-click on an image, an image viewer will appear; if it is a wave file, you will play it. If you right-click, a popup menu appears.

If your Navigator window is not visible on your screen, any of the following reasons could be the cause. First, the Navigator window could have been closed. If this is the case, its name doesn't appear in the numbered list of opened windows at the bottom of the Windows option on the menu bar. The Navigator can be opened if you select the View|Navigator menu item. Second, the Navigator might be open but masked under another window. If so, use View|Navigator or Window|Navigator to put it at the forefront. (Note: The Ctrl-F6 shortcut will also put it at the forefront, but won't show the Navigator at its normal size if it is minimized.) Third, the Navigator can be somewhere on the dBASE desktop, but out of the view. The solution is to use the scrollbar to find it. If none of these techniques work, quit dBASE, delete the vdb.ini or db2k.ini file (in dBASE's \BIN sub-directory) and restart dBASE. The latter will create a default .ini file and will appear as it was the first time you loaded it.

The Command window

The Command window has two parts: the input pane and, usually under it, the results pane. You can move and resize the two panes only as a single unit, but you can move the dividing line between the panes to alter their share of the combined space. That Command window is one of the advantages that dBASE and its clones have over other programming software. Just type any command to run it at once (without having to create a program, compile it and run it). So you can test any line of code to know if it gives you the result you expect.

You can change the font used in the results pane using the Properties|Command Window Properties menu item. (If you don't see it, it is because the cursor is not in the Command window.) You can get to the Command Window Properties dialog box directly when you right-click on the Command window. The first tab on the left allows you to change the display of the results pane. You flush the content of the results pane with the clear command typed in the Command window or through the Edit|Clear All Results menu item (available only when the cursor is in the Command window). Pressing the Esc key will clear the current line.

Now, lets do the following exercise. We will change the text that appears in the Title bar. Instead of Visual dBASE, for example, your name will be displayed. Don't worry, that will last only until you close dBASE. Everything will be back to normal the next time you will run dBASE. First, click anywhere in the Command window if the cursor is not already there. Then type the text below, replacing my name with yours (don't forget the quotes or the underscore before app: it is _app, not app). The quotes could be replaced with single quotes ' ', square brackets [ ], but not curved quotes , nor French quotes « ». Curved brackets { } can't be used here either since they are used for other purposes. If you are afraid to make a mistake while typing this code, just cut & paste between the dBulletin and the Command window.
 
 
_app.frameWin.text = "Jean-Pierre Martel"
   

Your name (or whatever text you typed) is displayed in the Title bar. Those of you who know other programming languages will note that we don't need a sign (for example, a semi-colon) to tell dBASE that the line is finished. The carriage return is enough for it to know that the line is finished and it has to run the code. Neither do we need additional words (e.g., sub/end sub) or some signs (e.g., curved brackets) to indicate where the code starts and where it ends, as other programming languages may need. dBL is thus less rigid than many programming languages.

Now we will do better. We will minimize dBASE. In other words, we want it to disappear from view and take its place in the Windows Task bar.
 
 
_app.frameWin.windowState = 1
   

Click on the task bearing your name (dBASE is now called by your name, isn't it) so that the application returns to its original state.

You might see that in the example before, the value given to _app.frameWin.windowState, which is 1, doesn't need to be between quotes. Why? Because it is a number. Numeric values don't need quotes. So why does the left part of the equation not need quotes? Isn't that a string of text? Yes, but only string values need quotes. dBASE distinguishes between variables and properties from their string values by the quotes that the latter need.

Let's take an example (illustrated in the pale grey area below). In the Command window, let's create a variable x and let's give it a value of 2. If you type ? x (in other words, if you ask what is the value of x), the results pane will answer 2, of course. If you then type x = x + 1 (x will be equal to its previous value incremented by 1. In other words, we add 1 to the actual value of x), ? x will give 3. That's obvious. But if we type x = "2", then x = x + "1", the value of x will be "21". That's not the number 21 but rather the combination of two strings, both of which happen to be numbers. dBASE doesn't even try to understand the meaning of such a construction. For dBASE, to add a "1" at the end of a "2", it's like adding "2001" at the end of "Year " (which gives "Year 2001"). That distinction is essential.

Note: There are many ways to add comments to dBL code. When you type two consecutive slashes, all the text typed thereafter on the same line will be ignored by the newest versions of dBASE. Visual dBASE 5.x users have to use two ampersands && instead.
 
 
x = 2
? x           // result : 2
x = x + 1
? x           // result : 3

x = '2'
? x           // result : '2'
x = x + '1'
? x           // result : '21'
 

If the distinction between numeric and textual values seems complicated to you, you may take relief in knowing that in other programming languages, it's worse. They would forbid you from transforming a numeric variable into a textual variable on the fly, as we just did. Not only would they have insisted on a formal declaration in advance of your intent to use a numeric value, but you would had been obliged to destroy that value before declaring the use of a different type of variable (bearing the same name), but of a textual nature this time. This recycling of variables on the fly is typical of the pliability of dBL.

On the other hand, dBASE insists on a minimum set of rules to prevent ambiguities. In the following example, on the second line, a variable called buys  is created and is given a value which is not the text "inventory", but rather the content of the variable inventory, previously created.
 
 
inventory = 5
buys = inventory
? buys       // result : 5
   

We will take advantage of this brief presentation of the Command window to create our first true program under Windows. We will create a dialog box with a title, some text, and a button. All this is done with a single line of dBL code. Beware: There should be no space between MsgBox and the opening of the parenthesis.
 
 
MsgBox("I can create Windows applications", " Kudos!")
   

Do you realize how simple it is to do Windows programming with dBL?  Just one short line of code was enough to draw all that.

Our last example illustrates something that doesn't work in the Command window but works perfectly when it is executed from within a program. Though lines have been numbered to facilitate our explanation, line numbers would never appear in a dBASE program.

Line 01 creates a variable x and gives it a value of two. As you already know, if we had wanted that variable to contain some text, that value would have been written between quotes, for example  x = "ten, in Roman numbers".  Line 02 will be read but will allow the execution of line 03 only if is worth a value of two, which is the case. Otherwise, line 04 would have allowed line 05 to be run if it would have been true. Line 06 tells dBASE that this is the end of the conditional block of instructions.
 
 
01  x = 2
02  if x = 2
03    msgBox("x is worth 2")
04  else
05   msgBox("x isn't worth 2")
06  endif
   

The Command window will stop the execution of that code at line 02 and will report the message Error: missing ENDIF. Why? Because when dBASE has to run some instructions, it always analyzes syntax first to check if it's appropriate. When these instructions are those of a program, dBASE checks for syntax errors throughout the entire program. It stops as soon as it finds an error. Since dBASE has to execute a line of code in the Command window as soon as the Enter key is pushed, it will analyze that line and report a programming error when it sees an IF that is not followed by an ENDIF. So what can we do?

One solution is to type each instruction into the Command window, ignoring the error messages as they come. Then, highlight the entire sequence of instructions and press the Enter key. Another solution is to type all the instructions on the same line, each instruction separated from the following one with a semi-colon. Among other purposes, this punctuation sign is used to combine many instructions into a single line of code. So the code to be typed in the Command window should be:
 
 
x = 2; if x = 2; msgBox("x is worth 2"); else; msgBox("x isn't worth 2"); endif
   

That long line of code is a lot harder to decipher than the numbered code we saw previously. Moreover, it is annoying that the Command window doesn't offer some means to save the code typed in it. But these are two reasons to use the Source editor, which is specially made to handle a complex set of instructions.

Since dBASE existed even before Windows was conceived, the former takes into consideration some habits prevalent under DOS, namely the use of function keys. To be compatible with the habits of its dBASE for DOS users, dBASE has shortcuts based on function keys F3 to F9. They work only from the Command window. To be honest, I use only F6 and F7. The other function keys (F2, F11 and F12) don't work from the Command window.
 
     
  F1  Help // on-line help
  F3  list // displays the list of records in the current table
  F4  dir // displays the list of tables in the working folder
  F5  display structure // displays the structure of the current table
  F6  display status // displays dBASE parameters
  F7  display memory // displays the dBASE variables in use
  F8  display // displays the actual record from the current table
  F9  append // adds a record in the current table
     

Note: You can use the UpArrow key to repeat a command in the Command window without having to type it again. This is quite useful when you made a typo. Let's do a test. Put the cursor in the Command window if it is not already there. Push F6. Then, after clearing any resulting message boxes, push the UpArrow key. The cursor will be moved to the beginning of the line that says display status. But before you push the Enter key, go to the end of that line and add to printer, so that the line will have become display status to printer. Then push the Enter key: the text will be printed in addition to being displayed in the results pane.

The Source editor

Some programming software creates binary files that can be read only by them. This is not the case with dBASE. Except for tables and compiled code, all the files created by dBASE are plain ordinary ASCII (DOS) or ANSI (Windows) text files. Their names carry different extensions in order to help dBASE to recognize their purposes: datamodules (*.dmd), programs (*.prg), reports (*.rep), forms (*.wfm), are all text files.  Note: The only practical difference between ASCII and ANSI text files is when you use accented vowels. The latter will be recognized and be displayed correctly by other Windows word processors only if they are reading ANSI text files. By default, dBASE makes ANSI text files.

One would believe that a Source editor would be made to edit the program source code (.prg files) . In fact, it is used to modify the code of all types of dBASE files. (Note: Please don't do that if you are a beginner.) You can call the Source editor through the File|New|Program menu item. If you select File|New|Form or any other choice besides Program, you will open a specific designer instead of the Source editor.

You may load a program into the Source editor using the File|Open menu item, its shortcut Ctrl-o, or using the appropriate Toolbutton. When the Open File dialog box appears, be sure to select the Open in Source Editor radiobutton as shown in the following illustration. When the Command window had focus when you called the Open File dialog box, the latter will offer to open forms. If the Navigator rather had focus, the Open File dialog box will offer to open the file type displayed in the Navigator.

In the dialog box above, you may notice the coexistence of English words with words from another language. That bilingualism is what you get when you run the English version of dBASE under Windows from another language. It reveals the Windows resources called by dBASE. If you want to use dBASE to create Windows software for international markets, you won't have to translate the text appearing on the pushbuttons of any of your standard message boxes. Windows will take care of that task.

You can also load a dBASE file in the Source editor when you select the file name in the Navigator and push F12, or when you right-click on that file and select the Open in Source Editor option in the popup menu. When no file name is selected in the Navigator, or when the Untitled name is selected, the F12 key will open an empty Source editor window. Remember the F12 shortcut. It is one of the most practical ones.

Tip: When many windows are open under dBASE (Navigator, Command window, Source editor, etc.), you can switch from one window to the next one with the Ctrl-F6 shortcut.

Finally, you can call the Source editor from the Command window with one of the following commands:
 
 
Modify command My_program
// or
Modify command "My program"
// or
Modify command  // to open an empty Source editor window
   

Tip: dBASE just reads the first four letters of its commands. This means that modify command My_program is the same as modi comm My_program. Of course, after the shortened command name, the full name of the program has to be typed.

With .prg files, you don't have to state their extension. They are automatically loaded by default. Conversely, you do have to write the extension of any other type of dBASE file you would like to load in the Source editor. Moreover, if My_program doesn't exist, the Source editor will presume that you want to create a new file with that name. When the name of the file contains a space, as in our second example, that name must be written between quotes. Users of Visual dBASE 5.x must chose a file name with a maximum of eight letters since, like all 16-bit applications, it won't accept files with names longer than that.

Since the files created by dBASE (beside tables and compiled code, as we know) are text files, they can be read and modified by any text editor (even the humble Windows Notepad) as long as that editor saves the text also in an ASCII or ANSI format. This is why dBASE offers you its Source editor as the default but doesn't impose it upon you. The user is free to go under the Properties|Desktop Properties menu item and change the default editor to the one he would rather like to use. Note: When this menu item is selected, the Command window writes SET to remind the user that this command leads directly to the Desktop Properties dialog box.

But before switching to another editor, think twice. dBASE's Source editor has many advantages. One of them is syntax coloration. What in the world is syntax coloration? That expression means that the Source editor recognizes the dBL syntax and will color your code to facilitate its comprehension. To get to the Source editor's properties, select Properties|Source Editor Properties from the menu (see the image below). If that item is not visible from the menu, that's because the cursor is not in the right-hand pane of the Source editor.

You can also access that dialog box by right-clicking the right-hand pane of the Source editor. Under the Editor tab of the notebook, check the Use syntax highlighting checkbox if it not already checked. Near the bottom left quarter of that page, the radiobuttons allow the editor to write either ASCII or ANSI text files, respectively. On the Display tab (not shown here), you can change the size and the font used in the Source editor. Finally, under the Colors tab, you can decide the colors you want for the syntax coloration.

The image below gives an example of syntax coloration. Another advantage of the Source editor is its left pane. This pane gives a hierarchical view of your code. That treeview is specially useful when we edit the code of a form. Each object that has been placed on the form is represented by an icon (entryfield, grid, image, text, etc.). While the right pane displays your code as such, the treeview shows an alphabetical list of the objects on your form under the objects branch, then a list of the functions, also in alphabetical order, under the methods branch. The only exception to that rule is a special type of object called container (because it contains other objects). The objects it contains are listed alphabetically under the branch of that container.

If you change the name dBASE gives by default to the objects you add to your form, it would be wise to leave the first few letters of these objects unchanged in order to assist in identifying the type of object each is.

Use the shortcut Ctrl-F9 to toggle the treeview on and off, or right-click in right pane and select the Open|Close TreeView item in the popup menu.

Once you have clicked in the treeview pane, if you type a letter, the first item whose name begins with that letter will be selected in the left pane while the right pane will display its code. If you type fast, this search will be incremental. The backspace key will jump to a higher level in the hierarchy, while the LeftArrow key will do about the same thing except it will collapse the branch you just left. The RightArrow key will have the opposite effect. The DownArrow and the UpArrow keys will move the cursor to the next or previous item, respectively. The + sign on the numeric keyboard can open a closed branch while the - will do the opposite. (But the same keys near the top of the regular keyboard do nothing.) The focus can switch from the left pane to the right one if the tab key is pushed once. If you push that key again, the code will get indented.

The right pane has all the shortcuts of most Windows text editors. The following ones are less well known or specific to the Source editor.
 
 
Ctrlr           Replaces the text...
Ctrlt           Deletes the word (or remaining part of the word) at right
Ctrlbackspace   Deletes the word (or remaining part of the word) at left
Ctrly           Deletes the line
Ctrlg           Jump to line...
   

Many dBASE files can be loaded into the Source editor. They are displayed under their respective tabs. Each time you load a file in the Source editor without using the Command window to do that, the latter will display the equivalent command ( modify command followed by the name of the file). The file can be closed using the Ctrl-F4 shortcut, the Ctrl-w shortcut (which also saves the file), using the popup menu, or by selecting the File|Close menu item.

How do we write a dBASE program in the Source editor? Simply by typing each successive command that you want dBASE to run. Those who knew batch files under DOS will rightly see a similarity. The only difference is that dBL is a lot more powerful.

To save the program, select File|Save from the menu (or Ctrl-s or the Save Toolbutton).

To close the Source editor, you have the choice between clicking the x in the upper right corner of the editor window, selecting the File|Close menu item, using the popup menu, pushing Ctrl-F4 or pushing Ctrl-w. If you use either of the first four methods, a dialog box will pop up asking you if you want to save your changes. If you use the Ctrl-w method, dBASE will both automatically save the file and close the Source editor with one action.

To run the program, you could select the name of that program in the Navigator (under the program tab) and push the F2 key or the run button on the Toolbar. From the Command window, you could run a program called My_program by typing:
 
 
do My_program
   

An application doesn't have to start with a program (i.e., a .prg). Gone are the days when the programs were the real motors of your applications while the screens were just dummy fronts. Now a .wfm (a form file) is also a dBASE program. An application can thus be started with:
 
 
do My_form.wfm
   

You can quit dBASE as you would for any Windows application. dBL adds its own special way: by typing quit in the Command window.
 

The Help

Only one book about Visual dBASE 7, Ted Blue's,  has been published so far. On the other hand, you will find extensive electronic documentation available under the Help menu.

The easiest way to get some help about a word is to highlight it and then push the F1 key. Honestly, I don't spend one day without consulting dBASE on-line help. How is a property spelled? What are the functions available in this stock class? Most of the time I use the help index through its Shift-F1 shortcut. In the upper part of the screen shot is a seeker. Just type the first few letter of a word and you will get an incremental search in the help file. From the Command window, you can get help by typing help  followed by the word for which you want to get help about.
 
 
help if
   

The Knowledgebase, available from the dBASE web site, is a gold mine for dBASE developers. In its Beginners section, two documents must be read: OODML.how written by dBASE Inc.'s CEO and a tutorial called An Application Tutorial, written by Ken Mayer, a world-class expert on dBASE.

In my humble opinion, the ideal way to learn dBASE is through the following steps :
this series of articles for beginners
Ken Mayer's tutorial
Ted Blue's Getting Started book (comes with your initial purchase of the lastest version of dBASE;
the Developer's Guide (available through the Help menu)
Mike Nuwer's or Ted Blue's classes
Ken Mayer's How documents, available in the Knowledgebase (under the Beginner, Intermediate and Advanced sections)
the rest of the dBulletin's articles
the (free) subscription to dBASE Inc.'s newsgroups

With Visual dBASE 7.5, you should get a thick binder containing the Language Reference, whose electronic version is available through the Help menu.

In the Knowledgebase (in the General section), you will find the dUFLP Code Library. It contains plenty of useful stuff, often essential to experienced developers. The form Library.wfm is used as its index.

If you are just starting to use dBASE but are already quite familiar with other xBase software (Clipper, for example), you will get plenty of information in The Xbase Files Magazine.

Moreover, in the folder where the Borland Database Engine (BDE) was installed, you should have two help files:  Localsql.hlp (about SQL language), and  BDE32.hlp (about the BDE) . In a dBASE sub-directory called MSHelp, you should have plenty of help files about Windows, aimed at very experienced developers.

Finally, once you become more familiar with dBASE, you should take advantage of the resources available in the Web sites dedicated to dBASE. These sites are listed in the dBASE Web Ring.

In a nutshell


I would like to thank Flip Young, my proof-reader, for her important contribution to this article. I would also like to thank Barbara Betcher, Steve Hawkins, Dennis Miller and Nate Salsbury, my beta-readers, for the improvements they brought to this text.

Visual dBASE, dBASE and dB2K are trademarks or registered trademarks of dBASE, Inc. Windows is a registered trademark of Microsoft Corporation.

© 2001 MGA Communications. This document can be freely reproduced as long as its text and its illustrations are not modified without its author's consent.


Bibliography
  1. Anonymous. Developer's Guide. Scotts Valley: Borland International. 1997.
  2. Anonymous. Guide de référence - Visual dBASE. Scotts Valley: Borland International. 1995: 1228.
  3. Anonymous. Guide du programmeur - Visual dBASE pour Windows. Scotts Valley: Borland International. 1995: 458.
  4. Anonymous. Language Reference. Vestal (New York): dBASE, Inc. 2000.
  5. Blue T. The dBASE Developer: Book 1 - Getting Started. San Diego: Blue Star Press. 1999.
  6. Coombs T and Coombs J. dBASE 5 for Windows Programming for DUMMIES. San Mateo: IDG Books Worldwide, Inc. 1994: 383.
  7. Green CR. Crash Course in dBASE 5.0 for Windows Programming. Indianapolis: Que Corporation. 1994: 283.
  8. Groh M et al. Killer dBASE 5 for Windows. Indianapolis: Que Corporation. 1994: 1019.
  9. Hovis T. dBASE 5 for Windows Developer's Guide.  Indianapolis: Sams Publishing. 1994: 568.
  10. Irwin MR. Visual dBASE programming. Upper Saddle River (New Jersey): Prentice Hall PTR. 1996: 725.
  11. Johnson Y et  al. Using Visual dBASE 5.5. Second edition. Indianapolis: Que Corporation. 1995: 750.
  12. Mahar P and Escobar E. Visual dBASE 5.5 Unleashed. 2nd edition.  Indianapolis: Sams Publishing. 1996: 963.
  13. Palmer S. dBASE for Windows for DUMMIES. San Mateo: IDG Books Worldwide, Inc. 1994: 316.
  14. Parsons J et al. Inside dBASE 5 for Windows. Indianapolis: New Riders Publishing. 1994: 1189.
  15. Rinehart ML. Learn Visual dBASE Programming: a hands-on guide to object-oriented database programming. Reading (Massachusetts): Addison-Wesley Publishing Company. 1995: 383.