Byref (Parameters)

Declaration specifier to explicitly pass a parameter by reference

Syntax
	ByRef param KeyPgAsAs DataTypedatatype

Usage
	[ KeyPgDeclareDeclare ] { KeyPgSubSub | KeyPgFunctionFunction } proc_name ( ByRef param KeyPgAsAs DataTypedatatype  )

Description
	Passes a variable by reference, that is its address, to a subroutine or 
	function. When a variable is passed by reference, the contents of the 
	variable can be changed by the target subroutine or function.

	In CompilerOptlang-lang qb and CompilerOptlang-lang fblite dialects, ByRef is the default parameter 
	passing convention, unless KeyPgOptionbyvalOption ByVal is in effect.

	Opposite of KeyPgByvalByVal.

	Note: A constant or a literal expression can also be passed to such a 
	procedure (which gets by reference), but they are obviously not 
	modifiable from the procedure body. In that case, the compiler passes by 
	reference a temporary variable initialized with the constant or the 
	literal expression.

	Note: Since fbc version 1.20.0, arguments of STRING*N type are copied to 
	a temporary variable when passed to BYREF ZSTRING (or BYVAL ZSTRING PTR) 
	parameters (since there is no expectation that STRING*N will have it's 
	own terminating null character) and copied back after the call.

	Warning: When passing by reference, it is recommended to pass an 
	argument of the same type (or fully compatible, like a derived type for 
	example) as that of the declared parameter. Although in some cases the 
	compiler accepts to pass a different type, often the result is not the 
	one expected.

Example
	Dim MyVar As Integer

	Sub ChangeVar(ByRef AVar As Integer)
	   AVar = AVar + 1
	End Sub

	MyVar = 1
	Print "MyVar: "; MyVar 'output = 1
	ChangeVar MyVar
	Print "MyVar: "; MyVar 'output = 2
	Sleep
	End

Dialect Differences
	* In CompilerOptlang-lang fb dialect, KeyPgByvalByVal is the default parameter passing 
	  convention for all built-in types except KeyPgStringString and user-defined KeyPgTypeType 
	  which are passed ByRef by default. The KeyPgZstringZString and KeyPgWstringWString built-in 
	  types are also passed ByRef by default, but passing KeyPgByvalByVal is 
	  forbidden. Arrays are always passed ByRef and the use of the specifier 
	  ByRef or KeyPgByvalByVal is forbidden.
	* In CompilerOptlang-lang qb and CompilerOptlang-lang fblite dialects, ByRef is the default parameter 
	  passing convention.

Differences from QB
	* New to FreeBASIC

See also
	* ProPgPassingArgumentsPassing Arguments to Procedures
	* KeyPgDeclareDeclare
	* KeyPgByvalByVal
	* KeyPgByrefFunctionByref (Function Results)
	* KeyPgByrefVariablesByref (Variables)

