Function DllPrepareCall() Foundation
Prepares a call to a DLL function and creates a call-template.
DllPrepareCall( <cDllName>|<nDllHandle>, [<nFunctionType>] , ; <cFuncName>|<nOrdinal> >, [<nParameterType1>, ...] ) --> cCallTemplate
|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|
|DLL_TYPE_INT16||16 bit integer|
|DLL_TYPE_UINT16||16 bit unsigned integer|
|DLL_TYPE_BOOL8||8 bit boolean|
|DLL_TYPE_BOOL32||32 bit boolean|
|DLL_TYPE_INT32 *)||32 bit integer|
|DLL_TYPE_UINT32||32 bit unsigned integer|
|DLL_TYPE_INT64||64 bit integer|
|DLL_TYPE_UINT64||64 bit unsigned integer|
|DLL_TYPE_FLOAT32||32 bit floating point|
|DLL_TYPE_FLOAT64||64 bit floating point|
|DLL_TYPE_IDISPATCH||COM/ActiveX object (IDispatch)|
|DLL_TYPE_INT16||16 bit integer||Numeric, Logical, NIL|
|DLL_TYPE_UINT16||16 bit unsigned integer||Numeric, Logical, NIL|
|DLL_TYPE_BOOL8||8 bit boolean||Logical, NIL|
|DLL_TYPE_BOOL32||32 bit boolean||Logical, NIL|
|DLL_TYPE_INT32||32 bit integer||Numeric, Logical, NIL|
|DLL_TYPE_UINT32||32 bit unsigned integer||Numeric, Logical, NIL|
|DLL_TYPE_INT64||64 bit integer||Numeric, Logical, NIL|
|DLL_TYPE_UINT64||64 bit unsigned integer||Numeric, Logical, NIL|
|DLL_TYPE_FLOAT32||32 bit floating point||Numeric, NIL|
|DLL_TYPE_FLOAT64||64 bit floating point||Numeric, NIL|
|DLL_TYPE_STRING||Character string||Numeric, Memo, NIL|
|DLL_TYPE_IDISPATCH||COM/ActiveX object (IDispatch)||Object (AutomationObject), NIL|
|DLL_TYPE_CALLBACK||Xbase++ callback function||Object (DllCallback), NIL|
|DLL_TYPE_ACALLBACK||Xbase++ Asynchronous callback function||Object (DllCallback), NIL|
|DLL_TYPE_XPPVALUE||Xbase++ native value||(all types)|
|DLL_TYPE_STRUCTURE||Memory structure||Structure instance, NIL|
The function returns a binary character string which must be passed as first parameter to DllExecuteCall().
The function DllPrepareCall() is designed for using DLL files which do not comply with the Xbase++ calling convention. Functions contained in such DLLs cannot be called via macro-operator. DllPrepareCall() creates a call-template (binary string) which contains all information about a DLL function that must be known when the function is executed. The call-template is then processed by DllExecuteCall(), which finally executes the DLL function.
DllPrepareCall() will cause a runtime error if the parameters are invalid, the DLL could not be loaded or the function <cFuncName>could not be found.
Executing a DLL function via the function pair DllPrepareCall() / DllExecuteCall() is a recommended technique when the function is called multiple times, like in a FOR...NEXT loop. The function call is prepared outside the loop and the execution part is done within the loop. However, if a DLL function is executed only once within a user-defined function, a direct call using DllCall() is faster than DllPrepareCall() / DllExecuteCall().
If a DLL file complies with the Xbase++ calling convention, the fastest possibility of executing a DLL function is provided by the macro-operator (refer to DllExecuteCall()). However, when a Xbase++ DLL function is to be executed via call-template, the original function name must be specified for <cFuncName>, even if the DLL is loaded with a function prefix.
Automatic data type conversion
The following automatic conversion rules as well as numeric range checking rules apply when the data type of the parameter(s) is not specified via the type list.
|Data type||Passing as value||Passing by reference|
|FLOAT is converted to unsigned long||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 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.