For the PROMOTIC system to know which functions from the DLL library can be used by it and what is the format of these functions, there must be a text file with the extension .INC at the DLL library that is named identically as the DLL library (for example at the XY.DLL library must be the XY.INC file). In this .INC file one line corresponds exactly to the declaration of one function.
Declare Function MyFce Lib "MyDll" ([ByVal] Par As TypePar[, ...]) As TypeRet
|MyFce||name of the declared function|
|MyDll||name of the DLL library|
|Par||name of the function parameter|
|TypePar||data type of the parameter (see next table)|
|TypeRet||data type of the returned value by the function|
If the ByVal keyword precedes the name of the parameter, then this parameter is passed by its value. Otherwise it is passed by its reference.
The following data types of parameters are allowed:
|Type name||Memory size||>meaning:||Range|
|Byte||1 byte||Integer||from 0 to 255|
|Integer||2 bytes||Integer||from -32 768 to +32 767|
|Long||4 bytes||Integer||from -2 147 483 648 to +2 147 483 647|
|Single||4 bytes||Real number||+/- 3,4E +/- 38 (7 valid digits)|
|Double||8 bytes||Real number||+/- 1,7E +/- 308 (15 valid digit)|
|String||by chars number||Text string|
|Any||byte sum of subitems||Array of values|
If the Any word is stated in the declaration of the function in the .INC file at the parameter type, then the PROMOTIC system allows passing any data as the function parameter. On calling the function it creates a buffer into which the binary content of the passed variable is copied (e.g. an array created by VBScript.Array). It passes this buffer to the called function. After the function termination it passes the data from the buffer back to the variable. So if you have, for example, an array whose type structure precisely corresponds to the passed structure, you can even use functions that have structures in their parameters.
!Caution! When passing the structures and arrays, required data types of array items must be strictly kept because the wrong usage can have destructive consequences!
Declare Function factor Lib "usrdll" (ByVal n As Integer) As Double
Declare Function nibble Lib "usrdll" (ByVal B As Byte, bit1 As Byte, bit2 As Byte, bit3 As Byte, bit4 As Byte) As Byte
The function accesses the Fce property by the above introduced way of the loaded library. Let's have a "MyDll" object of the PmaDll type, located in the "Lib" folder. If we want to call its function "factor", then we can write:
f = pMe.Pm("/Lib/MyDll").Fce.factor(6)
Dim oFce, f, g
Set oFce = pMe.Pm("/Lib/MyDll").Fce
f = oFce.factor(6)
g = oFce.factor(10)
This example demonstrates how the interface of the functions "factor" and "nibble" from examples 1 and 2 looks like in the C language. Variable of the "double" type is of 8B in length, variable of the "char" type 1B and variable of the "short" type 2B in length
extern "C" double __declspec(dllexport) __cdecl factor(short n);
extern "C" char __declspec(dllexport) __cdecl nibble(char B, char *bit1, char *bit2, char *bit3, char *bit4);