Register DLL

Command group Flag affected Reversible Execute on client Platform(s)
External commands YES NO NO Windows

Syntax

Register DLL (library, procedure, type-definition [,unregister {Default kFalse}]) Returns err-code

Description

Note: The flag is set according to whether Omnis was able to make a call to this external command.

This command registers a procedure in a DLL, so that you can use Call DLL to call it.

The library is the name or pathname of the DLL containing the procedure specified by procedure. If you do not specify a pathname for the library then the standard operating system search rules for DLLs will apply.

The type-definition specifies the data types of the return value and parameters required by procedure.  type-definition is a character string:

   The first character identifies the data type of the return value of the procedure

   The remaining characters (one for each parameter) identify the parameter data types

Register and Call DLL commands support 64-bit type specifiers. The following table lists the possible data type characters:

Character Description Pass By C declaration
A Logical Value short int
B IEEE 8 byte floating point Value double
C Null-terminated string Value TCHAR *
D Pascal string Value TCHAR *
E IEEE 8 byte floating point Reference double *
H Unsigned 16 bit integer Value unsigned short int
I Signed 16 bit integer Value short int
J Signed 32 bit integer Value long int
L Logical Reference short int *
M Signed 16 bit integer Reference short int *
N Signed 32 bit integer Reference long int *
O Null-terminated 8-bit string: Encoded as Ansi on Win32, MacRoman on macOS, ISO-8859-1 on Linux Value char *
P Signed integer of pointer size for the current architecture (32 or 64 bit) value Intptr_t
Q Signed integer of pointer size for the current architecture (32 or 64 bit) Reference Intptr_t *
R Signed 64-bit integer Value Int64_t
S Signed 64-bit integer Reference Int64_t *
V void (use if no return value) void
Z Cannot be used as a return value data type. When passing the parameter, behaves like data type C. Use Z to indicate that the procedure sets the parameter to a sequence of null-terminated strings,terminated by an additional null character. Call DLL sets the parameter to the same sequence of strings,using carriage returns instead of null terminators Value char *

Note that TCHAR represents the character type used for operating system API calls - for Windows it is 16 bit unsigned short.

When you have finished using the procedure, you may wish to unregister the procedure; this allows Omnis to unload the DLL containing the procedure. To do this, pass the unregister parameter as kTrue. Note that the DLL will remain loaded until all the registered procedures in the DLL have been unregistered; also, if the DLL is loaded into the Omnis process for another reason e.g. the DLL is linked with the Omnis executable, then it will remain loaded even after the last procedure has been unregistered.

Example

# Flash the Omnis window to attract the user's attention
# Win32 API to get the main Omnis window: HWND GetActiveWindow(VOID) 
Register DLL ('USER32.DLL','GetActiveWindow','J')
Call DLL ('USER32.DLL','GetActiveWindow') Returns lHWND
# Win32 API to Flash a window: BOOL FlashWindow(HWND, BOOL) 
Register DLL ('USER32.DLL','FlashWindow','JJJ')
Call DLL ('USER32.DLL','FlashWindow',lHWND,1) Returns lResult

This example creates a file and loads the contents:

Register DLL ("KERNEL32.DLL","CreateFileA","JCJJJJJJ")
Register DLL ("KERNEL32.DLL","CloseHandle","JJ")
Register DLL ("KERNEL32.DLL","ReadFile","J,J,C32768,J,N,J")
Call DLL ("KERNEL32.DLL","CreateFileA","c:\MYBIGFILE.TXT",-1073741824,3,0,3,268435584,0) Returns #1
Call DLL ("KERNEL32.DLL","ReadFile",#1,#S1,32767,#49,0) Returns #50
Call DLL ("KERNEL32.DLL","CloseHandle",#1) Returns #50
Calculate #1 as  binlength(#S1)