ByVal
 
Declaration specifier to explicitly pass a parameter by value

Syntax

ByVal param As datatype

Usage

[ Declare ] { Sub | Function } proc_name ( ByVal param As datatype )

Description

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.

Example

Sub MySub(ByVal value As Integer)
    value += 1
End Sub

Dim MyVar As Integer

MyVar = 1
Print "MyVar: "; MyVar 'output = 1
MySub MyVar
Print "MyVar: "; MyVar 'output = 1, because byval won't change the values passed into it globally.
Sleep
End


Dialect Differences

  • In the -lang fb dialect, ByVal is the default parameter passing convention for all built-in types except String and user-defined Type which are passed ByRef by default.
  • In -lang qb and -lang fblite dialects, ByRef is the default parameter passing convention.

Differences from QB

  • QB only used ByVal in declarations to non-Basic subroutines

See also