Tutorial:
Legion context-related commands

Table of Contents
Viewing contexts:
View a context's contents
Looking up LOIDs
Create a new context
Changing the working context
Verify the current working context
Naming:
Assigning alternate names to existing
context names
Assigning a context name to a LOID
Renaming an object 		Listing an object's names
Removing names
Using the same name in different contexts
Moving between local files and contexts:
Copying a local file to a Legion file object
Copying a Legion file object
Viewing a file object's contents
Importing a local Unix tree
Other
Other on-line tutorials & documentation
Click on the to move to the selected text.

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 where your Legion files are installed (i.e., the value of ~legion will depend on your individual Legion net). Consult your system administrator for more information.

The following style conventions are used in these tutorials:

Documentation about context space

In Unix space you move around directory space with command-line utilities, and Legion provides commands to let you move around in context space. This tutorial explains some basic context-related command line utilities. Most resemble Unix commands in both name and purpose to make them easier to use (e.g., legion_ls, legion_rm).

There are several other sources of information about Legion commands: a Quick Reference Guide lists all commands' syntax and the Reference Manual has complete information about all Legion commands (both available here in PostScript and PDF); the Legion release package includes man pages1 for all commands; and, on-line, there is an explanation of Legion commands and a quick list of the commands' syntax.

View a context's contents

Just as the ls command in Unix allows users to view the files located in a particular directory, the legion_context_list command shows all objects contained in a particular context. A home context of a new system will look something like this: 
$ legion_ls /
class
home
hosts
impls
vaults
$
You might see something different, depending on your individual system. 
$ legion_ls /
Fooclass
Foofile
Fooobject
class
home
hosts
impls
vaults
$
To view sub-contexts (similar to sub-directories), use a context's name is used an as argument. 2 
$ legion_ls /hosts 
.
..
BootstrapHost
your.host.DNS.name
$
You can use the legion_ls flags to get more specific information. There are eight flags, not all of which are discussed here.

You can use the -l and -a flags to get information about object types and descriptions. The -l flag displays object types and descriptions. 

$ legion_ls -l /
Fooclass                        (class)
Foofile                        43 bytes
Fooobject                      (object)
class                         (context)
home                          (context)
hosts                         (context)
impls                         (context)
vaults                        (context)
$
Objects of unknown type will be described as (object) and faulty objects will be described as (not available).

The -a flag shows "hidden" objects, such as those whose names begin with a ".": 

$ legion_ls -a /
.
Fooclass
Foofile
Fooobject
class
home
hosts
impls
vaults
$
You can use legion_ls plus an object name to get information about an individual object. For example, you can look up object Foofile's LOID: 
$ legion_ls -L Foofile
Foofile 1.01.66000000.02000000.00000...
$

Looking up LOIDs

Use the -L flag to list LOIDs associated with a context's entries. The output will be a "dotted hex" LOID.3 

$ legion_ls -L
Fooclass 1.35fe7c3d.07..000001fc0a7838d45ed
Foofile 1.01.66000000.02000000.00000...
Fooobject 1.35fe7c3d.66000000.01000000.00
class 1.01.05.02000000.00000...
home 1.01.05.05000000.00000...
hosts 1.01.05.03000000.00000...
impls 1.01.05.06000000.0000
vaults 1.01.05.04000000.00000...
$
You can look up an individual object's LOID by using the object's context name as a parameter: 
$ legion_ls -L /hosts/BootstrapHost
1.01.07.680c2608.000001fc0c1e0...
$

Create a new context

The legion_context_create command, not surprisingly, creates new contexts. It is similar to the Unix mkdir command. Note that the output shows the new context's parent context and its LOID. 
$ legion_context_create /tmp
Creating context "tmp" in parent ".".
New context LOID = "1.01.05.6c0c2608.000001fc0c923..."
$

Changing the working context

The legion_set_context command will change the current working context. For example, to change to /tmp, you would type: 
$ legion_set_context /tmp
This command sets an environment variable in the shell in which it has been invoked. The command is implemented as an alias (as supported by your shell) that sources the script legion_set_context.sh legion_set_context.csh.

Verify the current working context

Use legion_pwd to check your current working context. The output below, for example, tells you that you are in the tmp sub-context. 
$ legion_pwd
/tmp
$
This command is similar to the Unix pwd command.

Assigning multiple names to an object

An object can have multiple context names, assigned by multiple users. The legion_ln, similar to the Unix ln command, assigns alternate names to a previously named object (i.e., it works only with objects that already have a context name). If the object doesn't have any context names, use legion_context_add to give it a name.

Below, the new name Foo is assigned to the BootstrapHost object and placed in the /tmp context. 

$ legion_ln /hosts/BootstrapHost /tmp/Foo

$ legion_ls -la /tmp
.                             (context)
..                            (context)
Foo                                    
$
BootstrapHost and Foo have different context paths (/hosts/BootstrapHost and /tmp/Foo) but both point to the same LOID (and therefore to the same object). 
$ legion_ls -L /tmp/Foo
1.01.07.680c2608.000001fc0c1e0a395a4...
$

$ legion_ls -L /hosts/BootstrapHost
1.01.07.680c2608.000001fc0c1e0a395a4...
$

Assigning a context name to a LOID

The legion_context_add command maps a new context name to a LOID. It can be used to name a previously unnamed object or to assign an extra name to a previously named object. Either way you need to include the object's full LOID as a parameter. In the example below, the name newName is assigned to a LOID. 
$ legion_context_add 1.38e67781.07.01000000.000001fc0c1d
0f8ed1db36d559a5711c327b4131c51648b20f053feb0aeb55fb080c
ac5051b089805391f71629b3db6b8034124c5690b348355fb0c0f5f2
c3dc06f02a2f newName

Renaming an object

An object can be renamed with the legion_mv command (similar to the Unix mv command). In this example, the object that was named Foo is now named Bar. 
$ legion_mv Foo Bar
The name Foo is automatically removed. This process only affects the object in this specific context path: any other use of the name Foo, whether in this user's or any other user's context space, will be unchanged. The object's LOID and physical location is not changed.

Listing an object's names

Two commands will list an object's context names: legion_list_names and legion_ls.

The legion_list_names command will list all context paths that have been assigned to a given object. You must provide either a LOID or a context name. If you know an object's LOID you can use the -l flag to ask Legion to look up the object's name(s). 

$ legion_list_names -l 1.38e67781.07.01000000.000001fc0c
1d0f8ed1db36d559a5711c327b4131c51648b20f053feb0aeb55fb08
0cac5051b089805391f71629b3db6b8034124c5690b348355fb0c0f5
f2c3dc06f02a2f
/hosts/BootstrapHost
/hosts/my.host.DNS.name
$

If you already have a context name you can see what (if any) other names it has. This list will include names that other users (or the system) have assigned the object. 

$ legion_list_names /hosts/BootstrapHost
/hosts/BootstrapHost
/hosts/my.host.DNS.name
$

Similarly, legion_ls plus the -A flag looks up an object's other (if any) name[s]: 

$ legion_ls -A /hosts/BootstrapHost
/hosts/BootstrapHost
        /hosts/BootstrapHost
        /hosts/my.host.DNS.name
$

Removing names

You can remove one or more context names with legion_rm. 
$ legion_rm Bar
Note that this command may also remove its associated object. If the object has other names (assigned by you or someone else), it will just remove the specified name(s). If there are no other names the object will be destroyed. For example, if an object has two names, Foo and Foo2, and you run: 
$ legion_rm Foo

The name Foo would be removed but the associated object would remain. If you then run: 

$ legion_rm Foo2

The name Foo2 and the object will be destroyed, since Foo2 is its only context name. Use legion_ls -A to see whether or not an object has other names if you are not sure.

You can use the -v flag to run legion_rm in a verbose setting, which will show you whether objects or just context paths are being destroyed. E.g., 

$ legion_rm -v Foo2
Removing context name "foo2"
Destroying object "foo2" (1.3759173a.690...)
$

If you want to recursively remove an entire context and its contents, use the -r flag.

Using the same name in different contexts

As discussed in the Basic user manual, the same context name can refer to different objects in different contexts. For example, the name Foo can be assigned to two different objects in two different contexts.

Below, the name Bar is assigned to a LOID with the legion_ln command. 

$ legion_ln Foo Bar
The same name, in the tmp context, is then assigned to a different object. 
$ legion_ln OtherFoo /tmp/Bar
Alternatively, the same name can be used in different context paths to refer to the same object. 
$ legion_ln Foo Bar
$ legion_ln Foo /tmp/Bar

Copying a local file to a Legion BasicFileObject

You can copy the contents of a local file to a new BasicFileObject (a Legion file object) with the legion_cp command. The example below copies the contents of a local Unix file, UnixTextFile.txt, to a new BasicFileObject, called newFileObject, in the current working context. The -localsource flag indicates that UnixTextFile.txt can be found in the local file system. 
$ legion_cp -localsource UnixTextFile.txt newFileObject

Note that if you copy new material into a previously existing BasicFileObject the new material will write over any old material.

Copying a BasicFileObject

The legion_cp command will copy the contents of a file object to a new file object. 
$ legion_cp newFileObject newFileObject_copy

Use the -localdest flag to copy the contents of a BasicFileObject to a new text file in the local file system. 

$ legion_cp -localdest newFileObject anotherTextFile.txteObject_copy

Viewing the contents of a file object

You can view the contents of a BasicFileObject with the legion_cat command. The contents are printed to a standard output. 
$ legion_cat newFileObject
This is a test, just a test, nothing more.
$

Importing a local Unix tree

You can copy the contents of a local directory tree from your local Unix space into your context space with the legion_import_tree command. The contents of local files will be automatically copied into new BasicFileObjects.

In the example below, the contents of the Unix directory legion.practice are copied into the current Legion context. A listing of the Unix directory's contents shows that the directory contains one sub-directory and three files. The subdirectory /nextlevel also contains three files. 

$ ls -Fa legion.practice
./	../	nextlevel/	nothing	nothing2	nothing3
$ ls -Fa legion.practice/nextlevel 
./	../	nextnothing	nextnothing2	nextnothing3
$

The default values of legion_import_tree are the current Unix directory and the current Legion context (in this case, the home context "."), but you can specify the desired directory path and/or context path.

Note that Legion creates a new context called /nextlevel and copies the contents of the /nextlevel subdirectory into the new context. 

$ legion_import_tree legion.practice 
Making legion context "./nextlevel"
Creating context "nextlevel" in parent ".".
New  context LOID = "1.01.05.47b53908.000001fc0c01650..."
Copying contents of "legion.practice/nextlevel" "./nextlevel"
Copying unix file "legion.practice/nextlevel/nextnothing" to legion file "./nextlevel/nextnothing"
Copying unix file "legion.practice/nextlevel/nextnothing2" to legion file "./nextlevel/nextnothing2"
Copying unix file "legion.practice/nextlevel/nextnothing3" to legion file "./nextlevel/nextnothing3"
Copying unix file "legion.practice/nothing" to legion file "./nothing"
Copying unix file "legion.practice/nothing2" to legion file "./nothing2"
Copying unix file "legion.practice/nothing3" to legion file "./nothing3"
$

The legion_cat command shows that the file objects contain the same information as the Unix files. 

$ cat legion.practice/nextlevel/nextnothing3
3: This is a test, just a test, nothing more.
     
$ legion_cat nextnothing3
3: This is a test, just a test, nothing more.
$

1. Man page usage is man <command name>: ask your system adminstrator if you are unsure about using man pages on your system. You can also view the Legion man pages on-line. [Back]

2. Full path syntax can be used as well as relative syntax in all Legion commands.[Back]

3. In the interests of space and readability, in this and some of the following examples the entire LOID is not reproduced.[Back]

Other relevant on-line documents:
Click on the to go to the page.
Logging in to a running Legion system
Introduction to Legion context space
Context-related commands
Legion tty objects
Running a PVM code in Legion
Running a Legion MPI code
Running native MPI code 		Quick list of all 1.7 Legion commands
Usage of all 1.7 Legion commands
FAQs for running programs in Legion
Starting a new Legion system
Legion security
Legion host and vault objects
Adding host and vault objects
Brief descriptions of all on-line tutorials

Last modified: Tue May 2 16:59:42 2000

 

[Home] [General] [Documentation] [Software]
[Testbeds] [Et Cetera] [Map/Search]

legion@Virginia.edu
http://legion.virginia.edu/