ADDHOSTS(3PVM)						       ADDHOSTS(3PVM)

NAME
  pvm_addhosts - Add hosts to the virtual machine.

SYNOPSIS
  C	  int info = pvm_addhosts( char	**hosts, int nhost, int	*infos )

  Fortran call pvmfaddhost( host, info )

PARAMETERS

  hosts	  An array of strings naming the hosts to be added.  Pvmd must
	  already be installed and the user must have an account on the
	  specified hosts.

  nhost	  Integer specifying the length	of array hosts.

  infos	  Integer array	of length nhost	which returns the status for each
	  host.	 Values	less than zero indicate	an error, while	positive
	  values are TIDs of the new hosts.

  host	  Character string naming the host to be added.

  info	  Integer status code returned by the routine.	Values less than
	  nhost	indicate partial failure, and values less than 1 indicate
	  total	failure.

DISCUSSION
  The routine pvm_addhosts adds	the computers named in hosts to	the confi-
  guration of computers	making up the virtual machine.	The names should have
  the same syntax as lines of a	pvmd hostfile (see man page for	pvmd3):	A
  hostname followed by options of the form xx=y.

  If pvm_addhosts is successful, info will be equal to nhost. Partial success
  is indicated by 0 < info < nhost, and	total failure by info <	1.  The	array
  infos	can be checked to determine which host caused the error.

  The Fortran routine pvmfaddhost adds a single	host to	the configuration
  with each call.  info	will be	1 if successful	or < 0 if error.

  The status of	hosts can be requested by the application using	pvm_mstat and
  pvm_config.  If a host fails it will be automatically	deleted	from the con-
  figuration.  Using pvm_addhosts a replacement	host can be added by the
  application, however it is the responsibility	of the application developer
  to make his application tolerant of host failure.  Another use of this
  feature would	be to add more hosts as	they become available, for example on
  a weekend, or	if the application dynamically determines it could use more
  computational	power.

EXAMPLES
  C:
	  static char *hosts[] = {
	      "sparky",
	      "thud.cs.utk.edu",
	  };
	  info = pvm_addhosts( hosts, 2, infos );

  Fortran:
	  CALL PVMFADDHOST( 'azure', INFO )

ERRORS
  The following	error conditions can be	returned by pvm_addhosts:
       PvmBadParam    giving an	invalid	argument value.
       PvmAlready     another task is currently	adding hosts.
       PvmSysErr      local pvmd is not	responding.

  and in the infos vector:
       PvmBadParam    bad hostname syntax.
       PvmNoHost      no such host.
       PvmCantStart   failed to	start pvmd on host.
       PvmDupHost     host already configured.
       PvmBadVersion  pvmd protocol versions don't match.
       PvmOutOfRes    PVM has run out of system	resources.

SEE ALSO
  pvm_pvmd3(1PVM), pvm_delhosts(3PVM), pvm_start_pvmd(3PVM),
  pvm_config(3PVM), pvm_mstat(3PVM)