Functions and Directives

Function DllPrepareCall() Foundation

Prepares a call to a DLL function and creates a call-template.

Syntax
DllPrepareCall( <cDllName>|<nDllHandle>, [<nFunctionType>] , ;
               <cFuncName>|<nOrdinal> >, [<nParameterType1>, ...] )  --> cCallTemplate
Parameters
<cDllName>
<cDllName> is a character string containing the name of the DLL file that contains the function <cFuncName>. If the constant WIN32API from dll.ch is assigned to <cDLLName>, the function is automatically searched for in the following Win32 API libraries: Kernel32.dll, Gdi32.dll, User32.dll, Mpr.dll and Advapi32.dll.
<nDllHandle>
Instead of a file name, the numeric handle <nDllHandle> of an already loaded DLL can be passed. It is the return value of the DllLoad() function. If the value 0 is assigned to <nDLLHandle>, the function is automatically searched for in the following Win32 API libraries: Kernel32.dll, Gdi32.dll, User32.dll, Mpr.dll and Advapi32.dll.
<nFunctionType>
A #define constant from the following table can be used for <nFunctionType>. It specifies the calling convention to be used for the DLL function, the calling mode as well as the DLL function's return type.
Constants for the calling convention of DLL functions
Constant Description
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
  1. Default
Any calling convention constant can be combined with a calling mode constant using the '+' - operator, except DLL_XPPCALL.
Constants for calling mode
Constant Description
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
  1. Default
A return type can be defined for the function by adding one of the following constants using the '+' - operator.
Constants for the return type of DLL functions
Constant Description
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_STRING Character string
DLL_TYPE_IDISPATCH COM/ActiveX object (IDispatch)
  1. Default
<cFuncName>
<FunctionName> designates the name of the DLL function to be executed. Function names in DLLs are case-sensitive. A runtime error results if an attempt is made to call a function which cannot be found in the DLL.
<nOrdinal>
Alternatively, the numeric ordinal <nOrdinal> of the DLL function may be passed. This avoids a lookup of the function name in the symbol table of the DLL.
<nParameterType1>, ...
The data type of the parameter(s) of the DLL function can optionally be defined via a list of data types starting with <nParameterType1>. A constant from the following table must be specified for each parameter that is expected. A mixture of typed and untyped parameters is not allowed.
If the data type of the parameter(s) is not specified via the type list, the type of the actual parameters passed when calling the DLL function is automatically transformed to a corresponding C type.
Constants for the parameter type of DLL functions
Constant Description Supported values
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
Notes:
- Value NIL: NIL can be passed as a value for all parameter types. It corresponds to the numeric value 0 or a NULL pointer. However, unless the parameter is of type DLL_TYPE_STRING or DLL_TYPE_IDISPATCH, passing NIL by reference (@) yields a runtime error.
- AutomationObjects (IDispatch): Input values in parameters of type DLL_TYPE_IDISPATCH must be objects of a class derived from AutomationObject. Output values are instances of class AutomationObject. NIL as an input value denotes "no input".
- Callback functions: A callback function refers to Xbase++ code that is called implicitly by the DLL function, for example, for processing data about operating system objects that are enumerated. A callback function must be defined using the DllCallback class. Using callbacks is supported only for DLL functions using the DLL_CDECL or DLL_OSAPI calling conventions.
- STRUCTUREs: STRUCTURE instances can be passed as-is to a DLL or API function, provided the corresponding parameter is declared AS STRUCTURE. Structure parameters declared are type-safe, meaning is it not possible to assign a value of a different data type. Attempting to do so yields a runtime error. See the LOCAL statement for further details on creating structure instances.
Return

The function returns a binary character string which must be passed as first parameter to DllExecuteCall().

Description

DllPrepareCall() 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. DllPrepareCall() in conjunction with the DllExecuteCall() function is intended for usage in code providing specialized access to DLL functions, for example, in custom application frameworks.

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.

The call-template must not be altered!

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.

Conversion of data types to C
Data type Passing as value Passing by reference
Character const char* char*
Numeric long long*
FLOAT is converted to unsigned long unsigned long*
Logical long 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.

Feedback

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.