Provided by: pvm-dev_3.4.6-5_amd64 bug

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 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:
                    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".  Also, the  host  name  "."  is  taken  as  the
               localhost.   If  flag is 0, then where is ignored when determining the target host
               or architecture, and PVM will select the most appropriate host.

               The where argument can also be used to specify a custom working directory for each
               given  spawn  command.   This  is  done by appending a ':' and the desired working
               directory path to the where string, i.e.:

               "ibm1.epm.ornl.gov:/home/user/project/foo"

               PVM will temporarily change the working directory to spawn the given task(s),  and
               will  then  reset  to  the  default working directory after the spawn is executed.
               This option need not be  used  in  conjunction  with  either  the  PvmTaskHost  or
               PvmTaskArch  flags, as the working directory path is stripped off prior to parsing
               any host or architecture name.  A valid specification for where is therefore:

               ":/home/user/project/foo"

               The working directory can be either an absolute path name or can  be  relative  to
               the current default working directory.

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

DESCRIPTION

       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  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.  Given that the
       TaskHost  host name "." is taken as localhost, these can be used together, for example, to
       request n - 1 tasks on host "." but with flags TaskHost|HostCompl to spawn n - 1 tasks  on
       hosts other than 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.

SEE ALSO

       pvm_export(3PVM)

                                         30 August, 1993                              SPAWN(3PVM)