SPAWN(3PVM)							  SPAWN(3PVM)

NAME
  pvm_spawn - Starts new PVM processes.

SYNOPSIS
  C	  int numt = pvm_spawn(	char *task, char **argv, int flag, char
  *where, int ntask, int *tids )

  Fortran call pvmfspawn( task,	flag, where, ntask, tids, numt )

PARAMETERS

  task	  Character string which is the	executable file	name of	the PVM	pro-
	  cess to be started.  The executable must already reside on the host
	  on which it is to be started.	 The name may be a file	in the PVM
	  search path or an absolute path.  The	default	PVM search path	is
	  $HOME/pvm3/bin/$PVM_ARCH/ .

  argv	  Pointer to an	array of arguments to the executable (if supported on
	  the target machine), not including the executable name, with the
	  end of the array specified by	NULL. argv[0] of the spawned task is
	  set to the executable	path relative to the PVM working directory
	  (or absolute if an absolute filename was specified).	If the exe-
	  cutable needs	no arguments, then the second argument to pvm_spawn
	  is NULL.

  flag	  Integer specifying spawn options.

	  In C,	flag should be the sum of:
	       Option value	   MEANING
	       PvmTaskDefault 0	   PVM can choose any machine to start task
	       PvmTaskHost    1	   where specifies a particular	host
	       PvmTaskArch    2	   where specifies a type of architecture
	       PvmTaskDebug   4	   Start up processes under debugger
	       PvmTaskTrace   8	   Processes will generate PVM trace data. *
	       PvmMppFront    16   Start process on MPP	front-end.
	       PvmHostCompl   32   Use complement host set

	  In Fortran, flag should be the sum of:
	       Option value	   MEANING
	       PVMDEFAULT     0	   PVM can choose any machine to start task
	       PVMHOST	      1	   where specifies a particular	host
	       PVMARCH	      2	   where specifies a type of architecture
	       PVMDEBUG	      4	   Start up processes under debugger
	       PVMTRACE	      8	   Processes will generate PVM trace data. *

	  * future extension

  where	  Character string specifying where to start the PVM process.
	  Depending on the value of flag, where	can be a host name such	as
	  ``ibm1.epm.ornl.gov''	or a PVM architecture class such as ``SUN4''.
	  If flag is 0,	then where is ignored and PVM will select the most
	  appropriate host.

  ntask	  Integer specifying the number	of copies of the executable to start.

  tids	  Integer array	of length ntask	returning the tids of the PVM
	  processes started by this pvm_spawn call.

  numt	  Integer returning the	actual number of tasks started.	 Values	less
	  than zero indicate a system error.  A	positive value less than
	  ntask	indicates a partial failure.  In this case the user should
	  check	the tids array for the error code(s).

DISCUSSION
  The routine pvm_spawn	starts ntask copies of the executable named task. On
  systems that support environment, spawn passes selected variables from
  parent environment to	children tasks.	 If set, the envar PVM_EXPORT is
  passed.  If PVM_EXPORT contains other	names (separated by ':') they will be
  passed too.  This is useful for e.g.:

       setenv DISPLAY myworkstation:0.0
       setenv MYSTERYVAR 13
       setenv PVM_EXPORT DISPLAY:MYSTERYVAR

  The hosts on which the PVM processes are started are determined by the flag
  and where arguments. On return the array tids	contains the PVM task iden-
  tifiers for each process started.

  If pvm_spawn starts one or more tasks, numt will be the actual number	of
  tasks	started.  If a system error occurs then	numt will be < 0.  If numt is
  less than ntask then some executables	have failed to start and the user
  should check the last	ntask -	numt locations in the tids array which will
  contain error	codes (see below for meaning).	The first numt tids in the
  array	are always valid.

  When flag is set to 0	and where is set to NULL (or ``*'' in Fortran) a
  heuristic (round-robin assignment) is	used to	distribute the ntask
  processes across the virtual machine.

  If the PvmHostCompl flag is set, the resulting host set gets complemented.
  Also,	the TaskHost hostname "." is taken as localhost.  These	can be used,
  for example, to spawn	n - 1 tasks on host "."	with flags TaskHost|HostCompl
  to get all but the localhost.

  In the special case where a multiprocessor is	specified by where, pvm_spawn
  will start all ntask copies on this single machine using the vendor's
  underlying routines.

  The spawned task will	have argv[0] set to the	the executable path relative
  to its inherited working directory (or possibly an absolute path), so	the
  base filename	can be got by using:
       char *p;
       p = (p =	rindex(argv[0],	'/')) ?	p + 1 :	argv[0];

  If PvmTaskDebug is set, then the pvmd	will start the task(s) under
  debugger(s). In this case, instead of	executing pvm3/bin/ARCH/task args it
  executes pvm3/lib/debugger pvm3/bin/ARCH/task	args.  debugger	is a shell
  script that the users	can modify to their individual tastes.	Presently the
  script starts	an xterm with dbx or comparable	debugger in it.

EXAMPLES
  C:
       numt = pvm_spawn( "host", 0, PvmTaskHost, "sparky", 1, &tid[0] );
       numt = pvm_spawn( "host", 0, (PvmTaskHost+PvmTaskDebug),
		      "sparky",	1, &tid[0] );
       numt = pvm_spawn( "node", 0, PvmTaskArch, "RIOS", 1, &tid[i] );

       char *args[] = {	"12", "60" , (char*)0 };
       numt = pvm_spawn( "FEM1", args, 0, 0, 16, tids );

       numt = pvm_spawn( "pde",	0, PvmTaskHost,	"paragon.ornl",	512, tids );

  Fortran:
       FLAG = PVMARCH +	PVMDEBUG
       CALL PVMFSPAWN( 'node', FLAG, 'SUN4', 1,	TID(3),	NUMT )
       CALL PVMFSPAWN( 'FEM1', PVMDEFAULT, '*',	16, TIDS, NUMT )
       CALL PVMFSPAWN( 'TBMD', PVMHOST,	'cm5.utk.edu', 32, TIDS, NUMT )

ERRORS
  These	error conditions can be	returned by pvm_spawn either in	numt or	in
  the tids array.
       PvmBadParam    giving an	invalid	argument value.
       PvmNoHost      Specified	host is	not in the virtual machine.
       PvmNoFile      Specified	executable cannot be found. The	default
		      location PVM looks in is ~/pvm3/bin/ARCH,
		      where ARCH is a PVM architecture name.
       PvmNoMem	      Malloc failed. Not enough	memory on host.
       PvmSysErr      pvmd not responding.
       PvmOutOfRes    out of resources.