VEC_$IGATHER16                    Domain/OS                     VEC_$IGATHER16


NAME
     vec_$igather16 - translate a 16-bit integer vector out of scattered form

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

     void vec_$igather16(
          short int *start_vec,
          long int *indices,
          long int &length,
          short int *result_vec)

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

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

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

           parameter (nvec = 10)

           integer*2 start_vec(nvec), result_vec(nvec)
           integer*4 indices(nvec), length
           call vec_$igather16(start_vec, indices, length, result_vec)

DESCRIPTION
     Vec_$igather16 translates its input arrays from dense form (two  arrays,
     one containing data, the other containing the corresponding index) into
     one sparse output vector.  Vec_$igather16 is the inverse operation of
     vec_$iscatter16.

     For instance, if passed the arrays start_vec [1, 20, -1, 5] and indices
     [4, 5, 2, 7], the first seven entries in the output vector produced by
     vec_$igather16 would be [0, -1, 0, 1, 20, 0, 5].

     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 start_vec[whatever was
     declared as the starting entry] in Pascal.


     start_vec
          The dense array.

     indices
          The array of indices for start_vec.

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

     result_vec
          The sparse array created by ordering start_vec as indicated by
          indices.

NOTES
     When vec_$igather16 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.

     Vec_$igather16, like all 16-bit integer routines, performs poorly when
     compared to the 32-bit integer routines.  Its use should be avoided wher-
     ever possible, especially on high-performance workstations.

SEE ALSO
     vec_$scatter, vec_$dgather, vec_$igather, vec_$gather.