{{fbdoc item="title" value="Passing Arguments to Procedures"}}----
Passing information to procedures.

{{fbdoc item="section" value="Declaring parameters"}}
	Procedures can get passed information in the form of variables and objects when they are called. In the context of a procedure call, these variables and objects are called arguments. These arguments are then represented as so-called parameters inside the procedure body. Parameters can be used just like any other variable or object.

	To specify that a procedure should get passed arguments when called, declare the procedure with a parameter list. A parameter list is a list of one or more names and types that the procedure will use when referring to the arguments that are passed to it. Parameter lists are surrounded by parenthesis.

{{fbdoc item="filename" value="examples/manual/proguide/procs/passargs.bas"}}%%(freebasic)
sub Procedure (s as string, n as integer)
	print "The parameters have the values: " & s & " and " & n
end sub

Procedure "abc", 123
%%
	will produce the following output:

%%
The parameters have the values: abc and 123
%%
	There are two ways to pass arguments to procedures: by value and by reference. By default, arguments are passed by value unless otherwise specified.

{{fbdoc item="section" value="Passing arguments by value"}}
	Arguments that are passed by value are not actually passed to procedures; a copy of the argument is made and passed instead. This allows the procedure to modify the copy, and the original variable or object remains unchanged.

	When passing objects to procedures by value, the copy is made by calling the copy constructor of the ##[[KeyPgType Type]]## or ##[[KeyPgClass Class]]##.

	To specify that an argument should be passed by value, precede the parameter name in the procedure declaration with the ##[[KeyPgByval Byval]]## keyword:

{{fbdoc item="filename" value="examples/manual/proguide/procs/passbyval.bas"}}%%(freebasic)
sub Procedure (byval param as integer)
	param *= 2
	print "The parameter 'param' = " & param
end sub

dim arg as integer = 10
print "The variable 'arg' before the call = " & arg
Procedure(arg)
print "The variable 'arg' after the call = " & arg
%%
	will produce the following output:

%%
The variable 'arg' before the call = 10
The parameter 'param' = 20
The variable 'arg' after the call = 10
%%
	Notice how parenthesis surround the arguments - in this case only one, ##//arg//## - in the procedure call. These parenthesis are optional, but are a common convention to signify a procedure call.

{{fbdoc item="section" value="Passing arguments by reference"}}
	Unlike arguments that are passed by value, arguments that are passed to procedures by reference really do get passed; no copy is made. This allows the procedure to modify the original variable or object that was passed to it.

	A reference is like an alias for a variable or object. Whenever you refer to a reference, you're referring to the actual variable or object that it aliases. In other words, you can think of a reference parameter of a procedure as the argument that is passed to it; any changes made to the reference parameter are actually changes to the argument it represents.

	To specify that an argument should be passed by reference, precede the parameter name in the procedure declaration with the ##[[KeyPgByref Byref]]## keyword:

{{fbdoc item="filename" value="examples/manual/proguide/procs/passbyref.bas"}}%%(freebasic)
sub Procedure (byref param as integer)
	param *= 2
	print "The parameter 'param' = " & param
end sub

dim arg as integer = 10
print "The variable 'arg' before the call = " & arg
Procedure(arg)
print "The variable 'arg' after the call = " & arg
%%
	will produce the following output:

%%
The variable 'arg' before the call = 10
The parameter 'param' = 20
The variable 'arg' after the call = 20
%%

{{fbdoc item="section" value="Manually passing pointers to by-reference parameters"}}
	By specifying the ##Byval## keyword in front of an argument to a ##[[KeyPgByref Byref]]## parameter, an address (usually stored in a pointer) can be passed directly as-is, forcing the ##Byref## parameter to reference the same memory location which the address pointed to.

{{fbdoc item="filename" value="examples/manual/proguide/procs/byrefparam-explicit-byval.bas"}}%%(freebasic)
sub f( byref i as integer )
	i = 456
end sub

dim i as integer = 123
dim pi as integer ptr = @i

print i
f( byval pi )
print i
%%

{{fbdoc item="see"}}
	- [[ProPgProcedures Procedures Overview]]
	- [[ProPgReturnValue Returning a Value]]
	- ##[[KeyPgDeclare Declare]]##
	- ##[[KeyPgSub Sub]]##
	- ##[[KeyPgFunction Function]]##
	- ##[[KeyPgByval Byval]]##
	- ##[[KeyPgByref Byref]]##

{{fbdoc item="back" value="CatPgProgrammer|Programmer's Guide"}}