Harbour для начинающих

• 3.1 Обзор
• 3.2 Некоторые языковые расширения
• 3.3 Классы и объекты
• 3.4 Lang API (язык программы)
• 3.5 Codepage API
• 3.6 Работа с hrb - файлами
• 3.7 Встроенный C
• 3.8 Хэш массивы
• 3.9 Регулярные выражения
• 3.10 INET подсистема
• 3.11 Многопоточность
• 3.12 API файлового ввода/вывода (File IO API)
• 3.13 Интернационализация (hbi18n)
• 3.14 Всякие новые функции
  • 3.14.1 Встроенный компилятор
  • 3.14.2 Файловые функции
  • 3.14.3 Функции для манипуляций с именами файлов
  • 3.14.4 Строковые функции
  • 3.14.5 Функции для работы с массивами
  • 3.14.6 Управление запуском процессов
  • 3.14.7 Битовые операции
  • 3.14.8 Функции для манипуляции переменными
  • 3.14.9 Сравнение по маске
  • 3.14.10 Упаковка/распаковка строк с использованием zlib
  • 3.14.11 Idle state
  • 3.14.12 JSON
  • 3.14.13 Шифрование
  • 3.14.14 HiPer-SEEK (Fast Text Search)
  • 3.14.15 Разное

3. Отличия от Клиппера - краткое описание

3.1 Обзор

Харбор создавался как полностью совместимый с Клиппером компилятор. Это значит, что любая ваша программа, написанная на Клиппере, должна без проблем компилироваться Харбором и работать так же, как если бы она была откомпилирована Клиппером. Во многих случаях так оно и есть, но, конечно, могут возникать и проблемы - не все получается так, как задумано, Харбор не свободен от ошибок и недоделок.
Еще один возможный источник проблем при переходе с Клиппера на Харбор - это дополнительные библиотеки, вставки на C и ассемблере, если вы их используете - 16-разрядные объектники не прилинкуются к 32-разрядному приложению. Если у вас есть исходники этих модулей, то можно попробовать перекомпилировать их, хотя и тут успех не гарантирован - не все функции 16-разрядного C компилятора доступны в 32-разрядном.

Но, конечно же, Харбор не просто повторяет функциональность Клиппера, а существенно расширяет ее - иначе какой был бы в этом смысл ?! Помимо расширений, связанных с переходом от 16 к 32 разрядному коду ( снятие ограничений по памяти, по размерности массивов и длине строк ), Харбор предлагает и языковые расширения, и дополнительные функциональные возможности. Они и будут рассмотрены ниже.
Сразу хочу предупредить, что этот перечень будет неполным - о чем-то я могу забыть, что-то не написать просто из-за нехватки времени и терпения. Начну с немногого, потом постепенно, по мере возможности, буду пополнять этот список и расширять описания. Рекомендую вам также воспользоваться документацией с официального сайта Harbour, a также с постоянно пополняющегося сборника на docs.google.com. Она, правда, тоже не полная, и, к тому же, не на русском - но, даже если у вас с английским проблемы, что-нибудь полезное вы оттуда все равно почерпнете - хотя бы названия новых функций, образцы синтаксиса, и т.д. Очень рекомендую также уже упоминавшийся здесь англоязычный документ xhb-diff.txt, который есть любом дистрибутиве Harbour в каталоге Doc. Здесь содержится описание наиболее важных языковых расширений Harbour ( по сравнению с Clipper ) и отличие их реализаций от xHarbour.

И еще пара слов о языковых новшествах. Лично я использую их только при самой крайней необходимости. Не забывайте, что чем дальше вы от традиционного Clipper-кода, тем больше проблем у вас возникнет при необходимости перейти на какой-либо другой компилятор - кто знает, что в этой жизни может понадобиться. Даже при переходе Harbour <--> xHarbour могут появиться проблемы, т.к. многие новшества по-разному там реализованы - см. xhb-diff.txt. И если переход на другой компилятор может выглядеть весьма отдаленной перспективой, то потребность просмотреть/переконвертировать/модифицировать ваш dbf сторонними средствами может появиться в любой момент - именно поэтому я никогда не использую новые типы полей в dbf - файлах, тем более, что всю необходимую функциональность можно реализовать без них.

3.2 Некоторые языковые расширения

Здесь мы рассмотрим несколько новых операторов, появившихся в Harbour. Начнем с 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
      ? c      // alles
   

Еще один новый оператор - WITH OBJECT:

      WITH OBJECT expression
         ...
      ENDWITH
   

      // можно написать
      WITH OBJECT myobj:a[1]:myitem
         :message( 1 )
         :value := 9
      ENDWITH

      // вместо
      myobj:a[1]:myitem:message( 1 )
      myobj:a[1]:myitem:value := 9
   

Ну и, наконец, SWITCH:

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

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

В Harbour существенно расширены возможности использования макросов. Так, теперь в макросах ( и в кодоблоках ) можно использовать операторы ++, --, +=, -= и т.п., вложенные кодоблоки, выражения произвольной длины. Также допустимо использовать списки:

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

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

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

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

В Harbour реализованы расширенные кодоблоки. Такой кодоблок представляет собой многострочный фрагмент текста, в котором допустимы любые языковые элементы, в том числе Local и Static переменные и является, по сути, функцией, вложенной в функцию:

      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
   

Этот пример не так прост, как кажется на первый взгляд, он демонстрирует интересную особенность реализации кодоблоков, которая существовала и в Клиппере, но в полной мере смогла раскрыться в этих расширенных кодоблоках. Обратите внимание на параметр nSec, который является локальной переменной функции Fnc1. Он внешний по отношению к кодоблоку bCode, но и после завершения работы Fnc1 продолжает "жить" вместе с bCode. На первый взгляд может показаться, что такая переменная - своеобразный аналог Static, но это не так - дело в том, что у каждого экземпляра кодоблока будет свой экземпляр этой переменной, инициализированный в процессе вызова и работы функции Fnc1. Это называется "замыкание" (closure) - см. статью в Википедии, элемент, хорошо известный по некоторым современным языкам программирования. В Javascript, например, он используется очень широко и считается одним из наиболее интересных и мощных его инструментов.

Элементы массива, хэш-массива и объекты в Harbour можно передавать по ссылке:

      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
   

Функции с переменным количеством параметров. Harbour позволяет декларировать в объявлении функции и поименованные параметры, и затем неименованные. Эти неименованные параметры могут затем использоваться при помощи оператора "...":

      // как элементы массива
      Procedure 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" }

      // как индексы массива:
      Procedure main()
         local a := { { 1, 2 }, { 3, 4 }, 5 }
         ? aget( a, 1, 2 ), aget( a, 2, 1 ), aget( a, 3 )

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

      // как параметры функции:
      Procedure main()
         info( "test1" )
         info( "test2", 10, date(), .t. )

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

      // hb_arrayToParams(  ) -> [ 1 ] [, [ N ] ]
      // Например:
      Procedure main( ... )
         local aParams := hb_aParams(), n
         /* убираем параметры, начинающиеся с '--' */
         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
   

Новый тип данных - TIMESTAMP, он определен и в RDD (т.е. может использоваться как тип поля в dbf), и в VM (виртуальной машине). Для переменной типа TIMESTAMP функция Valtype вернет "T", с ней можно производить операции сложения, вычитания и сравнения. Константы этого типа данных можно декларировать в программе следующим образом:

      // { ^ [ 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]"
      Procedure 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  // Шаблон: 0dYYYYMMDD
   

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

      Local n := 0x1F
   

Еще одно интересное новшество в Harbour - указатели на функции. Их можно создавать на этапе сборки приложения, используя выражение @<funcName>(), или динамически во время исполнения с помощью макроподстановки: &("@<funcName>()"). Valtype() возвращает для таких указателей S.

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

3.3 Классы и объекты

Реализация ООП ( объектно-ориентированного программирования ) - это, пожалуй, первое, что добавили разработчики Harbour к стандарту языка. Клиппер последних версий содержал элементы ООП. Там было несколько предопределенных классов, можно было создавать их объекты, но свои классы создавать было нельзя. Были, правда некоторые недокументированные возможности, которые позволяли это делать, на них были основаны несколько 3rd party библиотек, реализующих ООП для Клиппера, наиболее известные из них - это Fivewin (точнее, Objects.lib из комплекта Fivewin) и Class(y). В Harbour для использования классов не требуется подключать дополнительные библиотеки, ООП является здесь частью языка и, поскольку соответствующие средства составляют часть ядра, Harbour предоставляет большие возможности, чем Клиппер со всеми сторонними библиотеками.

Итак, чтобы создать новый класс, используется команда 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 ]
   

Класс может быть объявлен как наследник от одного или нескольких родителей (особенности multiinheritance - множественного наследования мы рассмотрим позже) при помощи служебного слова FROM или INHERIT. Это значит, что он получает от родительского класса весь его набор переменных и методов (кроме помеченных как HIDDEN). Любой из унаследованных методов может быть переопределен. При этом родительский метод может быть вызван как Super:<methodName>() или ::<cSuperClass>:<methodName>() (если он не HIDDEN).

Отмечу еще одну интересную особенность, связанную с наследованием. Если в порожденном классе есть переменная с тем же именем, что и в родительском, то каждый объект содержит две переменных с этим именем. К одной из них следует обращаться obj:<varName>, к другой - obj:<cSuperClass>:<varName>.

Класс может быть объявлен как STATIC - т.е. он не может использоваться вне текущего модуля.

Класс может быть объявлен как MODULE FRIENDLY - это значит, что все классы и функции, объявленные в текущем модуле, его друзья (friends), т.е. имеют доступ к его HIDDEN и PROTECTED переменным и методам. И раз уж мы заговорили о дружественных функциях, то обратите внимание на строчки FRIEND CLASS и FRIEND FUNCTION - они определяют дружественные для этого класса классы и функции.

Слова FUNCTION <cFuncName> в объявлении класса определяют его как скалярный класс.

Предложения DATA или VAR - это определения переменных класса. При этом может быть строго определен тип переменной AS <type> (Character, Numeric, Date, Logical, Codeblock, Nil), задано ее начальное значение по умолчанию INIT <uValue> и определен Scope (Hidden,Protected,Exported,Readonly). Scope может быть задан как для каждой переменной отдельно ( в объявлении DATA ), так и для группы переменных и методов:

Переменные могут принадлежать объекту, а могут и всему классу - это переменные класса, они объявляются как CLASSDATA, CLASSVAR или CLASS VAR. Такая переменная доступна из любого объекта класса как obj:<DataName>, но хранится она не в областях данных объектов, а в одном месте, в области данных класса, и поэтому, естественно, имеет одно значение для всех объектов класса. Есть одно отличие в реализации CLASSDATA с одной стороны, и CLASSVAR или CLASS VAR с другой. Эти переменные могут быть объявлены как SHARED. Это означает, что если в родительском классе есть такая переменная, то производные классы используют ту же самую единственную ее копию, разделяют ее. Если же SHARED не объявлен, то производные классы наследуют ее обычным образом, создавая новую копию переменной для каждого класса-наследника. Так вот, для CLASSVAR и CLASS VAR это работает, как было описано выше, а CLASSDATA переменные ведут себя как SHARED независимо от того, используется это слово в объявлении или нет. Это было сделано для обратной совместимости с Fivewin программами для Клиппера.

Предложения METHOD - это определения методов класса. В общем случае, если метод не INLINE, не BLOCK, и не VIRTUAL,после определения класса (после ENDCLASS) необходимо поместить реализацию метода:

      METHOD ( [] ) CLASS 
         ...
      RETURN Self
   

Ниже описаны разные способы объявления метода:

Еще один способ объявления метода - задать его с помощью ERROR HANDLER или ON ERROR. Этот метод вызывается в том случае, если объекту класса, к которому он принадлежит, послано сообщение, не определенное для этого класса; иными словами, вызван метод или переменная, которой нет в этом классе. Можно, конечно, использовать такой метод по прямому назначению - для обработки ошибок, но есть и более интересные способы применения. Так, с его помощью можно динамически имитировать наличие методов и переменных объекта, которые не были определены при объявлении класса, причем у разных объектов одного и того же класса могут быть "сымитированы" разные методы и переменные.

SYNC METHOD применяется для синхронизации выполнения методов в многопотоковом приложении. Если метод помечен как SYNC, то он не будет выполняться двумя и более потоками одновременно для одного и того же объекта.

Опция LOCK или LOCKED предложения ENDCLASS предотвращает последующую модификацию этого класса, ее можно использовать при разработке больших проектов группой разработчиков, если вы не хотите, чтобы кто-то "хакнул ваш класс".

Для создания и проверки работы простейшего класса достаточно, например, написать:

      #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
   

Я воспользовался здесь объявлением INLINE (встроенного) метода, чтобы обойтись только конструкцией CLASS ... ENDCLASS и не описывать метод New(n) отдельно. Здесь следует обратить внимание на следующие моменты:

Теперь пример чуть посложнее:

      #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
   

Еще один пример, демонстрирующий объявления методов как BLOCK и 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
   

А вот пример использования 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
   

Далее следует список функций для манипуляции классами и объектами:

        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 (язык программы)

Эта подсистема предназначена для вывода аварийных сообщений и результата функций CMonth(), CDow() - но, в отличие от аналогичных средств в Клиппере, она позволяет менять язык программы во время исполнения.
Чтобы подключить ее к вашему приложению, надо указать в link - скрипте библиотеку hblang.lib и включить в главный prg файл предложения REQUEST с именами тех языков, которые вы предполагаете использовать, например:

     REQUEST HB_LANG_RU866
     REQUEST HB_LANG_RUWIN
   

3.5 Codepage API

Эта подсистема обеспечивает поддержку национальных кодовых страниц для ваших данных. Чтобы подключить ее к вашему приложению, надо указать в link - скрипте библиотеку hbcpage.lib и включить в главный prg файл предложения REQUEST с именами тех кодовых страниц, которые вы предполагаете использовать, например:

     REQUEST HB_CODEPAGE_RU866
     REQUEST HB_CODEPAGE_RUKOI8
     REQUEST HB_CODEPAGE_RU1251
   

Далее, следует определить главную кодовую страницу приложения. Именно эта кодовая страница будет использоваться для функций IsUpper(), IsLower(), IsAlpha(), Upper(), Lower(), Transform() и при сравнении строк. В консольном приложении, по-видимому, следует использовать "RU866", а в Windows GUI приложении - "RU1251".
Для установки главной кодовой страницы используется функция

     hb_cdpSelect( sCodepage )
      например:
     hb_cdpSelect( "RU866" )
   

Подобная возможность есть и в Клиппере ( путем подключения специальных obj ), но в Харборе, кроме того, можно определить кодовую страницу для любого открываемого файла данных - при этом все строки будут автоматически транслироваться в главную кодовую страницу приложения при чтении и обратно - при записи, транслироваться будут и строки в dbSeek(), dbLocate(), dbSetFilter(). Достаточно указать кодовую страницу при открытии файла - и вся последующая работа с ним будет выглядеть так, как будто данные находятся в основной кодовой странице:

      USE file_name ... CODEPAGE "RU1251"
      или
      dbUseArea( .T.,,file_name,,.T.,.F.,"RU1251" ) 
   

По умолчанию файл открывается с главной кодовой страницей приложения.
Эту возможность ( определение кодовой страницы файла ) следует использовать только с родными RDD - DBFNTX и DBFCDX.
ADS RDD предоставляет для этих целей другие средства ( настройка ini файла или SET CHARTYPE TO OEM/ANSI ).

Codepage API включает также функцию для трансляции строк из одной кодовой страницы в другую:

      Hb_Translate( sData, sCodepageIN, sCodepageOUT )
      например:
      Hb_Translate( "Привет", "RU1251", "RU866" )
   

и набор функций для utf8:

3.6 Работа с hrb - файлами

Я уже отмечал здесь, что Харбор может вместо C файла создать из вашего prg особый тип файла с расширением hrb, который содержит p-code вашей программы и может быть исполнен утилитой Hbrun.exe.
Но этот hrb может быть вызван на исполнение и непосредственно из вашей программы - для этого предусмотрены специальные функции:

   HB_HRB_BIND_DEFAULT    0x0  /* Не переопределяет никакие функции, игнорирует
                               PUBLIC функцию в загружаемом модуле, если функция
                               с таким именем уже определена */
   HB_HRB_BIND_LOCAL      0x1  /* Не переопределяет никакие функции, но оставляет
                               локальные ссылки, т.е., если модуль содержит
                               функцию FOO и такая функция уже определена, то в
                               HRB она конвертируется в STATIC */
   HB_HRB_BIND_OVERLOAD   0x2  /* Переопределяет уже существующие PUBLIC функции */
   HB_HRB_BIND_FORCELOCAL 0x3  /* Конвертирует все PUBLIC функции в STATIC */
   HB_HRB_BIND_LAZY       0x4  /* Не проверяет ссылки, позволяет загружать HRB
                               с неразрешенными к моменту загрузки ссылками */
         

   HB_HRB_FUNC_PUBLIC     0x1   /* Локально определенные PUBLIC функции */
   HB_HRB_FUNC_STATIC     0x2   /* Локально определенные STATIC функции */
   HB_HRB_FUNC_LOCAL      0x3   /* Локально определенные функции */
   HB_HRB_FUNC_EXTERN     0x4   /* Внешние функции, вызываемые в HRB модуле */
         

Необходимо проследить, чтобы приложение было собрано со всеми функциями, которые могут вызываться из .hrb, иначе во время исполнения программа вылетит. Лучше всего это сделать, поставив в вашей программе

     REQUEST <имя_функции>
   

Обратите внимание, что параметр hrbname функций hb_hrbRun() и hb_hrbload() может содержать не только имя hrb файла, но и сам p-code, предварительно загруженный с помощью, например, Memoread(), или полученный в результате компиляции с помощью hb_compileBuf() или hb_compileFromBuf() (см. описание этих функций здесь):

      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
   

И еще один интересный момент. Я уже отмечал, что hrb файлы очень похожи по функциональности на p-code dll. И действительно, функция hb_hrbLoad() загружает p-code в пространство вашего приложения так же, как функция hb_libLoad() подгружает динамическую библиотеку. А значит, функции из hrb файла можно вызывать таким же образом, т.е. напрямую, без всяких hb_hrbGetFunsym() и Do(). Для этого, как и в случае с использованием p-code dll, надо предварительно объявить эти функции в вашем приложении как DYNAMIC:

      DYNAMIC HRBFUNC1
      FUNCTION Main()
      Local x, handle := hb_hrbLoad( "my.hrb" )
      
      x := hrbFunc1()   // hrbFunc1 - функция из my.hrb
      
      hb_hrbUnload( handle )
      Return Nil
   

3.7 Встроенный C

В Харборе есть возможность вставлять фрагменты C кода в prg файл. Это может быть удобно, если вам лень из-за пары нужных C функций создавать .с файл и вставлять его в проект. Делается это при помощи директив #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 Хэш массивы

Хэш массивы ( или Хэш-таблицы - см. статью в Википедии - это одна из реализаций структуры данных, известной под названием ассоциативные массивы, которая хранит пары ( ключ,значение ) и позволяет выполнять, как минимум, три операции: добавление новой пары, поиск по ключу и удаление по ключу. Поддержка ассоциативных массивов есть во многих интерпретируемых языках программирования высокого уровня, например, в Perl, PHP, Python, Ruby, и др. Теперь она реализована и в Harbour.

Создается новый хэш-массив функцией hb_hash(), ее можно использовать без параметров ( в этом случае инициализируется пустой хэш-массив ) и с параметрами, определяющими произвольное количество пар массива:

   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 )
   

Для хэш массива определены 4 флага:

Ниже приведена таблица функций для хэш массивов.

3.9 Регулярные выражения

Многие думают ( и я так думал когда-то ), что регулярные выражения - это строки для поиска, где "*" обозначает несколько любых символов, а "?" - один любой символ, типа того что используются как маски для файлов. На самом деле это своеобразный язык, достаточно сложный - поначалу поисковые строки на нем производят шокирующее впечатление. Но по мере освоения и понимания логики этого языка постепенно привыкаешь к его виду и он перестает казаться неудобочитаемой абракадаброй.

Регулярные выражения - это очень мощное средство для поиска в тексте. Многие современные языки программирования ( Perl, Php, Python, Ruby, Javascript и др. ) имеют их встроенную поддержку. Детально познакомиться с регулярными выражениями можно, например, на pcre.ru.

Далее следует группа сходных по составу параметров функций. Здесь cRegEx - строка с регулярным выражением ( текст или уже откомпилированное ); cString - строка, в которой производится поиск; lCase указывает, следует ли учитывать регистр символов ( по умолчанию - следует - .T. ); что означает параметр lNewLine, мне пока не удалось выяснить, если кто подскажет - буду рад; nMaxMatches - максимальное количество соответствий, которые надо возвращать (по умолчанию - без ограничения - 0). Функции ищут в строке cString фрагменты, соответствующие регулярному выражению, заданному cRegEx. Регулярное выражение может состоять из частей, разделенных круглыми скобками. В этом случае фрагмент строки, соответствующий всему выражению, мы далее называем полным совпадением, а подстроку этого фрагмента, соответствующую части регулярного выражения (выделенной круглыми скобками), мы будем называть суб-совпадением. Так, например:

      s := "Claabrok abbey"   // Строка, где будем искать
      cRegex := "(a+)(b+)"    // Символ '+' в регулярном выражении означает, что
                              // предшествующий символ встречается 1 или более раз
      // Имеем 2 полных совпадения:
      // 1) 'aab', здесь 'aa' - первое суб-совпадение, 'b' - второе
      // 2) 'abb', здесь 'a' - первое суб-совпадение, 'bb' - второе
   

И еще 3 функции:

И, наконец, пример использования простейшего регулярного выражения, уже рассмотренного выше:

   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 подсистема

Это базовый набор функций, предназначенный для реализации работы в сети по IP протоколу. С их помощью можно создать сокет, установить соединение с другим сокетом ( на этом же или удаленном компьютере ) и организовать прием/передачу данных. Это именно базовый набор, реализующий TCP/IP и UDP протокол. Используя его, можно реализовать обмен по протоколу более высокого уровня - HTTP, FTP, POP3, и т.д. Одним из примеров такой реализации является библиотека hbtip, исходники которой находятся в harbour/contrib/hbtip.

Предлагаю вашему вниманию полезный :) пример использования описанных выше (INET) и ниже (многопоточность) функций. Итак, двухпоточное приложение, проверяющее каждые 2 минуты наличие обновлений на форуме clipper.borda.ru ( не забудьте, что его надо откомпилировать с поддержкой многопоточности, иначе оно не будет работать ):

   #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()

      // Создаем mutex для синхронизации потоков при обращении к массиву aNew
      mutex1 := hb_mutexCreate()
      // Создаем поток для проверки обновлений с clipper.borda.ru
      pThread := hb_threadStart( @GetData(), @lEnd )

      // Просто ждем пользовательского ввода.
      CLEAR SCREEN
      @ 24, 1 SAY "Нажмите Esc, чтобы завершить программу, F5 - изменения"
      read
      DO WHILE ( nKey := Inkey(0) ) != 27
         IF nKey == -4    // F5
            ShowUpd()
         ENDIF
      ENDDO

      // Посылаем посредством lEnd сигнал завершения потоку и ждем его.
      lEnd := .T.
      hb_threadJoin( pThread )

      hb_inetCleanup()

   Return .T.

   // Эта функция вызывается по F5 и показывает изменения на сайте
   Function ShowUpd()
   Local arr, bufc, i, l

      // Вот тут нам понадобился mutex - мы читаем массив aNew, который мог бы в это
      // время модифицироваться вторым потоком
      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.

   // Эта функция анализирует главную страницу сайта и ищет там нужные изменения.
   // Чтобы лучше ее понять, просмотрите исходный текст главной страницы 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

   // Это 2-й поток
   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()                   // создаем сокет
            hb_inetConnect( cServer, 80, hSocket )       // присоединяемся к сайту форума
            IF hb_inetErrorCode( hSocket ) != 0
               hb_dispOutAt( 0, 61, "Сбой...", "GR+/N" ) 
            ENDIF

            // Посылаем сформированный выше запрос и ждем ответа.
            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" )
                  // Используем mutex для безопасной модификации aNew
                  hb_mutexLock( mutex1 )
                  aNew := aRes
                  hb_mutexUnLock( mutex1 )
               ENDIF
               hb_dispOutAt( 0, 61, "       ", "GR+/N" )
            ELSE
               hb_dispOutAt( 0, 61, "Сбой...", "GR+/N" )
            ENDIF

            // Закрываем сокет
            hb_inetClose( hSocket ) 
         ENDIF
         hb_idleSleep(2)
         IF ++nCount >= 60
            nCount := 0
         ENDIF
      ENDDO

   Return Nil
   

При смене движка форума эта программа может перестать работать, потому что она предполагает наличие определенных строк в html коде - ищет вызовы javascript функций main2() и st().

3.11 Многопоточность

Многопоточность - это модель программирования, которая позволяет нескольким потокам выполняться в рамках одного процесса, одного приложения, взаимодействуя между собой, разделяя ресурсы этого приложения. Потоки выполняются операционной системой параллельно. Если система однопроцессорная, то это квазипараллельность, обеспечиваемая тем, что ОС распределяет время между потоками. В многопроцессорной системе потоки могут реально выполняться параллельно на разных процессорах, обеспечивая общее повышение производительности приложения. Часто бывает удобно использовать отдельные потоки для каких-то действий, связанных с длительными вычислениями или с длительным ожиданием какого-либо события, блокирующим выполнение программы ( например, при работе в сети с использованием сокетов ); при этом основной поток продолжает реагировать на действия пользователя.

Harbour - приложение может быть собрано для однопоточного выполнения и для многопоточного. В последнем случае необходимо использовать многопоточную версию виртуальной машины Harbour - библиотеку hbvmmt.lib вместо однопоточной hbvm.lib и библиотеку вашего C компилятора, содержащую функции для реализации многопоточности (для Borland C это cw32mt.lib). Самое простое решение - использовать для сборки вашего приложения hbmk2 с ключом -mt. Ничто не мешает вам собирать в многопоточном режиме и обычные однопоточные приложения, но так они будут работать чуть медленнее и займут чуть больше места на диске и в памяти.

При создании новый поток наследует от родителя:
    - кодовую страницу, установленную hb_cdpSelect(),
    - язык ( hb_langSelect() ),
    - все SET установки,
    - RDD по умолчанию,
    - GT драйвер и консольное окно,
    - установки I18N.

Эти установки инициализируются в начальные значения ( создается новая их копия ):
    - публичная переменная Getlist := {},
    - обработчик ошибок, инициализируемый вызовом Errorsys(),
    - обработчик математических ошибок,
    - установки макрокомпилятора ( устанавливаемые hb_setMacro() ),
    - RDDI_* установки в стандартных RDD ( сторонние RDD могут использовать глобальные установки ),
    - thread static переменные.

Отдельные Public и Private переменные могут передаваться потоку при его создании.

Следующие ресурсы используются совместно:
    - функции и процедуры,
    - определения классов,
    - модули RDD,
    - GT драйверы,
    - языковые модули,
    - модули кодовых страниц,
    - статические переменные.

Локальные ресурсы потока:
    - Public и Private переменные, кроме тех, что используются совместно,
    - рабочие области (workareas),
    - thread static переменные.

Ниже следует список функций, предназначенных для управления потоками, их созданием и завершением:

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

Пользуясь этими функциями, мы уже можем написать первые несложные многопоточные приложения, например вот такое, для вывода часов на экран:

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

      CLEAR SCREEN

      IF !hb_mtvm()
         ? "Отсутствует поддержка многопоточности, часов не будет видно."
         WAIT
      ELSE
         hb_threadStart( @Show_Time() )
      ENDIF

      @ 10, 10 SAY "Введите что-нибудь:" GET cVar
      READ
      SetPos( 12, 0 )
      ? "Вы ввели -> [" + 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
   

Мы создали поток, который начал выполнять функцию Show_Time(), постоянно выводящую текущее время в верхнем правом углу экрана и продолжаем заниматься своми делами. Обратите внимание, что для вывода времени на экран используется функция hb_dispOutAt(), она не изменяет текущего положения курсора и цвета в консоли.

Если бы использовалась друга функция, например, DispOut(), курсор перемещался бы из области ввода в основном потоке, при этом не помогло бы сохранение и восстановление его позиции в Show_Time(). Дело в том, что операционная система может прервать выполнение одного потока и передать управление другому в любой момент времени, посреди любой операции. Вы, например, восстанавливаете положение курсора функцией SetPos(), но на любой стадии ее выполнения ( а это длинная серия операций машинного кода ) операционная система может прервать ее и вернуть управление главному потоку или какому-либо другому, который в этот момент тоже модифицирует положение курсора - и результат будет непредсказуем. Поэтому в тех случаях, когда потоки используют какие-либо общие ресурсы ( чаще всего - переменные ), необходимы средства синхронизации работы потоков, чтобы они не обращались к общим ресурсам одновременно. Такими средствами являются семафоры и одна из их разновидностей - mutex ( их называют по-русски "мьютексы", но мне такое написание что-то не нравится ). Смотрим ниже описание соответствующих функций:

Итак, для предотвращения одновременого обращения разных потоков к одному и тому же ресурсу делаем следующее:
    1) создаем предварительно mutex: pMtx := hb_mutexCreate()
    2) в тех местах программы, где происходит обращение к защищаемым ресурсам, оборачиваем соответствующий код блокировкой/разблокировкой mutex'а, т.е. ставим перед перед ним hb_mutexLock( pMtx ) и после него hb_mutexUnLock( pMtx ) - точно так же, как мы блокируем/разблокируем запись расшаренной базы данных при записи в нее. Не забывайте, что, в отличие от rlock(), hb_mutexLock() приостанавливает дальнейшее выполнение потока, если mutex уже чем-то заблокирован - при невнимательности можно получить deadlock - ситуацию, когда несколько потоков взаимно заблокировали выполнение друг друга.

Правда, в нашем примере с часами, на тот случай, если бы мы использовали Setpos() и Dispout(), mutex'ы нам бы не помогли. В главном потоке управление курсором производится не непосредственно в нашей программе, а где-то внутри Харборовской RTL, в реализации функции Readmodal() - и вставить туда блокировку mutex'а мы не можем. Поэтому расширим немного этот пример, добавив туда установку параметров отображения даты:

   #include "box.ch"

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

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

      CLEAR SCREEN

      IF !hb_mtvm()
         ? "Отсутствует поддержка многопоточности, часов не будет видно."
         WAIT
      ELSE
         mutex1 := hb_mutexCreate()
         hb_threadStart( @Show_Time() )
      ENDIF

      SET KEY -4 TO Options
      @ 10, 10 SAY "Введите что-нибудь:" GET cVar
      READ
      SET KEY -4 TO
      SetPos( 12, 0 )
      ? "Вы ввели -> [" + 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
   

Итак мы имеем переменную cOpt, которая содержит строку формата отображения даты, функцию Options(), которая вызывается по нажатию клавиши F5 и изменяет эту строку формата. Поскольку поток, выполняющий Show_Time(), использует эту строку, то для исключения коллизий мы используем mutex.

Еще один пример многопоточной программы с mutex'ами смотрите в предыдущем разделе.

Еще 2 функции для синхронизации действий между потоками:

Теперь о доступе к базам данных в многопоточных приложениях. Как уже отмечалось выше, в Harbour рабочие области (workareas) локальны для потока, т.е. каждый поток имеет свои независимые рабочие области и алиасы и, в общем случае, если вам в потоке "Б" нужна база данных, уже открытая в потоке "А", вам надо открыть ее в "Б" по новой, что нетрудно сделать в shared mode.

Но есть и другая возможность - вы можете передать рабочую область от одного потока другому, используя для этого известное пользователям xBase++ zero space. Для этого предназначены следующие 2 функции:

Этот механизм позволяет разным потокам совместно использовать рабочие области. Для иллюстрации введем 2 команды:

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

После открытия таблицы командой Use поток выполняет UNLOCK WORKAREA и, т.о., перемещает ее в zero space. Теперь каждый поток, которому нужна эта таблица, может получить к ней доступ, например:

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

Другие примеры многопоточных программ вы можете найти в harbour/tests/mt.

3.12 API файлового ввода/вывода (File IO API)

Как известно, Harbour унаследовал от Clipper набор функций FOpen(), FSeek(), FRead(), ..., предназначенных для работы с файлами. Этот набор пополнился новыми функциями, полный их список приведен в подразделе 3.14.2 Файловые функции.

Новое API файлового ввода/вывода - это набор функций с префиксом hb_vf, аналогичных по набору параметров и производимым операциям обычным файловым функциям. Изменена реализация этих функций, что позволило использовать заменяемые драйверы наподобие RDD. Теперь, если перед именем файла поставить префикс какого-либо из существующих драйверов с двоеточием в конце ( "mem:", "net:", ... ), обращение к этому файлу пойдет через этот драйвер. Вот этот вызов, например:

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

Драйверы ввода/вывода - это дополнительные библиотеки Harbour, такие как hbnetio, hbmemio, hbgzio, hbbz2io, hbcomio и др.

Список функций:

3.13 Интернационализация (hbi18n)

Технология интернационализации приложений, основана на широко известной GNU gettext и обеспечивает сравнительно простой способ перевода приложений на разные языки.

Я попробую пошагово описать этот процесс. Итак,

1. Пометим специальным образом все строковые литералы, которые мы хотим перевести. Для этого мы вставляем в каждый исходный файл, в котором есть такие литералы, строчку типа

   #xtranslate _I( <x,...> ) => hb_i18n_gettext( <x> )
   

   Alert( _I("Dangerous error!") )
   

2. Создать так называемые pot-файлы. Для этого надо скомпилировать Харбором наши исходники с ключом -j (ну и с другими ключами, которые мы используем при компиляции), например:

   harbour myfile1.prg myfile2.prg -j -n -ic:\harbour\include
   

   #: /myfile1.prg:230
   #, c-format
   msgid "Dangerous error!"
   msgstr ""
   

3. Объединяем все .pot файлы нашего проекта. Для этого используется специальная программа, входящая в комплект Харбора, hbi18n. Запускаем ее с ключом -m (merge - объединение):

   hbi18n -m -omyproject.pot myfile1.pot myfile2.pot
   

4. Приступаем, собственно, к переводу. Для каждого msgid c текстом вставляем его перевод в msgstr. Теперь у нас в myproject.pot будут строки типа:

   #: /myfile1.prg:230
   #, c-format
   msgid "Dangerous error!"
   msgstr "Жуткая ошибка!"
   

5. Следующим шагом будет компиляция myproject.pot, для этого опять используем hbi18n, теперь уже с ключом -g:

   hbi18n -g myproject.pot
   

6. Для этого вставляем в программу следующие строки:

    cBuff := hb_MemoRead( "myproject..hbl" )
    IF hb_i18n_Check( cBuff )
       hb_i18n_Set( hb_i18n_RestoreTable(cBuff) )
    ENDIF
   

Ну хорошо, создали мы hbl-файлы, подгружаем их, все работает. Но мы меняем программу, добавляем новые литералы. Создаем pot-файлы по новой, но они без перевода. Что, писать перевод опять? Нет, конечно! Нам послужит все та же hbi18n, но уже с ключом -a (add - добавить). Она добавляет переводы слов из сохраненного старого pot-файла:

   hbi18n -a -omyproject.pot myproject.pot myproject_old.pot
   

В заключение приложу сюда в качестве примера мой рабочий bat-файл, который создает и модифицирует pot. Этот bat-файл взят из hbedit:

   @set SRC_DIR=\papps\gitapps\hbedit\source

   c:\harbour\bin\harbour %SRC_DIR%\fdiff.prg %SRC_DIR%\fedit.prg %SRC_DIR%\fmenu.prg %SRC_DIR%\fview.prg %SRC_DIR%\hbcommander.prg -j -n -q -ic:\harbour\include

   c:\harbour\bin\hbi18n.exe -m -ohbedit_ru_1.pot fdiff.pot fedit.pot fmenu.pot fview.pot hbcommander.pot
   c:\harbour\bin\hbi18n.exe -a -ohbedit_ru_1.pot hbedit_ru_1.pot hbedit_ru866.pot
   mv hbedit_ru_1.pot hbedit_ru866.pot

   @del *.c
   @del fdiff.pot
   @del fedit.pot
   @del fmenu.pot
   @del fview.pot
   @del hbcommander.pot
   

Как видите, сначала собирается временный hbedit_ru_1.pot, потом в него добавляются переводы из основного hbedit_ru866.pot и после этого временный hbedit_ru_1.pot переименовывается в основной hbedit_ru866.pot

3.14 Всякие новые функции

В этом разделе будут рассмотрены разнообразные новые функции, не попавшие в предыдущие тематические разделы.

3.14.1 Встроенный компилятор

Три функции, использующие встроенный компилятор (hbcplr.lib), основанный на том же коде, что и сам harbour.exe.

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

         buf := hb_compilebuf( "harbour", cFileName, "/n","/w" )  // Компилируем
         hb_hrbRun( buf )                                         // исполняем

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

      Return Nil
   

3.14.2 Файловые функции

#define HB_FA_READONLY     0x00000001  /* R */
#define HB_FA_HIDDEN       0x00000002  /* H */
#define HB_FA_SYSTEM       0x00000004  /* S */
#define HB_FA_LABEL        0x00000008  /* V */
#define HB_FA_DIRECTORY    0x00000010  /* D */
#define HB_FA_ARCHIVE      0x00000020  /* A */
#define HB_FA_DEVICE       0x00000040  /* I */
#define HB_FA_NORMAL       0x00000080  /*   */

#define HB_FA_TEMPORARY    0x00000100  /* T HB_FA_FIFO */
#define HB_FA_SPARSE       0x00000200  /* P */
#define HB_FA_REPARSE      0x00000400  /* L HB_FA_LINK */
#define HB_FA_COMPRESSED   0x00000800  /* C */
#define HB_FA_OFFLINE      0x00001000  /* O */
#define HB_FA_NOTINDEXED   0x00002000  /* X */
#define HB_FA_ENCRYPTED    0x00004000  /* E */

# Unix/Linux:
#define HB_FA_SUID         0x08000000  /* 4000 set user ID on execution */
#define HB_FA_SGID         0x04000000  /* 2000 set group ID on execution */
#define HB_FA_SVTX         0x02000000  /* 1000 sticky bit */
#define HB_FA_RUSR         0x01000000  /* 0400 read by owner */
#define HB_FA_WUSR         0x00800000  /* 0200 write by owner */
#define HB_FA_XUSR         0x00400000  /* 0100 execute/search by owner */
#define HB_FA_RGRP         0x00200000  /* 0040 read by group */
#define HB_FA_WGRP         0x00100000  /* 0020 write by group */
#define HB_FA_XGRP         0x00080000  /* 0010 execute/search by group */
#define HB_FA_ROTH         0x00040000  /* 0004 read by others */
#define HB_FA_WOTH         0x00020000  /* 0002 write by others */
#define HB_FA_XOTH         0x00010000  /* 0001 execute/search by others */
         

           FC_NORMAL          0
           FC_READONLY        1
           FC_HIDDEN          2
           FC_SYSTEM          4
        

3.14.3 Функции для манипуляций с именами файлов

3.14.4 Строковые функции

3.14.5 Функции для работы с массивами

3.14.6 Управление запуском процессов

3.14.7 Битовые операции

3.14.8 Функции для манипуляции переменными

         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.14.9 Функции сравнения по маске

3.14.10 Функции для упаковки/распаковки строк, использующие zlib

3.14.11 Idle state

Idle state - это состояние ожидания, когда программа на Harbour ждет ввода от пользователя, с клавиатуры или мыши. Оно возникает как результат вызова функции Inkey() ( команда READ использует Inkey(), так что и при ожидании ввода GET-объектов возникает idle state ). В этом состоянии происходит автоматическая сборка мусора и могут выполняться какие-либо фоновые задачи. Для добавления/удаления этих фоновых задач и предназначены последующие функции (пример использования см. в harbour/tests/testidle.prg):

3.14.12 JSON - туда и обратно

3.14.13 Шифрование

3.14.14 HiPer-SEEK (Fast Text Search)

Библиотека HiPer-SEEK (hbhsx) - это реализация для Harbour HiPer-SEEK от Six Drivers, которая, в свою очередь, основана на Fast Text Search компании Index Applications.

HiPer-SEEK - это набор функций, с помощью которого можно создать и использовать специальные индексные файлы, позволяющие быстрый поиск текста. Функции HiPer-SEEK могут использоваться для любого источника текстовых данных - dbf-файлов, текстовых файлов, массивов и пр.

Индексы HiPer-SEEK содержат ключи фиксированной длины которые отражают содержание текстовых записей. Текстовые записи могут содержать любые блоки текста. В случае использования .dbf они обычно представляют собой конкатенацию выбранных полей из записи файла. Это может быть также строка или параграф из текстового файла, или даже целый файл. В любом случае, у нас будет одна запись в индексе на каждую текстовую запись.

Индексный файл создается функцией hs_Create(). Она строит заголовок индекса и устанавливает атрибуты, но не добавляет записи в индекс. Это делается функцией hs_Add().

.hsx индекс - это не какое-то преобразование или сжатие текстовых данных. Его ключи "отслеживают" текстовые сигнатуры. Он идентифицирует совпадения как индексные записи, содержащие все сигнатуры или атрибуты строки поиска. Может получиться, что разные строки будут иметь одну и ту же сигнатуру. Это называется здесь алиасами. Поэтому надо проверять каждый результат, возвращаемый hs_Next(). Но, хотя .hsx индекс может ошибочно указать запись как соответствующую условию поиска, он никогда не пропустит действительное совпадение.

HiPer-SEEK позволяет строить системы поиска текста для самых разных приложений. Но надо учитывать следующие факторы. Если текстовые записи очень коротки, короче или почти такие же, как минимальный индексный ключ (16 байт), то индекс будет больше, чем исходные данные. Если же записи слишком велики - 64К, например, то из создания для них сигнатур (максимальная длина - 64 байта) ничего хорошего не выйдет.

    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.14.15 Разные функции - не знаю, в какую группу их включить

           ? 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 } )
           и т.д.
        

Карта сайта

© Copyright 2016. All Rights Reserved.