LOTUSSCRIPT LANGUAGE

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 typeHow it is passed to a C function
StringA 4-byte pointer to the string in the platform-native character set format
Product object

(including a collection)

A 4-byte product object handle
ArrayA 4-byte pointer to the array stored in the LotusScript internal array format
TypeA 4-byte pointer to the data in the type instance (This may include strings as elements)
User-defined objectA 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.


The C routine cannot change this value, even if the C routine defines the argument as passed by reference.
Data typeKeyword How it is passed to a C function
BooleanA 2-byte Integer, of value 0 or -1, is pushed on the call stack.
ByteA 1-byte Integer value is pushed on the call stack.
IntegerA 2-byte Integer value is pushed on the call stack.
LongA 4-byte Long value is pushed on the call stack.
SingleA 4-byte Single value is pushed on the call stack.
DoubleAn 8-byte Double value is pushed on the call stack.
CurrencyAn 8-byte value, in the LotusScript internal Currency format, is pushed on the call stack.
StringA 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.

VariantA 16-byte structure, in the LotusScript format for Variants, is pushed on the call stack.
Product objectA 4-byte product object handle is pushed on the call stack.
AnyThe 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.

See Also