See: the
PmaDll object.
Syntax description of the declaration file of the DLL library functions:
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
.INC extension 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 to the declaration of one function.
Line syntax:
Declare Function MyFce Lib "MyDll" ([ByVal] Par As TypePar[, ...]) As TypeRet
where:
| 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 the 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 |
Passing structures and arrays:
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. When 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 into 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!
Notes:
1. Binary content of the structure can even include padding determined for the justification of structure items to the defined number of bytes.
2. It is necessary to set explicitly the types of passed data by functions of the
CInt,
CLng, etc. groups.
3. It is never harmful to pass much more data into the function parameters than the function requires.
Example1:
Suppose that the library C:\Library\MyDll.dll contains the function "factor" for calculation of the factorial number. This function has a parameter of the 2-byte integer type and it returns a 8-byte real number. If we want to use it in the PROMOTIC system, then the C:\Library\MyDll.inc file must include the following line:
Declare Function factor Lib "usrdll" (ByVal n As Integer) As Double
Example2:
Suppose that the library C:\Library\MyDll.dll contains the function "nibble" that serves for obtaining the value of lower 4 bits of an integer number. This function returns a zero in the 1-byte integer if all four lower bits are null, otherwise it returns one. It sets the lower 4 bits of the first parameter that is of the Byte type into its second to fifth parameters (again of the Byte type). If we want to use it in the PROMOTIC system, then the C:\Library\MyDll.inc file must include the following line:
Declare Function nibble Lib "usrdll" (ByVal B As Byte, bit1 As Byte, bit2 As Byte, bit3 As Byte, bit4 As Byte) As Byte
Notice that the B parameter is passed by the value, while the other parameters are passed by reference.
Example3:
The usage of the PmaDll object:
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:
VBScriptSelect and copy to clipboard
Dim f
f = pMe.Pm("/Lib/MyDll").Fce.factor(6)If we want to use the library functions more often, then the following is more favorable:
VBScriptSelect and copy to clipboard
Dim oFce, f, g
Set oFce = pMe.Pm("/Lib/MyDll").Fce
f = oFce.factor(6)
g = oFce.factor(10)If we want to use the library globally, then it is favorable to enter the reference to the
Fce property in the "
Variables" configuration window.
Example4:
Declaration of the DLL function in the C++ language
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 size, variable of the char type 1B and variable of the short type 2B size
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);
At compilers of other producers the export of the DLL function (here __declspec(dllexport)) can be handled quite differently. Also at other programming languages it is necessary to read thoroughly the documentation that is connected with the export and import of DLL functions.