#### 16.4.4 The `CALL` Command ¶

A matrix function returns a single result. The `CALL` command implements procedures, which take a similar syntactic form to functions but yield results by modifying their arguments rather than returning a value.

Output arguments to a `CALL` procedure must be a single variable name.

The following procedures are implemented via `CALL` to allow them to return multiple results. For these procedures, the output arguments need not name existing variables; if they do, then their previous values are replaced:

`CALL EIGEN(M, evec, eval)`

  Computes the eigenvalues and eigenvector of symmetric n×n matrix M. Assigns the eigenvectors of M to the columns of n×n matrix evec and the eigenvalues in descending order to n-element column vector eval.

  Use the `EVAL` function (see EVAL) to compute just the eigenvalues of a symmetric matrix.

  For example, the following matrix language commands:

      CALL EIGEN({1, 0; 0, 1}, evec, eval).
      PRINT evec.
      PRINT eval.

      CALL EIGEN({3, 2, 4; 2, 0, 2; 4, 2, 3}, evec2, eval2).
      PRINT evec2.
      PRINT eval2.

  yield this output:

      evec
        1  0
        0  1

      eval
        1
        1

      evec2
        -.6666666667   .0000000000   .7453559925
        -.3333333333  -.8944271910  -.2981423970
        -.6666666667   .4472135955  -.5962847940

      eval2
        8.0000000000
       -1.0000000000
       -1.0000000000

`CALL SVD(M, U, S, V)`

  Computes the singular value decomposition of n×k matrix M, assigning S a n×k diagonal matrix and to U and V unitary k×k matrices such that M = U×S×V^T. The main diagonal of Q contains the singular values of M.

  Use the `SVAL` function (see SVAL) to compute just the singular values of a matrix.

  For example, the following matrix program:

      CALL SVD({3, 2, 2; 2, 3, -2}, u, s, v).
      PRINT (u * s * T(v))/FORMAT F5.1.

  yields this output:

      (u * s * T(v))
         3.0   2.0   2.0
         2.0   3.0  -2.0

The final procedure is implemented via `CALL` to allow it to modify a matrix instead of returning a modified version. For this procedure, the output argument must name an existing variable.

`CALL SETDIAG(M, V)`

  Replaces the main diagonal of n×p matrix M by the contents of k-element vector V. If k = 1, so that V is a scalar, replaces all of the diagonal elements of M by V. If k < \min(n,p), only the upper k diagonal elements are replaced; if k > \min(n,p), then the extra elements of V are ignored.

  Use the `MDIAG` function (see MDIAG) to construct a new matrix with a specified main diagonal.

  For example, this matrix program:

      COMPUTE x={1, 2, 3; 4, 5, 6; 7, 8, 9}.
      CALL SETDIAG(x, 10).
      PRINT x.

  outputs the following:

      x
        10   2   3
         4  10   6
         7   8  10