xHarbour Reference Documentation > Function Reference

DllExecuteCall()

Executes a DLL function via call template.

Syntax

DllExecuteCall( <pCallTemplate>, [<xParams,...>] ) --> nResult

Arguments

<pCallTemplate>

This is a pointer to the template for calling the DLL function. It is returned from function DllPrepareCall().

<xParams,...>

This is a comma separated list of parameters which are passed to the DLL function to call.

Return

The function returns the result of the executed DLL function as a numeric value.

Description

Function DllExecuteCall() executes a DLL function using the call template as it is prepared by function DllPrepareCall(). The DllPrepareCall()/DllExecuteCall() way of calling a function in an external DLL is advantageous when the same DLL function must be executed many times. The call template is prepared once and contains all information required to execute the DLL function. If a DLL function needs to be called only once or a few times, it can be called directly via DllCall(). The overhead of preparing the call template can be avoided in such cases.

Info

See also:	DllCall(), DllPrepareCall(), FreeLibrary(), GetProcAddress(), GetLastError(), LoadLibrary()
Category:	DLL functions , xHarbour extensions
Source:	rtl\dllcall.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example implements two Windows API wrappers for conversion of
// Ansi strings to Unicode and vice versa. The call templates for
// DllExecuteCall() are created on the first function call and stored
// in STATIC variables.

   #define DC_CALL_STD            0x0020

   PROCEDURE Main
      LOCAL cString, cWideString

      cString     := "Hello World"
      cWideString := AnsiToWide( cString )

      ? Len( cString ), cString
      ? Len( cWideString ), cWideString

      ? WideToAnsi( cWideString )
   RETURN


   FUNCTION AnsiToWide( cString )
      STATIC pCallTemplate

      LOCAL nWideLen  := 2 * ( Len( cString ) )
      LOCAL cWideChar := Replicate( Chr(0), nWideLen )
      LOCAL nRet

      IF pCallTemplate == NIL
         // create call template on first call
         pCallTemplate := DllPrepareCall(  ;
                           "Kernel32.dll", ;      // external DLL
                           DC_CALL_STD   , ;      // calling convention
                          "MultiByteToWideChar" ) // external function
      ENDIF

      nRet := DllExecuteCall(    ;
                 pCallTemplate , ;
                 0             , ;
                 0             , ;
                 cString       , ;
                 -1            , ;
                @cWideChar     , ;
                 nWideLen        )
   RETURN cWideChar


   FUNCTION WideToAnsi( cWideChar )
      STATIC pCallTemplate

      LOCAL nLen    := Int( Len( cWideChar ) / 2 )
      LOCAL cString := Replicate( Chr(0), nLen )
      LOCAL nRet

      IF pCallTemplate == NIL
         // create call template on first call
         pCallTemplate := DllPrepareCall(  ;
                           "Kernel32.dll", ;      // external DLL
                           DC_CALL_STD   , ;      // calling convention
                          "WideCharToMultiByte" ) // external function
      ENDIF

      nRet := DllExecuteCall(    ;
                 pCallTemplate , ;
                 0             , ;
                 0             , ;
                 cWideChar     , ;
                 -1            , ;
                @cstring       , ;
                 nLen          , ;
                 0             , ;
                 0               )
   RETURN cString