xHarbour Reference Documentation > Function Reference

HB_LibDo()

Executes a function located in a dynamically loaded xHarbour DLL.

Syntax

HB_LibDo( <cFuncName> [, <xParams,...>] ) --> xResult

Arguments

<cFuncName>

This is a character string holding the symbolic name of the function or procedure to execute.

<xParams,...>

The values of all following parameters specified in a comma separated list are passed on to the DLL function.

Return

The function returns the result of the called DLL function.

Description

Function HB_LibDo() is used to execute functions located in DLL files created by the xHarbour compiler and linker. This applies to DLL files loaded dynamically at runtime with function LibLoad(). If a DLL file is bound statically at link time, a DLL function can be called directly.

HB_LibDo() looks up the symbolic function name <cFuncName> and passes the values of <xParams,...> to it. The return value of HB_LibDo() is the result of <cFundName>. If <cFuncNmae> cannot be found, a runtime error is generated.

Important:  the EXE file loading the xHarbour DLL with LibLoad() must be created for DLL usage for HB_LibDo() to work properly (compiler switch -usedll, linker switch /DLL).

Info

See also:	DllCall(), LibLoad(), LoadLibrary()
Category:	DLL functions , xHarbour extensions
Source:	vm\dynlibhb.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example consists of two file. The first is compiled to an EXE
// and the second to a DLL. Function SayHello() resides in the DLL
// and is called from the EXE.

   /* ------------------------------------------------------------
   // File: DYNDLL.PRG
   //       Compile and link as EXE for DLL usage
   //       e.g. XBuild -usedll dyndll.exe dyndll.prg
   // ---------------------------------------------------------- */
   PROCEDURE Main
      LOCAL pDLL

      ? Type( "SayHello()" )
        // result is "U" because the function SayHello()
        // does not exist


      ? pDLL := LibLoad( "dyndll1.dll" )
        // result is a pointer to the loaded DLL


      ? Type( "SayHello()" )
        // result is "UI" because function SayHello()
        // exists now (in loaded DLL)


      ? HB_LibDo( "SayHello" )
        // result is:  1
        // displays : Hello from DLL


      ? HB_LibDo( "SayHello", "Called via HB_LibDo()" )
        // result is:  2
        // displays : Called via HB_LibDo()


      ? &("SayHello")( "Called via Macro operator" )
        // result is:  3
        // displays : Called via Macro operator
        //
        // NOTE:
        // This is the fastest way of calling a DLL function:
        //
        // The macro operator "&" looks up the function symbol.
        // The execution operator "()" calls the function and
        // passes parameter(s) on to it


      ? LibFree( pDll )
        // result is .T., DLL is successfully unloaded


      ? Type( "SayHello()" )
        // result is "U" because the function SayHello()
        // does not exist anymore

   RETURN


   /* ------------------------------------------------------------
   // File: DYNDLL1.PRG
   //       Compile and link as DLL
   //       e.g. XBuild dyndll1.dll dyndll.prg
   // ---------------------------------------------------------- */
   FUNCTION SayHello( cText )
      STATIC nCalls := 0

      IF cText == NIL
         cText := "Hello from DLL"
      ENDIF

      ? cText

   RETURN ++nCalls