Passing arguments to C functions

By default, LotusScript® passes arguments to functions and subs by reference. If the argument is an array, a user-defined data type variable, or an object reference variable, you must pass it by reference. In most other cases, you use the ByVal keyword to pass variables by value.

Passing arguments by reference

When an argument is passed by reference, the C function receives a 4-byte pointer to the value area.

In some cases, the actual stack argument is changed to a publicly readable structure. In all cases, the data may be changed by the called function, and the changed value is reflected in LotusScript® variables and in the properties of product objects. For such properties, this change occurs directly after the call has returned.


Data type	How it is passed to a C function
String	A 4-byte pointer to the string in the platform-native character set format
Product object (including a collection)	A 4-byte product object handle
Array	A 4-byte pointer to the array stored in the LotusScript® internal array format
Type	A 4-byte pointer to the data in the type instance (This may include strings as elements)
User-defined object	A 4-byte pointer to the data in the object (this data may include strings, arrays, lists, product objects, etc., as elements)

Note: Lists cannot be passed by reference. They also cannot be passed by value. Using a list as an argument produces a run-time error.

Passing arguments by value

When an argument is passed by value, the C function receives a copy of the actual value of the argument.

To specify that the argument should always be passed by value, use the keyword ByVal preceding the parameter declaration for that argument in the Declare statement for the C function.
To specify that the argument should be passed by value in a particular call to the function, use parentheses around the argument in the call.

The C routine cannot change this value, even if the C routine defines the argument as passed by reference.


Data type	Keyword	How it is passed to a C function
Boolean		A 2-byte Integer, of value 0 or -1, is pushed on the call stack.
Byte		A 1-byte Integer value is pushed on the call stack.
Integer		A 2-byte Integer value is pushed on the call stack.
Long		A 4-byte Long value is pushed on the call stack.
Single		A 4-byte Single value is pushed on the call stack.
Double		An 8-byte Double value is pushed on the call stack.
Currency		An 8-byte value, in the LotusScript® internal Currency format, is pushed on the call stack.
String		A 4-byte pointer to the characters is pushed on the call stack. The C function should not write to memory beyond the end of the string. If the call is made with a variable, changes to the string by the C function are reflected in the variable. This is not true for a string argument to a LotusScript® function declared as ByVal.
Variant		A 16-byte structure, in the LotusScript® format for Variants, is pushed on the call stack.
Product object		A 4-byte product object handle is pushed on the call stack.
Any		The number of bytes of data in the argument is pushed on the call stack. For example, the argument contains a Long value, then the called function receives 4 bytes. The function may receive a different number of bytes at run time.

No other data types--arrays, lists, fixed-length strings, types, classes, or voids--can be passed by value. It is a run-time error to use these types as arguments.

Any of the data types that can be passed by value can also be passed by reference.

The argument ByVal 0& specifies a null pointer to a C function, when the argument is declared as Any.

Example

Declare Sub SemiCopy Lib "mylib.dll" _
   (valPtr As Long, ByVal iVal As Long)
Dim vTestA As Long, vTestB As Long
vTestA = 1
vTestB = 2

SemiCopy vTestA, vTestB
' The C function named SemiCopy receives a 4-byte pointer to a 
' 2-byte integer containing the value of vTestA, and a 2-byte 
' integer containing the value of vTestB.
' Since vTestA is passed by reference, SemiCopy can dereference 
' the 4-byte pointer and assign any 2-byte integer to that 
' location. When control returns to LotusScript, vTestA 
' contains the modified value. Since vTestB was passed by 
' value, any changes made by the C function are not reflected 
' in vTestB after the function call.