LOTUSSCRIPT LANGUAGE

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.
PlatformCalling convention
Windows 3.1Pascal
Windows 95, Windows NTSTDCALL
OS/2_System
UNIXCDECL
MacintoshCDECL
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)

See Also