Omnis Technical Note TNNO0006
Using Register DLL and Call DLL
For Omnis Studio and Classic
By Tom Hume
Overview
'Register DLL' and 'Call DLL' give Omnis the capability to call functions
in existing Windows DLLs without writing or converting them into Omnis
extensions. This gives the developer the ability to run a function in
pre-existing Windows DLLs.
A Typical C Function in a DLL
The following is the anatomy of a C function used in a DLL. The developer
will need to know the format
of the function he intends to call within the DLL. The structure of a
function looks something like this:
<Function Name>([Parm1,[Parm2])
{
<Function code>
return <Return Type>
}
integer, character point, float, etc. If the function does not return
a value, the Return Type is of type void.
The parameters are optional; they can also be of any data type defined
by whoever wrote the DLL.
The function should be declared by the C programmer as exportable, meaning
Windows will let other programs see the function inside the DLL. Unless
the Omnis developer wrote the DLL, they will have
no control over this.
The Return Type, Parameter Types for the function, and the function name
are important to know because 'Register DLL' has to know what they are.
This information must be obtained from the developer of the DLL or the
documentation that came with the DLL.
Register DLL
Reversible: | NO | Flag affected: | NO |
Parameters: | Library name (of the DLL) Procedure name Type definition string Return field |
Syntax: | Register DLL (library-name, procedure-name, type-definition) [returns return-field] |
Register DLL' must be used before 'Call DLL' can be executed. Since
the DLL is not an Omnis Extension, OMNIS needs to know what to do with
it. A common mistake that is often made is that the DLL is placed in the
C:\OMNIS\EXTERNAL directory. The DLL actually belongs in the C:\WINDOWS\SYSTEM
directory to be properly called. The syntax of
'Register DLL' is as follows:
Register DLL('<File
Name>','<Function Name>
;','<parameter string>') with return
value <
RETURNVAL>
The quotes around each string are required.
File Name is the file name of the DLL, i.e., TEST.DLL. You may specify
the path, but if not then Windows will look in each path on the search
path (including the OMNIS directory).
Function name is the name of the function inside the DLL. You will have
to obtain this from the DLL programmer or the documentation that came
with the DLL.
All procedures in the DLL are called using the Pascal calling convention.
See Table 1.
The parameter string is a text string that describes the return
value types of the parameters to be passed if they exist. First obtain
the data type of the return value (void if there isnÕt one), and the data
type of all the parameters if any. Again, you will have to obtain this
from the DLL programmer or the documentation that came with the DLL. Table
1 maps character codes with data types. The first character of the parameter
string is the character code for the data type of the return value of
the function, i.e., if the return value is a void, the first character
of the parameter string would be 'V'. If it were a long integer,
it would be a 'J'. The next character would be the character code of the
first parameter passed, if any.
The remaining characters would be the character codes for any additional
parameters
Code | Description | Pass By | C declaration |
A | Logical | Value | short int |
B | IEEE 8-byte floating point | Value | double |
C | Null-terminated string | Reference | char * |
D | Pascal string | Reference | unsigned char * |
E | IEEE 8-byte floating point | Reference | double * |
H | Unsigned 2-byte integer | Value | unsigned short int |
I | Signed 2-byte integer | Value | short int |
J | Signed 4 byte integer | Value | long int |
L | Logical | Reference | short int * |
M | Signed 2-byte integer | Reference | short int * |
N | Signed 4-byte integer | Referencelll | long int * |
V | void | void |
Table 1.
Example 1: We have a DLL in the C:\WINDOWS\SYSTEM directory
called MYDLL.DLL (DLLs do not necessarily need to be in the C:\WINDOWS\SYSTEM,
also on the path or in the Omnis folder).
Inside there is a function called 'testme', which returns a long int and
has two parameters. The first is a pointer to a character string, the
second is a short int. If we refer to table 1, the character code for
a long int is 'J'. The code for a character point is 'C'. The code for
a short int is 'I'.
The register DLL call would be:
Register DLL('MYDLL.DLL','testme','JCI')
Call DLL
Reversible: | NO | Flag affected: | NO |
Parameters: | Library name (of the DLL) Procedure name Type definition string Return field |
Syntax: | Call DLL (library-name, procedure-name) [,parameter1]...) [returns return-field] |
To have Omnis call the function in the DLL use Call DLL. The syntax
is as follows:
Call DLL(","[,parameter1]...)[with return value]
File Name and Function Name are the same used in the Register DLL call.
The optional parameters are a list of Omnis variables to be passed to
the function separated by commas.
Example 2. In example 1 a DLL was
registered, now it needs to be called. In Omnis we declare three variables.
RETURN is of type long integer. We will use RETURN to store the return
value of the DLL Function; P1, which is type character; and P2, which
is of type short integer (0-255). P1 and P2 will store the parameters
we will pass to the DLL function. Calculate P1 and P2 to contain the values
that need to be passed to the DLL function, if it is necessary.
WARNING: For Omnis versions 7.3.2
or lower, any character strings longer than 255 characters will be truncated
when they are passed.
Now all we do is call the DLL function like this:
Call DLL('MYDLL.DLL','testme',P1,P2) with return value RETURN
RETURN will now contain the function return value.