SCATTER(3PVM)							SCATTER(3PVM)

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 speci-
	  fied 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.

DISCUSSION
  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 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.

  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_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)