VEC_$SCATTER                      Domain/OS                       VEC_$SCATTER


NAME
     vec_$scatter - translate a vector into scattered form

SYNOPSIS (C)
     #include <apollo/base.h>
     #include <apollo/vec.h>

     void vec_$scatter(
          float *start_vec,
          long int *indices,
          long int &length,
          float *result_vec)

SYNOPSIS (Pascal)
     %include '/sys/ins/base.ins.pas';
     %include '/sys/ins/vec.ins.pas';

     procedure vec_$scatter(
          in start_vec: univ vec_$real_vector;
          in indices: univ vec_$integer32_vector;
          in length: integer32;
          out result_vec: univ vec_$real_vector);

SYNOPSIS (FORTRAN)
     %include '/sys/ins/base.ins.ftn'
     %include '/sys/ins/vec.ins.ftn'

           parameter (nvec = 10)

           real start_vec(nvec), result_vec(nvec)
           integer*4 indices(nvec), length
           call vec_$scatter(start_vec, indices, length, result_vec)

DESCRIPTION
     Vec_$scatter translates its input arrays from sparse form (all entries
     are consecutively numbered, and entries of zero may be present) into
     dense form (two arrays, one containing non-zero data, the other contain-
     ing the corresponding array index). Vec_$gather is the inverse operation
     of vec_$scatter.

     For instance, if passed the array start_vec containing seven entries [0,
     -1, 20, 0, 30, 0, 7], vec_$scatter would produce an indices array con-
     taining [2, 3, 5, 7] and a result_vec containing [-1, 20, 30, 7].

     The index array contains 32-bit integers.  The individual entries are
     calculated relative to an array beginning of 1.  That is, an entry of 1
     in indices denotes the first element in the array, which is referred to
     as start_vec[0] in C, start_vec(1) in FORTRAN, and as start_vec[whatever
     was declared as the starting entry] in Pascal.


     start_vec
          The sparse array.

     indices
          The array of indices into result_vec.

     length
          The number of elements to be operated on;  normally the same as the
          number of elements in the vectors.

     result_vec
          The scattered array corresponding to start_vec.

NOTES
     When vec_$scatter is used to operate on matrixes in C and Pascal,
     start_vec and result_vec are row vectors; in FORTRAN, they are column
     vectors.

     As in all the vec_$ calls,  the result array must not overlap any of the
     input arrays; the result array may be identical to an input, but must not
     contain any subset of it.   Because of pipelining, using overlapping
     input and output arrays may cause incorrect results.


SEE ALSO
     vec_$gather, vec_$dscatter, vec_$iscatter, vec_$iscatter16.