Harbour for beginners

• 3.1 Overview
• 3.2 Some language extensions
• 3.3 Classes and objects
• 3.4 Lang API (the language of the program)
• 3.5 Codepage API
• 3.6 Working with hrb - files
• 3.7 The built-in C
• 3.8 Hash arrays
• 3.9 Regular expressions
• 3.10 INET subsystem
• 3.11 Multithreading
• 3.12 File IO API
• 3.13 Miscellaneous functions
• 3.13.1 Built-in compiler
• 3.13.2 File functions
• 3.13.3 hb_fname...() functions
• 3.13.4 String functions
• 3.13.5 Array functions
• 3.13.6 Processes
• 3.13.7 Bit operations
• 3.13.8 Functions for a manipulation with variables
• 3.13.9 hb_WildMatch...()
• 3.13.10 Strings packing/unpacking, based on zlib
• 3.13.11 Idle state
• 3.13.12 JSON
• 3.13.13 Encryption
• 3.13.14 HiPer-SEEK (Fast Text Search)
• 3.13.15 Miscellaneous

3. Differences from Clipper - a brief description

3.1 Overview

Harbour was created as a compiler fully compatible with Clipper. This means, that any program written in Clipper, Harbour should compile without problems and work in the same way as if it had been compiled with Clipper. In many cases it is so, but, of course, problems can also arise - not everything goes as planned, Harbour was not free from errors and defects.
Another possible source of problems in the transition from Clipper to the Harbour - it's the additional libraries, inserts of the C and assembler, if you use them - 16-bit objects can not be linked to the 32-bit application. If you have the source of these modules, you can try to recompile them, though the success is not guaranteed here - not all of the features of a 16-bit C compiler are available in 32-bit.

But, of course, the Harbour does not simply repeat the functionality of the Clipper, it significantly expands it - otherwise, it wouldn't make sense! In addition to extensions related to the transition from 16 to 32 bit code ( removal of restrictions on memory, on the dimension of the array and the length of the strings ), the Harbour offers the language extensions, and additional functionality. They will be discussed below.
I just want to warn that this list will be incomplete - something I could forget, something I might have not written simply because of the lack of time and patience. I'll start gradually, and then I will expand this description. I recommend that you also use the documentation on the the Harbour official site, and also on the constantly renewable collection on the docs.google.com. Highly recommend is also the already mentioned here English-language document xhb-diff.txtthat can be found in any Harbour distributive in the Doc directory. There you can find a description of the most important language extensions of the Harbour ( compared with Clipper ) and the differences between their implementations from xHarbour.

And a couple words about the language changes. Personally I use them only when extreme necessiry. Don't forget that the farther you are from the traditional Clipper code the more problems you will have with having to go to any other compiler - who knows, what in this life you may need. Even during the transition from Harbour to xHarbour problems can arise , because there are many of the innovations implemented in different ways - see. xhb-diff.txt. And even if the transition to a different compiler may look like a distant prospect, the need to browse/convert/modify your dbf with the third-party tools may appear in any moment - that's why I never use the new types of fields in the dbf files, the more so as all the necessary functionality can be implemented without them.

3.2 Some language extensions

Here we consider several new operators appeared in the Harbour. Let's start with FOR EACH:

      FOR EACH var1 [,var255] IN expr1 [,expr255] [DESCEND]
         [EXIT]
         [LOOP]
         ...
      NEXT
   

      Local c := "alles", s := "abcdefghijk"
      FOR EACH c IN @s
         IF c $ "aei"
            c := UPPER( c )
         ENDIF
      NEXT
      ? s      // AbcdEfghIjk
      ? s      // alles
   

Another new operator - WITH OBJECT:

      WITH OBJECT expression
         ...
      ENDWITH
   

      // you can write
      WITH OBJECT myobj:a[1]:myitem
         :message( 1 )
         :value := 9
      ENDWITH

      // instead of
      myobj:a[1]:myitem:message( 1 )
      myobj:a[1]:myitem:value := 9
   

And, finally, SWITCH:

      SWITCH expr
        CASE value
          [EXIT] 
        ... 
        OTHERWISE 
      ENDSWITCH
   

      SWITCH a
      CASE 1
         ? "FOUND: 1"
      CASE "2"
         ? "FOUND: 2"
      OTHERWISE
         ? "other"
      END
   

In the Harbour there are essentially expanded possibilities of using macros. So, now in macros ( and in codeblocs ) you can use the operators ++, --, +=, -=, etc., nested code-blocs, expressions of arbitrary length. Also you may use the lists:

      cMacro := "1, 150, 'Alexey Ivanov', 20, .T."
      { &cMacro } // массив
      SomeFun( &cMacro ) // Список аргументов

      cMacro := "1,10"
      SomeArray[ &cMacro ] // индексы массива
   

      proc main()
         memvar var
         local o := errorNew(), msg := "cargo"
         private var := "CAR"

         o:&msg := "/cargo/"
         o:&( upper( msg ) ) += "/value/"
         ? o:&var.go
   

Harbour provides extended codeblocks. Such a codeblock includes a multiline code snippet, which allows any any language elements, including the Local and Static variables and is, in fact, function, nested within a function:

      Function Main

         Local b1, b2

         b1 := Fnc1( Seconds() )
         ? Eval( b1 )

         ? "Press any key"
         inkey(0)

         b2 := Fnc1( Seconds() )
         ? Eval( b2 )

         ? "Press any key"
         inkey(0)

         ? Eval( b1,Seconds() )

         ? "Press any key"
         inkey(0)

         ? Eval( b1 )
         ?

      Return Nil

      Function Fnc1( nSec )

         Local bCode := {|p1|
            Local tmp := nSec
            IF p1 != Nil
               nSec := p1
            ENDIF
            Return tmp
         }

      Return bCode
   

This example is not as simple as it seems at first glance, it shows an interesting feature of the codeblocks, which existed in Clipper, but to fully was able to open up to these extended codeblocks. Note the nSec parameter, which is a local variable of Fnc1(). It is external to the codeblock bCode, but after the completion of Fnc1() continues to "live" with bCode. At first glance it may seem that such a variable - an analogue of Static, but it is not - the fact is that every instance of codeblock will have its own copy of this variable, which is initialized during the call and work of the Fnc1(). This is called closure ( see the Wikipedia entry ) - element, well known for some modern programming languages. In Javascript, for example, it is widely used and is considered as one of the most interesting and powerful tools.

The elements of the array, hash-array and objects in the Harbour you can pass by the reference:

      function main()
      Local arr := { 1,2,3 } 

         ? arr[1], arr[2], arr[3]   // 1   2   3
         p( @arr[2] )
         ? arr[1], arr[2], arr[3]   // 1  12   3

      return nil

      Function p( x )
         x += 10
      return nil
   

Functions with a variable number of parameters. Harbour allows you to declare in the function declaration the named parameters and then unnamed. These unnamed parameters can then be used with the help of "...":

      // as the array elements
      proc main()
         AEval( F( "1", "2", "A", "B", "C" ), {|x, i| qout( i, x ) } )

      func f( p1, p2, ... )
         ? "P1:", p1
         ? "P2:", p2
         ? "other parameters:", ...
      return { "X", ... , "Y", ... "Z" }

      // as indexes of the array:
      proc main()
         local a := { { 1, 2 }, { 3, 4 }, 5 }
         ? aget( a, 1, 2 ), aget( a, 2, 1 ), aget( a, 3 )

      func aget( aVal, ... )
      return aVal[ ... ]

      // as the parameters of the function:
      proc main()
         info( "test1" )
         info( "test2", 10, date(), .t. )

      proc info( msg, ... )
         qout( "[" + msg +"]: ", ... )
   

      // hb_arrayToParams(  ) -> [ 1 ] [, [ N ] ]
      // Например:
      proc main( ... )
         local aParams := hb_aParams(), n
         /* remove the options that start with '--' */
         n := 1
         while n < len( aParams )
            if left( aParams[ n ], 2 ) == "--"
               hb_adel( aParams, n, .t. )
            else
               ++n
            endif
         enddo
         ? "Public parameters:", hb_arrayToParams( aParams )
      return
   

A new type of data - TIMESTAMP, it is defined in RDD (i.e., can be used as the field type in the dbf), and in the VM (virtual machine). For the TIMESTAMP variable the function Valtype() returns "T", it is possible to produce operations of addition, subtraction and comparison. Constants of this data type can be declared in the program as follows:

      // { ^ [ YYYY-MM-DD [,] ] [ HH[:MM[:SS][.FFF]] [AM|PM] ] }
      // t"YYYY-MM-DD [H[H][:M[M][:S[S][.f[f[f[f]]]]]]] [PM|AM]"
      // t"YYYY-MM-DDT[H[H][:M[M][:S[S][.f[f[f[f]]]]]]] [PM|AM]"
      proc main()
         Local t1 := {^ 2012-11-28 10:22:30 }   // или {^ 2012/11/28 10:22:30 }
         Local t2 := t"2009-03-21 17:31:45.437" // или t"2009-03-21T17:31:45.437"

         ? t1 + 1      // 11/29/12 10:22:30.000
         ? t1 - t2     // 1347.701905
   

      Local d1 := 0d20121201  // Template: 0dYYYYMMDD
   

      Local str1 := e"Helow\r\nWorld \x21\041\x21\000abcdefgh"
   

      Local n := 0x1F
   

Another interesting innovation in the Harbour - pointers to functions. They can be created on the stage of building the application, using the expression @<funcName>(), or dynamically during execution with the help of the macro: &("@<funcName>()"). Valtype() returns S for such pointers.

      proc main()
         local funcSym
         funcSym := @str()
         ? funcSym:name, "=>", funcSym:exec( 123.456, 10, 5 )
         funcSym := &( "@upper()" )
         ? funcSym:name, "=>", funcSym:exec( "Harbour" )
      return
   

3.3 Classes and objects

Implementation of OOP ( object oriented programming ) is perhaps the first thing added by developers of the Harbour to the standard language. Clipper's latest versions contained elements of the OOP. There was several predefined classes, you could create their objects, but it wasn't possible to create own classes. There were however some of the undocumented possibilities, which allowed to do it, several 3rd party libraries that implement the OOP for Clipper were based on them, the most known of them are Fivewin (more precisely, Objects.lib from the Fivewin) and Class(y). To use the classes in the Harbour you don't need to link additional libraries, the OOP support is part of the language and, as the funds are the part of the kernel, the Harbour provides more possibilities than Clipper with all third-party libraries.

So, to create a new class, use the command CLASS ... ENDCLASS:

      [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 ]
   

A class can be declared as the heir of one or more parents (especially multiinheritance - multiple inheritance we will consider later) with the help of the clause FROM or INHERIT. This means that it receives from the parent class all its variables and methods (except those marked as HIDDEN). Any of the inherited methods can be overridden. The parent method can be invoked as Super:<methodName>() or ::<cSuperClass>:<methodName>() (if it is not HIDDEN).

I want to mention one interesting peculiarity related to inheritance. If the child class has a variable with the same name as the parent, then each object contains two variables with the same name. One of them should be adressed to as obj:<varName>, the other - obj:<cSuperClass>:<varName>.

A class can be declared as STATIC - i.e. it cannot be used outside of the current module.

A class can be declared as MODULE FRIENDLY - this means that all classes and functions, which are declared in the current module, are his friends, i.e., have an access to his HIDDEN and PROTECTED variables and methods. And since we're talking about the friendly functions pay attention to clauses FRIEND CLASS and FRIEND FUNCTION - they determine friendly for this class classes and functions.

The words FUNCTION <cFuncName> in the declaration of a class define it as a scalar class.

Clauses DATA or VAR - a definition of variables of a class. During this there can be strictly defined the type of the variable AS <type> (Character, Numeric, Date, Logical, Codeblock, Nil), can be set its initial default value INIT <uValue> and defined Scope (Hidden,Protected,Exported,Readonly). Scope can be set for each variable separately ( in the DATA clause ), and for the group of variables and methods:

Variables can belong to the object and to the whole class - the last are declared as CLASSDATA, CLASSVAR or CLASS VAR. Such a variable is available from any object of a class as a obj:<DataName>but it is stored not in the areas of data objects, but in one place, in the field of the class data , and therefore it has the same value for all the objects of a class. There is another difference in the implementation of CLASSDATA on the one hand, and CLASSVAR or CLASS VAR on the other. These variables can be declared as SHARED. This means that if the parent class has such a variable, then the derived classes use the same single copy of it, share it. If the same SHARED is not declared, then the derived classes inherit it in the usual way, creating a new copy of the variable for each class of the heir. So, for the CLASSVAR and CLASS VAR it works, as it was described above, and CLASSDATA variables behave like SHARED regardless of whether you use this word in the ad or not. It was for the backward compatibility with Fivewin programs for Clipper.

Clause METHOD - this is the definition of the methods of the class. In general case if the method is not INLINE, not BLOCK and not VIRTUAL, after the definition of the class (after ENDCLASS) you must put the implementation of the method:

      METHOD ( [] ) CLASS 
         ...
      RETURN Self
   

The following are different ways of declaring a method:

Another way of declaring a method is to set it with the help of ERROR HANDLER or ON ERROR. This method is invoked in the case, if the object class to which it belongs to, was sent a message not specified for this class; in other words, a method or variable which is not present in this class is being called to. You can, of course, use such a method for the direct purpose - for the treatment of errors, but there are more interesting ways to use it. So, it can be used dynamically to simulate the availability of the the object's variables, which were not defined in the class declaration, and in different objects of the same class different methods and the variables can be simulated.

SYNC METHOD is used to synchronize the execution of the methods in the multithread application. If a method is marked as SYNCthen it will not run two or more threads simultaneously for one object.

Option LOCK or LOCKED of the ENDCLASS prevents subsequent modification of this class, it can be used in the design of large projects of the group of developers, if you do not want, that someone hacks your class.

To create and test a simple class it is enough to write:

      #include "hbclass.ch"
      FUNCTION Main
      Local obj := myFirstClass():New(3)

         ? obj:x       // 3
         ?
      RETURN Nil

      CLASS myFirstClass
         VAR   x
         METHOD New( n )   INLINE ( ::x := n, Self )
      ENDCLASS
   

I announced here the INLINE (built-in) method to do only the design of the CLASS ... ENDCLASS and do not describe the method New(n) separately. Here we should pay attention to the following moments:

Now one more complicated example:

      #include "hbclass.ch"
      FUNCTION Main
         Local obj1, obj2

         obj1 := mySecondClass():New( 10,"Alex" )
         ? "Всего объектов mySecondClass:", mySecondClass():nKolObj
         obj2 := mySecondClass():New( 11,"Mike" )
         ? "Всего объектов mySecondClass:", mySecondClass():nKolObj
         ? obj1:x, obj2:x
         ? 
      RETURN Nil

      CLASS myFirstClass
         VAR   x
         METHOD New( n )   INLINE ( ::x := n, Self )
      ENDCLASS

      CLASS mySecondClass  FROM myFirstClass
      HIDDEN:
         VAR   cStringS

      EXPORTED:
         CLASS VAR  nKolObj     INIT 0
         VAR        cString1    INIT "Sample"
         METHOD New( n, s )
      ENDCLASS

      METHOD New( n, s ) CLASS mySecondClass

         Super:New( n )
         ::nKolObj ++
         ::cStringS := s
      RETURN Self
   

Another example showing the method declarations as BLOCK and EXTERN:

      #include "hbclass.ch"
      function Main()
      Local o1 := HSamp1():New()
      Local o2 := HSamp2():New()

         ? o1:x, o2:x                        // 10       20
         ? o1:Calc( 2,3 ), o2:Mul( 2,3 )     // 60      120
         ? o1:Sum( 5 )                       // 15
         ?

      return nil

      CLASS HSamp1

         DATA x   INIT 10
         METHOD New()  INLINE Self
         METHOD Sum( y )  BLOCK {|Self,y|::x += y}
         METHOD Calc( y,z ) EXTERN fr1( y,z )
      ENDCLASS

      CLASS HSamp2

         DATA x   INIT 20
         METHOD New()  INLINE Self
         METHOD Mul( y,z ) EXTERN fr1( y,z )
      ENDCLASS

      Function fr1( y, z )
      Local o := QSelf()
      Return o:x * y * z
   

And here is an example of use of ERROR HANDLER:

      #include "hbclass.ch"
      FUNCTION Main
         LOCAL oTable

         oTable := Table():Create( "sample.dbf", { {"F1","C",10,0}, {"F2","N",8,0} } )
         oTable:AppendRec()
         oTable:F1 := "FirstRec"
         oTable:F2 := 1
         oTable:AppendRec()
         ? oTable:nRec                // 2
         oTable:nRec := 1
         ? oTable:nRec                // 1
         ? oTable:F1, oTable:F2       // "FirstRec"     1
         ?

         RETURN nil

      CLASS Table

         METHOD Create( cName, aStru )
         METHOD AppendRec()   INLINE dbAppend()
         METHOD nRec( n )     SETGET

         ERROR HANDLER OnError( xParam )
      ENDCLASS

      METHOD Create( cName, aStru ) CLASS Table

         dbCreate( cName, aStru )
         USE (cName) NEW EXCLUSIVE
      RETURN Self

      METHOD nRec( n ) CLASS Table

         IF n != Nil
            dbGoTo( n )
         ENDIF
      RETURN Recno()

      METHOD OnError( xParam ) CLASS Table
      Local cMsg := __GetMessage(), cFieldName, nPos
      Local xValue

         IF Left( cMsg, 1 ) == '_'
            cFieldName := Substr( cMsg,2 )
         ELSE
            cFieldName := cMsg
         ENDIF
         IF ( nPos := FieldPos( cFieldName ) ) == 0
            Alert( cFieldName + " wrong field name!" )
         ELSEIF cFieldName == cMsg
            RETURN FieldGet( nPos )
         ELSE
            FieldPut( nPos, xParam )
         ENDIF

      Return Nil
   

A list of functions for the manipulation of classes and objects follows:

        HB_MSGLISTALL    0   все переменные
        HB_MSGLISTCLASS  1   переменные класса CLASS DATA
        HB_MSGLISTPURE   2   переменные объекта DATA
        

        oHappy := HBClass():New( "THappy" )
        __objAddMethod( oHappy, "Smile", @MySmile() )
        ? oHappy:Smile( 1 )

        Static Function MySmile( nType )
        Return Iif( nType==0,":)",":):)" )
        

3.4 Lang API (the language of the program)

This subsystem is intended for output of alarm messages and the result of CMonth(), CDow() functions - but, unlike Clipper, it allows you to to change language of the program during execution.
To link it to your application, you must specify the hblang.lib library in the link - script and include in chief prg file the REQUEST sentenses with the names of the languages, which you intend to use, for example:

     REQUEST HB_LANG_RU866
     REQUEST HB_LANG_RUWIN
   

3.5 Codepage API

This subsystem provides support for national code pages for your data. To link it to your application you must specify the library hbcpage.lib in a link - script and include in a chief prg file the proposal REQUEST with the names of the code pages, which you intend to use, for example:

     REQUEST HB_CODEPAGE_RU866
     REQUEST HB_CODEPAGE_RUKOI8
     REQUEST HB_CODEPAGE_RU1251
   

Further, you may determine the main code page of the application. This code page will be used for the IsUpper(), IsLower(), IsAlpha(), Upper() and Lower(), Transform (), and when comparing strings. In the console applications, one should use the OEM codepage ( "RU866" for Russian ) and in the Windows GUI application - ANSI ( "RU1251" for Russian ).
To set the code page the hb_cdpSelect() function is used

     hb_cdpSelect( sCodepage )
      // for example:
     hb_cdpSelect( "RU866" )
   

Such a possibility can be found by Clipper as well ( by connecting the special obj ), but in the Harbour, in addition to that you can define the code page for any opened file data, all the strings will be automatically translated into the main code page of the application for reading and return - when recording, the strings in dbSeek(), dbLocate(), dbSetFilter() will be translated, too. It is enough to specify the code page when opening a file, and all subsequent work with it will look as if the data is in the main code page:

      USE file_name ... CODEPAGE "RU1251"
      // or
      dbUseArea( .T.,,file_name,,.T.,.F.,"RU1251" ) 
   

By default the file opens with the main code page of the application.
This possibility ( the definition of the code page of the file ) should only be used with family RDD - DBFNDX and DBFCDX.
ADS RDD provides for these purposes other tools ( setting up the ini file or SET CHARTYPE TO OEM/ANSI ).

Codepage API also includes a function for translation of strings from one codepage to another:

      Hb_Translate( sData, sCodepageIN, sCodepageOUT )
      // for example:
      Hb_Translate( "Привет", "RU1251", "RU866" )
   

and a set of functions for utf8:

3.6 Working with hrb - files

I have already mentioned herethat instead of the C file Harbour can create a special type of file from your prg with the .hrb extension, which contains the p-code of your program and can be executed by the utility Hbrun.exe.
But the hrb can be called for execution directly from your program - there are special functions for this:

   HB_HRB_BIND_DEFAULT    0x0  /* do not overwrite any functions, ignore
                               public HRB functions if functions with the same
                               names already exist */
   HB_HRB_BIND_LOCAL      0x1  /* do not overwrite any functions, but keep local
                               references, so if module has public function FOO
                               and this function exists already, then the
                               function in HRB is converted to STATIC one */
   HB_HRB_BIND_OVERLOAD   0x2  /* overload all existing public functions */
   HB_HRB_BIND_FORCELOCAL 0x3  /* convert all public functions to STATIC ones */
   HB_HRB_BIND_LAZY       0x4  /* Doesn't check references, allows load HRB with
                               unresolved references */
         

   HB_HRB_FUNC_PUBLIC     0x1   /* locally defined public functions */
   HB_HRB_FUNC_STATIC     0x2   /* locally defined static functions */
   HB_HRB_FUNC_LOCAL      0x3   /* locally defined functions */
   HB_HRB_FUNC_EXTERN     0x4   /* external functions used in HRB module */
         

It is needed to ensure that the application has been built with all of the functions which can be called from .hrb, otherwise the program might fall out while runtime. The best way is to put in your program

     REQUEST 
   

Note that the hrbname parameter of the hb_hrbRun() and hb_hrbload() may contain not only the name of the hrb file, but also the p-code, pre-loaded with the help of, for example, Memoread(), or received as a result of compilation with the help of hb_compileBuf() or hb_compileFromBuf() (see the description of these functions here):

      FUNCTION Main()
      Local han, buf, cBuf := ""

         cBuf += "Procedure MM" +Chr(13)+Chr(10)
         cBuf += "? 'Just a test!'" +Chr(13)+Chr(10)

         buf := hb_compileFromBuf( cBuf, "harbour", "/n" )
         hb_hrbRun( buf )
         ?
      Return Nil
   

And one more interesting moment. I have already mentioned that hrb files are very similar judjing by functionality to the p-code dll. And indeed, the function hb_hrbLoad() loads p-code in the space of your application in the same way as a function of the hb_libLoad() loads the shared library. And therefore, the functions of the hrb file can be called with the same way, i.e. directly, without any hb_hrbGetFunsym() or Do(). To do this, as in the case of using the p-code dll, you must first declare these functions in your application as DYNAMIC:

      DYNAMIC HRBFUNC1
      FUNCTION Main()
      Local x, handle := hb_hrbLoad( "my.hrb" )
      
      x := hrbFunc1()   // hrbFunc1 - the function from my.hrb
      
      hb_hrbUnload( handle )
      Return Nil
   

3.7 the Built-in C

In the Harbour there is a possibility to insert fragments of C code in the prg file. This may be conveniently, if you don't want to create a .c file for a pair of C functions and then putting it in the project. This can be done with the help of directives #pragma BEGINDUMP ... #pragma ENDDUMP.

   #pragma BEGINDUMP
      #include < extend.h >
      #include < math.h >
      HB_FUNC( SIN )
      {
         double x = hb_parnd(1);
         hb_retnd( sin( x ) );
      }
   #pragma ENDDUMP
   

3.8 Hash arrays

Hash arrays or Hash tables - see. article in Wikipedia - is one of the implementations of data structures, known under the name of associative arrays, which stores the pair ( key,value ) and allows you to perform at least three operations: add a new pair, search according to the key and delete the key. The support of associative arrays is in many interpreted high-level programming languages, for example, in Perl, PHP, Python, Ruby, and others. Now it is also implemented in the Harbour.

A new hash-array is created by the function hb_hash(), it can be used without a parameter ( in this case initialized with the empty hash array ) and with parameters, defining an arbitrary number of pairs in the array.

   FUNCTION Main
   local harr := hb_Hash( "six", 6, "eight", 8, "eleven", 11 )

      harr[10] := "str1"
      harr[23] := "str2"
      harr["fantasy"] := "fiction"

      ? harr[10], harr[23]                                   // str1  str2
      ? harr["eight"], harr["eleven"], harr["fantasy"]       // 8       11  fiction
      ? len(harr)                                            // 6
      ?

      RETURN nil
   

   local harr := hb_Hash( "six" => 6, "eight" => 8, "eleven" => 11 )
   

For hash array 4 flags are defined:

Below is a table of functions for a hash of arrays.

3.9 Regular expressions

Many people think ( and I thought ), that regular expression are the strings for searching, where the "*" indicates a group of any characters, and "?" - any single character, the same as that are used as masks for files. In fact it is a kind of language, enough complex - the searching strings on it can shock at first. But if mastering and understanding the logic of the language gradually you get used to its view and it ceases to be a gobbledygook.

Regular expressions are a very powerful tool for searching in the text. Many modern programming languages ( Perl, Php, Python, Ruby, Javascript, etc. ) have the built-in support of them. You can get acquainted with the regular expressions for example on pcre.ru.

Further you will find a group of functions, similar in parameters structure. Here cRegEx - a string with a regular expression ( text or already compiled ); cString - a string in which the search is conducted; lCase specifies whether to take into account the register of symbols ( by default - to - .T. ); what about the parameter lNewLine - I have not yet managed to find it out, if someone tells me - I'll be glad; nMaxMatches - the maximum number of matches, which should be returned (by default - without limitation - 0). Functions have to be looking for in line cString fragments of the corresponding regular expression, specified cRegEx. The regular expression can consist of parts that are separated by round brackets. In this case, we call the fragment of the line corresponding to the entire expression the full coincidence, and a substring of this fragment, corresponding to the relevant part of the regular expression (dedicated round brackets) - the sub-coincidence. So, for example:

     s := "Claabrok abbey" // a String, where we will look 
     cRegex : = (a+)(b+)"  // the Symbol '+' in the regular expression means that
                           // the previous symbol occur 1 or more times
     // Have 2 full matches:
     // 1) 'REC', the 'aa' is the first sub-coincidence, 'b' - the second
     // 2) 'abb'here 'a' is the first sub-coincidence, 'bb' - the second
   

And another 3 functions:

And, finally, an example of the use of the simplest regular expression, already discussed above:

   FUNCTION Main()
   Local s := "ClaAbrok aBbey", n1, n2

      ? hb_isregex( hb_regexcomp( "a+b+" ) )                // .T.
      n1 := 1
      n2 := Len( s )
      ? hb_atx( "a+b+", s, .f., @n1, @n2 ), n1, n2          // aAb      3     3
      ? hb_regexhas( "a+b+", s, .f. )                       // .T.
      ? hb_regexhas( "a+b+", s )                            // .F.
      ? hb_regexlike( "a+b+", s, .f. )                      // .F.

      PrintArray( hb_regex( "a+b+",s,.f. ) )                // { aAb }
      PrintArray( hb_regex( "(a+)(b+)",s,.f. ) )            // { aAb aA b }

      PrintArray( hb_regexSplit( "a+b+",s,.f. ) )           // { Cl rok  ey }

      PrintArray( hb_regexAtx( "a+b+",s,.f. ) )             // { { aAb 3 5 } }
      PrintArray( hb_regexAtx( "(a+)(b+)",s,.f. ) )         // { { aAb 3 5 } { aA 3 4 } { b 5 5 } }

      PrintArray( hb_regexAll( "a+b+",s,.f. ) )             // { { aAb aBb } }
      PrintArray( hb_regexAll( "(a+)(b+)",s,.f. ) )         // { { aAb aA b } { aBb a Bb } }
      PrintArray( hb_regexAll( "(a+)(b+)",s,.f.,,,1 ) )     // { aAb aBb }
      PrintArray( hb_regexAll( "(a+)(b+)",s,.f.,,,2 ) )     // { aA a }
      PrintArray( hb_regexAll( "(a+)(b+)",s,.f.,,,0,.f. ) ) 
      // { { { aAb 3 5 } { aA 3 4 } { b 5 5 } } { { aBb 10 12 } { a 10 10 } { Bb 11 12 } } }
      PrintArray( hb_regexAll( "(a+)(b+)",s,.f.,,,1,.f. ) ) // { { aAb 3 5 } { aBb 10 12 } }

      ?
   Return Nil

   Function PrintArray( arr, lNoNewLine )
   Local i

      IF lNoNewLine == Nil .OR. !lNoNewLine
         ?
      ENDIF
      ?? " {"
      FOR i := 1 TO Len( arr )
         IF Valtype( arr[i] ) == "A"
            PrintArray( arr[i], .T. )
         ELSE
            ?? " " + Iif( Valtype( arr[i] ) == "N", Ltrim(Str(arr[i])), arr[i] )
         ENDIF
      NEXT
      ?? " }"
   Return Nil
   

3.10 INET subsystem

This is a basic set of functions, designed for the work in networks using the IP protocol. With their help it is possible to create a socket, to connect to another socket ( on the same or on the remote computer ) and arrange the reception/transmission of data. This is the basic set, and as such it implements the TCP/IP and UDP protocols. Using it, you can implement an exchange under the more high-leveled protocol - HTTP, FTP, POP3, etc. One example of such an implementation is the library hbtip, the sources of which are located in the harbour/contrib/hbtip.

I propose you a useful example of using the above (INET) and below (multithreading) functions. So, this is a 2-thread application inspecting every 2 minutes the updates on the forum clipper.borda.ru ( do not forget that it must be compiled with support for multi-threading, otherwise it will not work ):

   #include "box.ch"

   REQUEST HB_CODEPAGE_RU866
   REQUEST HB_CODEPAGE_RU1251

   Static mutex1
   Static aNew := {}

   Function Main()
   Local pThread, lEnd := .F., nkey

      hb_cdpSelect( "RU866" )
      hb_inetInit()

      // Create a mutex to synchronize threads when accessing the array aNew
      mutex1 := hb_mutexCreate()
      // Create a thread to check for updates with clipper.borda.ru
      pThread := hb_threadStart( @GetData(), @lEnd )

      // Just waiting for user input.
      CLEAR SCREEN
      @ 24, 1 SAY "Press Esc to complete the program, F5 - changes"
      read
      DO WHILE ( nKey := Inkey(0) ) != 27
         IF nKey == -4    // F5
            ShowUpd()
         ENDIF
      ENDDO

      // Send via lEnd completion signal to a thread and are looking forward to it.
      lEnd := .T.
      hb_threadJoin( pThread )

      hb_inetCleanup()

   Return .T.

   // This function is called by F5 and shows the changes to the site
   Function ShowUpd()
   Local arr, bufc, i, l

      // Here we need a mutex we read an array aNew, which could in this
      // time modified by a second thread
      hb_mutexLock( mutex1 )
      IF ( l := !Empty( aNew ) )
         arr := {}
         FOR i := 1 TO Len( aNew )
            Aadd( arr, Padr( hb_translate( Trim(aNew[i,2])+": " ;
               +Trim(aNew[i,3])+" "+Trim(aNew[i,4]),"RU1251","RU866" ),64 ) )
         NEXT
      ENDIF
      hb_mutexUnLock( mutex1 )


      bufc := Savescreen( 7,7,13,73 )
      @ 7,7,13,73 BOX B_DOUBLE_SINGLE + Space(1)
      IF l
         AChoice( 8,8,12,72,arr )
      ELSE
         @ 10, 35 SAY "Ничего нового..."
         Inkey(1)
      ENDIF
      Restscreen( 7,7,13,73, bufc )
      hb_dispOutAt( 0, 69, "          ", "GR+/N" )

   Return .T.

   // This function analyzes the main page of the site and looking for there the necessary changes.
   // In order to better understand it, look at the source text of the main page clipper.borda.ru
   Static Function CheckAns( cBuf )
   Local nPos1 := 1, nPos2, aItems, aRes := {}
   Local aStru := { {"ID","C",2,0}, {"NAME","C",16,0}, {"TM","C",10,0}, {"LOGIN","C",16,0}, {"TITLE","C",32,0} }
   Local fname := "cl_borda.dbf", lFirstTime := .F.
   Field ID, NAME, TM, LOGIN, TITLE

      IF !File( fname )
         dbCreate( fname, aStru )
         lFirstTime := .T.
      ENDIF
      USE (fname) NEW EXCLUSIVE
     
      DO WHILE ( nPos1 := hb_At( "st(", cBuf, nPos1 ) ) != 0
         IF ( nPos2 := hb_At( ")", cBuf, nPos1 ) ) != 0

            aItems := hb_aTokens( Substr(cBuf,nPos1+3,nPos2-nPos1-3), ",", .T. )
            aItems[1] := Padr( Substr( aItems[1], 2, Min( aStru[1,3],Len(aItems[1])-2 ) ), aStru[1,3] )
            aItems[2] := Padr( Substr( aItems[2], 2, Min( aStru[2,3],Len(aItems[2])-2 ) ), aStru[2,3] )
            aItems[5] := Padr( Substr( aItems[5], 2, Min( aStru[3,3],Len(aItems[5])-2 ) ), aStru[3,3] )
            aItems[8] := Padr( Substr( aItems[8], 2, Min( aStru[4,3],Len(aItems[8])-2 ) ), aStru[4,3] )
            aItems[9] := Padr( Substr( aItems[9], 2, Min( aStru[5,3],Len(aItems[9])-2 ) ), aStru[5,3] )

            IF lFirstTime
               APPEND BLANK
               REPLACE ID WITH aItems[1], NAME WITH aItems[2], TM WITH aItems[5], ;
                     LOGIN WITH aItems[8], TITLE WITH aItems[9]
            ELSE
               LOCATE FOR ID == aItems[1]
               IF !Found()
                  APPEND BLANK
                  REPLACE ID WITH aItems[1], NAME WITH aItems[2], TM WITH aItems[5], ;
                        LOGIN WITH aItems[8], TITLE WITH aItems[9]
                  Aadd( aRes, {aItems[1],aItems[2],aItems[8],aItems[9]} )
               ELSEIF TM != aItems[5] .OR. LOGIN != aItems[8] .OR. TITLE != aItems[9]
                  REPLACE TM WITH aItems[5], LOGIN WITH aItems[8], TITLE WITH aItems[9]
                  Aadd( aRes, {aItems[1],aItems[2],aItems[8],aItems[9]} )
               ENDIF
            ENDIF

            nPos1 := nPos2 + 1
         ELSE
            EXIT
         ENDIF
      ENDDO
      USE

   Return aRes

   // This is the 2nd flow
   Function GetData( lEnd )
   Local nCount := 0, hSocket, cUrl, cServer, cBuf, aRes

      cServer := "clipper.borda.ru"
      cURL := "GET http://" + cServer + "/ HTTP/1.1" +Chr(13)+Chr(10)
      cURL += "Host: " + cServer + Chr(13)+Chr(10)
      cURL += "User-Agent: test_util"+Chr(13)+Chr(10)
      cUrl += Chr(13)+Chr(10)

      DO WHILE !lEnd
         IF nCount == 0
            hb_dispOutAt( 0, 61, "Читаем.", "GR+/N" )
            hSocket := hb_inetCreate()                   // create a socket
            hb_inetConnect( cServer, 80, hSocket )       // connect to the web site of the forum
            IF hb_inetErrorCode( hSocket ) != 0
               hb_dispOutAt( 0, 61, "Сбой...", "GR+/N" ) 
            ENDIF

            // Send the request, formed above,  and waiting for a reply.
            IF hb_inetSendAll( hSocket, cURL ) > 0 .AND. !Empty( cBuf := hb_inetRecvEndBlock( hSocket, "main2(",,,4096 ) )
               IF !Empty( aRes := CheckAns( cBuf ) )
                  hb_dispOutAt( 0, 69, "!! Есть !!", "GR+/N" )
                  // Use a mutex for the safe aNew modification
                  hb_mutexLock( mutex1 )
                  aNew := aRes
                  hb_mutexUnLock( mutex1 )
               ENDIF
               hb_dispOutAt( 0, 61, "       ", "GR+/N" )
            ELSE
               hb_dispOutAt( 0, 61, "Сбой...", "GR+/N" )
            ENDIF

            // Close the socket
            hb_inetClose( hSocket ) 
         ENDIF
         hb_idleSleep(2)
         IF ++nCount >= 60
            nCount := 0
         ENDIF
      ENDDO

   Return Nil
   

When changing the engine of the forum this program may stop working, because it implies the presence of certain strings in the html code - searches for calls of javascript functions main2() and st().

3.11 Multithreading

Multithreading is a programming model that allows multiple threads to run within the same process, the same application, interacting with each other, sharing the resources of this application. Threads are performed by the operating system in parallel. If the system is a single-processor, it is a quasiparallelism provided by the fact that the OS allocates the time between threads. In a multiprocessor system threads can actually be performed in parallel on different processors, providing a general improvement in the performance of the application. It is often convenient to use separate threads for any action related to the lengthy computation or a lengthy waiting time of any event, blocking the execution of the program ( for example, when working in a network using sockets ); while the main thread continues to respond to user's actions.

The Harbour application can be built for a single-threaded execution and for multi-threading. In the last case it is necessary to use a multi-threaded version of the Harbour virtual machine - the hbvmmt.lib library instead of a single-threaded hbvm.lib and the library of your C compiler, containing functions for the realization of multi-threading (for Borland C it is cw32mt.lib). The most simple solution is to build your application using hbmk2 with the key -mt. Nothing prevents you from putting in the multi-threaded mode normal single-threaded applications, but the way they will work is a little slower and it will take a little more space on the disk and in memory.

When creating a new thread inherits from the parent:
    - the code page installed hb_cdpSelect(),
    - language ( hb_langSelect() ),
    - all SET options,
    - RDD by default,
    - GT driver and console window,
    - options of I18N.

These settings are initialized to its initial value ( a new copy is created ):
    - public variable Getlist := {},
    - an error handler, initialized by the Errorsys() call,
    - the handler of mathematical errors,
    - installation of a macrocomiler ( set hb_setMacro() ),
    - RDDI_* installation in standard RDD ( third-party RDD can use the global settings ),
    - thread static variables.

Individual Public and Private variables can be passed to the thread when it is created.

The following resources are used together:
    - functions and procedures,
    - definition of classes,
    - modules RDD,
    - GT drivers,
    - language modules,
    - modules of code pages,
    - static variables.

Local resources of a thread:
    - Public and Private variables, except those that are used together,
    - working areas (workareas),
    - thread static variables.

Below is a list of functions that are intended for management of threads, their creation and completion of:

   #define HB_THREAD_INHERIT_PUBLIC 1
   #define HB_THREAD_INHERIT_PRIVATE 2
   #define HB_THREAD_INHERIT_MEMVARS 3
   #define HB_THREAD_MEMVARS_COPY 4
        

Using these functions, we can now write the first simple multi-threaded applications, for example this one, to display a clock on the screen:

   FUNCTION Main()
      LOCAL cVar := Space( 20 )

      CLEAR SCREEN

      IF !hb_mtvm()
         ? "There is no support for multi-threading, clocks will not be seen."
         WAIT
      ELSE
         hb_threadStart( @Show_Time() )
      ENDIF

      @ 10, 10 SAY "Enter something:" GET cVar
      READ
      SetPos( 12, 0 )
      ? "You enter -> [" + cVar + "]"
      WAIT

      RETURN Nil

   FUNCTION Show_Time()
      LOCAL cTime

      DO WHILE .T.
         cTime := Dtoc( Date() ) + " " + Time()
         hb_dispOutAt( 0, MaxCol() - Len( cTime ) + 1, cTime, "GR+/N" )
         hb_idleSleep( 1 )
      ENDDO

      RETURN nil
   

We have created a thread that began to perform the function of Show_Time(), constantly showing the current time in the upper right corner of the screen. Please note, that the function hb_dispOutAt() is used for showing the time on the screen, it does not change the current cursor position and the color of the console.

If another function were used, for example, DispOut(), the cursor would have moved from the area of input in the main thread, this would not help the preservation and restoration of its position in Show_Time(). The fact is that the operating system can interrupt the thread and pass control to the other at any moment of time, in the middle of any operation. You, for example, are restoring the position of the cursor using the function SetPos(), but at any stage of its implementation ( as it is a long serie of native code operations ) the operating system can interrupt it and return control to the main thread, or any other, who also modifies at that moment the position of the cursor and the result will be unpredictable. Therefore,in cases when the use of any shared resources ( most often a variable ), required the synchronization tool of the work threads so that they do not address to the general resources at the same time. These means are semaphores, and one of them - mutex. Look below a description of the relevant functions:

So, to prevent simulteneous addressing of different threads to the same resource, do the following:
    1) create mutex: pMtx := hb_mutexCreate()
    2) in those parts of the program which refer to protected resources, wrap the code lock/unlocked mutex, but, i.e., put before it hb_mutexLock( pMtx ) and after it hb_mutexUnLock( pMtx ) - the same as if we are blocking/unblocking a record of an shared database while recording in it. Don't forget that, unlike rlock(), hb_mutexLock() suspends the further execution of a thread, if mutex is already blocked by something - cases of carelessness can cause the deadlock - the situation, when several threads mutually block the execution of each other.

However, in our example with the clock this is not the case - if we used Setpos() and Dispout(), mutex would not have helped us. In the main thread the cursor control is not directly in our program, but somewhere within the Harbour's RTL, in the implementation of the function Readmodal() - and we can't insert there a lock mutex. Therefore let's expand a little our example by adding there the parameter setting of the date display:

   #include "box.ch"

   Static mutex1
   Static cOpt := "DD.MM.YY"

   FUNCTION Main()
      LOCAL cVar := Space( 20 )

      CLEAR SCREEN

      IF !hb_mtvm()
         ? "There is no support for multi-threading, hours will not be seen."
         WAIT
      ELSE
         mutex1 := hb_mutexCreate()
         hb_threadStart( @Show_Time() )
      ENDIF

      SET KEY -4 TO Options
      @ 10, 10 SAY "Enter something:" GET cVar
      READ
      SET KEY -4 TO
      SetPos( 12, 0 )
      ? "You enter -> [" + cVar + "]"
      WAIT

      RETURN Nil

   FUNCTION Show_Time()
      LOCAL cTime

      DO WHILE .T.
         hb_mutexLock( mutex1 )
         cTime := Iif( !Empty( cOpt ), hb_Dtoc( Date(),cOpt ), Space(10) ) + " " + Time()
         hb_mutexUnLock( mutex1 )
         hb_dispOutAt( 0, MaxCol() - Len( cTime ) + 1, cTime, "GR+/N" )
         hb_idleSleep( 1 )
      ENDDO

      RETURN nil

   Function Options
   Local bufc, n, aOpt := { "DD.MM.YYYY","DD/MM/YYYY","DD.MM.YY","YYYY.MM.DD","       " }

      bufc := Savescreen( 7,31,13,49 )
      @ 7,31,13,49 BOX B_DOUBLE_SINGLE + Space(1)
      IF ( n := AChoice( 8,32,12,48,aOpt ) ) != 0
         hb_mutexLock( mutex1 )
         cOpt := aOpt[n]
         hb_mutexUnLock( mutex1 )
      ENDIF
      Restscreen( 7,31,13,49, bufc )

   Return Nil
   

So we have a variable cOpt, which contains the display format of the dates, the function Options(), which is invoked by pressing the F5 key and changes the string format. Since the thread executing Show_Time(), uses the string, we use mutex to avoid collisions.

Another example of a multithreaded program with mutex see in the previous section.

2 more functions to synchronize actions between threads:

Now about the access to the databases in multi-threaded applications. As already noted above, working area (workareas) in the Harbour are local to the thread, i.e. each thread has its own independent workspaces and aliases, and, in the general case, if you need a database in the thread "B" which is already opened in the thread "A", you need to open it in the "B" agein, which is easy to do in shared mode.

But there is another possibility - you can transfer the workspace from one thread to another, using the known by users xBase++ zero space. Two following options are designed for this:

This mechanism allows to use workspaces by different threads together . To illustrate it we shall take 2 commands:

      #xcommand UNLOCK WORKAREA [] => hb_dbDetach(  )
      #xcommand LOCK WORKAREA    => hb_dbRequest( , .T.,, .T. )
   

After the opening table by the command Use the thread executes UNLOCK WORKAREA and, i.e., moves it in zero space. Now each thread, which needs this table, can get access to it, for example:

      LOCK WORKAREA "DOCUMENTS"
         COUNT TO nInvoices FOR year( DOCUMENTS->DATE ) == year( date() )
      UNLOCK WORKAREA
   

Other examples of multi-threaded programs you can find in the harbour/tests/mt.

3.12 File IO API

Harbour inherited from the Clipper a set of functions FOpen(), FSeek(), FRead(), ..., that are designed to work with the files.

This collection supplemented with new functions, a complete list is provided in subsection 3.13.2 File functions.

New File IO API is a set of functions with hb_vf prefix, similar to the common file functions, with the same set of parameters and the same functionality. An implementation of these functions allows to use replaceable drivers like RDDs. Now, if you put a prefix of any of the existing drivers with a colon at the end in front of the file name ( "mem:", "net:", ... ), a communication with this file will go through appropriate driver. The following function call, for example:

      hb_vfCopyFile( "test.txt", "mem:test.txt" )

IO drivers are the contributed Harbour libraries, such as hbnetio, hbmemio, hbgzio, hbbz2io, hbcomio and others.

Functions list:

3.13 Miscellaneous functions

In this section we will cover a variety of new features that were not included in previous thematic sections.

3.13.1 Built-in compiler

      FUNCTION Main( cFileName )
      Local handle, buf, cBuf := "", i

         buf := hb_compilebuf( "harbour", cFileName, "/n","/w" )  // Compile
         hb_hrbRun( buf )                                         // Execute

         handle := FCreate( Iif((i:=Rat('.',cFileName))=0,cFileName,Substr(cFileName,1,i-1)) + ".hrb" )
         FWrite( handle, buf )
         FClose( handle )

      Return Nil
   

3.13.2 File functions.

           FC_NORMAL          0
           FC_READONLY        1
           FC_HIDDEN          2
           FC_SYSTEM          4
        

3.13.3 Set of functions, manipulating with file path, name, extension.

3.13.4 String functions

3.13.5 Array functions

3.13.6 Processes

3.13.7 Bit operations

3.13.8 Functions for a manipulation with variables

         HB_MV_NOT_FOUND      = переменная не найдена
         HB_MV_UNKNOWN        = переменная не существует, но есть в symbol table
         HB_MV_ERROR          = информация недоступна ( ошибка памяти или аргумента )
         HB_MV_PUBLIC         = Public переменная
         HB_MV_PRIVATE_GLOBAL = Private переменная, определена за пределами текущей функции/процедуры
         HB_MV_PRIVATE_LOCAL  = Private переменная, определена в текущей функции/процедуре
      

3.13.9 hb_WildMatch...()

3.13.10 Strings packing/unpacking, based on zlib

3.13.11 Idle state

Idle state this is a state of expectation, when the Harbour program is waiting for the input from the user with the keyboard or the mouse. It arises as the result of Inkey() function call ( the READ command uses Inkey(), so that while waiting for input GET-objects idle state occurs ). In this state, there is an automatic collect of the garbage and any background tasks can be carried out. To add/remove these background tasks the following functions are designed (example of usage see in the harbour/tests/testidle.prg):

3.13.12 JSON - there and back

3.13.13 Encryption

3.13.14 HiPer-SEEK (Fast Text Search)

Harbour's HiPer-SEEK library is compatible with Six Drivers's HiPer-SEEK system, which, in turn, uses Index Applications' Fast Text Search technology.

The HiPer-SEEK system is a set of functions, which create and maintain index files, enabling the rapid search of textual data. The HiPer-SEEK functions can be used to index and search any character based information the application can access.

HiPer-SEEK indexes contain fixed length keys (index records) which track the contents of text records. A text record may consist of any arbitrary block of text. In the case of a .dbf format file, a text record would usually consist of the concatenation of selected fields from a data record. A text record might also be a line or paragraph from a text file or even an entire file. In all cases, there will be one index record for each and every text record. This one to one relationship is critical to the proper operation of a HiPer-SEEK system.

An index file is created by hs_Create(). hs_Create() builds the index file header and establishes the index's attributes. It does not add records to the file. This is done by hs_Add().

An .hsx index is not an inversion or compression of the original textual data. Its keys track the occurrence of text signatures. It identifies matches as those index records containing all the signatures or attributes of the search string(s). It is possible that differing strings will resolve to the same signature. We refer to these as aliases. That's why you need to verify the result, returned by hs_Next(). It is important to note that while an .hsx index search may mistakenly identify a record as containing a match, it will never fail to find a record that does match.

As mentioned above, the HiPer-SEEK system has been built to provide fast text searches in a wide variety of applications. There are limits however. It will be less useful in two extreme situations. The first is where text records are very small. The smallest .hsx index key is 16 bytes. When individual text records are also that small the index file overhead can be 100% or more. The other extreme is where individual text records are very large. The largest choice for an .HSX index key is 64 bytes. It is easy to imagine that indexing 64 kilobytes of text with a single 64 byte key is not practical.

    USE test EXCL
    h := hs_Open( "SALES.HSX", 10, 1 )
    bExpr := { || Trim( test->FIRST ) + " " + Trim( test->LAST ) }
    DO WHILE !eof()
      nRec := hs_Add( h, bExpr )
      IF nRec < 1 .OR. nRec != RecNo()
        ? "Error adding record " + LTrim( Str( RecNo() )) + "!"
      ENDIF
      SKIP
    ENDDO
    

    h := hs_Create( "myindex.hsx", 8, 3, .T., 2 )
    IF h < 0
      ? "Error creating HiPer-SEEK index!"
    ENDIF
    

    USE sales EXCL
    h := hs_Open( "sales.hsx", 10, 1 )
    DO WHILE !eof()
      IF deleted()
        nVal := hs_Delete( h, RecNo() )
        IF nVal < 1
          ? "HiPer-SEEK delete error: " + LTrim( Str( RecNo() ))
        ENDIF
      ENDIF
      SKIP
    ENDDO
    

    #include "inkey.ch"

    LOCAL cExpr := "test->FIRST + test->LAST + test->STREET + test->CITY"
    LOCAL nCount := 0, lStrict := .F.
    LOCAL cSearch := "Steve John Robert"
    LOCAL GetList := {}

    CLS
    USE test EXCL

    IF !file("TEST.HSX")
      @ 0,0 "Building HiPer-SEEK Index..."
      hs_Index( "TEST.HSX", cExpr, 2 )
      ?? "Done!"
      Inkey(1)
      CLS
    ENDIF

    WHILE .T.
      cSearch := PadR( cSearch, 59 )
      @ 0,0 SAY "Search Values.....:" GET cSearch
      @ 1,0 SAY "Strict Match (Y/N):" GET lStrict PICTURE "Y"
      READ
      IF LastKey() == K_ESC
        CLS
        EXIT
      ENDIF
      cSearch := AllTrim( cSearch )

      @ 3,0 SAY "Setting HiPer-SEEK Filter ..."

      nCount := hs_Filter( "TEST.HSX", cSearch, iif( lStrict, cExpr, "" ))

      ?? "Done!"
      @ 4,0 SAY LTrim( Str( nCount )) + " records meeting filter condition."

      @ 6,0 SAY "Press any key to browse the matching records..."
      Inkey(0)

      GO TOP
      Browse()
      CLS
    ENDDO
    

    LOCAL cExpr := "test->FIRST + test->LAST + test->STREET + test->CITY"
    LOCAL h := 0

    USE test EXCL

    // Build HiPer-SEEK index using 64 byte index record, READ-WRITE + SHARED
    // mode, using a 16k buffer.

    h := hs_Index( "TEST.HSX", cExpr, 3, 0, 16 )

    hs_Close( h )
    

    // Lists all record numbers that contain the word "John" anywhere in
    // either the FIRST, LAST, STREET, or CITY fields.  Uses hs_Verify()
    // to prevent "fuzzy" matches.

    LOCAL cExpr := "test->FIRST + test->LAST + test->STREET + test->CITY"
    LOCAL bExpr := &( "{||" + cExpr + "}" )
    LOCAL cVal := "John", h := 0, nRec := 0

    CLS
    USE test EXCL

    IF !File("TEST.HSX")
      ? "Building HiPer-SEEK Index..."
      h := hs_Index( "TEST.HSX", cExpr, 2 )
    ELSE
      h := hs_Open( "TEST.HSX", 8, 1 )
    ENDIF

    hs_Set( h, cVal )
    nRec := hs_Next( h )

    DO WHILE nRec > 0
      dbGoto( nRec )
      IF hs_Verify( bExpr, cVal )
        ? nRec
      ENDIF
      nRec := hs_Next( h )
    ENDDO

    hs_Close( h )
    

    USE test EXCL

    h := hs_Open( "LOOKUP.HSX", 16, 1 )
    IF h < 0
      ? "Error opening HiPer-SEEK index!"
    ENDIF
    

    USE test EXCL
    h := hs_Open( "NAMES.HSX", 8, 1 )
    GOTO 10
    cStr := Trim( test->FIRST ) + " " + Trim( test->LAST )
    IF hs_Replace( h, cStr, RecNo() ) < 1
      ? "HiPer-SEEK replace error on record #" + LTrim( Str( RecNo() ))
    ENDIF
    

    h := hs_Open( "LOOKUP.HSX", 4, 1 )
    hs_Set( h, "Thompson" )
    nRec := hs_Next( h )

    ? "The first record conaining 'Thompson' is #" + LTrim( Str( nRec ))

    hs_Close( h )
    

    // Lists all record numbers that contain the word "John" anywhere in
    // either the FIRST, LAST, STREET, or CITY fields.  Uses hs_Verify()
    // to prevent "fuzzy" matches.

    LOCAL cExpr := "test->FIRST + test->LAST + test->STREET + test->CITY"
    LOCAL bExpr := &( "{||" + cExpr + "}" )
    LOCAL cVal := "John", h := 0, nRec := 0

    CLS
    USE test EXCL

    IF !file("TEST.HSX")
      ? "Building HiPer-SEEK Index..."
      h := hs_Index( "TEST.HSX", cExpr, 2 )
    ELSE
      h := hs_Open( "TEST.HSX", 8, 1 )
    ENDIF

    hs_Set( h, cVal )
    nRec := hs_Next( h )

    DO WHILE nRec > 0
      dbGoto( nRec )
      IF hs_Verify( bExpr, cVal )
        ? nRec
      ENDIF
      nRec := hs_Next( h )
    ENDDO

    hs_Close( h )
    

3.13.15 Miscellaneous

           ? hb_execFromArray( "Str", {11,6,3} )
        

           hfunc := @Str()
           ? hb_execFromArray( hfunc, {11,6,3} )
        

           ? hb_execFromArray( {|n1,n2,n3|Str(n1,n2,n3)}, { 11,6,3 } )
        

           ? hb_execFromArray( { "Str", 11,6,3 } )
           ? hb_execFromArray( { hfunc, 11,6,3 } )
           ? hb_execFromArray( { {|n1,n2,n3|Str(n1,n2,n3)},11,6,3 } )
        

Site map

© Copyright 2016. All Rights Reserved.