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

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.

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)