Tutorial:
Legion 1.4 Context-related commands


Table of Contents

  View a context's contents
Looking up an object's LOID
Create a new context
Changing the working context
Checking the current working context
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
Copying a local file to a Legion file object
Copying a Legion file object
Viewing a file object's contents
Importing a local Unix directory tree

  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
Object permissions
Legion tty objects
Running an MPI code in Legion
Running a PVM code in Legion
Quick list of all Legion commands
Usage of all Legion commands
Starting and shutting down Legion 1.4
Using Legion security features
Legion host and vault objects
Adding host and vault objects
The list of all on-line 1.4 tutorials


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.


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 flag to get information about 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 legion_ls command will not list the "hidden" objects (such as those beginning with a "." character) unless you use the -a flag.

$ legion_ls -a /
.
Fooclass
Foofile
Fooobject
class
home
hosts
impls
vaults
$

The -L flag will list the LOIDs3 associated with the context's entries.

$ 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 also use this command to get information about an individual object, by using the object's context name as an argument. For example:
$ legion_ls -L Foofile
Foofile 1.01.66000000.02000000.00000...
$

Looking up an object's LOID

You can look up an object's LOID with the legion_ls command. The output will be a "dotted hex" LOID. You will need to include the object's context space name (its context path) as a parameter.
$ legion_ls -L /hosts/BootstrapHost
1.01.07.680c2608.000001fc0c1e0...
$

Create a new context

You can create new contexts with the legion_context_create command. This is similar to the Unix mkdir command. Note that the output includes the new context's location 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, as can be seen in the following example.
$ legion_set_context /tmp
The sub-context tmp is now the current working context.

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.

Checking the current working context

You can use the legion_pwd command to check your current working context. It will print your current context path on the command line. 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 alternate names to existing context names

Users can create alternate names for objects with legion_ln, a command similar to the Unix ln command. Note that it works only with objects that already have a context name. If no context name has been assigned, you will need to use a different command (such as legion_context_add: see also "Assigning a context name to a LOID") to assign a name to the LOID.

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

$ legion_ln /hosts/BootstrapHost Foo

$ legion_ls -la
.                             (context)
..                            (context)
Foo                                    
$
Note that BootstrapHost and Foo have different context paths but both point to the same object (a host object) and thus to the same LOID.
$ legion_ls -L 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 an object's LOID to a context name. 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.01.66000000.05... newName

Renaming an object

An object can be renamed with the legion_mv command (similar to the Unix mv command). In this example, object Foo is renamed Bar.
$ legion_mv Foo Bar
The name Foo is automatically removed from the current context. This process only affects a 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.

Listing an object's names

There are two commands that will show an object's context names: legion_list_names and legion_ls. Note, though, that you must use a context name as an argument for legion_ls, so you'll need to know at least one of the object's names.

Use the legion_ls command with the -A flag to look up an object's other (if any) name[s]:

$ legion_ls -A /hosts/BootstrapHost
/hosts/BootstrapHost
        /hosts/BootstrapHost
        /hosts/my.host.DNS.name
$
The legion_list_names command will list all context paths that have been assigned to a given object. If, for example, you knew an object's LOID but not its context name you could use the -l flag to ask Legion to look up the object's name. The output below asks for the context names that have been assigned to a LOID then shows that this is the BootstrapVault's LOID.
$ legion_list_names -l 1.360830b6.07.0100000...
/hosts/BootstrapVault
$
If you already know an object's name you can use the -c flag to see what (if any) other names it has. The example below shows that object BootstrapHost has two names, BootstrapHost and my.host.DNS.name:
$ legion_list_names -c /hosts/BootstrapHost
/hosts/BootstrapHost
/hosts/my.host.DNS.name
$

Removing names

You can remove (i.e., destroy) context name with legion_rm.
$ legion_rm Bar
Note that destroying a context name does not necessarily destroy its associated object. If there are other names assigned to the object legion_rm will just remove the specified name(s). If there are no other names, however, the object will be destroyed. For example, if you gave Foo an additional name:
$ legion_ln Foo Foo2
And then ran:
$ legion_rm Foo
The name Foo would be removed but the object would be unaffected. If you then ran:
$ legion_rm Foo2
The name Foo2 and the associated object would be destroyed, since Foo2 is its only context name. 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.

You can use legion_ls -A to check which names are mapped to an object.

$ legion_ls -A Foo
/Foo
        /Foo
        /Foo2
$
If you want to remove an entire context, use legion_rm -r: the -r flag recursively destroys a context and all of its contents.

Using the same name in different contexts

As discussed elsewhere, the same context name can be used to 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 Foo is assigned to a LOID with the legion_ln command.

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

Copying a local file to a Legion file object

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

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

Copying a Legion file object

The legion_cp command will also copy the contents ofa file object to a new file object.
$ legion_cp newFileObject newFileObject_copy
Use the -localdest flag to copy the contents of a Legion file object 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 Legion file object with the legion_cat command, similar to the Unix 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 directory 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 Legion file objects.

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.
$ 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"
$
Note that Legion copied the contents of the nextlevel subdirectory into a new sub-context called /nextlevel:
$ legion_ls -la /nextlevel
nextnothing3                   46 bytes
nextnothing2                   46 bytes
nextnothing                    43 bytes
..                            (context)
.                             (context)
$

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.[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]