Provided by: pvm-dev_3.4.6-5_amd64 bug

NAME

       pvm_gather  -  A  specified  member of the group receives messages from each member of the
       group and gathers these messages into a single array.

SYNOPSIS

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

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

PARAMETERS

       result  On the root this is a pointer to the starting address  of  an  array  datatype  of
               local  values  which are to be accumulated from the members of the group.  If n if
               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.

       data    For  each  group  member  this is a pointer to the starting address of an array of
               length count of datatype which will be sent to the specified root  member  of  the
               group.

       count   Integer specifying the number of elements of datatype to be sent by each member of
               the group to 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 gather  of  the  messages
               from the members of the group.

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

DESCRIPTION

       pvm_gather() performs a send of messages from each member of the group  to  the  specified
       root  member of the group.  All group members must call pvm_gather(), each sends its array
       data of length count of datatype to the root which accumulates  these  messages  into  its
       result  array.   It  is  as  if  the root receives count elements of datatype from the ith
       member of the group and places these values in  its  result  array  starting  with  offset
       i*count  from  the  beginning  of  the  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.

       Note: pvm_gather() does not block.   If a task calls pvm_gather and then leaves the  group
       before the root has called pvm_gather an error may occur.

       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_gather(&getmatrix, &myrow, 10, PVM_INT,
                             msgtag, "workers", rootginst);

       Fortran:
          CALL PVMFGATHER(GETMATRIX, MYCOLUMN, COUNT, INTEGER4,
         &                MTAG, 'workers', ROOT, INFO)

ERRORS

       These error conditions can be returned by pvm_gather

       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                             GATHER(3PVM)