{{fbdoc item="title" value="BYREF (parameters)"}}----
Declaration specifier to explicitly pass a parameter by reference

{{fbdoc item="syntax"}}##
	**Byref** //param// [[KeyPgAs|as]] [[DataType|datatype]]
##
{{fbdoc item="usage"}}##
	[ [[KeyPgDeclare|declare]] ] { [[KeyPgSub|sub]] | [[KeyPgFunction|function]] } //proc_name// ( **Byref** //param// [[KeyPgAs|as]] [[DataType|datatype]]  )
##
{{fbdoc item="desc"}}
	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.

{{fbdoc item="ex"}}
{{fbdoc item="filename" value="examples/manual/procs/byref.bas"}}%%(freebasic)
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
%%

{{fbdoc item="lang"}}
	- 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.

{{fbdoc item="diff"}}
	- New to ""FreeBASIC""

{{fbdoc item="see"}}
	- [[ProPgPassingArguments|Passing Arguments to Procedures]]
	- ##[[KeyPgDeclare|Declare]]##
	- ##[[KeyPgByval|ByVal]]##
	- ##[[KeyPgByrefFunction|Byref (function results)]]##
	- ##[[KeyPgByrefVariables|Byref (variables)]]##

{{fbdoc item="back" value="CatPgProcedures|Procedures"}}