Tutorial:
Legion tty Objects and tty-related commands

Table of Contents

  About Legion tty objects
Simple tty management
Complex tty management
Managing individual object output
Other relevant on-line documents:
  Starting and shutting down Legion 1.3
Logging in to a Legion system
Legion context space
Legion host and vault objects
How to start remote programs in Legion
Legion graphical user interface
Quick list of all Legion commands
Usage of all Legion commands
The Legion tutorials offer quick and simple instructions for various key procedures for a Legion system. More complete explanations of all of the procedures discussed here are available on separate pages, and can be found by clicking on the icon.

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
The exact syntax will depend on what kind of shell you are using and on where your Legion files are installed. Consult your system administrator for more information.

About Legion tty objects

A Legion tty object directs output from Legion processes towards a specific shell. This means that you can see the output from a remotely executed program on your workstation, direct output from a locally executed program into a file, or perhaps view the output from several simultaneously executed programs in a single shell. Generally, you will want one tty object per shell, so that each shell's output will appear in that shell, regardless of where its processes are run.

There are three steps involved in using Legion tty objects:

  1. Create an instance of the ttyObjectClass.
  2. Set a tty object for the shell. This means that all output resulting from processes run in the shell will be directed towards the selected tty object. Only one tty object can be set per shell.
  3. Watch the output that arrives at a tty object. This involves creating a special tty watch object, which runs a tty_watch process. This process constantly watches its assigned tty object and sends a copy of any input the tty object receives to standard output in its shell.

Note that a shell does not have to watch its set tty object, and that multiple shells can watch the same tty object.

When you exit from a shell the tty_watch process will not automatically shut down. That is, it will continue to send information to the now defunct shell. This will bog down the tty process and may result in error messages. We therefore suggest that before you exit a shell you stop the tty_watch process.

There are two different ways to create and use tty objects in Legion, a simple approach, which will probably be acceptable for most users, and a complex approach.

Simple tty management

There are two commands for the simple approach: legion_tty and legion_tty_off. The former creates, sets, and watches a tty object and the latter stops the tty_watch process, so that the output from the shell will no longer be directed towards the shell. The example below use legion_tty to create a tty object called mytty: 
$ legion_tty mytty
You might find it convenient to create a context (with the legion_context_create command) to organize your tty objects (e.g., /tty/mytty).

If /context_path/mytty does not already exist, a new tty object will be created and assigned the context path name /context_path/mytty. The output from all processes run in your current shell, whether on your local system or a foreign system, will now be directed to mytty, and a tty_watch process will start. This process will watch its assigned tty object and pass a copy of the tty object's information to the shell's standard output (i.e., to the shell's command line). Note that a shell can run only one tty_watch process at a time.

To stop a tty_watch process started with legion_tty run the legion_tty_off command. This will end whatever tty_watch process is currently running in the current shell, although it will not destroy the tty object being watched.

Complex tty management

The complex procedure requires three different steps to create, set, and watch the tty object.

First, if you do not already have a tty object you must use legion_create_object to create a tty object. Then use legion_set_tty to set a tty object for your shell. Remember that you can only have one tty object set per shell. If a tty object has already been set, legion_set_tty will just switch to the new one. Finally, use legion_tty_watch to start watching your current (set) tty object. The whole procedure looks something like this: 

$ legion_create_object -c /class/ttyObjectClass /context_path/mytty
$ legion_set_tty /context_path/mytty
$ legion_tty_watch &
The legion_tty_watch command can be run with or without a tty object's name: multiple tty_watch processes can be run, and can be started at different times. They can be piped to a file, or run in a different window, as desired. To stop the tty_watch procedure, send a SIGINIT, using either "kill -INT" or the Ctrl-C key combination.

To direct the current tty object's output to a file object instead of standard output, use the legion_tty_redirect command. The example below redirects the current tty's object output to file object Foo. If no file object of that name exists, Legion will create a new one. 

$ legion_tty_redirect Foo
Use the legion_tty_unredirect command to stop this process. 
$ legion_tty_unredirect Foo

Managing individual object output

You can also direct a specific object's output to a specific tty object, with the legion_direct_output command. 
$ legion_direct_output -c Foo -c /context_path/mytty
This tells object Foo to direct its output to the tty object mytty. Note that this does not start a tty_watch process. Please also note tthat the object must have dynamic output redirection enabled or you will get an error message.