Declare statement (external C calls) (LotusScript® Language)

Note the Declare statement (external C calls) is not supported under OS/2.

Syntax

Declare [ Public | Private ] { Function | Sub } LSname Lib libName [ Alias aliasName ] ( [ argList ] ) [ As returnType ]

Elements

Public | Private

Optional. Public indicates that the declared C function is visible outside this module, for as long as the module is loaded. Private indicates that the declared C function is visible only within this module.

A declared C function is Private by default.

Function | Sub

Specifies that the C function is to be called as either a function or a sub.

LSname

The function or sub name used within LotusScript®. If you omit the Alias clause, this name must match the name declared in the shared library.

If the statement is declaring a Function (using the keyword Function), then you can append a data type suffix character to LSname, to declare the type of the function's return value.

libName

A literal string, or a string constant, specifying the shared library file name. The file name extension is optional. You can optionally include a complete path specification. LotusScript® automatically converts libName to uppercase. If you need to preserve case sensitivity, use the aliasName described as follows.

aliasName

Optional. A literal string containing one of the following:

• A case-sensitive C function name as declared in the shared library
• A pound sign (#) followed by an ordinal number representing the position of the function in the library; for example, "#1"

This argument is useful when the C function name is not a valid LotusScript® name, or when you need to preserve case sensitivity (for example, when calling an exported library function in a 32-bit version of Windows™).

argList

Optional. An argument list for the external function. Parentheses enclosing the list are required, even if the C function takes no arguments.

argList has the form:

argument [, argument ] ...

where argument is:

[ ByVal ] name As [ LMBCS | Unicode ] [ dataType | Any ]

The optional LMBCS and Unicode keywords may be used with the String data type only, to specify the character set. See the usage information and examples that follow.

Use the keyword Any to pass an argument to a C function without specifying a data type, suppressing type checking.

returnType

The data type of the function's return value. The clause As returnType is not allowed for a sub, since a sub doesn't return a value.

For a function, either specify As returnType, or append a data type suffix character to LSname, todeclare the data type of the function's return value. Do not specify both a returnType and a data type suffix character.

You can't use Any as a returnType.

You can't use Variant, Currency, or fixed-length String as a returnType.

If you omit As returnType and the function name has no data type suffix character appended, the function returns a value of the data type specified by a Deftype statement that applies to the function name. A C function can't return a Variant; so a DefVar statement can't apply to the function name.

returnType has the form:

[ LMBCS | Unicode ] dataType

The dataType must match the C function return type exactly; no conversion is performed on the return value.

The optional LMBCS and Unicode keywords may be used with the String data type only, to specify the character set. See the usage information and examples that follow.

Usage

The Public keyword cannot be used in a product object script or %Include file in a product object script, except to declare class members. You must put such Public declarations in (Globals).

You can only declare external functions at the module level. If a function is not typed with a return type or a data type suffix character, LotusScript® generates an error.

The "_" is reserved for Notes® specific DLLs. This is a change put in 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".

Passing arguments

By default, LotusScript® passes arguments to external functions by reference. Arguments can be passed by value using the ByVal keyword, but only if LotusScript® can convert the value passed to the data type of the corresponding C function argument.

Arrays, type variables, and user-defined objects must be passed by reference.

You can't pass lists as arguments to C functions.

You can't use a fixed-length String as an argument.

Product objects can be passed by reference (passing a reference to the instance handle) or by value (passing the instance handle itself). They can be passed by value only by using the keyword ByVal. Parentheses can't be used on the actual argument.

An argument can be typed as Any to avoid data type restrictions. Arguments of type Any are always passed by reference, regardless of the type of data they contain. You can pass a Variant containing an array or list to a C function argument declared as Any.

Using LMBCS or Unicode strings

Use the optional keywords LMBCS and Unicode with a String argument or returnType to specify the character set.

Unicode designates a Unicode string of two-byte characters (words) using the platform-native byte order.

LMBCS designates a LMBCS optimization group 1 string (multibyte characters).

If neither LMBCS nor Unicode is specified, the string variable uses the platform-native character set.

Calling exported library functions in 32-bit versions of Windows™

If you're using a 32-bit version of Windows™, the names of exported library functions are case sensitive; however, LotusScript® automatically converts them to uppercase in the Declare statement. To successfully call an exported library function, use the Alias clause to specify the function name with correct capitalization (LotusScript® leaves the alias alone).

Example