@
 Pass-by-reference--unary                        (Special)
------------------------------------------------------------------------------
 Syntax

     @<idVar>

 Operands

     <idVar> is any valid CA-Clipper variable identifier, other than a
     database field or an array element, to pass by reference.  Database
     fields and array elements can only be passed by value.

 Description

     The pass-by-reference operator (@) passes variables by reference to
     functions or procedures invoked with function-calling syntax.  It is a
     unary prefix operator whose operand may be any variable name.

     Passing a variable by reference means that a reference to the value of
     the argument is passed instead of a copy of the value.  The receiving
     parameter then refers to the same location in memory as the argument.
     If the called routine changes the value of the receiving parameter, it
     also changes the argument passed from the calling routine.

     Passing a variable by value means that the argument is evaluated and its
     value is copied to the receiving parameter.  Changes to a receiving
     parameter are local to the called routine and lost when the routine
     terminates.  The default method of passing arguments is by value for all
     data types including references to arrays and objects.

 Examples

     .  This example demonstrates the difference between passing a
        user-defined function argument by reference and by value:

        LOCAL nNum := 1                     // Initial values

        LOCAL aArr := { "a", "b", "c" }
        //
        CLS
        // Print initial values
        ? VALTYPE(nNum), nNum
        ? VALTYPE(aArr), aArr[1], aArr[2], aArr[3]
        //
        Udf1(nNum)                          // Pass by value (default)
        ? VALTYPE(nNum), nNum               // Result:  N, 1
        //
        Udf1(aArr[1])                       // Pass by value (default)
        ? VALTYPE(aArr), aArr[1],;
              aArr[2], aArr[3]              // Result:  A, "a" "b" "c"
        //
        Udf2(aArr)                          // Pass a reference to
        ? VALTYPE(aArr), aArr[1],;          // the array (default)
              aArr[2], aArr[3]              // A, "Oi!" "b" "c"
        //
        Udf1(@nNum)                         // Force pass by reference
        ? VALTYPE(nNum), nNum               // Result:  N, 1000
        //
        Udf3(@aArr)                         // Pass array by reference
        ? VALTYPE(aArr)                     // Result:  N
        //
        RETURN NIL


        FUNCTION Udf1(nParam)               // Receive as a local
        ? nParam                            // parameter
        nParam := 1000
        ? nParam
        RETURN NIL
        //
        FUNCTION Udf2( aParam )             // Receive as a local
        ? VALTYPE(aParam), aParam[1]        // parameter
        aParam[1] := "Oi!"
        ? aParam[1]
        RETURN NIL
        //
        FUNCTION Udf3(aParam)               // Receive as a local
        ? VALTYPE(aParam), aParam[1]        // parameter
        aParam := 1000
        ? aParam
        RETURN NIL