Last modified on 7 September 2014, at 13:45

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. When (and if) finished, it will prove a complete guide to Open Source Clipper programming. However, this page is still very incomplete.

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 (and I wonder if I can recover the syntax highlighting...). 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).

Some sections are missing. Illustrations are missing. I will try to upload all the rest next time I connect... (note written 16.56 02/06/2012, Italian time).

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.

This Guide was born because I had to follow 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 tutorial and that the books about Clipper/xBase/Visual Objects and so on couldn't be found in any bookstore (not even in libraries!).

Open Source and licensesEdit

Let's define 'Open Source': it is software distributed with the source code that anybody can study, modify for their own needs and redistribute. It is often also free (it costs nothing).

If you want to know more, go to www.opensource.org, and http://en.wikipedia.org/wiki/Open_source.

Harbour, xHarbour and Clip are released under the GNU General Public License (GPL) plus an option that allow the users to distribute the applications they develop under the license they wish (if they were to follow strictly the GPL they would have had to distribute their applications under the GPL). The GPL is the license adopted by the GNU project, and it makes it perhaps the most famous Open Source license because an entire operating system is released under it - the OS that is commonly referred to by the name of its kernel, Linux, and that some people call GNU/Linux.

Links for "what is the GNU Project?", "what is the General Public License?", "what is Linux?".

For more informations visit http://www.gnu.org/gnu/thegnuproject.html and http://en.wikipedia.org/wiki/GNU, http://www.fsf.org/licensing/licenses/gpl.html, http://www.linux.org/.

In addition to the GPL, Clip offers optionally a commercial license. The user can choose which license applies to his installation.

x2c is released under the Apache license. The most important software released under the Apache license is Apache, a widely used open source web server.

http://en.wikipedia.org/wiki/Apache_HTTP_server and http://en.wikipedia.org/wiki/Apache_License.

http://en.wikibooks.org/wiki/Wikibooks:Creative_Commons_Attribution-ShareAlike_3.0_Unported_License

Some curiosities and a little historyEdit

Definition of 'clipper' translated and adapted from two Italian encyclopaedias: «sailing vessel with three or five masts, sharp prow, large, square sails, gross tonnage 600-1200.». Thus a "clipper" was a kind of ship, used in the second half of the XIX century. The choice of this name, and of other names such as "Harbour" and "Flagship", suggests that xBase programmers might have a distinctive maritime vocation. The first Clipper was built in Baltimore in 1746. During the War of American Independence, the Baltimore Clipper had great development. Other ships then took the name of Clipper though there was little similarity (except for the width of the canopy) with the first. From 1840 onwards, Clippers became especially famous for the gold rush and for the famous "tea and wool races". Although at that time regular steamships were already navigating, the Clippers maintained slightly higher average speeds of the fastest steamers. In 1854 the Clipper Lightning by Donald Mc Kay covered the distance from Boston to Liverpool in 13 days, 19 hours and a half (a record time for a vessel). The famous English Clipper Cutty Sark, one of the fastest sailing ships of all time, launched in 1869, traveled 363 miles in 24 hours. Another famous Clipper, the Melbourne, used to transport passengers, launched in 1875, travelled from England to Australia in 81 days. The golden age of Clippers ended around 1880.

A few links to expand on this type of Clipper:

http://www.titanic-nautical.com/Clipper-Ships-Wiki.html http://en.wikipedia.org/wiki/Donald_McKay http://en.wikipedia.org/wiki/Lightning_(clipper)

According to my Italian dictionary, "clipper" has two other meanings: "(aviation) big airplane for trans-Atlantic flights" - see http://www.flyingclippers.com/transoceanic.html and "(electronics) electronic device to reduce the amplitude of a wave" - see http://www.daenotes.com/electronics/devices-circuits/clipper-clamper, http://www.daenotes.com/electronics/digital-electronics/clipper-circuits.

I knew the name of the developer who chose the name "Clipper", but I have forgot it :-(

xBase ANSI standard: http://www.fghoche.com/Xbaseus.htm, http://www.fghoche.com/whatxb.htm.

http://cbbrowne.com/info/xbase.html.

http://linux.techass.com/projects/xdb/xbasedocs/xbase_c1.html.

http://www.underflap.com/clipper/.

Today there is a free dBase clone: http://dollybase.sourceforge.net/. (The reference to the sheep "Dolly", clonated in 1997, looks quite overt...).

At the moment, the commercial software available comprehends CA-Clipper 5.3x, Alaska Xbase++, CA-Visual Objects, Multisoft Flagship, Microsoft FoxPro, Visual dBase, Harbour.

The May 1998 issue of the Italian magazine PC Professionale in a review for Borland Visual dBase 7 started by summarizing its "glorious" history:

«dBase III has been the workhorse of the programmers of the '80s, then gave way to other instruments, especially in the transition from MS-DOS to Windows 3.1, but it never left the scene, it even had visual developments. The seventh version of the scion of that language, fiercer than ever, is thirty-two bits, supports ActiveX controls, remote SQL databases and a renewed and productive work environment.

It is unusual for programmers who have been in business for several years to never have heard of dBase. The first version of this product was a sort of Visual Basic of the 80s: it freed developers from the complications of access to database files and the interface was easy to use as it could be DOS, thanks to the automatic instructions completion and effective online help. Since then much water has passed under the bridges and dBase programmers had access to a first compiler, graphical interfaces, and even then a migration of the syntax to an object oriented approach.»

The author, Michele Costabile, noted also that:

«The difference between programmable databases (Access, FoxPro) and traditional development tools (Visual Basic, Delphi) is becoming largely a matter of nuances: the first were born as a language built around a database, and the latters have come to assimilate structurally database support.»

According to Dev (a programmers' Italian magazine), the Harbour Project was started by Antonio Linares, author of FiveWin, about 1998 with an original name as Five and that the project started on a CVS server named harbour.joca.es.

Getting StartedEdit

Other sites to visit & files to downloadEdit

The article on Freshmeat at the address http://freshmeat.net/articles/view/307/, Non-SQL Databases for Linux, is a good starting point for our xBase study. If you discover that you like very much xBase, have a look at http://www.reocities.com/tablizer/xbasefan.htm, a page for xBase fans.

A set of Norton Guides, including documentation for Clipper from Summer 87 to Clipper 5.3, and also for Clip-4-Win version 3.0, Blinker 5.1, Harbour 0.37, and other tools is located in this good website worth a visit: http://www.clipx.net/norton.php. The last Harbour installs a Norton Guide file (namely in the path c:\hb31\examples\gfspell\spell.ng). A Norton Guide Viewer for Windows by Dave Pearson can be downloaded at his website http://www.davep.org/norton-guides/

discovered a pair of basic tutorials - yet complete - in Spanish (being Italian, I can read and understand Spanish without too much trouble...). One is contained in this page: http://www.elguille.info/Clipper/manual.htm (if you know Spanish and want to print it, it's about 50 pages long). The second tutorial is compressed in a zip you can download from http://mx.geocities.com/maghtin/manuals.htm (the file is named clipper5.zip and it contains a 33-page pdf file).

http://www.ousob.com/norton.php

I will surf to know what's in The Oasis (http://www.the-oasis.net/). They included a link to this Guide and seem to have a large archive of Clipper material.

Clipper TutorialEdit

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: an analysisEdit

Let's try to highlight the parts of helloworld:

function MAIN* This is an exampleclear?"Hello, the weather is fine today" return (you can obtain this highlighting by using 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).

? "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.

The compilation processEdit

A flowchart of the compilation process (kindly supplied by Wojtek Birula).

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.

Data Types in General (and Their Operators)Edit

  • string
  • number
  • date
  • boolean
  • array
  • memo

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 && it would lament with
&& 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
caporetto := ctod("10-24-1917")
a := date() && system date
? a + 1 && 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 for expand on the subject of operator precedence
? 1/2+2^3*sqr(25)-3^2
? 1/2+2^3*(sqr(25)-3^2)

Now, about the 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

Boolean Algebra & Flow ControlEdit

DO WHILE, EXIT, LOOP, ENDDOEdit

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 num, sum, n 
CLS 
? "Let's sum up the first n odd numbers." 
INPUT "How many numbers shall I sum up? " TO n 
sum=0 
num=1 
DO WHILE num <= 2*n    
 sum=sum+num    
 num=num+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 Galois' 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
...
lMore := ()
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.

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.

FOR...NEXTEdit

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.

Database makingEdit

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 - 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).

For more complex databases, the flat approach is not recommended, and the solution is to use relational databases. They are "a database with relationships between more than one table of records based on common fields". http://www.databasedev.co.uk/design_basics.html

http://www.filemaker.com/help/html/relational.11.2.html

http://www.lnf.infn.it/Calcolo/doc/AppuntiLinux/a2471.html

CREATE NAMES
USE NAMES
APPEND BLANK
REPLACE FIELD_NAME WITH "NAME"
REPLACE FIELD_TYPE WITH "C"
REPLACE FIELD_LEN WITH 15
APPEND BLANK
REPLACE FIELD_NAME WITH "ADDRESS"
REPLACE FIELD_TYPE WITH "C"
REPLACE FIELD_LEN WITH 30
CLOSE
RETURN
CREATE NAMES FROM NAMES

The following code will add a record to the names.dbf file created by the code above:

CLEAR
? "First Sample Program"
SELECT 1
USE NAMES
APPEND BLANK
REPLACE NAME WITH "MIKE BROWN"
REPLACE ADDRESS WITH "ROME STREET, 56"
QUIT


GUI DesignEdit

This section focuses on the use of some libraries for producing a Graphical User Interface.

http://www.the-holms.org/xharbour/minigui.htm http://tutorial.software.informer.com/download-tutorial-clipper-dbf/

http://www.clipper.com/Clipper_Tutorials_Index.htm http://www.the-holms.org/xharbour/compiler.htm


http://www.oohg.org/

http://sourceforge.net/projects/hmg

http://sourceforge.net/projects/minigui

Fivewin for Harbour (FWH) FiveWin is original a library for Clipper 5 which you ... More info can be found here: http://sourceforge.net/projects/wxharbour/

http://www.harbourminigui.com/index.php?option=com_content&task=view&id=16&Itemid=29

http://xbaseguru.blogspot.it/2009/04/tutorial-de-xharbour-para-windows.html

http://comments.gmane.org/gmane.comp.compilers.harbour.user/270

http://ehmdunque.altervista.org/i-informatica/manuali/Harbour/Breve_intro_Harbour.html

http://cch4clipper.blogspot.it/2011/04/harbour-howto-tutorial-rev-51-is-born.html

http://www.gruppoeratostene.com/harbour/harbour-tutorials.htm

http://aruiz.synaptia.net/siliconisland/2006/08/clipem_my_own_c.html

http://harbourlanguage.blogspot.it/2011/03/tutorial-qt.html

http://mingw.turbolinux.org/tag/minigui

http://www.gruppoeratostene.com/harbour/hb-howto-tutorial.pdf


http://vivaclipper.wordpress.com/ (edited by bpd2000)