Function DllCall() Foundation
Calls a DLL function dynamically at runtime.
The function is deprecated. Use the EXTERN command instead.
DllCall( <cDllName>|<nDllHandle>, [<nCallingConv>] , ; <cFuncName>|<nOrdinal> [, <xParam,...>] ) --> xReturn
|DLL_CDECL||C calling convention|
|DLL_OSAPI||Calling convention for the operating system API|
|DLL_STDCALL||Standard for the Windows 32bit API|
|DLL_SYSTEM||Standard for the OS/2 API|
|DLL_XPPCALL *)||Calling convention for Xbase++ DLLs|
|DLL_CALLMODE_NORMAL *)||Fastest mode, original parameters passed|
|DLL_CALLMODE_COPY||Safest mode, callee uses a copy of passed parameters|
|DLL_CALLMODE_RESTOREFPU||Caller restores FPU control word|
DllCall() 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 value substituted by the error handler is returned.
The function DllCall() executes a function which is contained in an external 32bit DLL file. When the DLL is not loaded, an implicit call to DllLoad() occurs prior to calling the DLL function. The DLL remains loaded.
DllCall() is able to call functions from DLLs which comply with different calling conventions. Functions in system DLLs (API functions) use a different calling convention than those in Xbase++ DLLs, for example. Many producers of DLLs use the C calling convention which is supported by DllCall() as well.
When parameters are passed to functions which do not comply with the Xbase++ calling convention, only values of the data type "character", "numeric" or "logical" can be used. They are converted to C data types as is shown in the following table:
|Data type||Passing as value||Passing by reference|
|FLOAT is converted to unsigned||*unsigned long|
|NIL||long with value zero||n/a|
The range of the Xbase++ data type Numeric is larger than the C data type unsigned long (0..0xFFFFFFFF). If the passed value is out of the unsigned long range, a runtime error is posted to indicate loss of data. NIL will be accepted and converted to a long with the value of zero. Passing a reference to a variable containing NIL is not possible and will cause a runtime error.
If the called API needs an undefined amount of time and the default calling mode DLL_CALLMODE_NORMAL is used, the runtime system is hindered by this call and cannot release garbage memory while the API is called. To avoid this, use the calling mode DLL_CALLMODE_COPY. It causes DllCall() to copy all passed parameters (which is slower) but unblocks the Xbase++ memory system.
If a DLL file is created by Xbase++, all data types may be passed to a DLL function and can be processed by it. Executing a DLL function from an Xbase++ DLL is possible using DllCall(). However, it is recommended to use the macro-operator in this case, since it provides the fastest possible way to call a function contained in a dynamically loaded Xbase++ DLL. The following expression is used for that purpose:
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.
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.