Promotic
WikipediaLinkedInYoutubeTwitterFacebook

PmDll - Deatiled object description

See: Object PmDll
 
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 extension .INC at the DLL library that is named identically as the DLL library (for example at the XY.DLL library must by 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
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, 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 from 255
Integer 2 bytes Integer from -32 768 from +32 767
Long 4 bytes Integer from -2 147 483 648 from +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 summary 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, 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!

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 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, the file C:\Library\MyDll.inc 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 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, the file C:\Library\MyDll.inc 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 parameter B is passed by its value whilst the other parameters are passed by their pointers.
Example3:
The usage of the PmDll object:

The function accesses the Fce property by the above introduced way of the loaded library. Let's have a "MyDll" object of the PmDll type, located in the "Lib" folder. If we want to call its function "factor", we can write:

Dim f
f = pMe.Pm("/Lib/MyDll").Fce.factor(6)
If we want to use the library functions more often, the following is more favorable:
Dim f, g, oFce
Set oFce = pMe.Pm("/Lib/MyDll").Fce
f = oFce.factor(6)
g = oFce.factor(10)
If we want to use the library globally, it is favorable to enter the reference to the Fce property into the page PmRoot > Variables.
Example4:
Declaration of the DLL function in the Microsoft Visual 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 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);
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.
Navigation:
 
 
- Fce
- PmDll - Deatiled object description
 
 
- Dll
© MICROSYS, spol. s r. o.Tavičská 845/21 703 00 Ostrava-Vítkovice