NAME

       pvm_scatter  -  Sends  to  each  member  of a group a section of an array from a specified
       member of the group.

SYNOPSIS

       C    int info = pvm_scatter( void *result, void *data,
                         int count, int datatype, int msgtag,
                         char *group, int rootginst)

       Fortran    call pvmfscatter(result, data, count, datatype,
                                  msgtag, group, rootginst, info)

PARAMETERS

       result  Pointer to the starting address of an array of length count of datatype which will
               be overwritten by the message from the specified root member of the group.

       data    On  the  root  this  is  a pointer to the starting address of an array datatype of
               local values which are to be distributed to the members of the group.  If n is the
               number of members in the group, then this array of datatype should be of length at
               least n*count.  This argument is meaningful only on the root.

       count   Integer specifying the number of elements of datatype to be sent to each member of
               the group from the root.

       datatype
               Integer  specifying  the  type of the entries in the result and data arrays.  (See
               below for defined types.)

       msgtag  Integer message tag supplied by the user.  msgtag should be >= 0.  It  allows  the
               user's program to distinguish between different kinds of messages.

       group   Character string group name of an existing group.

       rootginst
               Integer  instance  number of group member who performs the scatter of its array to
               the members of the group.

       info    Integer status code returned by the routine.  Values less than  zero  indicate  an
               error.

DESCRIPTION

       pvm_scatter()  performs  a  scatter of data from the specified root member of the group to
       each of the members  of  the  group,  including  itself.   All  group  members  must  call
       pvm_scatter(),  each  receives  a  portion  of the data array from the root in their local
       result array.  It is as if the root node sends to  the  ith  member  of  the  group  count
       elements  from  its  array  data starting at offset i*count from the beginning of the data
       array.  And, it is as if, each member of the group performs  a  corresponding  receive  of
       count  values  of  datatype  into  its  result  array.  The root task is identified by its
       instance number in the group.

       C and Fortran defined datatypes are:
                  C datatypes   FORTRAN datatypes
                -----------------------------------
                  PVM_BYTE       BYTE1
                  PVM_SHORT      INTEGER2
                  PVM_INT        INTEGER4
                  PVM_FLOAT      REAL4
                  PVM_CPLX       COMPLEX8
                  PVM_DOUBLE     REAL8
                  PVM_DCPLX      COMPLEX16
                  PVM_LONG

       In using the scatter and gather routines, keep in  mind  that  C  stores  multidimensional
       arrays  in  row  order,  typically  starting  with an initial index of 0; whereas, Fortran
       stores arrays in column order, typically starting with an offset of 1.

       The current algorithm is very simple and robust.  A future implementation  may  make  more
       efficient use of the architecture to allow greater parallelism.

EXAMPLES

       C:
          info =  pvm_scatter(&getmyrow, &matrix, 10, PVM_INT,
                             msgtag, "workers", rootginst);

       Fortran:
          CALL PVMFSCATTER(GETMYCOLUMN, MATRIX, COUNT, INTEGER4,
         &                MTAG, 'workers', ROOT, INFO)

ERRORS

       These error conditions can be returned by pvm_scatter

       PvmNoInst
              Calling task is not in the group

       PvmBadParam
              The datatype specified is not appropriate

       PvmSysErr
              Pvm system error

SEE ALSO

       pvm_bcast(3PVM), pvm_barrier(3PVM), pvm_psend(3PVM)

                                          21 April, 1994                            SCATTER(3PVM)