Resources

Links

Chapter 9: Programming Essentials

Introduction

All computer programming languages need to carry out, or execute, certain instructions, actions, procedures or routines when they run. For example, your program may need to reserve a portion of the computer's memory in which it will store certain information that other parts of the program can access and use. To do this, your program needs to be instructed to reserve the required amount of memory, told what information to put in there, and what to call it, so that later on in the program, you can instruct the program to access and then use that information.

In the Harbour programming language, the most basic and essential of these types of instruction, action, procedure or routine are grouped into three different categories which are known as commands, functions and statements.

The rest of this chapter provides a detailed explanation of each of these categories and describes the words, symbols, layout and essential rules that need to be followed to structure each correctly. The concept of "laying out" a combination of words and symbols that conform to certain rules is known, in computer science, as
syntax.

Before we continue, and as a reminder, please take special note of any terms I use below that appear below in italics. Such terms, such as execute, argument or value, are used to reflect the terminology used in programming (and in the Harbour programming language in particular) and I will begin to use these with increasing frequency in future. It is therefore important that you understand what each term actually means!

Commands

A command is the one of the most basic instructions possible in a computer program. Generally speaking, a command performs (or executes) a single solitary action although this is not strictly true as, at a much lower level, the computer may need to execute a series of very small individual steps to achieve the desired result.

Commands can also – and sometimes need – to be "customised" with additional information to fine tune what you need them to do. This is achieved by stating the command name followed by a space and then the additional information that you want the command to act on. Such "additional information" is referred to in programming an argument of the command whilst the actual information is the value of the argument.

In summary, aside from understanding the terminology and syntax (which I will explain next) to create a command, all you really need to know is that when you use them, they will execute a single, easily understood action and you can leave it to the computer to manage the low level, technical detail.

Command Syntax

In the Harbour programming language, each command is documented in a consistent way and I use the same approach whenever I discuss a command in these in this guide. In the documentation, the syntax of each command appears as follows;

COMMANDNAME <mandatory argument> | [ <optional argument> ]

To understand this better, let's break this up into more easily digested chunks!

COMMANDNAME

This, obviously, is the "plain English" word you use in a computer program to represent the instruction you want that program to execute. These are usually expressed by a single word but, in the Harbour programming language, there are some that contain two or more words separated by a space.

<mandatory argument>

A mandatory argument is one that must be included along with the command for it to work correctly. However, what are those two symbols, "<" and ">", that appear in the documentation? These are used in the documentation to surround (or delimit) a description which replaces the words mandatory argument that I have used above with something a little more meaningful. For example, <AMERICAN>, <BRITISH>, <FRENCH> or <GERMAN> are some of the options available when you use the SET DATE FORMAT command in Harbour and you must choose one, and only one, of these mandatory arguments. So, how do you know when the documentation offers you several options? That's when the "pipe character" is used!

| (otherwise known as a "pipe character")

In the Harbour programming documentation, this symbol (which is represented as two small vertical lines above one another on a computer keyboard) can be understood to mean "or" in plain English. Where this character is used, it separates a number of choices, of which only one can be used, which represents the valid arguments of whichever command you are using.

[ <optional argument> ]

An optional argument is one that might be included along with the command but it is not required for the command to work correctly. These are used when you need to "customise" what the command does.

So, how do you know if an argument is mandatory or optional? Notice the two symbols, "[" and "]", that I used above? These are used in the Harbour documentation to delimit any argument that is optional!

Statements

A statement is another of the most basic instructions possible in a computer program and like a command they can use an argument to control their behaviour. In the Harbour programming language, the key difference between the two is that while a command actually "does something", a statement is used to change the "state" of the program until something else occurs that causes the program to change "state" again.

So what do I mean by the "state" of a program? Put in very simple terms, a program normally exists in a state where it will execute commands or functions one after the other, in order, until it gets to the end of the program and finishes running. This can be thought of as working in a sequential fashion.

While that might sound exactly like the kind of behaviour you would want in a program there are times when you might want the program to repeatedly execute a certain number of actions until a certain task has been completed before going on to perform other actions. This concept of repeatedly performing a series of actions until a certain task is completed is known as iteration or, more often, as looping.

In order to change the program from a state where it is running in a sequential fashion to one where it runs in an iterative state, you instruct the program accordingly by using a statement. The iteration (or loop) is then ended by another statement once a certain condition has been achieved.

The use of statements isn't always so complicated. Some statements are very simple and don't appear to involve iteration. For example, if you wrote the statement LOCAL cHello in a Harbour program, it enters a state where it will reserve a small part of the computer's memory which you are going to call cHello. It then automatically does back to a state that enables it to execute the next action. However, if you wrote the statement LOCAL cHello, cBye, cByeBye the program enters a state where it first reserves a bit memory which it calls cHello, then it reserves another bit of memory which it calls cBye before, finally, reserving a third bit of memory which it calls cByeBye (notice the iterative nature of this example?). After that, the program re-enters a state ready to execute the next action.

Confused? I'm sure you are but I want to re-assure you the explanation above is focused more on "theory" than it is about knowing what the various statements are, what they can be used for and, more importantly, when and how to use them. The good news is that the total number of different statements that can be used in the Harbour language is far less than those that can be used as commands. However, it is just as important to understand the syntax used to document a statement and this is also a useful time to start exploring instances where the documentation is a little more involved than the explanation I provided previously for command syntax.

Statement Syntax

The syntax for some of the simpler statements in the Harbour language is virtually identical to that which is used in documenting commands. As a very brief reminder, let's review the simplest "level" of syntax used for a statement.

STATEMENTNAME <mandatory argument> | [ <optional argument> ]

The only difference between this statement syntax and the command syntax previously explained is STATEMENTNAME which refers to the "plain English" word used in the program to represent a statement. These are usually expressed by a single word but, in the Harbour programming language, there are some that contain two or more words separated by a space.

Whilst this is fairly straightforward, other statements (and commands) have a more detailed level of syntax and a useful way of exploring this is to first introduce you to control structures, an essential important tool in computer programming.

Control Structure Statements and Syntax

Many of the statements you will find in Harbour are used to create what is known as a control structure. A control structure is a "block" of code in the program that caters for a number of different possible scenarios. Any commands, statements or functions to be executed for each scenario will only be run when certain conditions exist that mean that particular scenario exists (or that the condition for that scenario is logically true). The syntax for control structures generally appears as follows.

You might be wondering how to cater for a scenario that you expect to occur most of the time or, if you are thinking ahead, how to deal with a scenario that you didn't expect or anticipate (which is good practice, by the way)! All control structures include an optional way to deal with such exceptions and they only come into force when none of the previous conditions for each scenario you stated are true. In the example of a DO CASE control structure any such exceptions are dealt with by the commands, statements or functions that you include following an OTHERWISE directive.

STATEMENTEND[NAME]

The final part in a control structure is the closing statement. A closing statement is used to complete the control structure and it serves an additional purpose in that it changes the "state" back to whichever state the program was in prior to encountering the control structure. Like many of the control structure opening statements in the Harbour programming language, the closing statement can often be represented by two words separated by a space with the second word being optional in many cases.

I hope you have this discussion of control structures useful. The control structures available in Harbour are extremely powerful, flexible and actually fairly easy to understand and use. We will start to explore some of these in greater detail in chapter 10.

Functions

A function is the most wide ranging and powerful way to complete certain tasks in Harbour and HMG and you have already used them extensively in Section 1 of this guide. As you may recall, it is even possible for you to create your own functions with Harbour which are referred to as User Defined Functions or UDFs. However, what exactly is a function, what do they do and how do you use them?

Functions are, at a high level, a kind of procedure or routine that is used to perform specific operations which are comprised of a number of lower steps or tasks. The benefit is that you don't need to write each of these lower levels steps or tasks yourself and you often don't even need to know what these are. Every function has a unique name and generally has a well defined and understood purpose such as opening a database file. Functions always return a value once they complete running and these "return values" can be useful in several ways; for example, to check if the database file was successfully opened or not.

Most programming languages come with a pre-written set of functions and Harbour is no different. In fact, both Harbour and HMG include an enormous number of functions, so the job of explaining every single one of them would be close to impossible in a guide such as this. I have previously explained some of the Harbour and HMG functions we used in Section 1 and, indeed, I expand on a number of the most common and useful functions later on in this section as well as in later sections in this guide. As before, however, it is useful to understand the syntax of functions.

Function Syntax

Many parts of the documentation for the syntax of a function are similar to those used in documenting commands and statements, so I will refrain from repeating myself on the assumption that you understand what these are. For example, mandatory arguments (or parameters as they are sometimes called in functions) do not appear with the "[" and "]" delimiters whilst optional parameters do.

FUNCTIONNAME( <Argument1>, [<Argument2>] ) --> ReturnedValue

You will immediately notice a few differences in the syntax used in documenting functions and I will focus on explaining these bit by bit.

FUNCTIONNAME

This really should be quite obvious by now! Every Harbour and HMG function has a unique name (these are known as reserved words) and I strongly recommend that you take great care not to create your own UDFs with a name that is already in use. On some occasions if you did do so, your program will compile and run but the exact results are unpredictable so it's better to avoid the risk altogether. If you are unsure if the name you have given to a UDF is already in use, check the documentation available when you install HMG (see "More Help" in Chapter 1 if you are not sure how to access this help documentation) to see if there is a Harbour or HMG function with the same name..

()

All functions include an opening and closing bracket after the FUNCTIONNAME which is used to indicate that a function is being used and to distinguish them from commands and statements. These frequently include a number of arguments enclosed within the brackets separated from each other by a comma and there are often many more than the two simple examples I have included here. As I said earlier, these arguments included in a function are sometimes also referred to as parameters and, regardless of what you decide to call them, they are passed to the function which then uses them to "customise" or control the way the function works. We will explore such "customisation" or control later on in this guide.

<Argument1>, [<Argument2>]

By now, you will recognise when an argument (or parameter) is mandatory and when it is optional. At the risk of repeating myself, please remember that these are always included within the two brackets and each one must be separated by a comma when included in a function.

--> ReturnedValue

This part of the syntax documentation details the returned value and it always appears at the end of the functions description. The symbols, -->, are never actually entered in your computer code as they are used simply to inform you that details of the return value follow. You might think that this example doesn't really tell you much about the data type of the return value but, fortunately, the documentation is much more helpful as it follows a couple of standard conventions. These conventions are mainly used to try and describe what the returned value is as well as what data type it consists of. We explore data types in greater detail in the next chapter but for now, the following examples should help to explain these conventions a little more clearly;

cSurname – The first, or leading character, "c", indicates that a character data type is being returned whilst the rest of the return values name suggest a surname is being returned by the function

nTotal – The leading character "n" indicates that a numeric data type is being returned which is likely to be a total of some sort

lContinue – The leading character "l" indicates that a logical data type is being returned, which will contain either be a true or false value, which you might use to decide whether to continue a certain action or not

dYesterday – The leading character "d" indicates that a date data type is being returned which is likely to be the date yesterday

There are other data types available in Harbour which we explore in detail in chapters 10 and 11. Before we move on to explore those, there is one more thing you may come across in Harbour and HMG, especially in some of the documentation examples but also on some of the websites you might visit, which you need to have a basic understanding of.

Procedures

Earlier on, whilst discussing the definition of a function, I purposely avoided discussion another type of high level mechanism available in Harbour and HMG which are known as Procedures. These are very similar to functions but, broadly speaking, the only difference between the two is that procedures do not return any value after they complete running.

From a personal perspective, I avoid using procedures preferring instead to only use functions even when I know I do not need, or want, to do anything with a return value. This is simply because I prefer to take a consistent approach in my programming projects and I personally don't see any real advantage to using a procedure rather than a function. I mention procedures simply to make you aware that these exist (so you may come across them in other places) and to explain what they are and what you need to know about them.