Calling external C language functions

LotusScript® allows you to call external C language functions. You implement external C functions inside a named library module that generally contains several C functions. With Windows, this is a Dynamic Link Library (DLL). All Windows users have access to the libraries in the Windows application programming interface (API).

Note: The C functions that are in DLLs/shared libraries must be exported. Different platforms will have different rules and ways for exporting them.

To work with C functions, you need documentation that explains their input and output parameters, return values, and what operations they perform. The Windows Software Developer's Kit, for example, includes Windows API documentation. The Windows API is also documented in a variety of commercially available books.

To call C functions contained in an external library module from LotusScript®, use a Declare statement for external C calls for each function you want to call. To avoid declaring external library functions in multiple scripts, use Declare Public statements in a module which remains loaded.

The following table shows the convention that function calls from LotusScript® must use to external functions.

Platform

Calling convention

Windows 3.1

Pascal

Windows 95, Windows NT

STDCALL

UNIX

CDECL

Macintosh

CDECL

If you are using a C++ compiler, the name of any function becomes corrupted. Use the extern "C" {. . .} construct to keep the exact name intact.

If you are using Windows 95 or Windows NT, the name of an exported DLL function is case sensitive, although LotusScript® automatically converts the name to uppercase in the Declare statement. To successfully call an exported DLL, use the Alias clause in the Declare statement to specify the function name with correct capitalization. LotusScript® leaves the alias alone.

Note: The "_" is reserved for Notes-specific DLLs. This is a change effective as of Notes® 4.5.1. If you attempt to load a DLL in Notes® 4.51 or greater using LotusScript®, and the name of the DLL is preceded by an underscore, you will receive the error "Error in loading DLL."

Example

' The following statements declare an exported DLL with an 
'alias (preserving case sensitivity), and then call that 
'function.
Declare Function DirDLL Lib "C:\myxports.dll" _
   Alias "_HelpOut" (I1 As Long, I2 As Long)
DirDLL(5, 10)