See: the PmaDll
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 exactly to the declaration of one function.
Declare Function MyFce Lib "MyDll" ([ByVal] Par As TypePar[, ...]) As TypeRet
||name of the declared function|
||name of the DLL library|
||name of the function parameter|
||data type of the parameter (see next table)|
||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
Passing structures and arrays:
||from 0 to 255|
||from -32 768 to +32 767|
||from -2 147 483 648 to +2 147 483 647|
||+/- 3,4E +/- 38 (7 valid digits)|
||+/- 1,7E +/- 308 (15 valid digit)|
||by chars number
||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. 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 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!
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
, etc. groups.
3. It is never harmful to pass much more data into the function parameters than the function requires.
Suppose that the library C:\Library\MyDll.dll contains the function "factor" for the factorial calculation of the 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
Suppose that the library C:\Library\MyDll.dll contains the function "nibble" that serves for getting 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 value, while the other parameters are passed by reference.
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
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.
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.