Tutorial:
Starting a remote program in Legion 1.2

Table of Contents

Depending on how your system is set up, you may need to set up your access to your system before you can run Legion commands. This will probably involve running a command such as this:

$ . ~LEGION/setup.sh

or

$ source ~LEGION/setup.csh

What is a remote program?

A remote program is an executable process that can be started with a command-line utility. Note that a remote program is not part of the Legion system, but is an independent program that may or may not be compatible with Legion. Remote programs might be shell scripts, compilers, existing executables, etc. The term "remote" here means that the program does not need to be executed on the local host.

What kind of programs can Legion run?

Legion can run both Legion-compatible and non-Legion-compatible programs. A compatible program is linked to the Legion libraries. A non-compatible program does not have these links. The legion_register_program command, which registers non-compatible programs with the Legion system, creates a proxy to handle a particular program. When the program is run, with the legion_run command, the proxy is activated and can instruct the program to begin execution.

Can Legion run only Legion-compatible remote programs?

Legion can run both Legion and non-Legion (i.e., programs that are not linked to the Legion libraries, such as shell scripts) remote program since it relies on two different types of interfaces to pass Legion's execution order to the program. Before either a compatible or non-compatible remote program can be run from Legion it is registered. The legion_register_runnable command registers Legion-compatible programs, and the legion_register_program command registers a non-Legion program. A single command, legion_run, runs both types of remote programs. Both of these commands have parameters that include the remote program's binary path name and architecture and assign the program a context path name: this allows Legion to know where the program's executable files are located, what platform the files use, and how to find the program's Legion interface.

Registering non-Legion-compatible programs

Non-compatible remote programs are registered with the legion_register_program command. The user includes information on the program's architecture (e.g., linux, sgi, solaris, etc.), its binary path name, and a program class.

    legion_register_program <program class> <executable path> <legion arch>

The <program class> parameter is a context path name for the class that will manage Legion objects related to a particular program. Note that since the user decides how to organize his or her own context space, the path name can be whatever the user finds most convenient (although you might want to use the name of the program in the <program class> parameter, so that it will be easier to remember). The context path name can be new or can use a previously created path (if the user is registering multiple versions of a the same program), and will refer to a (new or previously created) Legion object that functions as a proxy for executing a non-compatible remote program. Note also that if multiple programs are registered with the same program class and architecture, the most recently registered version will be used when the program is run on that particular architecture. Once the program has been registered, it can be run with the legion_run command.

An example of this command might look like this:

$ legion_register_program myProgram /bin/programs/myProgram linux
Program class "myProgram" does not exist.
Creating class "myProgram".
Registering implementation for class "myProgram"
$

This output shows Legion creating the program class myProgram, as the command requested. If this class had been previously created, the output would look like this:

$ legion_register_program myProgram /bin/programs/myProgram linux
Registering implementation for class "myProgram"
$

Registering Legion-compatible programs

The legion_register_runnable command registers programs that are linked to the Legion libraries, and export a runnable object interface. This is, the command creates an interface between the Legion system and the remote program and this interface transfers the execution command from Legion to the remote program. Like legion_register_program, this command specifies the remote program's program class, executable binary path, and architecture. Its usage is:

    legion_register_runnable <program class> <executable path> <legion arch>

As with legion_register_program, the <program class> parameter is a context path name for the Legion objects that will handle a particular program. And, again, the user is free to choose a context path that best suits his or her organizational scheme, or use a previously created context (although you might want to use the name of the program in the <program class> parameter, so that it will be easier to remember). In that case, note that Legion will use the most recently registered program class and architecture when running a remote program. Once the program has been registered, it can be run with the legion_run command.

$ legion_register_runnable myProgram /bin/programs/myProgram linux
Program class "myProgram" does not exist.
Creating class "myProgram".
Registering implementation for class "myProgram"
$

This output shows Legion creating the program class myProgram, as the command requested. If this class had been previously created, the output would look like this:

$ legion_register_runnable myProgram /bin/programs/myProgram linux
Registering implementation for class "myProgram"
$

Use legion_run to remotely execute programs. but note that you must first register the program with either legion_register_program for non-Legion compatible programs or legion_register_runnable for Legion compatible programs. The usage of this command is:

legion_run [-help] [-w] [a <architecture>]
        [-in <contex path name>] [-out <context path name>] 
	[-IN <local file name>] [-OUT <local file name>] 
	[-f <options file>] <program class> [<arg1>, <arg2>, ... <argn>]

The legion_run command executes a single instance of the program associated with the <program class> parameter. Legion will randomly choose a host with a suitable architecture (specified when the program was registered) to execute the program.

There are several optional parameters associated with this command. The -help flag displays the command's syntax and provides a brief description of how to use its options. The -w flag directs Legion to direct the command's output to your tty object. Note that if you have not created or set a tty object for your current window, you will not be able to see the command's output and an error message will appear. You can use the legion_create_object command to create a tty object, and the legion_set_tty command to set the tty as an environmental variable:

$ legion_create_object -c class/ttyObjectClass mytty
1.01.67000000.01000000.000001fc0a6876...
$ legion_set_tty mytty
$ legion_tty_watch &

If you prefer not to use the -w flag, you can use the legion_tty_watch command to direct your output to a previously created tty object.

The -a flag allows you to specify the type of platform the program requires. Note that the possible architectures are limited. At the moment they are:

linux	corresponds to x86 running Red Hat 4.x Linux
solaris	corresponds to Sun workstations running Solaris 5.x
sgi	corresponds to SGI workstations running IRIX 5.x
alpha_linux	corresponds to DEC Alphas running Red Hat 4.x Linux
alpha_DEC	corresponds to DEC Alphas running OSF1 v4
t90	corresponds to Cray T90s running Unicos 10.x
rs6000	corresponds to IBM RS/6000s running AIX 4.2

The -in <contex path name> option allows you to select a Legion file that should be copied into the remote program's current working directory before the program executes. The -out <context path name> option instructs Legion to copy the program's output from the remote program's current working directory to the Legion file named in <context path name>, after the program terminates (partial results will be available if the program crashes).

The other two options operate on a local file: -IN <local file name> tells Legion to copy the files named in <local file name> into the the remote program's current working directory before the program executes, and -OUT <local file name> tells Legion to copy the program's output to the file named in <local file name>.

Files that are listed with the -in/-out and -IN/-OUT options can be named with either full or relative path names. Note, however, that the remote program will use the file path's basename (i.e., as relative path names from the current working directory) to gain access to the named file. New files will be given names corresponding to the basename of the current Legion context path or local directory path. The <arg1>, <arg2>, ... <argn> parameters are arbitrary command-line arguments.

If your program requires extensive use of these options you may want to use the -f flag, which allows user to list the options in a separate file rather than on the command line. The file can contain any of the options discussed above (except <program class> parameter or the [<arg1>, <arg2>>, ... <argn>] and can be delimited with spaces or new lines.

Summary

The entire process, using the Unix cp process as a sample program, might look like this:

$ legion_register_program cp /bin/cp linux
Program class "cp" does not exist.
Creating class "cp".
Registering implementation for class "cp"
$ legion_run -in /dir1/src -out /dir2/dest cp src dest
$

The remote Unix program cp is first registered (with legion_register_program, since it is a non-Legion compatible program), and the program class "cp" is created in the user's local context, /bin/cp is declared to be its local executable path name, and linux is declared to be its architecture type.

The program is then remotely executed on a randomly chosen linux host, and a series of events takes place: first, the -in option tells Legion to copy the Legion file /dir1/src into the remote program's cp's current working directory and call it src. The remote program cp then executes, copying src to a new Unix file, dest. Finally, once cp has terminated, Legion copies the contents of Unix file dest to a new Legion file called dest, and adds the context name dest to /dir2 (i.e., if the user runs legion_context_list, dest will now be listed and will refer to the dest file).

Note that you can ask for multiple input and output files when you execute a program by repeating the -in/-out and -IN/-OUT options.

Running a remote program from the GUI

Once a program has been registered, it can be run from the Legion GUI.

Go to the context containing the program class context name, and click the right mouse button on the icon representing the program class. A list of options will appear: click on the Run... option.

This will bring up a new window, which users should use to specify arbitrary command-line arguments for running the program and the context names of any input or output files (the -in/-out parameters). Users can use currently existing output files or create new ones. Users can also specify the program's architecture from a list of acceptable architectures at the bottom of the Run window: this list contains the names of the architectures that Legion currently accepts. The any option uses the default architecture.

A few caveats:

• The GUI version of legion_run does not include all of the options that the command-line version does: the -IN/-OUT, -f <options file>, and the -w options are not available. Programs that require these options should be run from the command line.

• The Input Legion Files and Output Legion Files dialog boxes use context path names, just as the -in/-out parameters do in legion_run. In other words, if a file does not have a context name it cannot be used as an input or output file.