Author: Eric Lendvai     

Eric Lendvai

×

Bio
Full Stack Web and Desktop App Developer with 30+ years of experience in designing and developing medium to large applications in multiple computer languages.

Website
https://www.linkedin.com/in/ericlendvai/

Country
United States of America

Languages
English, French, Hungarian

Done

function main()?"Hello World"   return nil

#include "hbclass.ch"function main()local cString1 := "Hello"local cString2local oLocation1 := Location()local oLocation2local aList1 := {1,2,3,4,{"a","b","c"}}local aList2local aList3local nNumber1 := 1local dDate1 := 0d20220319local dDate2 := {^ 2022-02-01}local tTime1 := {^ 2022-03-05 10:22:30 }local tTime2 := t"2022-04-06 20:44:45.437"set century on   // Will direct the ? operator (print) to display 4 digits for year component of dates.cString1 += " World"?((cString2 := cString1) == "Hello") // -> .F.?cString1                            // -> "Hello World"?cString2                            // -> "Hello World"oLocation2 := oLocation1oLocation1:cCity := "Tacoma"?oLocation1:cCountry+", "+oLocation1:cState+", "+oLocation1:cCity  // -> United States of America, Washington, Tacoma?oLocation2:cCountry+", "+oLocation2:cState+", "+oLocation2:cCity  // -> United States of America, Washington, TacomaaList2 := aList1aList3 := AClone(aList1)aList2[1] := "a"?hb_jsonEncode(aList1)  // -> ["a",2,3,4,["a","b","c"]]?hb_jsonEncode(aList2)  // -> ["a",2,3,4,["a","b","c"]]?hb_jsonEncode(aList3)  // -> [1,2,3,4,["a","b","c"]]?"Are the objects 1 and 2 the same ",oLocation1 == oLocation2  // -> .T.?"Are the arrays 1 and 2 the same ",aList1 == aList2           // -> .T.?"Are the arrays 1 and 3 the same ",aList1 == aList3           // -> .F.nNumber1 += 5     // Increment by 5nNumber1 -= 2     // Decrement by 2?nNumber1         // -> 4dDate2 += 1       // Increment by 1 daydDate2 -= 2       // Decrement by 2 daysdDate1 -= dDate2?dDate1    // -> 47           (meaining there are 45 days between the 2 dates)?dDate2    // -> 01/31/2022   (Added a day to the date. The display will depend of localisation.)?tTime1 += 1       // ->  03/06/2022 10:22:30.000    (Incrementation are by days not seconds)?tTime2 - tTime1   // ->  31.432123                  (Number of days. The fractions represents the hours and seconds.)return nilclass Location    //Extra Line after class to work around bug definition    DATA cState   init "Washington"    DATA cCity    init "Seattle"    DATA cCountry init "United States of America"endclass

function main()local l_tNow := hb_datetime()  // To get the current date time.local l_dDatelocal l_cTime24    // Will receive the current time of the day in 24 hours mode as text.local l_cTimeAmPm  // Will receive the current time of the day in 12 hours mode as text.local l_nSeconds   // will receive the current time of the day in seconds with fractions.local l_tMoonLoadingGMT := hb_CtoT("08/20/1969 4:17 pm GMT")local l_tMoonLoadingPSTset century on  //To display the years with 4 digits instead of 2.l_dDate := hb_TtoD(l_tNow,@l_cTime24,"hh:mm:ss")hb_TtoD(l_tNow,@l_cTimeAmPm,"hh:mm:ss am")hb_TtoD(l_tNow,@l_nSeconds)l_tTime := hb_SecToT(l_nSeconds)   // To create a Datetime with only the time component.?"l_tNow",l_tNow?"Now with no milliseconds",hb_SecToT(round(hb_TToSec(l_tNow),0))?"l_dDate",l_dDate?"l_cTime24",l_cTime24?"l_cTimeAmPm",l_cTimeAmPm?"l_nSeconds",l_nSeconds?"l_tTime",l_tTime// Two methods to recombine the date and time values.?"Method 1)",l_dDate+l_tTime?"Method 2)",hb_DtoT(l_dDate)+(l_nSeconds/(24*60*60))?// to display the time as of UTC?"hb_TSToUTC(l_tNow)",hb_TSToUTC(l_tNow)// To find out what the UTC shift is in seconds.// The parameter is used to determine as of when we want to know the UTC shift.// In the USA there is a concept of daylight savings time which will affect the result.?"hb_UTCOffset(l_tNow)",hb_UTCOffset(l_tNow)?"hb_UTCOffset(l_tNow) in hours",hb_UTCOffset(l_tNow)/3600??"Moon Landing time in GMT",l_tMoonLoadingGMTl_tMoonLoadingPST := l_tMoonLoadingGMT+(hb_UTCOffset(l_tMoonLoadingGMT)/86400)?"Moon Landing time in Seattle",l_tMoonLoadingPST?"Moon Landing time in GMT knowing Seattle time",hb_TSToUTC(l_tMoonLoadingPST)??"An empty date",ctod(""),empty(ctod(""))return nil

Executing the code returns the following:

if dow(date()) == 2    // dow() returns the Day Of the Week number    ?"Monday"elseif dow(date()) == 1 .or. dow(date()) == 7    ?"Weekend"else    ?"Tuesday to Friday"endifdo casecase dow(date()) == 2    ?"Monday"case dow(date()) == 1 .or. dow(date()) == 7    ?"Weekend"otherwise    ?"Tuesday to Friday"endcaseswitch dow(date())case 2    ?"Monday"case 1case 7    ?"Weekend"    EXITotherwise    ?"Tuesday to Friday"endswitch

local nLooplocal dLooplocal tLoopset century onfor nLoop = 1 to 10 step 2    ?"Regular Numeric Loop ",nLoop    if nLoop > 6        exit    endif    loop    ?"extra"endfor?nLoop?for dLoop = date() to date()+2 step 1    ?"Regular Date Loop ",dLoopendfor?dLoop?for tLoop = hb_DateTime() to hb_DateTime()+2 step 6/24    ?"Regular Timestamp Loop ",tLoopendfor?tLoop

local nLoopVal1 := -1local nLoopVal2 := -2local cChar1    := "?"local cChar2local hItem     := {=>}local cStringUTF8local cString1 := "hello world"local hArray := {=>}set century onfor each nLoopVal1,nLoopVal2 in {1,3,5,7},{2,4,6,8,10,12,14} DESCEND    ?"For each val1: ",nLoopVal1," (",nLoopVal1:__enumindex,") val2: ",nLoopVal2," (",nLoopVal2:__enumindex,")"endfor?"nLoopVal1 = ",nLoopVal1,"  nLoopVal2 = ",nLoopVal2?cStringUTF8 := "Hello élève"  // This loop will prove bytes are extracted, not characters.?cStringUTF8," Byte Length=",len(cStringUTF8)," UTF Length=",hb_utf8Len(cStringUTF8)for each cChar1,cChar2 in cStringUTF8,@cString1    ?cChar1:__enumindex," ",cChar1    if empty(mod(cChar2:__enumindex,2))        cChar2 := upper(cChar2)    endifendfor?"cChar1 = ",cChar1?"cString1 = ",cString1hb_HKeepOrder(hArray,.t.)hb_HCaseMatch(hArray,.f.)hArray["City"]    := "Seattle"hArray["State"]   := "WA"hArray["Country"] := "USA"for each hItem in hArray DESCEND    ?"HPosition = ",hb_HPos(hArray,hItem:__enumkey)," enumindex = ",hItem:__enumindex," Key = ",hItem:__enumkey," Value = ",hItem:__enumvalueendfor

function main()local nCondi := 7do while nCondi-- > 0    ?nCondi    nCondi -= 1enddoreturn nil

Since Harbour is based on the old language Clipper, created in 1984, before the common use of NULL in databases and SQL, the concept of NULL was not used as "Not Defined" but instead as "Empty" ( Len() == 0 ). 

And NIL had the concept of Unknown variable type (valtype() == "U").

By default Harbour DOES NOT SUPPORT NULL in DBF Tables, and therefore in generic methods to get backend data.

But with the use of the Harbour_ORM and Harbour_VFP repos all these issues can be resolved. Other contributions and repos might also provide a solution, but as the creator of those particular ones, this is what I am covering in the guide.

To be real clear, the native functions for supporting null and nil in Harbour are only for variables, not table->columns. We will discuss later in this guide the support for database/tables/columns....

If you are not using the Harbour_VFP repo to extend your Harbour program use  hb_IsNil(<xExp>), where <xExp> can be a variable or any expression to test if the value is what any other language would consider NULL.

The following is a list of functions that can be used for dealing with NIL variables (NULL in other languages): 

From	Function or Value	Description
Harbour Runtime	hb_IsNull(<xExp>) ➔ <lResult>	Determines if the length of <xExp>, when is a string, an array or a hash, is zero ( Len() == 0 ). A runtime error will happen if <xExp> is not a string, array or hash array.
Harbour Runtime	hb_IsNIL(<xExp>) ➔ <lResult>	Determines if <xExp> evaluates to NIL (valtype() == "U").
Harbour Runtime	hb_Default(<@xVar>,[<xValue>]) ➔ NIL	Sets the value of variable <xVar> to <xValue> when either the current <xVar> value is NIL or its type is different than <xValue>. If no <xValue> specified then, evidently, the <xVar> becomes NIL. If <xVar> has already a value of same type with <xValue>, no change is done! Note: <xVar> must be passed by reference and be an existing variable (if not exists a runtime error occurs). Unlike the VFP NVL() function the type of the second parameter matters.
Harbour Runtime	hb_DefaultValue(<xValue>,<xDefaultValue>) ➔ <xReturn>	Returns <xDefaultValue> if <xValue> is NIL or different type of <xDefaultValue>, otherwise returns <xValue>. It's similar to hb_Default() but not modifying the variable. Unlike the VFP NVL() function the type of the second parameter matters.
Harbour Runtime	NIL	Remember NULL does not exists as part of the core Harbour language.
Harbour Runtime	empty(<xExp>)	Unlike hb_IsNull <xExp> can be of any type. Additionally if it is a string, for empty() to return .f. (false) the string must include a character different than "space","tab", "line feed" and "carriage return", meaning not ascii character 9,10,13 or 32. This is the exact same behavior as in VFP.
Harbour_VFP	IsNull(<x>)	Is simply a preprocessor equivalent to hb_IsNIL(). #xtranslate ISNULL(<x>) => hb_isnil(<x>)
Harbour_VFP	NVL(xExp1,xExp2)	Will return xExp2 if xExp1 is NIL. #xtranslate NVL(<v1>,<v2>) => vfp_nvl(<v1>,<v2>)
Harbour_VFP	.null. NULL	Is simply a preprocessor equivalent to NIL. #xtranslate .null. => NIL #xtranslate NULL => NIL
Harbour_ORM	hb_orm_isnull(<cAliasName>,<cFieldName>)	Will return .t. (true) if the field <cFieldName> in the current record of the alias <xAliasName> is NULL (NIL in Harbour). The function is definied at https://github.com/EricLendvai/Harbour_ORM/blob/master/hb_orm_core.prg The hb_IsNIL(cAliasName->cFieldName) may not work depending of the RDD implementation.
Harbour_ORM	hb_orm_SQLData.Field(par_cName,par_Value)	When querying SQL backends in Harbour by default it is not possible to assign NULL (database NULL). With the Harbour_ORM, it is possible to assign NULL to columns (fields) that are nullable.

The program below will return the following matrix:

function main()local cValues := {"NIL","0","1",[""],[" "],[chr(9)+chr(10)+chr(13)],[0d20220320],[ctod("")],[{}],[{=>}],[{1}],[{"key"=>"value"}],[.f.],[.t.]}local nLooplocal xValue? [<table border="1" pading="2">]?? [<tr>]?? [<td style="padding: 5px;">Value</td>]?? [<td style="padding: 5px;">hb_IsNil()</td>]?? [<td style="padding: 5px;">hb_IsNull()</td>]?? [<td style="padding: 5px;">empty()</td>]?? [</tr>]For nLoop := 1 to Len(cValues)    xValue := Eval(hb_macroBlock(cValues[nLoop]))   // Will convert the text of a value to the actual value.    ?? [<tr>]    ?? [<td style="padding: 5px;">],cValues[nLoop],[</td>]    ?? [<td style="padding: 5px;text-align: center;">],hb_IsNil(xValue),[</td>]    ?? [<td style="padding: 5px;text-align: center;">],iif(valtype(xValue)$"CAH",hb_IsNull(xValue),"NA"),[</td>]    ?? [<td style="padding: 5px;text-align: center;">],empty(xValue),[</td>]    ?? [</tr>]endforreturn nil

function main()local nlooplocal cBuffer := ""local cSource := replicate("X",15)for nloop = 1 to 100000    cBuffer += cSourceendfor?str(len(cBuffer)) //Should be 1,500,000 (1.5 Mb)return nil

Scope hack: If a variable, even a local one, is passed by reference in a sub routine, its value can be altered in the sub routine.

The following are interesting Harbour compilation flags.

• -w3   = warn for variable declarations. Great to ensure missing variable declaration will not default to creating private variables.
• -es2  = process warning as errors.

For public or private variables used across multiple PRG files, at the top of PRG files, a memvar statement should be used to avoid compiler warnings. 

Sometimes at runtime, Harbour can be confused between a public and private variable name or a field name in the current work area. In this case you can use the prefix "M->" in front of the variable name. The use of memvar basically tells Harbour that we are talking about a variable and not a field name. By the way, the prefix "FIELD->" can be used to specify the opposite.

The following code will demonstrate many aspects of variables in Harbour.

Output generated when using the code below, by the Harbour FastCGI sandbox application.

#include "hbmemvar.ch"   static nPRGCounter := 0   memvar nDefineUp   function main()local nMainCounter := 0private cVar1 := "InMain"private cVar2 := "InMain"if hb_isFunction("__DebugItem")       ?"Program was compiled in Debug Mode"endif?"main - cVar1 = ",cVar1?"main - cVar2 = ",cVar2Routine1(@nMainCounter)Routine2(@nMainCounter)Routine3(@nMainCounter)Routine3(@nMainCounter)Routine3(nMainCounter)?"cVar1 = ",cVar1?"cVar2 = ",cVar2?"nPRGCounter = ",nPRGCounter?"main - valtype(nDefineUp) = ",valtype(nDefineUp)?"nMainCounter = ",nMainCounterPrintVariable()??"__mvExist cVar1 = ",__mvExist("cVar1")?"__mvExist cVarx = ",__mvExist("cVarx")?"__mvExist Routine1 = ",__mvExist("Routine1")?"__mvScope('cVar1')  ",__mvScope("cVar1")   ?"__mvScope('nDefineUp')  ",__mvScope("nDefineUp")return nil//---------------------------------------------------------------------------function Routine1()cVar1 := "InRoutine1"?"Routine1 - cVar1 = ",cVar1nPRGCounter++return nil//---------------------------------------------------------------------------function Routine2()local nPRGCounter := 0   // Will hide the PRG level static nPRGCounterlocal cVar2cVar2 := "InRoutine2"?"Routine2 - cVar2 = ",cVar2nPRGCounter++return nil//---------------------------------------------------------------------------function Routine3(par_variableInMain)static nCount := 0?"Routine3 - nCount = ",++nCountnPRGCounter++public nDefineUp := 1par_variableInMain++return nil//---------------------------------------------------------------------------function PrintVariable()local aVariableTypelocal nscopelocal nCountlocal nLooplocal xValuelocal cName := " "for each aVariableType in { {HB_MV_PUBLIC,"Public"}, {HB_MV_PRIVATE,"Private"}}    nScope := aVariableType[1]    nCount := __mvDbgInfo( nScope )    for nLoop := 1 TO nCount        xValue := __mvDbgInfo( nScope, nLoop, @cName )        if ValType( xValue ) $ "CNDTL"            ? aVariableType[2],"  ",cName + " TYPE " + ValType( xValue ) + " " + hb_CStr( xValue )        endif    endforendforreturn nil//---------------------------------------------------------------------------

Harbour is classified as a xBase language, the generic term for all programming languages that derive from the original dBASE (Ashton-Tate) programming language and database formats, as per https://en.wikipedia.org/wiki/XBase.

The dBase system (language and IDE), created in 1979, included a core database engine using flat files with the extension dbf.
From dBase, several other languages were created, including Clipper, in 1984. This was the first compiler type of language in the xBase family. Most xBase languages were not open source and at the mercy of their owning companies. Harbour was the open-source recreation of the Clipper language. The Harbour project started in 1999. Since then the language expended so much in features, capacity and use that it would not be recognized as the old Clipper language. But the concept of "databases", which at that time meant "tables", still exists in Harbour. Another xBase language, Visual FoxPro, actually recreated the concept of databases, as a collection of tables. But Harbour never created a true "database" concept, but left it for developers to manage tables together as a database.

All these xBase languages existed before SQL became popular. To my knowledge only VFP (Visual FoxPro) and Xbase++ added the support for SQL syntax to access the dbf flat file/tables.

All tables are a series of columns aka fields, and rows aka records. The clipper original dbf tables had a certain list of field types it supported, like characters, numeric, date and memo (blob). Newer versions expended to additional field types, and even more options are available now due to the use of RDDs (Replaceable Database Driver). In Harbour we can now open (use) even VFP versions of dbf tables.

Think of RDDs as the MySQL database support for multiple database engines. The RDD concept allow you to use different type of tables implementations, while still use the same functions / commands to navigate through tables. The original Clipper dbf did not support nulls in fields, while the latest version of VFP tables supports nulls, integers, auto-increment fields and more. 

With the use of certain open-source and commercial RDDs it is even possible to access backend SQL tables and make them appear as flat files. But I will not recommend doing so, since I will introduce you to an ORM that makes a bridge between the SQL server world and flat file (tables).

Tables, .dbf, will also have companion files, dbt or fpt (VFP),  to store the content of variable length fields like memo/blobs. Indexes can also be created on column expressions. Some dbf versions had one .ndx or .idx file per index, others had a single .cdx (VFP) to store multiple indexes, here called tags (confusing name). But the reason I am mentioning this, is simply to highlight the concept of indexes in non SQL backend server.

All of these tables, memos, indexes, tags are stored on drives that your Harbour app need to have access to. This is basically the same as SQLite, except without the SQL syntax, and having every table and index in their own file.

To have access to records and fields of a table, it has to be "opened" in a "work area". 

Each work area also have the concept of current record number, aka recno. It is possible to place ourselves on a certain record, move through them in any directions, or even skip around. 

We can also use an index in the work area to specify how we scan/list the records, meaning not to use the physical order of records.

For local or mapped drives, table are opened via the USE command, which in turn is the dbUseArea(...) function. The Harbour compiler will generate .ppo from .prg files. Those .ppo files a the result of the Harbour pre-processor, where amongst many things, command are converted to functions. Those .ppo files are by default not keeps. They are only a step from transforming .prg Harbour files, to .c C files.

For the Harbour_ORM, a SQL command is executed on the backend server and an in-memory table is opened (placed) in a work area with the result of the query.

It is also possible to create a table on the fly and have it opened in a "work area".

Harbour can have virtually an unlimited number of work areas. Each work area has a number and an alias (usually the table name).

Unlike variables, work areas are in scope for the entire program.

To see how to create and update tables with indexes go to the following repo: https://github.com/EricLendvai/Harbour_Samples/tree/main/LocalTables

Today these type of table access are also referred to Indexed Sequential Access Method (ISAM) 

I would highly recommend not to use dbf tables, or any other local tables, but instead use SQL servers like PostgreSQL, MariaDB, MySQL, or even some commercial solutions like MS SQL. A previously popular dbf files/SQL server was/is the Advantage Database Server (ADS), now owned by SAP. This is a commercial non-free, non-open source product that provided a bridge between ISAM and SQL systems. But as more a more open source solutions like PostgreSQL and Harbour ORM became available, fewer developers seem to choose creating new applications using ADS.

The Harbour ORM project was created to make it easier to handle your data on real SQL servers, making the bridge between SQL and ISAM + local in-memory tables.

Using PostgreSQL or other SQL databases, will ensure you will not have to worry about file size limitations, reduce the chance of data corruptions, scalability and allow you to use SQL syntax, directly or via the ORM.

The Harbour ORM will still use work areas to give you access to all the result sets from querying your database, but all are in-memory tables! 

You could then create local indexes, use the seek function or simply scan all the records (ISAM behavior).

 By the way the same Table can be opened more than once in different work areas. Each will have a difference "alias" name, its own recno (record position), active order (index), and optional filter.

The following is a list of the most useful commands and functions to deal with work areas:

Command or function	Used for	Example
select <cAliasName> dbSelectArea(<cAliasNameExpression>)	Change the current work area to <cAliasName> If using the dbSelectArea() function you can use an expression that returns an alias name, case insensitive.
alias()	Returns the current work area alias name all upper case.
vfp_dbf([<cAliasName>])	Get the path and name of the physical table. Will be empty for in-memory tables. Is actually a translation of the following: #xtranslate vfp_dbf(<xAlias>) => (<xAlias>)->(DBINFO(DBI_FULLPATH))
reccount()	Returns the total number or records (rows) that exists in the table used in the current work area. 0 if no records exists. This is not impacted by orders and filters. To get the record count in an other work area use the following syntax: (cAliasName)->(reccount())
recno()	Returns the current record number as an integer. At eof(), recno() will be reccount()+1. At bof(), if not also eof(), recno() will be 1 It reccount() = 0, recno() will return 1.
goto top dbGoTop()	Move the current record position to the top of the table. If an index is used it will be based on the first entry in the index, or last if index is descending. If no index (order) is user the top will be the first record. If no records are present, current record will be at bof() and eof(), meaning "beginning of file" and "end of file".
goto bottom dbGoBottom()

To view all the functions specific to work areas go here.

request HB_CODEPAGE_UTF8EXfunction main()local cUString1 := "UTF String őöüóéáűÉÁŰŐÚçèéù"local cUString2 := "ASCII Hello World"local lUString1UTFLengthlocal l_nLoophb_cdpselect("UTF8EX")?"Student in French élève"?? cUString1," ",hb_StrIsUTF8(cUString1)," ",hb_utf8Len(cUString1)," ",len(cUString1)?"  Upper: ",upper(cUString1)?"  Lower: ",lower(cUString1)?? cUString2 , hb_StrIsUTF8(cUString2) , hb_utf8Len(cUString2) , len(cUString2)//hb_utf8Poke( @cUString1,13,hb_utf8Asc("ç"))for l_nLoop := 1 to (lUString1UTFLength := hb_utf8Len(cUString1))    ? l_nLoop , hb_utf8Chr(hb_utf8Peek( cUString1, l_nLoop )),hb_NumToHex(hb_utf8Peek( cUString1, l_nLoop ))next??hb_utf8Asc(cUString1)return nil