Function DllPrepareCall() | Xbase++

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

DllPrepareCall( <cDllName>|<nDllHandle>, [<nFunctionType>] , ;
               <cFuncName>|<nOrdinal> >, [<nParameterType1>, ...] )  --> cCallTemplate

<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.

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.

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.

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
Default

Any calling convention constant can be combined with one or more calling mode constants using the '+' - operator, except DLL_XPPCALL.

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
Default

A return type can be defined for the function by adding one of the following constants using the '+' - operator.

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)
Default

<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.

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.

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.

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

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.

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.

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 DllPrepareCall() Foundation