PmaDll - Deatiled object description

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 exactly to the declaration of one function.

Line syntax:
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

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 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, CLng, 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\ 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 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\ 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

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.
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.
PROMOTIC 9.0.27 SCADA system documentation MICROSYS, spol. s r.o.

Send page remarkContact responsible person
- Dll
- Fce
- PmaDll - Deatiled object description
© MICROSYS, spol. s r.o.