Calling User-defined Functions
==============================

   "Calling a function" means causing the function to run and do its
job.  A function call is an expression, and its value is the value
returned by the function.

   A function call consists of the function name followed by the
arguments in parentheses.  What you write in the call for the arguments
are `awk' expressions; each time the call is executed, these
expressions are evaluated, and the values are the actual arguments.  For
example, here is a call to `foo' with three arguments (the first being
a string concatenation):

     foo(x y, "lose", 4 * z)

     *Caution:* whitespace characters (spaces and tabs) are not allowed
     between the function name and the open-parenthesis of the argument
     list.  If you write whitespace by mistake, `awk' might think that
     you mean to concatenate a variable with an expression in
     parentheses.  However, it notices that you used a function name
     and not a variable name, and reports an error.

   When a function is called, it is given a *copy* of the values of its
arguments.  This is called "call by value".  The caller may use a
variable as the expression for the argument, but the called function
does not know this: it only knows what value the argument had.  For
example, if you write this code:

     foo = "bar"
     z = myfunc(foo)

then you should not think of the argument to `myfunc' as being "the
variable `foo'."  Instead, think of the argument as the string value,
`"bar"'.

   If the function `myfunc' alters the values of its local variables,
this has no effect on any other variables.  In particular, if `myfunc'
does this:

     function myfunc (win) {
       print win
       win = "zzz"
       print win
     }

to change its first argument variable `win', this *does not* change the
value of `foo' in the caller.  The role of `foo' in calling `myfunc'
ended when its value, `"bar"', was computed.  If `win' also exists
outside of `myfunc', the function body cannot alter this outer value,
because it is shadowed during the execution of `myfunc' and cannot be
seen or changed from there.

   However, when arrays are the parameters to functions, they are *not*
copied.  Instead, the array itself is made available for direct
manipulation by the function.  This is usually called "call by
reference".  Changes made to an array parameter inside the body of a
function *are* visible outside that function.  This can be *very*
dangerous if you do not watch what you are doing.  For example:

     function changeit (array, ind, nvalue) {
          array[ind] = nvalue
     }
     
     BEGIN {
                a[1] = 1 ; a[2] = 2 ; a[3] = 3
                changeit(a, 2, "two")
                printf "a[1] = %s, a[2] = %s, a[3] = %s\n", a[1], a[2], a[3]
           }

prints `a[1] = 1, a[2] = two, a[3] = 3', because calling `changeit'
stores `"two"' in the second element of `a'.