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 containing the executable file name of the PVM process to be started. The executable must already reside on the host on which it is to be started. The default location PVM looks in is $HOME/pvm3/bin/architecture_name/filename .

argv
    Pointer to an array of arguments to the executable with the end of the array specified by NULL. If the executable takes 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 up.

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 up ntask copies of the executable named task. On systems that support environment, spawn passes selected variables in parent environment to children tasks. if set, the envar PVM_EXPORT is passed. if PVM_EXPORT contains other names (multiple sep. 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 set by the flag and where arguments. On return the array tids contains the PVM task identifiers 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 the associated error codes, see below for meaning. Meaning the first numt tids in the array are good, which can be useful for functions such as pvm_mcast().

When flag is set to 0 and where is set to NULL (or ``*'' in Fortran) a heuristic is used to distribute the ntask processes across the virtual machine. Initially the heuristic is round-robin assignment. Later PVM will use the metrics of machine load and rated performance (sp=) to determine the most appropriate hosts.

If the PvmHostCompl flag is set, the resulting host set gets complemented. Also, the TaskHost hostname "." is taken as localhost. This allows spawning tasks on "." to get the localhost or to spawn n - 1 things on TaskHost|HostCompl "." to get any 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.

If PvmTaskDebug is set, then the pvmd will start the task(s) in a debugger. 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] );
	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.