{{fbdoc item="title" value="BYVAL"}}----
Declaration specifier to explicitly pass a parameter by value

{{fbdoc item="syntax"}}##
	**Byval** //param// [[KeyPgAs|as]] [[DataType|datatype]]
##
{{fbdoc item="usage"}}##
	[ [[KeyPgDeclare|declare]] ] { [[KeyPgSub|sub]] | [[KeyPgFunction|function]] } //proc_name// ( **Byval** //param// [[KeyPgAs|as]] [[DataType|datatype]]  )
##
{{fbdoc item="desc"}}
	##**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 ##[[KeyPgByref|Byref]]##, the value of the original variable //##x##// could be modified by the called function.
	
	Opposite of ##[[KeyPgByref|ByRef]]##.
	
	The ##**Byval**## keyword is also used in the context of ##Byref## [[KeyPgByref|parameters]] and [[KeyPgByrefFunction|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:
		- [[ProPgPassingArguments|Manually passing pointers to by-reference parameters]]
		- [[ProPgReturnValue|Manually returning pointers as-is from Byref functions]]
		

	**Note:** ##**Byval**## (passing by copy) is good for small objects (4 or 8 bytes, a bit more will still be ok) that are easy to copy, like numeric types. Passing ##**Byval**## avoids the overhead of the pointer used by ##[[KeyPgByref|ByRef]]##.
	##[[KeyPgByref|ByRef]]## is better for passing huge objects like strings or big UDTs that should not be copied. Even though ##[[KeyPgByref|ByRef]]## has some overhead because it has to pass a pointer (and dereference at each access to the object), this is still better than copying a multitude of bytes on to the stack every-time the procedure is called.

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

{{fbdoc item="lang"}}
	- In the //[[CompilerOptlang|-lang fb]]// dialect, ##**Byval**## is the default parameter passing convention for all built-in types except ##[[KeyPgString|String]]## and user-defined ##[[KeyPgType|Type]]## which are passed ##[[KeyPgByref|Byref]]## by default. The ##[[KeyPgZstring|Zstring]]## and ##[[KeyPgWstring|Wstring]]## built-in types are also passed ##[[KeyPgByref|Byref]]## by default, but passing ##**Byval**## is forbidden. Arrays are always passed ##[[KeyPgByref|Byref]]## and the use of the specifier ##[[KeyPgByref|Byref]]## or ##**Byval**## is forbidden.
	- In //[[CompilerOptlang|-lang qb]]// and //[[CompilerOptlang|-lang fblite]]// dialects, ##[[KeyPgByref|Byref]]## is the default parameter passing convention.

{{fbdoc item="diff"}}
	- QB only used ##**Byval**## in declarations to non-Basic subroutines

{{fbdoc item="see"}}
	- [[ProPgPassingArguments|Passing Arguments to Procedures]]
	- ##[[KeyPgDeclare|Declare]]##
	- ##[[KeyPgByref|ByRef]]##

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