Chapter 1: First Steps


The intention of this guide is to introduce people who are new to computer programming gain the basic knowledge and skills necessary to be able to start developing their own computer programs. The guide will also be useful to those who have previously used any computer language based on the xBase language, such as Clipper, but no prior knowledge is assumed to ensure all readers have the best chance of gaining a new and valuable skill.

The computer programming language that this guide will focus on is known as "Harbour" which was developed by a global team of programming enthusiasts. At the core of the Harbour Project is a powerful, and free, product that enables computer program developers to build applications using the xBase superset language which begun its development during the 1980s. This language is also commonly referred to as "Clipper".

In addition to learning how to develop computers programs using the core xBase/Clipper language, the guide will also focus on introducing readers to using the Harbour Mini GUI ("HMG"). This seamlessly integrates with Harbour to enable development of programs that computer users are able to interact with visually through the use of icons, windows and a wide range of other types of visual control.

References in this guide from this point may refer to either "Harbour" or "HMG", however, readers should take this as implying both the Harbour language and the Harbour Mini GUI (HMG) unless otherwise stated.

Both Harbour and HMG are provided as free software under the terms and conditions of GNU General Public License as published by the Free Software Foundation. For more information please visit The Free Software Foundation.

For more information about Harbour and the Harbour Project, please visit the Harbour Project . Further information about HMG can be found at The HMG Forum.


I have always held two convictions about the best way to learn a computer programming language! Firstly, the best way to really understand a language is to learn it in its "raw" form by actually writing the source code from scratch and without the aid of an Integrated Development Environment (IDE). HMG does, in fact, include an IDE but it is not my intention to provide any further information about how to use this in this guide as, in my opinion, an IDE masks some of the intricacies, quirks and depths of the language.

The second conviction I hold is that the best way to learn a language is to use a guide that is based around a "learning project" where the reader learns how to develop a computer program step by step. Almost every technical book I have read does not take this approach and I have found this can be frustrating and slow down the learning process.

With that in mind, I have developed a "learning project" for this guide which will produce a simple database program which I have called ePortfolio! By the time you have completed all of the chapters in the guide, you will have developed a basic program that can to be used to record, track and manage investments made in the shares of publically listed companies found on many global stock markets.

By completing this learning project, you will gain hands-on practice in "coding" and learn a wide range of the various commands, functions, controls and other language capabilities that are available to developers who choose to use Harbour and HMG. Each chapter introduces and explains new language capabilities and concepts to gradually build the program and, by the end, you should develop enough knowledge and skills to be able to start creating your own applications.


In concluding this section, I would like to draw your attention a further important note about the ePortfolio learning project. I have deliberately developed the program in a manner that will enable this guide to cover as many of the language capabilities as possible and I have done this at the expense of "consistency" at almost every level of the program! So, for example, the window you will see on screen (as above) only uses "picture buttons" that the user is able to click. Each of these will then open a further window which will then use a different type of capability such as menus, toolbars or tabs. Whilst a consistent approach to developing a computer program is essential to making them more "user friendly", I have deliberately chosen to approach the project in a way that gives you the best opportunity to learn the widest range of capabilities as possible.


This guide assumes the following;

  • Access to a computer running a MS-Windows operating system
  • Good basic knowledge of MS-Windows operating systems such as Windows 7
  • Knowledge of Windows Explorer to navigate the folder and file structure
  • Knowledge of how to open and use a Windows Command Prompt (CMD)
  • Administrator level access may be required to install and run Harbour and HMG
  • Internet access to view additional information referenced in this guide


This guide uses the following conventions;

  • Access to definitions, explanations or further information is provided via hyperlinks to other internet resources. The copyright, content, information and accuracy of any such resource is the sole responsibility of the provider of such resources
  • The program code to be used within each chapter of this guide will be detailed with a blue text box with the Courier New font;(example below);

  cd \
  cd \HMG.3.4.0
  cd MySourceCode

  • Parts of the program code that are being explained within this guide will be expressed with the Courier New font
  • Any changes or additions to source code introduced in each new chapter will be highlighted in yellow within the source code box
  • Only these new or changed lines of source code will be followed by a full explanation. For details of any unchanged lines of code, please refer to previous chapters
  • Source code files in Section 1 will be named as HMGGuide-Ch<chapter number> where <chapter number> will be replaced with the number of the chapter. Thereafter, each program file will adopt a unique name (see later sections for further details and an explanation of why this will be necessary)
  • Bold and underlined wording will be used to stress important text. Readers should pay extra attention to any such text
  • Italicised words indicate a programming concept or term. Each will be followed by a brief explanation which readers should pay extra attention to

Installing Harbour and HMG

The latest versions of Harbour and HMG can be found on several websites. The Download HMG link at the HMG Forum includes details of the latest release of HMG which includes everything, including Harbour, necessary to continue using this guide.

It is highly recommended that you install HMG using the default installation settings, as I have done. If you choose to install to a different drive and/or folder, please ensure you modify any references to drive letters or folders that you see in this guide as appropriate.

This guide is being written using HMG version 3.4.0 however it is likely that a later version will be released by the time you read this and I recommend that you install the latest version available. Where this is the case, please modify any references used in this guide to the hmg.3.4.0 folder to reference the latest HMG installation folder where appropriate. I will make every effort to fully test of the code used during this guide to ensure that it is compatible with the latest releases.

Once HMG has installed, use Windows Explorer to create the following additional folders in the HMG folder (c:\hmg.3.4.0) which will be used through-out this guide;


Editing Tools

One of the most important tools you will need as a programmer is a good text based editor. This will enable you to write and edit the various files that will be needed during program development.

Windows already includes a very basic text editor - Notepad – but there are a variety of more sophisticated editors available which have features which make writing program files far simpler and quicker. I have tried a variety of these and personally feel that the standard version of Komodo Edit is one of the best available. Komodo also produce a more advanced paid-for version, which includes an IDE, but I have not found the need to use this version. Please note, I have no links to the developers of Komodo and you should ensure that if you use of their product that you comply with their licensing terms and conditions.

From this point onwards, I will simply refer you to use your chosen editor when we need to create and edit any program files.

Accessing the Development Environment

A "development environment" refers mainly to the computer on which you will develop your programs. More specifically, the development environment comprises of the computer language you are using, the version of HMG that you have installed in this case, and the various files and folders that you will use to create your programs. Finally, you will need to gain access to use the language, create and edit files and folders and perform a variety of tasks that are required to make your programs work.

By now, you should have already installed the computer language system – HMG – and decided which text editor you will use to create and edit the various files that will be used to create your programs. You should also have used Windows Explorer to create the additional folders that we will use to store these files once you have completed installing HMG (see "Installing HMG" above for further details). At this point, you are probably wondering what type of files will be stored in these folders and how you will "access" them! A brief description of the main types of these follows and I will provide more details of these and other files later in this guide.

Source Code - These will be the main type of files that you edit and each contains a set of "instructions" that the HMG system will use to create a program file that the computer is able to understand and run. You will use your text editor to create, edit and save these in the folder called "MySourceCode" which you created after installing HMG (for the purposes of this guide, the full folder name, which is also known as a "path", is "C:\HMG.3.0.0\MySourceCode" ). HMG source code files need to be saved with a file extension of ".prg" for HMG to recognise them as source code.

Executable files - An executable is a file that HMG creates when it converts source code files into a form that computers can understand and run on the computer. To create these files, you will need to use the Windows Command Line Interface and instruct HMG to build the executable file. Such files mostly have a file extension of ".exe" and these will be saved in the "MySourceCode" folder. Further details of how to access a command prompt and build a program (which is also known as "comiling" is detailed later in this guide.

"Database"Files - These are used to capture and save small individual pieces of information as a "record". Taken separately, each record doesn’t really mean much on its own but your program will be designed to access hundreds, perhaps even thousands, of these records which it will then organise and present in a manner that provides much more meaningful information to the program user. These database files generally have a file extension of ".dbf" and will be stored in the "C:\HMG.3.0.0\MySourceCode\Data" folder . The subject of database files, and how they are accessed, will be covered in much greater detail later in this guide once you have got to grips with some of the basics of writing programs in HMG.

Icons – During the process of creating you programs, you will need to use a variety of pictures, icons and other files to make the program visually attractive and easier for a user to interact with. For the purposes of this guide, such files will be stored in the "C:\HMG.3.0.0\MySourceCode\Icons" folder and more detail about how to use these follows starting in chapter 4.

Please note that if you choose to install HMG to a different hard drive or folder or you want to save your files to a folder structure other than that which I have used in this guide, you must ensure you change any references used in this guide to match the changes you have made.

Earlier in this section, I said that HMG converts source code files into an executable, that computers can understand and run on the computer, and that this "build" process was known as compiling the program. To do this, you need to access a command prompt and enter a series of commands to get to the right folder and instruct HMG to perform the compile. The subject of the types of commands you can use at a command prompt, and what they mean, is complex and not something I am able to cover in this guide.

Therefore, to make it safer, easier and quicker to open a command prompt and access the right folder where you will compile your program, you should use your text editor to write a short DOS Batch File and save this file on your desktop or in a location that you can easily access.

You must ensure the file is saved with ".bat" as the file name extension (without the invested commas) as most text editors will, by default, save any file with ".txt" as the extension and such files will not run as a batch file.

Save this DOS batch file with the name MySourceCode.bat;

  REM – this is comment and is not actually executed
  REM - turn ECHO off
  echo off
  REM - start at the root of the c: drive
  cd \
  REM - change to the HMG folder
  cd hmg.3.4.0
  REM - change to the source code folder
  cd mysourcecode
  REM - clear the screen
  REM - tell the user you are ready
  echo Hello. Command prompt is now ready
  echo To exit, type EXIT and press the Enter key
  echo ...

Once you have created this batch file, try running it and you should see a screen similar to the one below. To close this command prompt, type "exit" (again, without the inverted commas) and press enter.

Command Prompt

More Help

The HMG installation includes an extensive help library which is useful for understanding various aspects of the Harbour and HMG language. For now, I recommend setting this up so that you are able to access it quickly in future.

  • Use Windows Explorer to browse to the DOC folder in the main HMG folder. If you installed HMG as per the above installation, this will be located in C:\HMG.3.4.0\DOC
  • Double click the HMGDOC file. This is an HTML file which should open in your default Internet Browser
  • Click on the Click Here To Start link that should appear when the HMGDOC file loads on your default Internet Browser. This uses ActiveX controls, so you may need to allow these controls to run in your browser
  • I recommend that you save a link to the HMG Help within your Internet Browser Favourites

I also strongly recommend saving a link to the HMG Forum which is a community of programmers ranging from beginner through to expert. This is a very useful place for seeking advice and help with various aspects of Harbour and HMG.


I have no doubt that you will experience some problems when you are entering the source code listed at the start of each of the chapters that follow! Harbour and HMG relies on your code being entered in very specific way and it will fail to compile and run in the event that it encounters any problems with the source code. In some circumstances, the program can also appear to compile and run without a problem until the user tries to perform a specific task which then causes the program to crash. This is known as a "run-time error" and, in most cases, it will cause the program to completely close down!

In both cases, a "compile error" or "run-time error", HMG will try to give you some clues as to where the problem lies but this will be appear as a series of quite confusing text when it happens. We will explore ways to understand this, and what to do, later on in this guide.

For now, if you do experience any problems, double check to ensure you have entered the source code listed at the start of each chapter exactly as you see it including correct spelling, all semi-colons (;), commas (,) and full-tops (.), then try to compile and run it again.

If all else fails and you have tried entering the source code listing and saving it exactly as it appears (this is important to ensure you get hands-on practice) then please use the link which will appear after each source code box listed at the start of each chapter. This will download a copy of the source code which you can use to work out what was missing or has been entered incorrectly.

Section 1 Overview <<     >> Chapter 2: The Launch Program