Tutorial:
Legion 1.5 graphics user interface (GUI)

Table of Contents

  Other relevant on-line documents:

Logging in to a running Legion system Legion graphical user interface Introduction to Legion context space Context-related commands How to start remote programs in Legion Sample makefile for remote programs Object permissions Legion tty objects Running a PVM code in Legion

Running an MPI code in Legion Quick list of all Legion commands Usage of all Legion commands Starting and shutting down Legion 1.5 Using Legion security features Legion host and vault objects Adding host and vault objects The list of all on-line 1.5 tutorials

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 Legion GUI

There are two ways to negotiate in and manage context space: command-line utilities such as legion_ls and legion_rm and with the Legion graphic user interface (GUI). This page discusses the GUI (version 0.1 alpha). The alpha release has a number of limitations, but it is a useful tool for seeing and controlling your context space.

Installing the GUI in Windows 95

You must have the Java Runtime Environment (JRE) or the Java Developer Kit (JDK) 1.1.3 or later in order to run this application. You can download these from http://java.sun.com/products.

The files for running the GUI in Windows95 must be stored in a specific directory configuration. The installation package is in the LegionGui.zip file. It consists of three parts: binaries, libraries and classes. Move the package to your hard drive, then unzip it.

The unzipped package must have the directory structure shown below. If you are using WinZip be sure to check the Use folder names option before extracting the files. All directory names must appear as shown, particularly the GUI classes, since these names reflect the package structure of the program.

c:\LegionGui
	\Bin
	\context_manager
		\dialogs
	\displays
		\attributes
		\instances
		\methods
	\LegionBridge
	\Lib
	\processors
		\multi_run
	\usage
	\views
		\viewTree

The \Bin subdirectory holds the jre.exe, and the *.dll files. The \Lib subdirectory holds the *.jar files and classes.zip. The remaining directories hold the compiled classes of the GUI program.

The GuiStart.bat file is in the \LegionGui directory, but you can move it anywhere in your current machine's directory structure. It assumes that the directory structure above is in c:\, but you can put the unzipped package in any part of your current machine. If the GUI files are not on the c:\ drive you must alter the GuiStart.bat file accordingly.

Running the GUI in Windows95

There are two steps to this process:

1. Open a Telnet or Exceed window to your Legion host, and execute the following command:

   $ javaLegionServer

   This will return a port number <PPP>.

2. Open a DOS window. Move to the directory containing the \LegionGui directory structure (e.g., c:\), and type the following into the Run dialog:

   GuiStart <my_host> <PPP>

   The <my_host> argument is the address of the Legion host computer (e.g., host.cs.virginia.edu). The <PPP> argument is the port number produced by the JavaLegionServer command in step 1. This will load the GUI and display its initial view of your context space.

Running the GUI in a Unix environment

The GUI is not currently supported for a Unix environment. We will remedy this in a future release.

The main GUI window

All views appear within the GUI main window. This window takes up the full screen and has a main menu bar immediately under the window title. The menu shows the full complement of commands contemplated for the Legion GUI.

The complete set of GUI commands fall into three main categories: manipulating Legion classes, objects and data; navigating and manipulating context space; and managing the GUI itself. Most of these commands are dimmed to indicate that they are not yet available for use in the current release. The available commands allow you to add, replace, and control view windows.

In order to display Legion context space information on the screen, the GUI creates a highly structured memory cache in your computer. The GUI gets the data for this cache from the Legion host computer via a port you specify when you start the GUI. Legion context space can be quite large, so when the GUI first starts up the initial tree view window shows the GUI context space / root context and only three levels of context folders. (This is an Edit|Preferences limitation and is fixed in this version.) From here you can tailor one or more view windows with the View|Add and View|Replace commands. You can also directly modify this startup view with the View|Extend command.

The GUI's initial display of context space may therefore be smaller than the actual Legion context space. You can use the View|Add, View|Replace and View|Extend main menu commands to extend the number of levels appearing in any view window.

In order to close all currently open view windows and exit the GUI, click the File|Exit command on the main menu bar.

View windows

From the main window you can open multiple view windows, which show selected parts of your context space. Every view window has a view origin, or origin. This will always be a Context Folder and is the zero level of its tree view.

The first view window displayed on startup uses the context space root as its view origin. This is designated by the symbol / and is an absolute point of reference in the GUI. It represents the highest level of the data contained in the GUI cache.

The more general term root can be used to indicate a view origin that is other than /; i.e., a context member at a different point in the tree. Figure 2 shows a tree view with view origin /. A selected context, such as /home, can be used as the view origin for the creation of a new tree. Any context in any view can be used to create a new view window with that member as its view origin.

The title bar of each view identifies its view origin and the number of levels in that view. The context path of any member relative to the view origin is easily determined from the path shown in the title bar.

To close a view window, click the closure icon at on the right side of the title bar. This will remove the view from the screen entirely. It cannot be recovered. There is no command in this version to generate a view without a spawn, so once you have closed the last view window you must restart the GUI to open a new view window.

The startup view window

The initial view window is currently fixed in this version, but in future versions you will be able to select the initial portion of context space shown. The startup view window is a folders-only tree view showing up to three levels of folders from your context space. This view can be extended with the View|Extend command or used to spawn additional view windows with the View|Add command. The spawned view windows can in turn spawn other views or be replaced with the View|Replace command.

Main menu commands

File
File|Exit
This command closes all view windows and exits the GUI.

View
View|Extend
The Extend command lets you extend the current view window down one level.

If the selected member is a folder the command extends only the members of that folder. This allows you to focus on a particular branch of the context space tree

If the selected member is not a folder the entire view is extended down one more level. This means that every empty folder is checked for children and those children are displayed.

View|Add
The Add command lets you add a new tree view to your screen. In the current version a sub menu is displayed with only the Tree selection available. This selection opens a dialog box labelled New View Specification (shown below).

The New View Specification dialog box has three areas of interest. These are Display, Origin At and Levels.

Display: You can select Folders Only to create a view that shows only folders and no non-folder members (as in Figure 3). Select Root to display the view origin. Select Root Level to display the children of the view origin, and not the origin itself. The Root and Root Level buttons act like radio buttons (i.e., they are mutually exclusive). The Folders Only button is independent of the other two.

Origin At: The Root button creates a new view window with a view origin that is the same as that of the spawning view window. The Selection button creates a new view with the current selection taken as its view origin. The Context Space Root button sets / as the origin of the new view window. These three buttons are mutually exclusive.

Levels: This section specifies how many levels of context space should be displayed in the new view window.

If you wish to alter the tree in the new view window relative to your current (spawning) view, select Yes in the View Relative? option. You can indicate that you want to extend, reduce or leave unchanged the number of levels to appear in the new view relative to the spawning view. You should then either enter a number in the Number Of Levels field or choose one of the buttons offering fixed settings (e.g., if you want to reduce the number of levels by one you would select Reducing and then enter 1 in the Number of Levels field).

If you select No for View Relative? you can specify an exact number of levels. In this case, the Extending and Reducing buttons are dimmed, and the 1 Level Only button is removed (a view window tree displays a minimum of two levels).

In either case you can use the Number of Levels field to set the number of levels. The current release limits this value to five new levels in a single View|Add operation. Selecting the Maximum Of 5 Levels button is the equivalent of entering a value of 5 in the Number Of Levels field.

The default setting is a relative view, extended by one level.

View|Replace
The Replace command lets you replace the current view with a new tree. In this version, a sub menu is displayed with only the Tree selection available. This selection displays a dialog box labelled Replacement View Specification. It is the same dialog box shown above.

Replacement View Specification: All buttons in this dialog box operate the same as described above for View|Add.

Extend: The created view is extended by the Number of Levels entry. Extension occurs at the lowest level of the view.

Reduce: The created view is reduced by the Number of Levels entry. The reduction occurs at the lowest level of the view.

Unchanged: The new view is created with no change in the number of levels.

View|Clone:
This command creates an exact copy of the spawning view window and adds it to those already on the screen.

View|Close:
You can close the current view window with this command. No other view will be affected and no other view window will be selected. You will have to select a new view window before you can execute any further menu commands.

You can also close any view window on your screen with the view closure button on the right side of the title bar.