lamexec - Run non-MPI programs on LAM nodes.


SYNTAX

       lamexec [-fhvD] [-c <#> | -np <#>] [-nw | -w] [-pty] [-s
              <node>] [-x VAR1[=VALUE1][,VAR2[=VALUE2],...]]
              [<nodes>] <program> [-- <args>]


OPTIONS

       -c <#>    Synonym for -np (see below).

       -D        Use  the executable program location as the cur­
                 rent working directory  for  created  processes.
                 The  current  working  directory  of the created
                 processes will be set before the user's  program
                 is invoked.

       -f        Do not configure standard I/O file descriptors -
                 use defaults.

       -h        Print useful information on this command.

       -np <#>   Run this many copies of the program on the given
                 nodes.  This option indicates that the specified
                 file is an executable program and not an  appli­
                 cation  schema.   If no nodes are specified, all
                 LAM nodes are  considered  for  scheduling;  LAM
                 will  schedule  the  programs  in  a round-robin
                 fashion, "wrapping around" (and scheduling  mul­
                 tiple copies on a single node) if necessary.

       -nw       Do not wait for all processes to complete before
                 exiting lamexec.  This option is mutually exclu­
                 sive with -w.

       -pty      Enable  pseudo-tty support.  Among other things,
                 this  enabled  line-buffered  output  (which  is
                 probably  what  you want).  The only reason that
                 this feature is not enabled by  default  is  be­
                 cause  it is so new and has not been extensively
                 tested yet.

       -s <node> Load the program from this node.  This option is
                 not  valid on the command line if an application
                 schema is specified.

       -v        Be verbose; report on important  steps  as  they
                 are done.

       -w        Wait for all applications to exit before lamexec
                 exits.

       -x        Export the specified  environment  variables  to
                 the  remote  nodes before executing the program.

                 (see  the Examples section, below), or new vari­
                 able names specified with corresponding  values.
                 The parser for the -x option is not very sophis­
                 ticated; it does not even understand quoted val­
                 ues.   Users are advised to set variables in the
                 environment, and then use -x to export (not  de­
                 fine) them.

       -- <args> Pass  these  runtime arguments to every new pro­
                 cess.  This must always be the last argument  to
                 lamexec.   This  option is not valid on the com­
                 mand line if an application schema is specified.


DESCRIPTION

       lamexec  is  essentially  a clone of the mpirun(1), but is
       intended for non-MPI programs.

       One invocation of lamexec  starts  a  non-MPI  application
       running  under  LAM.  To start the same program on all LAM
       nodes, the application can be  specified  on  the  lamexec
       command  line.   To start multiple applications on the LAM
       nodes, an application schema is  required  in  a  separate
       file.   See appschema(5) for a description of the applica­
       tion schema syntax, but it essentially  contains  multiple
       lamexec  command lines, less the command name itself.  The
       ability to specify different options for different instan­
       tiations of a program is another reason to use an applica­
       tion schema.

   Application Schema or Executable Program?
       To distinguish the two different forms, lamexec  looks  on
       the command line for <nodes> or the -c option.  If neither
       is specified, then the file named on the command  line  is
       assumed  to  be  an  application schema.  If either one or
       both are specified, then the file is assumed to be an exe­
       cutable  program.   If  <nodes> and -c both are specified,
       then copies of the program are started  on  the  specified
       nodes  according  to  an  internal  LAM scheduling policy.
       Specifying just one node effectively forces LAM to run all
       copies  of  the program in one place.  If -c is given, but
       not <nodes>, then all LAM nodes are used.  If  <nodes>  is
       given,  but not -c, then one copy of the program is run on
       each node.

   Program Transfer
       By default, LAM searches for executable  programs  on  the
       target node where a particular instantiation will run.  If
       the file system is not shared, the target nodes are  homo­
       geneous,  and the program is frequently recompiled, it can
       be convenient to have LAM  transfer  the  program  from  a
       source  node (usually the local node) to each target node.
       The -s option specifies this behavior and  identifies  the
       single source node.

       LAM  looks  for an executable program by searching the di­
       rectories in the user's PATH environment variable  as  de­
       fined  on the source node(s).  This behavior is consistent
       with logging into the source node and executing  the  pro­
       gram from the shell.  On remote nodes, the "." path is the
       home directory.

       LAM looks for an application schema in three  directories:
       the  local directory, the value of the LAMAPPLDIR environ­
       ment variable, and LAMHOME/boot, where LAMHOME is the  LAM
       installation directory.

   Standard I/O
       LAM directs UNIX standard input to /dev/null on all remote
       nodes.  On the local node that invoked  lamexec,  standard
       input is inherited from lamexec.  The default is what used
       to be the -w option to prevent conflicting access  to  the
       terminal.

       LAM directs UNIX standard output and error to the LAM dae­
       mon on all remote nodes.   LAM  ships  all  captured  out­
       put/error  to  the node that invoked lamexec and prints it
       on the standard output/error of lamexec.  Local  processes
       inherit  the standard output/error of lamexec and transfer
       to it directly.

       Thus it is possible to redirect standard I/O for  LAM  ap­
       plications  by  using the typical shell redirection proce­
       dure on lamexec.

              % lamexec N my_app < my_input > my_output

       The -f option avoids all the  setup  required  to  support
       standard  I/O  described above.  Remote processes are com­
       pletely directed to /dev/null and local processes  inherit
       file descriptors from lamboot(1).

   Pseudo-tty support
       The  -pty  option  enabled  pseudo-tty support for process
       output.   This  allows,  among  other  things,  for   line
       buffered  output from remote nodes (which is probably what
       you want).

       This option is not currently the default for  lamexec  be­
       cause  it  has  not been thoroughly tested on a variety of
       different Unixes. Users are encouraged to use -pty and re­
       port any problems back to the LAM Team.

   Current Working Directory
       The current working directory for new processes created on
       the local node is inherited  from  lamexec.   The  current
       working  directory  for  new  processes  created on remote
       nodes is the remote user's home directory.   This  default


       The -D option will change the current working directory of
       new processes to the directory where  the  executable  re­
       sides before the new user's program is invoked.

       An  alternative  to  the -D option is the -wd option.  -wd
       allows the user to specify an  arbitrary  current  working
       directory (vs. the location of the executable).  Note that
       the -wd option can be used  in  application  schema  files
       (see appschema(5)) as well.

   Process Environment
       Processes  in  the  application  inherit their environment
       from the LAM daemon upon the node on which they  are  run­
       ning.  The environment of a LAM daemon is fixed upon boot­
       ing of the LAM with lamboot(1) and is inherited  from  the
       user's  shell.   On the origin node this will be the shell
       from which lamboot(1) was invoked and on remote nodes this
       will be the shell started by rsh(1).  When running dynami­
       cally  linked  applications  which  require   the   LD_LI­
       BRARY_PATH  environment  variable  to be set, care must be
       taken to ensure that it is correctly set when booting  the
       LAM.

   Exported Environment Variables
       The  -x  option  to lamexec can be used to export specific
       environment variables to the  new  processes.   While  the
       syntax of the -x option allows the definition of new vari­
       ables, note that the parser for this option  is  currently
       not very sophisticated - it does not even understand quot­
       ed values.  Users are advised to set variables in the  en­
       vironment and use -x to export them; not to define them.


EXAMPLES

       lamexec N prog1
           Load  and  execute prog1 on all nodes.  Search for the
           executable file on each node.

       lamexec -c 8 prog1
           Run 8 copies of prog1 wherever LAM wants to run  them.

       lamexec n8-10 -v -nw -s n3 prog1 -- -q
           Load  and execute prog1 on nodes 8, 9, and 10.  Search
           for prog1 on node 3 and transfer it to the three  tar­
           get  nodes.   Report as each process is created.  Give
           "-q" as a command line to each new  process.   Do  not
           wait  for  the  processes  to  complete before exiting
           lamexec.

       lamexec -v myapp
           Parse the application schema,  myapp,  and  start  all
           processes  specified in it.  Report as each process is
           created.

           run_app.csh
           Run the application "run_app.csh" (assumedly a C shell
           script) twice on each node in the  system  (ideal  for
           2-way  SMPs).   Also enable pseudo-tty support, change
           directory to /workstuff/output, and export the DISPLAY
           variable  to  the  new  processes  (perhaps  the shell
           script will invoke an X application such as xv to dis­
           play output).

       lamexec -np 5 -D `pwd`/my_application
           A  common  usage  of  lamexec  in environments where a
           filesystem is shared between all nodes in  the  multi­
           computer, using the shell-escaped "pwd" command speci­
           fies the full name of the  executable  to  run.   This
           prevents  the  need  for  putting the directory in the
           path; the remote notes will have an absolute  filename
           to  execute  (and  change directory to it upon invoca­
           tion).


DIAGNOSTICS

       lamexec: Exec format error
           A non-ASCII character was detected in the  application
           schema.   This  is  usually a command line usage error
           where lamexec is expecting an application  schema  and
           an executable file was given.

       lamexec: syntax error in application schema, line XXX
           The  application  schema cannot be parsed because of a
           usage or syntax error on the given line in the file.

       <filename>: No such file or directory
           This error can occur in two cases.  Either  the  named
           file  cannot  be  located or it has been found but the
           user does not have sufficient permissions  to  execute
           the program or read the application schema.


SEE ALSO

       mpimsg(1), mpirun(1), mpitask(1), loadgo(1)


Man(1) output converted with man2html