ByVal in a parameter list of a declare statement causes a copy of the variable to be passed to the procedure (for example, a sub or function) by its value.
This means that if the value of the variable
x is passed, then the original variable
x will not be modified in any way; however, if the variable were passed
ByRef, the value of the original variable
x could be modified by the called function.
Note: For string arguments,
ByVal currently has a different meaning: instead of passing a copy of the string, it passes a
ZString pointer to the string data, while
ByRef passes a normal
String reference, i.e. a pointer to the FreeBASIC string descriptor. This behavior allows passing a
ByVal String directly to C procedures. The string passed this way should not be changed by the
Sub/
Function, as the string descriptor would not be updated. The meaning of passing a
String ByVal might change in the future; therefore, passing a
String ByVal should be avoided.
ZString is more suited for the purpose of passing zero-terminated strings to C functions.
Opposite of
ByRef.
The
ByVal keyword is also used in the context of
Byref Parameters and
Function Results, where it can be used to explicitly override the by-reference semantics in order to pass or assign a pointer as-is to a
Byref parameter or function result. For reference: