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:

([Parm1,[Parm2]É)

<Function code>

{

return(<Return Type>);

}

The Return Type is the data type of the value that the function returns after execution. It can be an
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.