Passing Function Arguments by Reference

Format

function FunctionName(numeric function_variable)
function_variable = 500;
end;

// using ref, any changes made to function_variable
// in the function will be assigned to MY_VALUE
FunctionName(ref MY_VALUE);

Description

By default, numeric and string variables that are passed as an argument to a function are not changed by actions within the function. This is called "pass by value." On the other hand, objects (such as arrays and file handlers) passed as arguments refer to the source variable and interactions on the variable within the function affect the source variable. This is called "pass by reference."

If you want to pass a numeric or string variable by reference, you can use the ref keyword to signify that changes made in the function should affect the source variable. You cannot use ref with expressions, only with numeric and string variables (such as dictionary items, array cells, list cells, etc.).

Example 1

function MyFunc(numeric numeric_value)
numeric_value = 999;
end;

// ...

numeric test_value = 100;

// the value of test_value (100) is passed (copied) to the function
// and the function has no effect on the contents of test_value
MyFunc(test_value);
errmsg("%d", test_value); // pass by value, prints 100

// by reference (ref) indicates the variable location itself is passed
// to the function; performing any operation on the variable inside the
// function is the same as performing that operation outside of the function
MyFunc(ref test_value);
errmsg("%d", test_value); // pass by reference, prints 999

Example 2

function numeric ReadGPS(optional numeric latitude, optional numeric longitude)

numeric successful_reading = false;

if gps(open) then

// attempt to read the GPS for up to two minutes
if gps(read, 120) then
successful_reading = true;
latitude = gps(latitude);
longitude = gps(longitude);
endif;

gps(close);

endif;

exit successful_reading;

end;

// ...

// because HH_LATITUDE and HH_LONGITUDE are passed by reference (ref),
// they will contain the values as updated in the function
if not ReadGps(ref HH_LATITUDE, ref HH_LONGITUDE) then
errmsg("GPS reading error");
endif;