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