Function DllExecuteCall() | Xbase++

Calls a function from a dynamically loaded DLL using a call-template.

DllExecuteCall( <cCallTemplate> [, <xParam,...>] ) --> xReturn

<cCallTemplate> is a binary character string which is returned by the function DllPrepareCall().

Optionally, <xParam> is a comma-separated list of parameters that are passed as arguments to the DLL function. The arguments must have the correct data types as required by the called function. If a value of an illegal data type is passed, a runtime error occurs.

DllExecuteCall() returns the return value of the executed DLL function. If the DLL complies with the Xbase++ calling convention, the value may be of any Xbase++ data type. Otherwise, the return value is of numeric data type.

In case of a runtime error, the return value can be substituted by the error handler.

DllExecuteCall() is a low-level function. The EXTERN command provides a higher-level interface to the same functionality and should be used in normal application scenarios. DllExecuteCall() in conjunction with the DllPrepareCall() function is intended for usage in code providing specialized access to DLL functions, for example, in custom application frameworks.

The function DllExecuteCall() is used in conjunction with DllPrepareCall() which prepares a call-template for the execution of a DLL function. The call-template is passed to DllExecuteCall() together with the parameters for the DLL function. The call-template can be reused any number of times. However, call-templates can only be used by the process in which they were created.

Notes for Xbase++ DLLs

If a DLL file is created by Xbase++, the fastest possible way to call a function contained in a dynamically loaded Xbase++ DLL is provided by the macro-operator. The following expression is used for that purpose:

&(<cFuncName>) ( [<xParam,...>] )

The macro-operator searches for the function name in the symbol table, the execution-operator () calls this function and passes the optional parameters<xParam> to it. If a DLL does not comply with the Xbase++ calling convention, this is not possible.

When the Xbase++ DLL is loaded with a function prefix specified, the character expression <cFuncName> must contain both prefix and function name. However, this is not necessary if the function is called via DllCall(). In that case, the prefix of the DLL will implicitly be retrieved and concatenated with the parameter <cFuncName> to the resulting function name before the call is executed.

Execute DLL functions via call-template

// The example shows the technique how to execute a DLL function 
// using a call-template. It is assumed that the file MYXPP.DLL 
// complies with the Xbase++ calling convention. 

PROCEDURE Main 
   LOCAL nDllHandle, cTemplate, i, xResult 

   nDllHandle := DllLoad( "MYXPP.DLL" ) 
   cTemplate  := DllPrepareCall( nDllHandle, , "MyFunction" ) 

   FOR i:=1 TO 100 
      xResult := DllExecuteCall( cTemplate, "p1", "p2", i ) 
      ? xResult 
   NEXT 

   DllUnload( nDllHandle ) 

RETURN

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.

Function DllExecuteCall() Foundation