# Clipper Tutorial: a Guide to Open Source Clipper(s)

Quite a lot of people were interested in this page (it was the most visited page in my former website) and so I feel that I must complete it. This page disappeared when GeoCities was closed (in fact it still contains some broken links to GeoCities pages), and it has been reloaded thank to some requests I got, for example on Facebook. There you can find the "Harbour MiniGUI" group, and others.

When (and if) finished, it will prove a complete guide to Open Source Clipper programming. However, this page is still very incomplete. Recently (it is now 16/12/2014) I noticed a new Wikibook on a subject similar to this: http://en.wikibooks.org/wiki/Category:Application_Development_with_Harbour

I just threw in some stuff, for the moment. This page is derived from what I call the "hubbub version". As a newbie to Wikibooks, I did not yet properly format the few sources in this page (Wikibooks has syntax highlighting for Clipper, but it is a bit buggy). If you check it, you will see misplaced links and so... this page definitely needs proofreading!

A former version of this 'ebook' :-) is at http://www.geocities.ws/povigna/computer/clipper.html (I'd like to thank W. Birula for making me know it).

I'd like to see this tutorial grow! If someone on the newsgroup comp.lang.clipper or on the mailing lists HarbourUsers (http://lists.harbour-project.org/mailman/listinfo/harbourusers) would give me help or clues. To apologize for its incompletedness, I can only say that this page contains everything I know about Clipper and xBase programming (in a given moment... I always try to learn new things...).

I tried to adhere to the classical tutorials' bottom-up approach of showing all the basic function via very simple examples. The plan to include some bigger examples, with the top-down approach (how do I deal with this problem?) is suggested, but not yet pursued...

I have decided to name this tutorial "a Guide to Open Source Clipper(s)" and not "a Guide to Open Source xBase" because I like the name Clipper, and as you can see by watching at the open source compilers I discuss (Clip and (x)Harbour) the influence of the name Clipper is great. Only X2c doesn't recall the name Clipper. And now X# https://www.xsharp.info/

Modern xBase open source dialects are:

1. Harbour and xHarbour, which are the more active projects
2. Clip, which is not being updated since 2013
3. X#, which will be a xBase for .NET

X2c is too old - what use could be for a modern xBase the need to get its compiler from the Borland Museum?

This Guide was born when I followed a small project (the port of an old Summer 87 application to Windows) and I saw the many Clipper compatible open source compilers available, but noticed also that there were no good tutorials and that the books about Clipper/xBase/Visual Objects and so on couldn't be found in any bookstore (not even in libraries!).

I think that the first part of the tutorial will cover the basic of the language, up to the procedural programming facilities. Part 2 will deal with the native DBF file support. Part 3 will explain OOP. Part 4 will cover other programming topics, and the last part will be about programming a user interface. This makes up for a nice introduction to computer science.

Thanks to bpd2000 for the nice link he provided.

Michele Povigna

1. Getting Acquainted
2. Getting Started
3. Part 1: The Common Ground
1. Chapter 1: Basic Language Tutorial
2. Chapter 2: Database Making
4. Part 2: Additions to the Language
1. Chapter 3: Object Oriented Programming
2. Chapter 4: Some More Advanced Programming Topics
5. Part 3: Making Up a User Interface

## Clipper Tutorial

Please note: if anybody will add his work to this stuff, the Clipper tutorial should contain only 'standard' code that would compile on Harbour, xHarbour and Clip. Compiler-specific code should be placed somewhere else.

### The helloworld application line by line

Let's try to highlight the parts of helloworld:

 function MAIN
* This is an example
clear
?"Hello, the weather is fine today"
return


(in GeoCities this and all other sources were highlighted by the on-line service CodeColorizer at http://www.chami.com/colorizer/).

We will comment each line of the helloworld program.

function MAIN


The first line defines a function named MAIN. Defining such a function is not compulsory with Harbour, as if it is missed errors would occur during compilation, but I will keep it to make sure the examples work with all compilers.

We will learn later how to define and use functions and procedures.

* This is an example


The second line is a comment. Commenting your programs will help you when you are to modify them later. If they aren't commenting, modifying them will be a very hard task. It will be much more difficult if you are to modify programs written by others if they didn't comment them: figuring out what a program does using only its code is very difficult and even the most clean programming language may prove to be write-only if not properly commented.

You can write comments in many different styles: using an asterisk (*), two sweeps (//), a double ampersand (&&) or a couple sweep-asterisk (/*) and asterisk-sweep (*/), as you see below:

* This is a comment...
// ...and so is this...
&& ...and this.
/* This is an example of the fourth commenting style,
which may span over several lines.*/


The second and the fourth commenting styles are derived from the C programming language, the first and the third are peculiar of the Clipper/xBase standard.

clear


No, the purpose of this command is not to make the source code clear (that would be too easy! It is up to us to write clear source code, and to do so we must comment it well), but instead to clean the screen. :-) You could also use clear screen or cls, although these two commands are not exactly the same of this clear (the difference will be clear later, when we can GET the point - then, you could also appreciate the pun in this paragraph - but will more likely not).

What are commands?
Harbour commands are defined in the file std.ch via the #command macro directive (http://harbour.edu.pl/clipper/en/ng122d3c.html). The first commands we encountered are defined by these lines:

#command CLS                        => Scroll() ; SetPos(0,0)
#command ?  [<explist,...>]         => QOut( <explist> )

? "Hello, the weather is fine today"


The ? is a command which means print. In the BASIC programming language, it is also an abbreviation for its print command (the syntax of xBase is quite similar to that of the BASIC programming language).

In this case ? print the string Hello, the weather is fine today. Please note that the string

return


Return is used to terminate the function. We will explain later what the return exactly does.

Today Harbour needs not an explicitly defined main function/procedure. The following version of helloworld will compile and is exactly the same of the previous one:

&& hello world without commands and main
Scroll() ; SetPos(0,0)
QOut( "Hello world" )


The Harbour Interpreter and Virtual Machine
The program above, stored in a text file named hello.prg, can be run with the command

hbrun hello.prg


hbrun is an interpreter for Harbour. This means that if we run it, we get to a screen with a "Dot prompt" on its last line, where we can enter and run instructions. For example entering

? "Hello world"


will get Hello world printed on the screen, but only after the interpreter hbrun itself is closed. To quit the interpreter and get the greeting printed type

QUIT


All in all, hbrun permits to feel how handling databases was done in the old dBase "Dot prompt" mode - that is, like this: http://manmrk.net/tutorials/database/dbase/IntrodBASEIIIPlus.htm

Running the compiler harbour (harbour.exe on Windows) on a printA.prg containing the line

? "A"


will output a printA.c file. The bottom of this file reads:

HB_FUNC( PRINTA )
{
static const HB_BYTE pcode[] =
{
36,1,0,176,1,0,106,2,65,0,20,1,7
};

hb_vmExecute( pcode, symbols );
}


that is, as an intermediate step the Harbour compiler compiles pcode, or bytecode for a virtual machine.

If the compilation is done with the /gh option

hbmk2 /gh printA.prg


the result will be a file named printA.hrb, a "Harbour Portable Object" file which can be executed by

hbrun printA.hrb


In this way, hbmk2 and hbrun work in couple as a perfectly equivalent tools to the Java compiler javac and java interpreter java.

As a parenthesis, virtual machines are not a new concept. If we look into the retrocomputing field, we'll see that in the late 1970s and early 1980s the University of California San Diego has a portable operating system based on pcode, the UCSD P-System which was written in UCSD Pascal and could be run on 6502, 8080, Z-80, and on PDP-11 http://www.threedee.com/jcm/psystem/index.html (it actually was a competitor of MS-DOS, PC DOS and CP/M - http://www.digitalresearch.biz/CPM.HTM and http://www.seasip.info/Cpm/index.html).

Also, in 1979 Joel Berez and Marc Blank developed the Z-machine as a virtual machine to run Infocom's text adventure games, the name not hiding they were mainly thinking about Zork. The programming language for the Z-machine was called ZIL (Zork Implementation Language). A modern compiler for ZIL to Microsoft .NET is ZILF https://bitbucket.org/jmcgrew/zilf/wiki/Home and a Z-machine.NET https://zmachine.codeplex.com/. More informations at http://inform-fiction.org/zmachine/index.html.

Apart from the JVM (Java Virtual Machine), the Microsoft .NET CLR (Common Language Runtime), is another modern virtual machine.

hbmk2 was created to support all shells, all compilers on all platforms, also to replace old 'bld.bat' solution, while staying compatible with existing hbmk script features and options.

Informations on how to get an executable without using hbmk2 can be found at http://www.kresin.ru/en/hrbfaq.html.

Remember SET PATH=C:\hb30\bin;%PATH%

### Data Types in General (and Their Operators)

The list of types supported by Clipper is as follows:

• A Array
• B Block
• C Character
• D Date
• L Logical
• M Memo
• N Numeric
• O Object
• U NIL

This is the list of results returned by the function VALTYPE(). The function TYPE() returns also:

• U NIL, local, or static
• UE Error syntactical
• UI Error indeterminate

Harbour has a longer list (http://www.fivetechsoft.com/harbour-docs/harbour.html):

• HB_ISARRAY
• HB_ISBLOCK
• HB_ISCHAR
• HB_ISDATE
• HB_ISDATETIME
• HB_ISHASH
• HB_ISLOGICAL
• HB_ISMEMO
• HB_ISNIL
• HB_ISNULL
• HB_ISNUMERIC
• HB_ISOBJECT
• HB_ISPOINTER
• HB_ISPRINTER
• HB_ISREGEX
• HB_ISSTRING
• HB_ISSYMBOL
• HB_ISTIMESTAMP

ISPOINTER() for example is marked: Not available in CA-Cl*pper.

Let us see a little program that shows the use of the most common data types.

I wanted to show, in this example, a computation of π instead of that of √2, but xBase misses the ArcTan function. We may solve this problem by importing it from an external library, or by supplying it ourselves. (Both ways should be pursued in this tutorial).

The last two data types, are a bit different from the preceding: "Memo" is not very useful when used outside of a database, and the arrays cannot be used in databases.

This alternate highlighting is from the web service at the URL http://tohtml.com/Clipper/.

 && example of compilation command
&& A:\>c:\hb31\bin\hbmk2 -quiet -oc:\test.exe test.prg -run

&& please note that this example has not a MAIN function: I found that Harbour 3.0 can compile it anyway

&& an example of string concatenation
? "Hello" + " " + "World!"

&& let us do now a few numerical computations, integer numbers are a good starting point
? 5+13
? 12*8

? 3/2
SET DECIMALS TO 15
sqrt2=sqrt(2) && computing the square root of 2...
? sqrt2 && ... and printing it

&& ? caporetto
&& if the line above was not commented, the compiler would issue the two following lines
&& Error BASE/1003  Variable does not exist: CAPORETTO
&& Called from TEST(8)

&& as xBase is not good at history, let us revise it: http://www.historyofwar.org/articles/battles_caporetto.html,  http://www.firstworldwar.com/battles/caporetto.htm
&& we can then assign the correct date to this war
caporetto := ctod("10-24-1917")

a := date() && system date
? a + 1 && will print tomorrow's date
? a - caporetto && this will tell us how many days have passed since Caporetto's battle (difference between two dates)

SET DECIMALS TO 2
? (a - caporetto) / 365
?? " years have passed since Caporetto's battle"

? 1+1=3
&& it will print ".F.", that is, "FALSE" (of course...)

&& The following two instructions should be discussed to expand on the subject of operator precedence
? 1/2+2^3*sqr(25)-3^2
? 1/2+2^3*(sqr(25)-3^2)


From the following example (which runs) we see that Harbour is a weakly typed programming language: a variable, such as a in our example can be a number, and then become a string of text.

a := 1+1
? a
a := "abc"
? a


There is a problem: if the variable type changed and the programmer did not get aware of it he may issue some instruction that will cause an error at run time. If we had another line of code

?a+1


in the program above, Harbour will attempt to add the number 1 to the string "abc", and the result will be the error

Error BASE/1081 Argument error: +.

Now, consider this example about arrays...

 && C:\hb31\bin\hbmk2 -quiet -oc:\test.exe mesi.prg -run
DECLARE months [12]
? LEN (months)
&& We shall now load some data into our arrays
PRIVATE month_names: = {"January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"}
PRIVATE months: = {31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31}

&& Let us make some output (using a FOR loop - see below)
FOR I: = 1 TO LEN (months)
? month_names [i], "is", months [i], "days long."
NEXT


#### Other Considerations about the Classification of Data Types

simple data types: numbers, logical values, strings, dates

Primitive data types can be composed into structured data types: arrays, associative arrays (hash tables), table records, objects

Memos and code blocks are special data types.

#### Operators and Precedence

&& First we print the values of two expressions with the exponentiation operator
? 3**3**3 && is 19683
? 3**(3**3) && is 7625597484987

&& Then we let our compiler tell us if they are the same
? 3**3**3 = 3**(3**3) && result is .F.

&& We've a look at how our compiler deals with overflow and underflow...
? 9*10
&& ***********************
? 1/9**9**9
&& 0.00
? -(9**9**9)
&& ***********************


We see in this example that the exponentiation operator ** is left-associative (where in mathematics exponentiation is a right-associative operation).

The fact that 3**3**3 and 3**(3**3) give two different results means that parenthesis alter the operator precedence: whatever is enclosed in parenthesis is evaluated first.

Even when the operation is left-associative, the result of 9**9**9 is quite a "large" number (196627050475552913618075908526912116283103450944214766927315415537966391196809 to be precise, as you can easily check - maybe using some arbitrary precision calculator program, such as GNU bc, which is available on every Linux distribution and as a download for Windows at http://gnuwin32.sourceforge.net/packages/calc.htm) which exceeds the resources Harbour allocates for a number (which is called overflow) and it therefore prints 23 times a * to indicate this error. It also gives zero (0.00) if we try to compute its reciprocal (which is underflow). Overflow and underflow errors happen when the result of a computation is, respectively, too big or too small to be represented with the number of bits a compiler has allocated for the variable in which we're trying to store it in.

### Boolean Algebra & Flow Control

We can print the result of a comparison, which is a Boolean value (represented as .T. or .F.), but they are useful with special words in order to branch or repeat the execution of one or more instructions.

We have a Boolean expression when its result is true (whose xBase symbol is .T.) or false (.F.). The easiest way to get a Boolean result is to use a comparison (relational) operator: =, ==, !=, <>, #, >, <, >=, and <=. Always remember the difference between the comparison operators = (equal), == (exactly equal) and the assignment operator :=.

Actually the "real" (mathematical) definition of a Boolean expression is different from what is stated in the last paragraph. A "real" Boolean expression would contain only the two Boolean values .T. and .F. and the Boolean operators (.AND., .OR., .NOT.).

Boolean Algebra is applied to electronic digital circuits since the work of Claude Shannon in 1937. See http://www.allaboutcircuits.com/textbook/digital/chpt-7/introduction-boolean-algebra/ (and the successive pages of that online textbook) to have an idea of what Boolean Algebra means when it's applied to bits within a circuit (including a microprocessor). Here we're using it at a much higher level.

#### Conditional execution

The following example gets a number from the keyboard and prints it. If the number is 0 it comments that value (I presented this example as a typical nihilist programming).

Function MAIN()
LOCAL number
INPUT "Key in a number: " TO number
IF number = 0
?? "Congratulations, you keyed the fabolous number "
ENDIF
? number
RETURN


This example prints two different comments, whether the condition of the remainder of the division of the number supplied by 2 is, or is not, 0.

Function MAIN()
LOCAL number
INPUT "Key in a number: " TO number
IF number % 2 = 0
? "You keyed in an even number"
ELSE
? "You keyed in an odd number"
ENDIF
RETURN


This example shows that more than a command can be executed.

Function MAIN()
LOCAL number
INPUT "Key in a number: " TO number
IF number % 2 = 0
? "You keyed in an even number"
? "I can prove it:"
? "the result of ",number," % 2 = 0 is ", number % 2 = 0
ELSE
? "You keyed in an odd number"
? "I can prove it:"
? "the result of ",number," % 2 = 0 is ", number % 2 = 0
ENDIF
RETURN


This example adds another keyword, ELSEIF, to show that the choices are not necessarily dichotomic. This is a chained conditional. Only one of the branches will be executed.

function MAIN
LOCAL nNumber := 0
//
INPUT "Key in a number: " TO nNumber
//
IF nNumber < 50
? "less than 50"
ELSEIF nNumber = 50
? "equal to 50"
ELSE
? "greater than 50"
ENDIF

   ? Time()
// CToN source is numconv.prg, library is libct.
IF CToN( SubStr( Time(), 1, 2 ) ) < 18
? "Good day"
ELSE
? "Good evening"
ENDIF


Here is a more complex example, coordinating more conditions with .OR. operators. There are three logical operators: .AND., .OR., and .NOT.

   INPUT "Key in a number: " TO char
char := "e"
IF ( ( char = "a" .OR. char = "A" ) .OR. ( char = "e" .OR. char = "E" ) .OR. ( char = "i" .OR. char = "I" ) .OR. ( char = "o" .OR. char = "O" ) .OR. ( char = "u" .OR. char = "U" ) )
? char, " is a vowel"
ELSE
? char, " is not a vowel"
ENDIF


This same thing could however be achieved better by the use of regular expressions.

#### Looping

DO WHILE, EXIT, LOOP, ENDDO are keywords used To repeatedly execute a series of statements (loop body) while a condition is true (i.e. its result is .T.).

Loops come in several flavours: the pre-tested loop, the post-tested loop, and the definite iteration, which is done via a count-controlled loop (usually called a for loop). In practice, we may have a middle-tested loop as well, but no specific syntax for it... we need to put an EXIT statement within an already existing loop body to get this one. The next program we will key in is of some interest for the mathematicians (Real Programmers aren't afraid of maths, do you know this famous adage?)

Here is it:

 && Function MAIN LOCAL number, sum, n
&& An anonymous contributor renamed the variable "num" into "number", increasing this short program readability, but the line above would give
&& Error E0030  Syntax error "syntax error at 'LOCAL'"
Function MAIN
LOCAL number, sum, n
CLS
? "Let's sum up the first n odd numbers."
INPUT "How many numbers shall I sum up? " TO n
sum=0
number=1
DO WHILE number <= 2*n
sum=sum+number
number=number+2
ENDDO
? "The sum requested is ", sum


As you can see, this looping statement is similar to the IF statement: both of them are ended by a END-corresponding statement, both of them contains a logical espression.

This looping statement will continue until its condition remains true (will evaluate to .T.).

The two instructions it repeats are sum=sum+num and num=num+2. The second is fundamental: if it wasn't there or was wrong (for example if you keyed in num=num/2), the condition would not evaluate to .F. and the program would not stop its execution (this is called infinite looping). When this happens to you, press the keys Ctrl and C at the same time. This should convince the computer to give his attention to you instead of running the loop.

The programs above is a nice example of how an extremely methodical calculator without any creativity would attack the problem of summing up the first n odd numbers. Notes about the creative approach to it can be found at this address: http://betterexplained.com/articles/techniques-for-adding-the-numbers-1-to-100/ (along with the usual anedocte about Gauss' show off about it in elementary school).

The WHILE looping statement is said to have the control expression in its head,opposed to the Pascal REPEAT-UNTIL looping statement (a post-test loop) which has the control of the condition in its tail (these are the Italian computer science slang for pre- and post- tested loops, aren't they funny?). How does the xBase/Clipper say REPEAT-UNTIL? It doesn't. Here is how to emulate it (copied & pasted from the Norton Guide):

LOCAL lMore := .T.
DO WHILE lMore
loopbody
lMore := condition
ENDDO

As you see, we first set a variable to be true, enter the loop, and specify the condition at the end of the loop, to make sure its body is executed at least once.

Here is an example, equivalent to the one at the pascal_repeat_until_loop page in tutorialspoint.com.

LOCAL a := 10
LOCAL lMore := .T.

DO WHILE lMore
? 'value of a: ', a
a := a + 1
lMore := ( a != 20 )
ENDDO


But the code above changed the condition. If we didn't want this to happen, we can simply negate the condition we'd use in the Pascal code:

repeat loopbody until condition

becomes then:

LOCAL a := 10
LOCAL lMore := .T.

DO WHILE lMore
? 'value of a: ', a
a := a + 1
lMore := .NOT. ( a = 20 ) // also lMore := ! ( a = 20 )
ENDDO


Let us now see this kind of loop:

 DO WHILE .T.
? "I won't stop."
ENDDO


This loop prints "I won't stop." as long as 'true' is... true. It is thus called an infinite loop because the ending condition will never be satisfied. It is the first example of control flaw studied in computer science classes. By definition, you incur in an infinite loop every time you specify a tautology as the condition to be checked. It is not always obvious to detect this and other control flaws and errors - it is indeed a process that involves the use of a specific piece of software called a debugger.

#### Counter-controlled Loops

The FOR...NEXT construct (counter-controlled loop) is useful when we know how many times we want the loop body be executed. We shall now use it to print out and revise multiplication tables.

 CLEAR
FOR I := 1 TO 8
FOR J := 1 TO 8
?? I*J  NEXT
NEXT


(Please note in this example we have a loop inside the body of another loop: this is called a nested loop). Well, this works, but its output is not very nice... Moreover, it is customary to print the multiplication tables up to 10, since we're using a decimal numeration system... let us try it again!

 CLEAR
FOR I := 1 TO 10
FOR J := 1 TO 10
@i,j*4 SAY  I*J PICTURE "999"
NEXT
NEXT


this way we can print it much prettier... by the way, when nesting loops and branching statements, it becomes important (practitioning programmers say so, and in my little I agree) to arrange the indentations in order to make the program easier to read... in The Oasis are available "source code beautifiers" such as dst314.zip. Harbour gives us the hbformat tool, https://vivaclipper.wordpress.com/tag/hbformat/.

PICTURE "999" is the instruction to specify we want the output format - as we specified three digits, the numbers in output will be printed as if they were three digits long, thus aligning them in our multiplication table.

### Functions and Procedures

A function is a piece of code that returns a result every time it is called. Let us consider a function to convert Celsius into Fahrenheit:

FUNCTION cels2f( tempCelsius )
tempFahrenheit := (tempCelsius*1.8 + 32)
RETURN tempFahrenheit

FUNCTION MAIN()
? cels2f(100)
? cels2f(0)


But have a look at the following:

/**
* by choosing better variable names this function becomes self-explanatory
*/
function convert_Celsius_to_Fahrenheit(Celsius_temperature)
return Celsius_temperature * 1.8 + 32

FUNCTION MAIN()
? convert_Celsius_to_Fahrenheit(100)
? convert_Celsius_to_Fahrenheit(0)


Consider this example of use for the function HB_Random():

PROCEDURE Main
// Random number between 0.01 and 0.99
? HB_Random()
// Random number between 0.01 and 9.99
? HB_Random(10)
// Random number between 8.01 and 9.99
? HB_Random(8,10)
RETURN


A good function would function as a "black box", that is you can use it without worrying about how it internally works. An example usually given at this point is that of driving a car: you can use it without worrying about how the engine works (do you know anybody which looked at the pistons of their new car before buying it?). Someone else designed the engine. But there may be problems: if we change our Celsius into Fahrenheit function as follows

FUNCTION cels2f( tempCelsius )

tempFahrenheit := (tempCelsius*1.8 + 32)
number := number + 1

RETURN tempFahrenheit

FUNCTION MAIN()

number := 0
? cels2f( 100 )
? cels2f( 0 )
? number


we'll get a side effect. This program output is

      212.0
32.0
2


That is, our new function did not only return a value, it also increased by 1 the variable number.

The Clipper Norton Guides read, "A procedure in CA-Clipper is the same as a user-defined function, with the exception that it always returns NIL" (http://www.oohg.org/cl53/ng10a778.html), thus a procedure is really just a type of function that relies on these side effects to get something done.

The utility of functions is that they improve program readability, maintainability. Splitting a program into functions is a good design approach, which lets breaking a complex problem into smaller, simpler problems (top-down).

Harbour has four different kinds of subroutines/subprograms:

• the FUNCTION and
• the PROCEDURE (which is a FUNCTION with no return value),
• the method (which has not an associated keyword, works like every object oriented programming language) and
• the code block.

### Why the Main Function?

The main function is the designated start of a program written in C or C++ (Java uses a static main method). Since a procedure is a function that returns NIL, we can have a procedure main instead of a function main in our program,. With Harbour it is not necessary anymore.

### Another characteristic of variables: scope identifiers

Variables have a name, a type, a scope and a lifetime (http://www.dbase.com/Knowledgebase/dbulletin/bu05vari.htm) which may be explicitly declared as (list below copied verbatim from w:Harbour (software)):

• LOCAL: Visible only within the routine which declared it. Value is lost upon exit of the routine.
• STATIC: Visible only within the routine which declared it. Value is preserved for subsequent invocations of the routine. If a STATIC variable is declared before any Procedure/Function/Method is defined, it has a MODULE scope, and is visible within any routine defined within that same source file, it will maintain its life for the duration of the application lifetime.
• PRIVATE: Visible within the routine which declared it, and all routines called by that routine.
• PUBLIC: Visible by all routines in the same application.

They do not make sense before we work with functions and procedures.

/* Work on the following.
* hbformat was run on this piece of code
* need to provide comments, nest more functions and procedures to help figuring what goes on with scope modifiers
*/

STATIC x := 9

? x
A()
? x
B()
? x
C()
? x
D()
? x
E()
? x

PROCEDURE A

LOCAL x := 10

? "x from A=", x

RETURN

PROCEDURE B

PRIVATE x := 5

? "x from B=", x

RETURN

PROCEDURE C

PUBLIC x := -1

? "x from C=", x

RETURN

PROCEDURE D

? "x from D before updating value=", x

x := 12

? "x from D=", x

RETURN

PROCEDURE E

? "x from E=", x

RETURN


On running this, we get a strange output:

         9
x from A=         10
9
x from B=          5
9
x from C=          -1
9
x from D before updating value=          -1
x from D=         12
9
x from E=         12
9


This program sets a variable x and five different procedures, A, B, C, D, E. The first three procedures define a variable x within themselves, assign it a value and print it. The fourth function assigns a new value to some variable named x without declaring it. The fifth function shows the value of some x variable, which happens to be the value of the fourth x variable. The main fact to remember here is that two variables are not the same, even if hey have the same name, provided they have different scopes and this feature is called shadowing.

x := 9

? x
A()
? x
B()
? x
C()
? x
D()
? x
E()
? x

PROCEDURE A

LOCAL x := 10

? "x from A=", x

RETURN

PROCEDURE B

PRIVATE x := 5

? "x from B=", x

RETURN

PROCEDURE C

PUBLIC x := -1

? "x from C=", x

RETURN

PROCEDURE D

? "x from D before updating value=", x

x := 12

? "x from D=", x

RETURN

PROCEDURE E

? "x from E=", x

RETURN

         9
x from A=         10
9
x from B=          5
9
x from C=         -1
-1
x from D before updating value=         -1
x from D=         12
12
x from E=         12
12


As static variables seem to require further informations (they work like C static variables), here is an example:

// adapted from "An example of static local variable in C" (from Wikipedia Static_variable)
FUNCTION func()
static x := 0
/* x is initialized only once, the first time func() is called */
x := x+1
? x
RETURN

FUNCTION main()
func() // calls func() a first time: it prints 1
func() // value 1 was preserved; this time it prints 2
func() // prints 3
func() // prints 4
func() // prints 5


See pascal_variable_scope in tutorialspoint.com and http://aelinik.free.fr/c/ch14.htm

Variable scope is a foretaste of object oriented programming, in the sense that it anticipates some encapsulation concepts.

### The search for the Ludolphine

#### Part 1: Using the Clipper Tools (CT) Library

If you checked the list of functions you will have noticed that the xBases have no trigonometric functions. Not that in general they miss them: these languages are targeted database applications such as "accounting systems and airline reservations systems" (see w:Database application. ) in which trigonometric functions are not really important. But we now ask ourself how to compute an approximation to the Ludolphine number, π (more informations on this "search" at http://www.mathpages.com/home/kmath457.htm), We can do it using the CT library (see http://vouch.info/harbour/index.html?hbct.htm), or importing the C standard library function atan.

 && compile with ''hbmk2 computepi.prg -lhbct''
PROCEDURE MAIN
SET DECIMAL TO 14
? 4 * ATAN (1)


#### Part 2: Mixing C and Harbour Code

We get the idea from Harbour for beginners by Alexander Kresin (http://www.kresin.ru/en/hrbfaq_3.html).

  #pragma BEGINDUMP
#include <extend.h>
#include <math.h>
HB_FUNC( ATAN )
{
double x = hb_parnd(1);
hb_retnd( atan( x ) );
};
#pragma ENDDUMP
SET DECIMAL TO 14
? 4 * ATAN (1)


It must be noted that the extend.h file (* Compatibility header file for CA-Cl*pper Extend System) contains this warning:

/* DON'T USE THIS FILE FOR NEW HARBOUR C CODE */
/* This file is provided to support some level of */
/* Harbour compatibility for old Clipper C extension code */


In fact this example is here only to consider how the open source cross-compilers (Harbour in this case) extend themselves with C library functions, which gives them a lot of flexibility. Not that computing π would be useful in itself for for the average xBase programmer (by the way the CT library contains a function to directly compute π). We shall not concern ourselves with a method to do that, but move to something more conventional.

### Sorting Algorithms

   // we'll declare and load random numbers from 1 to 100 in an array
DECLARE arrayToSort [12]
FOR I = 1 TO 12
arrayToSort [I] = Int( HB_Random( 1,101 ) )
NEXT

// we review our array
FOR I = 1 TO 12
?? arrayToSort [I]
NEXT

// we'll do Exchange Sort as described in http://www.ee.ryerson.ca/~courses/coe428/sorting/exchangesort.html
// where there is also a nice animation showing how it works! :)
for i := 2 TO Len(arrayToSort)
for j := Len(arrayToSort) TO i step -1
IF arrayToSort [j - 1] > arrayToSort [j]
TEMP := arrayToSort [j - 1]
arrayToSort [j - 1] := arrayToSort [j]
arrayToSort [j] := TEMP
ENDIF
NEXT
NEXT

?
? "Sorted array:"
?

// we look at our sorted array
FOR I = 1 TO 12
?? arrayToSort [I]
NEXT


Here is our basis. We'll add a flag variable to improve this algorithm.

## Database making

Different kinds of database applications exists as well. If you did store your friend's phone numbers and addresses into a word processor, you would have what is called a Free-Form Database (however, a similar expression is an oxymoron in computer science) - askSam is a specialized free-form database application. Now, a word processor lets us search the informations, but other operations, such as sorting them, cannot be done automatically by a word processor.

What about attempting to store it into a spreadsheet? We may use one column for the name, one for the surname, one for the telefone number, one for the city. This quick database, stored in a spreadsheet, may be searched and sorted: for example we can sort it by city and person's name in alphabetical order. This is a flat database, http://www2.research.att.com/~gsf/man/man1/cql.html: a flat database is a sequence of newline terminated records of delimiter separated fields, and a spreadsheet shows its limits in data entry and reporting (if you did want to use the data in your table to print out addresses on envelopes a spreadsheet is not a good tool). An example is MyDatabase (http://www.pcmag.com/article2/0,2817,760833,00.asp).

Spreadsheets are much better to do accounting: how much harder a book-keeper's work would be if his data were stored in a wordprocessing program? The purpose here is to have our data structured in a certain way: all the costs in a place, all earnings in another.

Before 1970 complex databases where managed using Hierarchical Databases (very little information is needed about them - see for example http://www.extropia.com/tutorials/sql/hierarchical_databases.html and http://people.cs.pitt.edu/~chang/156/14hier.html). An example of a hierarchical database is IBM IMS (Information Management System, which was developed during the mid-1960s for applications in the aerospace industry). Hierarchical Databases and Network Databases together form what today are referred to as Legacy Database Systems. Network databases where born as an extension to the programming language COBOL by the Conference on Data Systems Languages (CODASYL).

Today's standard is a relational database, which is "a database with relationships between more than one table of records based on common fields". We will speak of them in detail, but we will briefly mention the fourth approach: Object Oriented Databases. These databases store objects (in the same sense the word is used in the expression object oriented programming). They're not much used, mostly because object are more complex than the simple fields a relational database stores in its tables. Informations at http://www.odbms.org/odmg-standard/.

### Making a first database and recording some data

#### A verbose way

 CREATE TMPNAMES
USE TMPNAMES
APPEND BLANK
REPLACE FIELD_NAME WITH "NAME"
REPLACE FIELD_TYPE WITH "C"
REPLACE FIELD_LEN WITH 15
APPEND BLANK
REPLACE FIELD_TYPE WITH "C"
REPLACE FIELD_LEN WITH 30
CLOSE
CREATE NAMES FROM TMPNAMES && http://www.ousob.com/ng/clguide/ng849db.php


The code above created a DBF file, names.dbf, to be used by the following code. It will add a record to the DBF file. It is equivalent to the "First Sample Program" of my old PC GUIDE, which missed a line that is necessary in modern xBase.

 CLEAR
? "First Sample Program"
SELECT 1
USE NAMES
APPEND BLANK
REPLACE NAME WITH "MIKE BROWN"
REPLACE ADDRESS WITH "ROME STREET, 56"
CLOSE && this line is missing in my PC GUIDE but is needed
QUIT


The CLOSE command is equivalent to the dbCloseArea() function, which closes a work area: Pending updates are written, pending locks are released.

#### A more concise way

The short code below does the same work of the two pieces of code of the previous section (it only produces a different file name, namesdb.dbf instead of names.dbf).

 local aStruct := { { "NAME", "C", 15, 0 }, ;
{ "ADDRESS",   "C",  30, 0 }}
REQUEST DBFCDX
dbCreate( "namesdb", aStruct, "DBFCDX", .t., "NAMESDB" )
&& http://www.fivetechsoft.com/harbour-docs/api.html
USE NAMESDB
NAMESDB->(DbAppend())
NAMESDB->NAME := "MIKE BROWN"


This example uses the alias operator, ->. http://www.ousob.com/ng/clguide/ngcf412.php

The alias->field_name notation is used to allow access to fields of databases that are loaded but not active. The alias can be specified with the work area number (e.g. 2->std_id), with the work area alias (e.g. B->std_id), or with the database name (e.g. STUDENTS->std_id).

The result of this code is a file named namesdb.dbf. Informations about how DBF files are can be find at DBF File structure, http://www.dbf2002.com/dbf-file-format.html, where we find this list of Field type:

• C – Character
• Y – Currency
• N – Numeric
• F – Float
• D – Date
• T – DateTime
• B – Double
• I – Integer
• L – Logical
• M – Memo
• G – General
• C – Character (binary)
• M – Memo (binary)
• P – Picture
• + – Autoincrement (dBase Level 7)
• O – Double (dBase Level 7)
• @ – Timestamp (dBase Level 7)

In my PC Guide the .dbf file was made with the DataBase Utility DBU. Clones of this utility are FiveDBU (with source code) at https://code.google.com/archive/p/fivewin-contributions/downloads, DBF Viewer Plus at http://www.alexnolan.net/software/dbf.htm, CLUT at http://www.scovetta.com/archives/simtelnet/msdos/clipper.

From https://code.google.com/archive/p/fivewin-contributions/downloads we can get fivedbu_20130930.zip (New FiveDBU version with enhancements on ADO fields editing). It supports ADO, 3 RDD (DBFNTX, CBFCDX and RDDADS) and 6 languages - select "Bases de datos -> Preferencias -> Lenguaje: Inglés" to have it in English.

Let us see what is in our little file so far.

 USE NAMES


### Database Design Issue: the First Normal Form (1NF)

The work done in the previous section was intended to exactly reproduce the database proposed in my PC GUIDE. There are, however, inconvenients: having only one NAME field, this database cannot sort its data on the last name. Also, a careless user might insert the data of some people with the last name first, and some other data with the first name last. When designing a database precautions should be taken of these possibilities. The first normal form (http://www.1keydata.com/database-normalization/first-normal-form-1nf.php, http://www.sqa.org.uk/e-learning/SoftDevRDS02CD/page_14.htm) requires you to define fields whose information cannot be divided into smaller parts. So, instead of a NAME field, we should have a FIRST_NAME and LAST_NAME fields. Complying to the first normal form, our little database would be on the on the right track to being a normalized database.

### Complicating our simple database

Harbour contains a file named test.dbf. Launch hbrun in its directory and type in

use test
browse()


At this point we see that it is a 500 record table. Move around with the cursor keys and, when you're finished, punch the Esc key to quit this interactive table browser and editor. To get the record number of a person called Ted issue:

locate for first="Ted"
? recno()


Here is the testdbf.prg source from \hb30\tests. It should be discussed in detail. It is a GPL piece of code poorly commented.

 /*
* $Id: testdbf.prg 1792 1999-11-10 10:17:19Z bcantero$
*/

function main()

local nI, aStruct := { { "CHARACTER", "C", 25, 0 }, ;
{ "NUMERIC",   "N",  8, 0 }, ;
{ "DOUBLE",    "N",  8, 2 }, ;
{ "DATE",      "D",  8, 0 }, ;
{ "LOGICAL",   "L",  1, 0 }, ;
{ "MEMO1",     "M", 10, 0 }, ;
{ "MEMO2",     "M", 10, 0 } }

REQUEST DBFCDX

dbCreate( "testdbf", aStruct, "DBFCDX", .t., "MYALIAS" )

? "[" + MYALIAS->MEMO1 + "]"
? "[" + MYALIAS->MEMO2 + "]"
? "-"
MYALIAS->( dbAppend() )
MYALIAS->MEMO1 := "Hello world!"
MYALIAS->MEMO2 := "Harbour power"
? "[" + MYALIAS->MEMO1 + "]"
? "[" + MYALIAS->MEMO2 + "]"
MYALIAS->( dbAppend() )
MYALIAS->MEMO1 := "This is a test for field MEMO1."
MYALIAS->MEMO2 := "This is a test for field MEMO2."
? "[" + MYALIAS->MEMO1 + "]"
? "[" + MYALIAS->MEMO2 + "]"
MYALIAS->NUMERIC := 90
MYALIAS->DOUBLE := 120.138
? "[" + Str( MYALIAS->DOUBLE ) + "]"
? "[" + Str( MYALIAS->NUMERIC ) + "]"

? ""
? "Press any key..."
InKey( 0 )

? ""
? "Append 50 records with memos..."
for nI := 1 to 50
MYALIAS->( dbAppend() )
MYALIAS->MEMO1 := "This is a very long string. " + ;
"This may seem silly however strings like this are still " + ;
"used. Not by good programmers though, but I've seen " + ;
"stuff like this used for Copyright messages and other " + ;
"long text. What is the point to all of this you'd say. " + ;
"Well I am coming to the point right now, the constant " + ;
"string is limited to 256 characters and this string is " + ;
"a lot bigger. Do you get my drift ? If there is somebody " + ;
"who has read this line upto the very end: Esto es un " + ;
"sombrero grande rid¡culo." + Chr( 13 ) + Chr( 10 ) + ;
"/" + Chr( 13 ) + Chr( 10 ) + "[;-)" + Chr( 13 ) + Chr( 10 )+ ;
"\"
next
MYALIAS->( dbCommit() )

? "Records before ZAP:", MYALIAS->( LastRec() )
? "Size of files (data and memo):", Directory( "testdbf.dbf" )[1][2], ;
Directory( "testdbf.fpt" )[1][2]
MYALIAS->( __dbZap() )
MYALIAS->( dbCommit() )
? "Records after ZAP:", MYALIAS->( LastRec() )
? "Size of files (data and memo):", Directory( "testdbf.dbf" )[1][2], ;
Directory( "testdbf.fpt" )[1][2]
? "Value of fields MEMO1, MEMO2, DOUBLE and NUMERIC:"
? "[" + MYALIAS->MEMO1 + "]"
? "[" + MYALIAS->MEMO2 + "]"
? "[" + Str( MYALIAS->DOUBLE ) + "]"
? "[" + Str( MYALIAS->NUMERIC ) + "]"
? "Press any key..."
InKey( 0 )
dbCloseAll()

dbCreate( "testdbf", aStruct,, .t., "MYALIAS" )

for nI := 1 to 10
MYALIAS->( dbAppend() )
MYALIAS->NUMERIC := nI
if nI == 3 .or. nI == 7
MYALIAS->( dbDelete() )
? "Deleting record", nI
endif
next
MYALIAS->( dbCommit() )

? ""
? "With SET DELETED OFF"
? "Press any key..."
InKey( 0 )

MYALIAS->( dbGoTop() )
do while !MYALIAS->( Eof() )
? MYALIAS->NUMERIC
MYALIAS->( dbSkip() )
enddo

SET DELETED ON
? ""
? "With SET DELETED ON"
? "Press any key..."
InKey( 0 )

MYALIAS->( dbGoTop() )
do while !MYALIAS->( Eof() )
? MYALIAS->NUMERIC
MYALIAS->( dbSkip() )
enddo

? ""
? "With SET DELETED ON"
? "and  SET FILTER TO MYALIAS->NUMERIC > 2 .AND. MYALIAS->NUMERIC < 8"
? "Press any key..."
InKey( 0 )

MYALIAS->( dbSetFilter( { || MYALIAS->NUMERIC > 2 .AND. MYALIAS->NUMERIC < 8 }, ;
"MYALIAS->NUMERIC > 2 .AND. MYALIAS->NUMERIC < 8" ) )
MYALIAS->( dbGoTop() )
do while !MYALIAS->( Eof() )
? MYALIAS->NUMERIC
MYALIAS->( dbSkip() )
enddo

SET DELETED OFF
? ""
? "With SET DELETED OFF"
? "and  SET FILTER TO MYALIAS->NUMERIC > 2 .AND. MYALIAS->NUMERIC < 8"
? "Press any key..."
InKey( 0 )

MYALIAS->( dbSetFilter( { || MYALIAS->NUMERIC > 2 .AND. MYALIAS->NUMERIC < 8 }, ;
"MYALIAS->NUMERIC > 2 .AND. MYALIAS->NUMERIC < 8" ) )
MYALIAS->( dbGoTop() )
do while !MYALIAS->( Eof() )
? MYALIAS->NUMERIC
MYALIAS->( dbSkip() )
enddo

? "dbFilter() => " + dbFilter()
? ""

? "Testing __dbPack()"
? "Records before PACK:", MYALIAS->( LastRec() )
? "Size of files (data and memo):", Directory( "testdbf.dbf" )[1][2], ;
Directory( "testdbf.dbt" )[1][2]
SET FILTER TO
MYALIAS->( __dbPack() )
MYALIAS->( dbCommit() )
? "Records after PACK:", MYALIAS->( LastRec() )
? "Size of files (data and memo):", Directory( "testdbf.dbf" )[1][2], ;
Directory( "testdbf.dbt" )[1][2]
? "Press any key..."
InKey( 0 )
? "Value of fields:"
MYALIAS->( dbGoTop() )
do while !MYALIAS->( Eof() )
? MYALIAS->NUMERIC
MYALIAS->( dbSkip() )
enddo
? ""

? "Open test.dbf and LOCATE FOR TESTDBF->SALARY > 145000"
? "Press any key..."
InKey( 0 )
dbUseArea( ,, "test", "TESTDBF" )
locate for TESTDBF->SALARY > 145000
do while TESTDBF->( Found() )
? TESTDBF->FIRST, TESTDBF->LAST, TESTDBF->SALARY
continue
enddo
? ""
? "LOCATE FOR TESTDBF->MARRIED .AND. TESTDBF->FIRST > 'S'"
? "Press any key..."
InKey( 0 )
dbUseArea( ,, "test", "TESTDBF" )
locate for TESTDBF->MARRIED .AND. TESTDBF->FIRST > 'S'
do while TESTDBF->( Found() )
? TESTDBF->FIRST, TESTDBF->LAST, TESTDBF->MARRIED
continue
enddo

return nil


A simple data base input mask (from the Wikipedia Clipper entry):

USE Customer SHARED NEW
clear
@  1, 0 SAY "CustNum" GET Customer->CustNum PICT "999999" VALID Customer->CustNum > 0
@  3, 0 SAY "Contact" GET Customer->Contact VALID !empty(Customer->Contact)


### Deleting records

? LASTREC()
DELETE RECORD 4
PACK
? LASTREC()


In this piece of code the command DELETE marks the fourth record for deletion. But the file is not altered, not even by a CLOSE command. The PACK command actually removes the records marked for deletion (and also makes some additional work). The RECALL command removes the deleted flags. The function DELETED() returns .T. if the current record is marked for deletion, .F. if not.

The PACK command, which does the actual deletion of data from the table, PACK requires that the current database be USEd EXCLUSIVEly. If this condition is not met when PACK is invoked, CA-Clipper generates a runtime error. Additional work that PACK does is to update indexes on the table it alters (if any).

The commands DELETE ALL and PACK are executed by a single command called ZAP.

     &&  This example demonstrates a typical ZAP operation in a network
&&   environment:

USE Sales EXCLUSIVE NEW
IF !NETERR()
SET INDEX TO Sales, Branch, Salesman
ZAP
CLOSE Sales
ELSE
? "Zap operation failed"
BREAK
ENDIF


### An Indexed Example

USE Clients NEW
INDEX ON Name TO Clients UNIQUE


Suppose a table containing these data:

FSTNAME	LSTNAME
John   	Doe
John   	Doe
John   	Doe
Jane   	Doe


We can create a little index file with this piece of code:

SELECT 1
USE ind
? FILE("ind.ntx")
INDEX ON FstName TO ind
? FILE("ind.ntx") // we verify that a NTX file has been created


## Other programming topics

### Code blocks

Sites around the Net says that Clipper 5 documentation called them unnamed assignable functions.

Let us get back at our Celsius to Fahrenheit temperature converting function:

FUNCTION cels2f( tempCelsius )
tempFahrenheit := (tempCelsius*1.8 + 32)
RETURN tempFahrenheit


and redo it as a codeblock:

Cels2F := { | celsius | Fahrenheit := (Celsius * 1.8 + 32) } // our first codeblock

? Eval(Cels2F,100)
? Eval(Cels2F,0)


In the first line we assigned a code block to a variable named Cels2F. The code block is comprised in braces. The first thing is a variable that is to be passed to the block, between vertical bars (|). More variables should be separated by commas. Then we can write the instructions (more than one should be separated by commas).

Later we use two times the Eval function giving it two arguments: the name we assigned to our codeblock and the parameter to pass it. In addition to Eval, other functions can evaluate code block: AEval() and dbEval(). Ascan() and Asort() can be given code blocks to change their behavior.

A code block cannot contain commands.

As code blocks can't contain commands, we can't put a ? command in them, but have to use the corresponding QOut() function.

## Object Oriented Programming

### Looking at Object-Oriented Programming from a Safety Distance

Let us suppose we're dealing with the distance function given the Cartesian coordinates of the points (http://mathinsight.org/cartesian_coordinates). The formulas we'll apply are:

${\displaystyle D_{1}={\sqrt {(x_{2}-x_{1})^{2}}}}$

${\displaystyle D_{2}={\sqrt {(x_{2}-x_{1})^{2}+(y_{2}-y_{1})^{2}}}}$

${\displaystyle D_{3}={\sqrt {(x_{2}-x_{1})^{2}+(y_{2}-y_{1})^{2}+(z_{2}-z_{1})^{2}}}}$

for (Euclidean) distance on a real line, Euclidean plane and Euclidean space respectively.

In procedural programming our functions would look like this:

? distance1d(4,-3)
? distance2d(2,-3,-1,-2)
? distance3d(1,1,1,4,4,4)

FUNCTION distance1d( x1, x2 )
RETURN sqrt((x2-x1)^2)

FUNCTION distance2d( x1,y1,x2,y2 )
RETURN sqrt((x2-x1)^2+(y2-y1)^2)

FUNCTION distance3d( x1,y1,z1,x2,y2,z2 )
RETURN sqrt((x1-x2)^2+(y1-y2)^2+(z1-z2)^2)


We defined three functions, with different names, which take as arguments the coordinates. But doing so we need to pass six arguments for the distance in a three-dimensional space.

If we're doing it with object oriented programming we may get something like this:

#include "hbclass.ch"

CREATE CLASS Point1D

VAR Abscissa    // the abscissa of our point

METHOD New( Abscissa )    // Constructor

METHOD Distance( Point )

ENDCLASS

CREATE CLASS Point2D INHERIT Point1D

VAR Ordinate    // the ordinate of our point

METHOD New( Abscissa, Ordinate )    // Constructor

METHOD Distance( Point )

ENDCLASS

CREATE CLASS Point3D INHERIT Point2D

VAR Zcoord    // the Z-coordinate of our point

METHOD New( Zcoord )    // Constructor

METHOD Distance( Point )

ENDCLASS

&& Constructors Zone
METHOD New( Abscissa ) CLASS Point1D

::Abscissa := Abscissa

RETURN Self

METHOD New( Abscissa, Ordinate ) CLASS Point2D

::Abscissa := Abscissa
::Ordinate := Ordinate

RETURN Self

METHOD New( Abscissa, Ordinate, Zcoord ) CLASS Point3D

::Abscissa := Abscissa
::Ordinate := Ordinate
::Zcoord := Zcoord

RETURN Self

&&Distances Methods

METHOD Distance( Point ) CLASS Point1D

RETURN Sqrt( ( Self:Abscissa - Point:Abscissa ) ^ 2 )

METHOD Distance( Point ) CLASS Point2D

RETURN Sqrt( ( Self:Abscissa - Point:Abscissa ) ^ 2 + ( Self:Ordinate - Point:Ordinate ) ^ 2 )

METHOD Distance( Point ) CLASS Point3D

RETURN Sqrt( ( Self:Abscissa - Point:Abscissa ) ^ 2 + ( Self:Ordinate - Point:Ordinate ) ^ 2 + ( Self:Zcoord - Point:Zcoord ) ^ 2 )

PROCEDURE Main()

FirstPoint := Point1D():New( 3 )
SecondPoint := Point1D():New( - 3 )
? FirstPoint:Abscissa
? FirstPoint:Distance( SecondPoint )
ThirdPoint := Point2D():New( 2, - 3 )
FourthPoint := Point2D():New( - 1, - 2 )
? ThirdPoint:Distance( FourthPoint )
FifthPoint := Point3D():New( 1, 1, 1 )
SixthPoint := Point3D():New( 4, 4, 4 )
? FifthPoint:Distance( SixthPoint )

RETURN


Here we've defined three classes, their constructors, and a distance method for each of them, and showed how to use them. It is also a simple example of how inheritance works. Other concepts are encapsulation (information hiding or data hiding), abstraction, polymorphism, overloading and overriding of methods. Inheritance plays a central role in a key concept: reuse. A class can be reused in a software project if it is exactly what was needed; or if it is not exactly what was needed it can be extended by defining a subclass. Much like the design of a database, the design of object oriented class is an art with its principles, see for example http://www.oodesign.com/, http://www.codeproject.com/articles/567768/object-oriented-design-principles and pages about UML like http://www.uml-diagrams.org/uml-object-oriented-concepts.html.

The first thing to note is that we start by including the clipper header file hbclass.ch, the header file for Class commands. This means that object oriented commands have been added to the xBase foundation of Harbour.

Access to variables and methods of an object is done via the colon operator. A prepended double colon refers to variables with a larger scope (such as those passed to a method).

In the code above we defined three classes, each one implementing a Point. Point2D for example was defined as a class extending Point1D, that is a generalization of the concept. A method Distance was given for each of the classes.

A line such as

  ? FifthPoint:Distance( SixthPoint )


contain the output command ?, the reference to an object (FifthPoint in this case), an invocation of the Distance method :Distance, to which another point was passed ( SixthPoint ).

It is also possible to write a Distance function which takes two arguments of a Point class, that may look like this:

FUNCTION Distance ( Point1, Point2 )
RETURN Sqrt( ( Point1:Abscissa - Point2:Abscissa ) ^ 2 + ( Point1:Ordinate - Point2:Ordinate ) ^ 2 + ( Point1:Zcoord - Point2:Zcoord ) ^ 2 )

? Distance( FifthPoint, SixthPoint )


This is, however, not object-oriented programming, as we could have written the same function with a not object-oriented language such as Pascal or C, passing it two structs, or records as Pascal calls them, named Point1 and Point2.

It is important the fact that some data internal to the object (set by the real programmer of the thing) can't be changed by the object user. In real life an example is that of a car engine. The provider of the object set a number of cylinders, and we have not many chances of changing that: we've got to regard it as a constant. There is naturally a number of interesting formulas about engines that engineers use (some to be seen at http://www.thecartech.com/subjects/engine/engine_formulas.htm). For example the one for computing the Engine Volumetric Efficiency given the volume of air taken into a cylinder and the cylinder swept volume. Here comes the importance of data hiding: nobody needs to know those informations to get his car going. Also, when someone designes an engine they probably don't expect the user to change the volumetric efficiency by operating on the engine. The same thing is obtained in object oriented programming using visibility modifiers, or access modifiers.

   [CREATE] CLASS <cClassName> [ FROM | INHERIT <cSuperClass1> [, ... ,<cSuperClassN>] ]
[ MODULE FRIENDLY ] [ STATIC ] [ FUNCTION <cFuncName> ]

[HIDDEN:]
[ CLASSDATA | CLASSVAR  | CLASS VAR <DataName1>]
[ DATA | VAR  <DataName1> [,<DataNameN>] [ AS <type> ] [ INIT <uValue> ]
[[EXPORTED | VISIBLE] | [PROTECTED] | [HIDDEN]] [READONLY | RO] ]
...
[ METHOD <MethodName>( [<params,...>] ) [CONSTRUCTOR] ]
[ METHOD <MethodName>( [<params,...>] ) INLINE <Code,...> ]
[ METHOD <MethodName>( [<params,...>] ) BLOCK  <CodeBlock> ]
[ METHOD <MethodName>( [<params,...>] ) EXTERN <funcName>([<args,...>]) ]
[ METHOD <MethodName>( [<params,...>] ) SETGET ]
[ METHOD <MethodName>( [<params,...>] ) VIRTUAL ]
[ METHOD <MethodName>( [<params,...>] ) OPERATOR <op> ]
[ ERROR HANDLER <MethodName>( [<params,...>] ) ]
[ ON ERROR <MethodName>( [<params,...>] ) ]
...
[PROTECTED:]
...
[VISIBLE:]
[EXPORTED:]
...

[FRIEND CLASS <ClassName,...>]
[FRIEND FUNCTION <FuncName,...>]

[SYNC METHOD <cSyncMethod>]

ENDCLASS [ LOCK | LOCKED ]


### Another example

Copied verbatim from w:Harbour (software)

 #include "hbclass.ch"

PROCEDURE Main()

LOCAL oPerson

CLS

oPerson := Person():New( "Dave" )

oPerson:Eyes := "Invalid"

oPerson:Eyes := "Blue"

RETURN

CREATE CLASS Person

VAR Name INIT ""

METHOD New( cName )
METHOD Describe()

ACCESS Eyes INLINE ::pvtEyes
ASSIGN Eyes( x ) INLINE iif( HB_ISSTRING( x ) .AND. x \$ "Blue,Brown,Green", ::pvtEyes := x, Alert( "Invalid value" ) )

PROTECTED:

VAR pvtEyes

ENDCLASS

// Sample of normal Method definition
METHOD New( cName ) CLASS Person

::Name := cName

RETURN Self

METHOD Describe() CLASS Person

LOCAL cDescription

IF Empty( ::Name )
cDescription := "I have no name yet."
ELSE
cDescription := "My name is: " + ::Name + ";"
ENDIF

IF ! Empty( ::Eyes )
cDescription += "my eyes' color is: " + ::Eyes
ENDIF

RETURN cDescription


## Harbour CGI

and see the side box at http://gnosis.cx/publish/programming/harbour.html