Provided by: lam-runtime_7.1.2-1.3_i386 bug

NAME

       lamexec - Run non-MPI programs on LAM nodes.

SYNTAX

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

OPTIONS

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

       -D        Use  the  executable  program location as the current 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 <#>   (see  below).   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 application 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 multiple copies on
                 a single node) if necessary.

       -nw       Do  not  wait  for  all  processes to complete before exiting
                 lamexec.  This option is mutually exclusive 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
                 because 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.   Existing  environment
                 variables can be specified (see the Examples section, below),
                 or new variable names specified  with  corresponding  values.
                 The  parser  for  the -x option is not very sophisticated; it
                 does not even understand quoted values.  Users are advised to
                 set  variables  in the environment, and then use -x to export
                 (not define) them.

       <where>   A set of node and/or  CPU  identifiers  indicating  where  to
                 start

       -- <args> Pass these runtime arguments to every new process.  This must
                 always be the last argument to lamexec.  This option  is  not
                 valid  on  the  command  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 application
       schema syntax, but it essentially  contains  multiple  lamexec  command
       lines,  less the command name itself.  The ability to specify different
       options for different instantiations of a program is another reason  to
       use an application schema.

   Location Nomenclature
       The  location  nomenclature that is used for the <where> clause mention
       in the SYNTAX section, above, is identical to mpirun(1)’s nomenclature.
       See  the  mpirun(1)  man  page for a lengthy discussion of the location
       nomenclature.

       Note that the by-CPU syntax, while valid for lamexec, is not  quite  as
       meaningful   because   process   rank  ordering  in  MPI_COMM_WORLD  is
       irrelevant.   As  such,  the  by-node  nomenclature  is  typically  the
       preferred syntax for lamexec.

   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
       executable  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 homogeneous, 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.

   Locating Files
       LAM looks for an executable program by searching the directories in the
       user’s PATH environment variable as  defined  on  the  source  node(s).
       This  behavior  is  consistent  with  logging  into the source node and
       executing the program 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  environment  variable,  and
       laminstalldir/boot,   where  "laminstalldir"  is  the  directory  where
       LAM/MPI was installed.

   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 daemon on all
       remote nodes.  LAM ships all captured output/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 applications by
       using the typical shell redirection procedure 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 completely 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 because it has not
       been  thoroughly  tested  on  a  variety of different Unixes. Users are
       encouraged to use -pty and report 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 behavior is overridden by the -D option.

       The  -D  option  will  change  the  current  working  directory  of new
       processes to the directory where the executable resides 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 running.  The environment of a
       LAM daemon is fixed upon booting 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 dynamically linked
       applications which require the LD_LIBRARY_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 variables, note that the parser  for  this
       option  is  currently  not  very  sophisticated  -  it  does  not  even
       understand quoted values.  Users are advised to set  variables  in  the
       environment 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 target 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.

       lamexec N N -pty -wd /workstuff/output -x DISPLAY 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 display
           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 multicomputer, using the shell-
           escaped "pwd" command specifies 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 invocation).

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.

RETURN VALUE

       lamexec returns 0 if all processes started by lamexec exit normally.  A
       non-zero value is returned if an internal error occurred in lamexec, or
       one or more processes exited abnormally.  If an internal error occurred
       in lamexec, the corresponding error code is  returned.   In  the  event
       that  one  or  more  processes exit with non-zero exit code, the return
       value of the process that lamexec first notices died abnormally will be
       returned.   Note  that, in general, this will be the first process that
       died but is not guaranteed to be so.

       However, note that if the -nw switch is used,  the  return  value  from
       lamexec  does  not indicate the exit status of the processes started by
       it.

SEE ALSO

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