GATHER(3PVM)							  PVM Version 3.4						      GATHER(3PVM)

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  ini-
       tial 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)