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

DISCUSSION
  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 mul-
  tidimensional	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 parallel-
  ism.

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)