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 )
task Character string which is 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 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 executable 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:
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).
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 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 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, 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.