Parameters and Arguments

Identifiers that are used in the parameter list of a routine declaration are referred to as parameters.

A parameter declared in a routine can be referenced throughout the routine. Parameters are used to pass data between the calling program and the routine. The data supplied in a call, referred to as arguments, can affect the way in which the routine is executed.

The following rules apply to the parameter list of a routine call:

5. ROUTINES MARRC75KR07091E Rev H

• As part of the routine call, you must supply a data item, referred to as an argument, for each parameter in the routine declaration.

• An argument can be a variable, constant, or expression. There must be one argument corresponding to each parameter.

• Arguments must be of the same data type as the parameters to which they correspond, with three exceptions:

— An INTEGER argument can be passed to a REAL parameter. In this case, the INTEGER value is treated as type REAL, and the REAL equivalent of the INTEGER is passed by value to the routine.

— A BYTE or SHORT argument can be passed by value to an INTEGER or REAL parameter.

— Any positional types can be passed to any other positional type. If they are being passed to a user-defined routine, the argument positional type is converted and passed by value to the parameter type.

— ARRAY or STRING arguments of any length can be passed to parameters of the same data type.

Corresponding Parameters and Argumentsshows an example of a routine declaration and three calls to that routine.

Corresponding Parameters and Arguments PROGRAM params

VAR

long_string: STRING[10]; short_string: STRING[5]

exact_dist: REAL; rough_dist: INTEGER

ROUTINE label_dist (strg: STRING; dist: REAL) &

FROM procs_lib BEGIN

...

label_dist(long_string, exact_dist) --long_string corresponds to strg;

--exact_dist corresponds to dist label_dist(short_string, rough_dist)

--short_string, of a different length, --corresponds to strg; rough_dist, an --INTEGER, corresponds to REAL dist

label_dist('new distance', (exact_dist * .75)) --literal constant and REAL expression

--arguments correspond to the parameters END params

• When the routine is invoked, the argument used in the routine call is passed to the corresponding parameter. Two methods are used for passing arguments to parameters:

MARRC75KR07091E Rev H 5. ROUTINES

If an argument is passed by reference, the corresponding parameter shares the same memory location as the argument. Therefore, changing the value of the parameter changes the value of the corresponding argument.

— Passing Arguments By Value

If an argument is passed by value, a temporary copy of the argument is passed to the routine.

The corresponding parameter uses this temporary copy. Changing the parameter does not affect the original argument.

• Constant and expression arguments are always passed to the routine by value. Variables are normally passed by reference. The following variable arguments, however, are passed by value:

— Port array variables

— INTEGER variables passed to REAL parameters

— BYTE and SHORT arguments passed to INTEGER or REAL parameters

— System variables with read only (RO) access

— Positional parameters that need to be converted

• While variable arguments are normally passed by reference, you can pass them by value by enclosing the variable identifier in parentheses. The parentheses, in effect, turn the variable into an expression.

• PATH, FILE, and vision variables can not be passed by value. ARRAY elements (indexed form of an ARRAY variable) can be passed by value, but entire ARRAY variables cannot.

Passing Variable Argumentsshows a routine that affects the argument being passed to it differently depending on how the variable argument is passed.

Passing Variable Arguments PROGRAM reference

VAR arg : INTEGER

ROUTINE test(param : INTEGER) BEGIN

param = param * 3

WRITE ('value of param:', param, CR) END test

BEGIN arg = 5

test((arg)) --arg passed to param by value WRITE('value of arg:', arg, CR)

test(arg) --arg passed to param by reference WRITE('value of arg:', arg, CR)

END reference

The output from the program inPassing Variable Argumentsis as follows:

value of param: 15

5. ROUTINES MARRC75KR07091E Rev H

value of arg: 5 value of param: 15 value of arg: 15

If the routine calls fromPassing Variable Argumentswere made in reverse order, first passing arg by reference using "test(arg)" and then passing it by value using "test ((arg))," the output would be affected as follows:

value of param: 15 value of arg: 15 value of param: 45 value of arg: 15

• To pass a variable as a parameter to a KAREL routine you can use one of two methods:

— You can specify the name of the variable in the parameter list. For example,

other_rtn(param_var) passes the variable param_var to the routine other_rtn. To write this statement, you have to know the name of the variable to be passed.

— You can use BYNAME. The BYNAME feature allows a program to pass as a parameter to a routine a variable whose name is contained in a string. For example, if the string variables prog_name and var_name contain the name of a program and variable the operator has entered, this variable is passed to a routine using this syntax:

other_rtn(BYNAME(prog_name,var_name, entry)) Refer to Appendix A for more information about BYNAME.

• If a function routine returns an ARRAY, a call to this function cannot be used as an argument to another routine. If an incorrect pass is attempted, a translation error is detected.

Correct Passage of an ARRAYshows the correct use of an ARRAY passed between two function routines.

Correct Passage of an ARRAY PROGRAM correct

VAR a : ARRAY[8] of INTEGER

ROUTINE rtn_ary : ARRAY of INTEGER FROM util_prog ROUTINE print_ary(arg : ARRAY of INTEGER)

VAR i : INTEGER BEGIN

FOR i = 1 to ARRAY_LEN(arg) DO WRITE(arg[i],cr)

ENDFOR END print_ary BEGIN

MARRC75KR07091E Rev H 5. ROUTINES

END correct

Incorrect Passage of an ARRAYshows the incorrect use of an ARRAY passed between two function routines.

Incorrect Passage of an ARRAY PROGRAM wrong

ROUTINE rtn_ary : ARRAY of INTEGER FROM util_prog ROUTINE print_ary(arg : ARRAY of INTEGER)

VAR i : INTEGER BEGIN

FOR i = 1 to ARRAY_LEN(arg) DO WRITE(arg[i],cr)

See Also: ARRAY_LEN Built-In Function,Appendix A, STR_LEN Built-In Function,Appendix A,Appendix E, "Syntax Diagrams