Calls on objects

legion_exports_interface
    {-l <LOID> | -c <context path>}
    {-w <well-known class type> | -f <function signature>}+
    [-debug] [-help]

Creates an interface from the list of <well-known class type> and <function signature> arguments specified in the argument list. Sends this interface to the object specified by <LOID> or <context path> in the form of a call to the object mandatory function named exportsInterface(). Prints to standard output the return value from the call:

1	if the interface of the object contains the entire interface of functions specified by the user
0	if any one or more of the functions are not exported by the object
-1	(without contacting the specified object) if the user creates a malformed argument list

The <well-known class type> argument is a string in the set of well known strings, which can be listed via the legion_wellknown_class tool.

For the purposes of this tool, "ClassObject" is a well-known class string. "CommandLineClass" and "BootstrapMetaClass" are not considered well-known classes because they do not have any special member functions, as shown in the examples below.

$ legion_exports_interface -c LegionClass -w ClassObject
1
$

$ legion_exports_interface -c /class/LegionClass \
  -w CommandLineObject
"CommandLineObject" is not a well known class. Exiting.
usage: legion_exports_interface
{-l <class loid> | -c <legion space path>}
{-w <well known class type> | -f <function signature>}+
-1
$

$ legion_exports_interface -c LegionClass -w LegionClass \
  -w ClassObject
1
$

$ legion_exports_interface -c /hosts/BootstrapHost \
  -w UnixHostClass
1
$

$ legion_exports_interface -c /hosts/BootstrapHost \
  -w ClassObject
0
$

$ legion_exports_interface -c /class/LegionClass \
  -f "     LegionLOID ping();"
1
$

$ legion_exports_interface -c /hosts/BootstrapHost \
  -f "     LegionLOID ping();" -w UnixHostClass
1
$

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_get_interface
    {-l <class LOID> | -c <context path>}
    [-debug] [-help]

Retrieves the interface of a Legion object, named by <class LOID> or <context path>, by calling that object's getInterface() member function. Prints the returned interface to stdout.

This example returns the interface of the LegionClass (the metaclass for all Legion classes).

$ legion_get_interface -c class/LegionClass
Getting the interface of object:1.01.01..000001fc0b325...
Object Interface:
  void deactivate();
  RestoreStateReply restoreState();
  SaveStateReply saveState(SaveStateRequest);
  LegionLOID ping();
  LegionObjectInterface getInterface();
  int exportsInterface(LegionObjectInterface);
  int addAttribute(ObjectAttribute);
  int addAttributes(ObjectAttributeList);
  int replaceAttribute(ObjectAttribute, ObjectAttribute);
  int replaceAttribute_s(ObjectAttribute,
        ObjectAttribute);
  int replaceAttributes(ObjectAttributeList, 
	ObjectAttributeList);
  int replaceAttributes_s(ObjectAttributeSignatureList, 
	ObjectAttributeList);
  int removeAttribute(ObjectAttribute);
  int removeAttribute_s(ObjectAttributeSignature);
  int removeAttributes(ObjectAttributeList);
  int removeAttributes_s(ObjectAttributeSignatureList);
  LegionAttributeList retrieveAttributes(
        ObjectAttributeList);
  LegionAttributeSignatureList retrieveAttributes_s(
        ObjectAttributeSignatureList);
  LegionAttributeList retrieveAllAttributes();
$

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_ping 
    {-l <object LOID> | -c <context path>} [-timeout <seconds>]
    [-debug] [-help]

Calls the object-mandatory ping member function on the object named in <object LOID>. If the command returns, the object exists in an active state and its LOID is displayed. If the command does not return, the object is not accessible by the tool.

$ legion_ping -c foo
Pinging:  1.01.66000000.14000000.00...
Returned: 1.01.66000000.14000000.00...
$

The following options are supported:

-timeout <seconds>	The time-out flag specifies a maximum number of seconds to wait for the ping to complete successfully. If the object does not respond to the ping within that amount of time, legion_ping will exit. Please note that legion_ping failing due to a user-specified time-out does not necessarily mean that the object is inactive or otherwise unreachable. There is no default time-out setting.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_list_attributes
    {-l <object LOID> | -c <context path>} [-L] [<attribute name>]
    [-debug] [-help]

Lists an object's attributes from the command line. Optional parameters do the following:

-L	Lists the LOID of each attribute
<attribute name>	Specify the attribute to be listed (more than one attribute can be listed)
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

A very simple example of this command is below. An object's attributes can include architecture, operating system information, host or vault compatibility, encryption information, etc.

$ legion_list_attributes -c Foo
Foo:
  (ALL)
Total attributes retrieved 1
        favoritecolors('puce', 'apricot')
$

legion_list_invocations
    {-l <object LOID> | -c <object context path>}
    [-debug] [-help]

Prints a list of currently pending, started, and recently completed invocations for a given object. The output will include information about each invocation's status, timing, progress, and errors.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_object_info
    {[-c] <object context path> | -l <object LOID>} [-v]
    [-debug] [-help]

Prints information about a given object. The output (obtained from the object's class) will include the object's host, vault, owner, Object Address, status, etc. Optional parameters do the following:

-v	Print additional details about the specified object (host machine name and context name, OPA, and vault context name).
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_set_worm
    [[-c] <object context path> | -l <object LOID>]

This command tells Legion that the specified object has Write-Once Read-Many (WORM) semantics. It should be used in conjunction with the legion_set_backup_vaults command.

legion_unset_worm
    [[-c] <object context path> | -l <object LOID>]

This command tells Legion that the specified object no longer uses Write-Once Read-Many (WORM) semantics. It should be used in conjunction with the legion_set_worm command.

legion_update_attributes
    {[-c] <object context path> | -l <object LOID>} 
    [-a <new attribute>] [-d <attribute>] 
    [-r <old attribute> <new attribute>] 
    [-debug] [-help]

Adds, deletes, and replaces an object's attributes. The attribute(s) takes the form "name('val1 ... valn')". The attribute description must not contain any spaces or begin with an uppercase letter.

Optional parameters do the following:

-a <new attribute>	Add an attribute
-d <attribute>	Delete an attribute
-r <old attribute> <new attribute>	Replace an attribute
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

The following example adds the attribute color('red,blue') to object Foo, with the -a flag.

$ legion_update_attributes Foo -a "color('red,blue')"
legion_update_attributes:  Added 1 attributes(s) to object
$

Similarly, you can remove attributes, with the -d flag. Note, however, that if you must provide all of an attribute's parameters.

$ legion_update_attributes Foo -d "color('red')"
legion_update_attributes:  Warning - Deleted 0 attributes(s) from
object instead of 1 specified
     
$ legion_update_attributes Foo -d "color('red,blue')"
legion_update_attributes:  Deleted 1 attributes(s) from object
$

Calls on Class Objects

legion_activate_object 
    {-c <context path> | -l <object LOID>}
    [-debug] [-help]

Activates the object named in <object LOID> or <context path> (i.e., instantiates that object as a process) if it is inert. If the object is already active, the command has no effect.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_create_object
    {-l <class LOID> | -c <class context path>}
    <new object context path>
    [-h <host name on which to place new object>]
    [-v <vault on which to place new object>]
    [-H <context path of preferred host class>]
    [-V <context path of preferred vault class>]
    [-Ch <context containing list of preferred hosts>]
    [-Cv <context containing list of preferred vaults>]
    [-d <recorder context path> <debug session name>]
    [-debug] [-help]

Creates an object of the class named in <class LOID> or <class context path>. No start-up parameters will be supplied for the class or new object.

If the -h flag isn't used, the host is selected by the class in which you are creating an instance. Similarly, the class will choose a vault if the -v flag isn't used. Normally, this means that a random host is selected, but some classes may act differently. If the -Ch or -Cv flag is used, the class will randomly choose a host or vault from the hosts or vaults listed in the specified context. In both cases, the system will not return the LOID of the randomly chosen host. The legion_host_vault_list and legion_vault_host_list commands will allow users to limit the placement of a given class's instances (i.e., any instances of class Foo can only be placed on hosts X, Y, and Z).

The following options are supported:

-h	Specify a host for the new object
-v	Specify a vault for the new object
-H	Specify the preferred host class's context path
-V	Specify the context path of the preferred vault
-Ch	Specify a context which contains a list of the preferred hosts
-Cv	Specify a context which contains a list of the preferred vaults
-d	Automatically start a legion_record session for the newly created object. This allows you to debug server objects. The object's relevant activity will be recorded by a previously started Legion recorder object, named in <recorder context path>.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_create_object_r 
    {-l <class LOID> | -c <class context path>} 
    <context path> <host name> <host architecture> 
    <$LEGION> <$LEGION_OPR> <$LEGION_OPA> <binary path>
    [<user id>]
    [-debug] [-help]

Causes the specified class object to create a new object on the host named in <host name> using the rsh (remote shell) mechanism. The object will be managed with rsh, if the class it is invoked on is an rshStartClass. If this utility is invoked on a normal class, normal object create mechanism will be used, and the object will not be managed by rsh. This command is generally used only by the legion_create_host and legion_create_vault scripts, not by users.

The additional arguments specify information for the rsh environment.

<host name>	Specifies the host upon which the new object should be placed. Note that this should be a DNS name
<host architecture>	Specifies the host's architecture
<$LEGION>	Specifies the Legion environment variable on the rsh host
<$LEGION_OPR>	Specifies LEGION_OPR for host
<$LEGION_OPA>	Specifies the OPR address for the object, i.e, a unique directory in which the object will maintain its persistent representation on the remote host
<binary path>	Binary executable path for the object on the remote host

Optional parameters do the following:

<user id>	Specifies the appropriate user name on the rsh host
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_deactivate_object
    [-debug] [-help] [-stay_down]
    {-l <object LOID> | -c <context path>}
    

Deactivates the object named in <object LOID> or <context path> (moves it to an inert state) if it is currently active. If the object is already inactive, the command has no effect.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.
-stay_down	Forces object to stay inactive. It can only be reactivated by legion_allow_activation.

legion_destroy_object 
    {-l <object LOID> | -c <context path>}
    [-debug] [-help]

Deletes the object named in <context path> or <object LOID>. More specifically, it removes the object's LOID but not its context name (if there is one). If the object is active, the command deactivates the object. In all cases, it deletes the OPR (object persistent representation) associated with the object.

This command will not remove an object's context name: you must use the legion_rm command to remove the context name(s) or you will get binding errors in that context. (You can use legion_ls -A to check for multiple context names.)

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_get_host {-l <object LOID> | -c <object context path>}
    [-debug] [-help]

This command looks up and returns the LOID of the host on which the object named in <object LOID> or <object context path> resides.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_get_vault {-l <object LOID> | -c <object context path>}
    [-debug] [-help]

Returns the LOID of the vault which the object named in <object context path> or <object LOID> is currently using to store its OPR.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_list_implementations [-vL] {-l <class LOID> | [-c] <class context path>}
    [-debug] [-help]

Lists the implementation objects associated with the class named in <class LOID> or <class context path>. In its default setting the output will consist of each implementation object's LOID and architecture type. If the -vL flag is included, the output will include byte size and a brief description of each object.

The following options are supported:

-vL	Run the command in a verbose setting
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

Note that if the -v flag is used Legion will use one extra method invocation per implementation object.

legion_list_instances {-l <class LOID> | -c <context path>}
    [-debug] [-help]

Displays information about the instances of the class named by <context path> or <class LOID>. For every instance, the tool displays the class's LOID, current object address, status (active or inert), the host on which it resides, and the vault that holds its OPR. The example below shows that class BasicFileClass has two instances, and that both are currently running.

$ legion_list_instances -c /class/BasicFileClass
Class 1.01.66000000..000001fc0d63e97... knows about
the following instances:
LOID: 1.01.66000000.01000000.000001fc0a00...
        Current oa   : [xxx.xxx.xxx.xxx : 2020]
        Current host : 1.01.07.30232908.000001fc0...
        Current vault: 1.01.03.2e232908.000001fc0...
        Status       : object-running
LOID: 1.01.66000000.02000000.000001fc0edd...
        Current oa   : [xxx.xxx.xxx.xxx : 1895]
        Current host : 1.01.07.31232908.000001fc0...
        Current vault: 1.01.03.2e232908.000001fc0...
        Status       : object-running
$

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_refresh_local_cache

In a login session, the local binding agent caches some high-use objects' bindings and high-use contexts' LOIDs. These bindings may become stale, in which case you can manually refresh them with this tool. We suggest running it if you notice a consistent delay of around thirty seconds before and after commands respond.

legion_set_backup_vaults
     {[-c] <instance context path> | -l <instance LOID>}
     [-nodeac[tivate]]
     {[-a | -d] [-c <vault1 context path> | -l <vault1 LOID>]
           [-a | -d] [-c <vault2 context path> | -l <vault2 LOID>] ...
           [-a | -d] [-c <vaultn context path> | -l <vaultn LOID>]}
     | {-Cv <vault context path> -n <total number of vaults>}

Specify one or more backup vaults for an object. Backup vaults are used to replicate an object's persistant state: the object's persistant state is replicated and stored in multiple vaults when it is deactivated, so that if its main vault crashes the object's state is still available. However, the replication policy synchronizes the object's state when the object deactivates, so if the main vault crashes whle the object is still alive, the backup vaults will not have the object's most current state. If the object needs to be reactivated, it will use an out-of-date state.

Therefore, this command should only be used for objects that can tolerate potentially old states. As of the 1.7 release, this functionality is supported for the following classes: ContextClass, BasicFileClass, AuthenticationObjectClass, and ImplementationObjectClass.

You can either give a list of specific vaults or a context path from which a specified number of vaults will be selected. For example, to add Vault2 and Vault3 to object Foo's list of backup vaults, you would enter:

$ legion_set_backup_vaults /home/mycontext/Foo -a /vaults/Vault2 \
   -a /vaults/Vault3

To add any two vaults from the /vaults context, you would enter:

$ legion_set_backup_vaults /home/mycontext/Foo -Cv /vaults -n 2

Use legion_object_info to view an object's list of backup vaults.

The following options are supported:

-nodeac[tivate]	Do not deactivate the specified object when setting up its backup vaults.
-a	Add the specified vault to the object's list of backup vaults.
-d	Delete the specified vault from the object's list of backup vaults.
-Cv	Select the backup vaults from the specified context path.
-n	Number of vaults to be selected.

legion_set_binding_agent
     [-unset] [-make_default] [-make_default_only]
     {-l <object context path> | -c <object LOID>} 

Set or unset the binding agent named in <object context path> or <object LOID> as the user's current and/or future login session binding agent. The following options are supported:

-unset	Clear the current binding agent.
-make_default	Set the specified binding agent to be the user's binding agent for the current login session and any future login sessions.
-make_default_only	Set the specified binding agent to be the user's binding agent for the any future login sessions but do not set it as the current session's binding agent.

legion_set_host {-l <instance LOID> | -c <instance context path>} 
    {-l <host LOID> | -c <host context path>}
    [-debug] [-help]

Calls the set_host() class-mandatory member function on the class of the object named by in <object LOID> or <object context path>, causing that object to migrate to the host named in <host LOID> or <host context path>.

In the example below, object Foo's host is changed from BootstrapHost to newHost.

$ legion_set_host -c Foo -c /hosts/newHost

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_set_vault {-l <instance LOID> | -c <instance context path>}
    {-l <vault LOID> | -c <vault context path>}
    [-permanent] [-debug] [-help]

Moves the OPR of the object named in <object LOID> or <object context path> to the vault named in <vault LOID> or <vault context path>.

The following options are supported:

-permanent	Makes the migration permanent. I.e., the object's acceptable vault list will be change to list only the new vault. No further migration can occur without user intervention (via the legion_instance_vault_list command)
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

Be careful with the -permanent flag. If none of the instance's acceptable hosts match the chosen vault (i.e., there are no compatible host-vault pairs) the instance cannot be reactivated. Alternatively, the chosen vault may be compatible only with hosts for which the class has no implementation.

Please note that this command can fail for many reasons, including:

• the instance does not exist
• the user does not have permission to perform the migration
• the target vault does not exist
• the target vault will not grant the request to create a new OPR for the object
• the source vault is unavailable or will not grant the request to get the current OPR
• other machine or system failure
• the specified vault is unacceptable

The class object will enforce the current restrictions on its instance's acceptable vaults before it migrates the object's state. You may need to change the instance's list of acceptable vaults (via the legion_instance_vault_list command) to include the target vault before running legion_set_vault. This command is not exactly the equivalent of a true object migration, since the object is not reactivated after its state is moved. Where the object reactivates depends on the scheduling decision made at the time the reactivation occurs. If the -permanent flag is not used and the instance's acceptable vault list is not otherwise altered, future activations of the instance may be on different vaults. If the -permanent flag is used, all future activations must use the specified vault, until the acceptable vault list is altered. >

legion_synch_vaults
     {[-c] <instance context path> | -l <instance LOID>}
     [-nodeac[tivate]]

Synchronize the specified object's state in its main and backup vaults. The command copies the state contained in the object's main vault to all of its backup vaults. It will deactivate the object before synchronizing vault state unless the -nodeactivate flag is used.

If the object has been marked as Write-Once Read-Many (WORM) with the legion_set_worm command, its state does not change. You can still run this command for a WORM object, but it is not necessary.

This command is implicitly called upon object deactivation.

As of version 1.7, this funcationality is supported for ContextClass, BasicFileClass, AuthenticationObjectClass, and ImplementationObjectClass objects.

The following option is supported:

-nodeac[tivate]

Do not deactivate the specified object when setting up its backup vaults.

Calls on LegionClass

legion_add_class_mapping <metaclass LOID> <class LOID>
    [-debug] [-help]

This command notifies LegionClass that the meta-class named by <metaclass LOID> is the class of the class named by <class LOID>. LegionClass updates its class map accordingly.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_combine_domains [-v] <list of domain cookie files>
    [-debug] [-help]

Joins a set of Legion domains (systems) to create a single, larger, multi-domain Legion system. Before you run this command, you must obtain a copy of the Legion domain cookie files from all of the involved domains (see legion_generate_domain_cookie and legion_print_domain_cookie), including the current Legion domain. If you are joining domain A to domain B and domain B has already been joined to domain C, you will need cookie files from domains A, B, and C. This provides transitivity in the system join. All three domains will be joined to one another to form a single system. The command is implemented this way to avoid communication failures; if a LOID can be passed to an object (e.g., in a method continuation list), that object should be able to use the LOID for further communication.

Non-transitive or non-reflexive joins would allow communication of LOIDs for which an object could not obtain a binding. For example, object X in domain A might be able to bind to object Y in domain B and pass a method to it, but object Y might not be able to bind to object X to pass it the return value.

In addition to joining the binding trees of the involved domains, legion_combine_domains also creates context links in the current domain's context space to all of the remote domains' root contexts. These links appear in local context space in the following path: /domain/LegionDomain.<domain-id>.

If the command is run on domains that are already connected, it has no affect and is harmless.

There is currently no mechanism supporting "unjoining" of domains. However, Legion security mechanisms (e.g., ACLs) can be used to effectively forbid any use of the current domain by outside domains.

The following options are supported:

-v	Provide a verbose output as the command is running.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

The example below combines two domains. If either had previously been connected to another domain, three cookie files would be listed.

$ legion_combine_domains LegionDomainCookie.35d82a07 \
     LegionDomainCookie.c8
Created 2 new domain interconnections.
$

legion_create_implementation 
    <binary path name> <architecture>
    [-l <class LOID> | -c <class context path>]
    [-c <object context path>] [-nc] [-v] [-a <attribute>]
    [-debug] [-help]

Creates an implementation object based on the binary executable named in <binary path name>. The new implementation object is associated with the class object named in <class LOID> or <context path>, and is marked as usable for hosts of a specified type (Linux, Solaris, or SGI).

The following options are supported:

-c <context path>	Specify a context path for the new object. Default is /impls/<binary_name>.<architecture>.<#>.
-nc	Specify that the new object have no context name.
-v	Run the command in verbose mode.
-a <attribute>	Assign the new object an extra attribute.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_generate_domain_cookie 
    [-o <cookie output filename>]
    [-debug] [-help]

Generates a domain cookie file for the current Legion domain, as required by legion_combine_domains. A cookie file contains binding information for the LegionClass in the current domain, security credentials for joining to the current domain, and information about the context space of the current domain (for creating interdomain context space links). The default cookie file name is LegionDomainCookie.<domain-id>, or you can use the -o flag to specify a name.

In a secure environment, you must be logged in as /users/admin for the current domain. This ensures that the required credentials can be generated and saved in the cookie file.

The following options are supported:

-o <cookie output filename>	Specify the local pathname of the resulting output cookie file.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_init_arch
    [-debug] [-help]

Creates and registers implementation objects for commonly used classes in the current architecture. This command is run on new hosts, so as to create the implmentation objects in the proper place. Implementation objects for specific binary executables can be created with the legion_create_implementation utility.

$ legion_init_arch
Initializing Legion implementations for "linux"

Creating an implementation (ContextObject) for
   ContextClass
Continue (y=yes, Y=yes to all, n=no, N=no to all, 
     v=verbose, V=verbose all)? Y
Creating an implementation (MetaClassObject) for
   LegionClass
Creating an implementation (ClassObject) for
   VanillaMetaClass
Creating an implementation (BindingAgent) for
   BindingAgentClass
Creating an implementation (BasicFileObject) for
   BasicFileClass
Creating an implementation (ttyObject) for
   ttyObjectClass
Creating an implementation (StatTreeObject) for
   StatTreeClass
$

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_list_domains
    [-debug] [-help]

List the domains currently connected to your current Legion domain. The output will list the binding for your current domain and any domains linked to your current domain. Please see legion_combine_domains for information about connecting Legion domains.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_print_domain_cookie
    [-i <cookie input file>]
    [-debug] [-help]

Displays the contents of a Legion domain cookie file (required for using legion_combine_domains). By default the command displays the contents of the file LegionDomainCookie.<current-domain-id>, but any input file name can be specified using the -i option.

The following options are supported:

-i <cookie input filename>	Specify the path of the cookie file to print.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

Calls on File and Context Objects

legion_activate_instances
    {-l <class LOID> | -c <class context path>}
    [-debug] [-help]

Activates all instances of the class named in <class context path> or <class LOID>. Instances that are already active will be unaffected.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_allow_activation
    [-entire_class] [-debug] [-help]
    {-l <LOID> | -c <context path>}

Activates the object or instances of the class named in <context path> or <LOID>. This should be used in association with the -stay_down option of legion_deactivate_object or legion_deactivate_instances.

The following options are supported:

-entire_class	Unlock all of the class's instances. You must be the class's owner in order to use this option.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_cat <context path1> <context path2> ... <context pathN>
    [-debug] [-help]

Prints the contents of the Legion file object(s) named in <context path> to standard output. It is similar to the Unix cat command.

$ legion_cat newFileObject
This is a test, just a test, nothing more.
$

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_cd <context path>
    [-debug] [-help]

Changes the current working context to the context named in <context path>. Note that the path name can be relative or absolute. This command is identical to the legion_set_context command and analogous to the Unix cd command .

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_context_add <object LOID> <context name>
    [-debug] [-help]

Adds a new name <context name> for the object named in <object LOID> to the current context space.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_context_create <context path>
    [-debug] [-help]

Creates a new context in Legion context space, and assigns it the name given in <context path>. This command is analogous to the Unix mkdir command. The new context will be placed in your current context. The output will contain the new context's location and its LOID.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_cp 
     [-r] [-v] [-m] [-p] [-localsrc] [-localdest] 
     [-V <vault context path>] <source file> <destination file>
    [-debug] [-help]

Copies the file named in <source file> (named as either a context path or a local path) to a new, duplicate, file object named in <destination file> (named as either a context path or a local path). The command is analogous to the Unix cp command. For example, to copy the file object Foo to /home/myContext/Bar, you would enter:

$ legion_cp Foo /home/myContext/Bar

You can now use wildcards in the <source path> parameter (for context space or local file space). Please note that you must escape the "*" character. The example below copies all files that start with "Foo" from local directory space into the /home/myContext context.

$ legion_cp -localsrc Foo\* /home/myContext

The new file objects are assigned the same names (e.g., if Foo\* finds Foo1 and Foo2, the duplicate file objects will be at /home/myContext/Foo1 and /home/myContext/Foo2).

Note that you cannot use wildcards in a destination path and you cannot copy multiple files to a single file object.

The following optional parameters are supported:

-v	Verbose mode. Prints information about which files and directories the command is currently working on.
-r	Recursive mode. If the <source path> is a directory, all of its contents are copied recursively. Only files and contexts/directories are handled. If other objects are encountered, they are skipped and legion_cp prints a warning message. Note that recursive mode automatically detects cycles in context space and prevents the recursive copy from revisiting context nodes in the cycle. A warning message is printed in the event that cycles are detected.
-localsrc	Indicates that the source path (<source path>) is in the local files system
-localdest	Indicates that the target path (<destination path>) is in the local file system.
-V <vault context path>	Specify a vault restriction for new objects created by this command. Supply the context path of the vault that should manage new objects created as legion_cp runs.
-m	Match-class mode. This mode indicates that when files or contexts are created by this command, they should match the class of their source context or file. By default, new files and contexts are created using the default file and context classes for your current Legion environment. This mode can only be used when copying within Legion context space (i.e., when no -localsrc or -localdest options are specified).
-p	Print out the size, transfer time, and transfer rate for each file copied.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_deactivate_instances 
    [-debug] [-help] [-stay_down]
    {-l <class LOID> | -c <class context path>}

Deactivates all instances of the class named in <class context path> or <class LOID>. Instances that are already deactivated will be unaffected.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.
-stay_down	Forces instances to stay inactive. It can only be reactivated by legion_allow_activation.

legion_destroy_instances 
    {-l <class LOID> | -c <class context path>}
    [-debug] [-help]

Destroys all instances of the class named in <class context path> or <class LOID>. If any instances are active, they are deactivated.

This command will remove the LOIDs of the specified class' instances in all contexts, not just the current context. However, it will not remove the context names: you must use the legion_rm command to the object's name(s), or you will get binding errors. (You can use legion_ls -A to check for multiple context names).

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_direct_output {-l <LOID> | -c <object path>}
    {-l <tty LOID> | -c <tty context path>}
    [-debug] [-help]

Causes the object named in <object path> or <LOID> to direct its output (standard out and standard error) to the Legion tty object named by <tty LOID> or <tty context path>. Note, this command can only be invoked on objects that have dynamic output redirection enabled. If the command is invoked on an object that does not have redirection enabled, neither the object nor the tty is affected and an error message is displayed.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_export_dir [-v] [-fc] [-cc]
    <local base directory path> <target base context path>
    [-debug] [-help]

The legion_export_dir command allows a complete directory tree in the local file system to be linked into Legion context space without requiring the creation of file copies. A matching context will be created to match the local directory tree, and the context names will match the local directory's file names. However, the command executes for the duration of time that you wish to use the exported files and directories: if you pause the command the tree's context space will not be available. Once you resume the command, however, the context space will be available. To pause the command, press "Control-C". To resume using the exported files, re-execute the command, specifying the same local base directory path and target context path.

Use of exported files and directories while the command is not active will cause binding errors. The context space will not be automatically removed when the command is paused or stopped. To delete an exported directory tree's context space, use legion_rm -r while legion_export_dir is active.

For best results, do make any changes to the exported directory tree or to the tree's context. Any changes that you make to the context, such as changing or removing context names, will not be reflected in the local directory tree (and vice versa). For this same reason you should delete the tree's context space when you are finished.

Optional parameters do the following:

-v	Verbose mode. Prints information about which files and directories the command is currently exporting.
-fc	Specify the context path of the class to use for file objects. This class should be an instance of the metaclass "/class/ProxyBindingMetaClass", since the style of file object used by legion_export_dir requires specialized binding services. The default is "/class/ContextProxyClass".
-cc	Specify the context path of the class to use for context objects. This class should also be an instance of "/class/ProxyBindingMetaClass". The default used is "/class/FileProxyClass".
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_get_host {-l <object LOID> | -c <object context path>}
    [-debug] [-help]

This command looks up and returns the LOID of the host on which the object named in <object context path> or <object LOID> currently resides.

$ legion_get_host -c Foo
1.01.07.d49d1a40.000001fc0c04724...
$

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_get_vault {-l <object LOID> | -c <object context path>}
    [-debug] [-help]

Returns the LOID of the vault which the object named in <object context path> or <object LOID> is currently using to store its OPR.

$ legion_get_vault -c Foo
1.01.03.d49d1a40.000001fc0a69cbb8...
$

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_import_tree [<unix directory path> [<legion context path>]]
    [-debug] [-help]

Recursively copies a local directory tree in Unix space, named by <unix directory path>, into a Legion context, named by <legion context path>. The output will include the new context's LOID and location. Pathnames can be relative or absolute. Default values are the current working directory and the current working context.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_list_names {-l <object LOID> | -c <object context path>} 
    [-debug] [-help]

Lists all of the given object's context names. This includes names assigned by other users.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_ln <context path> <new alias>
    [-debug] [-help]

Assigns an additional name, given in <new alias>, to the object named in <context path>. Analogous to the Unix ln command. Path names can be relative or absolute.

An object can have multiple context names, assigned by one or more users. The same context name can be assigned to different objects or to the same object so long as the contexts names are in different contexts (just as the same file names can be used in different levels of a Unix directory).

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_ls [-laLRAdqv] [<context path>]
    [-debug] [-help]

Lists the contents of a named Legion context in ascii-alphabetical order. Note that the pathname can be relative or absolute. The command is analogous to the Unix ls command. The default setting lists the current context. You can include a context path in the <context path> parameter to list the contents of that context. For example:

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

You can now use wildcards in the <context path> parameter. Please note that you must escape the "*" character. I.e., to search for context objects containing "foo" in their names you would enter:

$ legion_ls \*foo\*

You cannot use wildcards with the -R flag.

Optional parameters do the following:

-l	List object type and information, if available. Objects of unknown type will be listed as object and faulty objects will be listed as not available.
-a	List "hidden" objects in the context, i.e. those objects whose names begin with a "." character. Examples would be the "." (current) and ".." (parent) contexts.
-L	Lists LOIDs associated with names.
-R	Print a recursive listing of the current context. You cannot use this flag with wildcards.
-A	List all known context aliases for each listed object.
-d	List contexts like other objects, rather than listing their contents.
-q	When creating a long listing, do not activate inactive objects.
-v	Run command in verbose mode.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

You can get more information about the objects in the current or a selected object or about a particular object by including one or more flags and a context path name. The output below combines the -l, -a, and -A flags to get a list of all objects in the /hosts context, their type, and all of their context names.

$ legion_ls -laA /hosts
.                              (context)
        /hosts
..                             (context)
        /class/..
        /hosts/..
        /vaults/..
        /home/..
BootstrapHost                  (object)
        /hosts/BootstrapHost
        /hosts/stonesoup01.cs.virginia.edu
stonesoup01.cs.virginia.edu    (object)
        /hosts/BootstrapHost
        /hosts/stonesoup01.cs.virginia.edu
$

According to this, there are four names listed in /hosts, two referring to contexts and two to objects. We can see from the alternative context names, though, that BootstrapHost and my.host.DNS.name refer to the same object.

legion_make_hostlist
    {-h <new host context>} {-f <file1> <file2> ... <filen>}
    [<host context path>] [-v] [-help]

Creates a new context which contains a list of host context names. The new context contains links (via legion_ln) to the specified hosts. All host names provided in the -f and <host context path> parameters are concatenated into the new context in your current working context.

This host list context can be used to run a Legion class object (e.g., a Legion MPI program with legion_mpi_run).

The following parameters are used:

-h <new host context>	The name of the new context that you wish to create. It will be placed in your current working context.
-f <file1> <file2> ... <filen>	One or more local text files that contains a list of host context paths.

The following options are supported:

<host context path>	The context path of a host that you wish to include in the new context. You can list as many of these as you wish.
-v	Run the command in verbose mode.
-help	Print command syntax and exit.

The example below will create a new context called /myList. The new context will contain pointers to HostA, HostB, and the hosts named in List1.

$ legion_make_hostlist -h myList -f List1 hosts/HostA hosts/HostB

Caveat: Since this command uses legion_ln to connect to your hosts, if you are in a system with Legion security turned on you will not be able to make back pointers to contexts that are owned by admin. Generally, /hosts will be owned by admin in a secure system. So, when you link to hosts listed in /hosts, you may get error messages saying "unable to set attributes on linked objects." Similarly, removing hosts from the context may get messages saying "unable to remove context path mylist/hostA."

legion_mkdir <context path>
    [-debug] [-help]

Creates a new context in Legion context space, and assigns it the name given in <context path>. This command is analogous to the Unix mkdir command (it is also identical to the legion_context_create command). The new context will be placed in your current context. The output will contain the new context's location and its LOID.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_mv <context path> <new context path>
    [-debug] [-help]

Assigns a new context name, given in <new context path> to the object named in <context path>. Pathnames can be relative or absolute. Analogous to the Unix mv command.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_pwd
    [-debug] [-help]

Prints your current context path (similar to the Unix pwd command).

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_rm [-r] [-f] [v] <context path list>
    [-debug] [-help]

Removes the context path[s] named in <context path list> from Legion context space. Pathnames can be relative or absolute. Analogous to the Unix rm command.

If the context path listed is the last (i.e., only) name mapped to a given object, the object will be destroyed. If there are other names mapped to the object, the object will be removed.

You can now use wildcards in the <context path list> parameter. Please note that you must escape the "*" character. I.e., to remove all context objects containing "foo" in their names you would enter:

$ legion_rm \*foo\*

Optional parameters do the following:

-r	Recursively remove one or more contexts and all of their contents.
-f	Force faulty objects (those with bad bindings) to be removed.
-v	Run this command in a verbose setting. This will indicate when objects are destroyed and when only names are being destroyed.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_set_context <context path>
    [-debug] [-help]

Changes the current working context to the context named in <context path>. Note that the path name can be relative or absolute. Analogous to the Unix cd command.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_set_tty <tty context path>
    [-debug] [-help]

This command will set an environment variable to indicate which tty object should be used by subsequent programs. By selecting a new current tty object, users can redirect the output to any window or file.

$ legion_set_tty /context_path/my-tty

Note that program output does not have to be directed to the same window in which the program is run. By setting a new current tty object, the output can be redirected to any window, or even a file. For example:

$ legion_create_object -c /class/ttyObjectClass \
  /context_path/my-tty
$ legion_set_tty /log-file

creates a tty object whose output is sent to a file. To view the tty output, use the legion_tty_watch command.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_tty <tty context path>
    [-debug] [-help]

This command can be used to direct all output from a particular shell back to that shell--i.e., create and set a tty object for a shell--in one step, rather than running legion_create_object, legion_set_tty, and legion_tty_watch. If no tty object exists at the path named in <context path> it creates a new object, sets it as the target tty, and starts the legion_tty_watch process in the background of the shell in which the command was run. If a tty object already exists at the named context path, the command sets that tty object as the target tty.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_tty_off
    [-debug] [-help]

Turns off the backgrounded legion_tty_watch process for that shell, i.e., stops directing the shell's output back to itself. Note that this only works when coupled with the legion_tty command (above).

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_tty_redirect <object context path>
    [-debug] [-help]

Causes the Legion tty object currently set in the shell environment to stream directly into the file object named in <context path>. If the file does not already exist the system creates it. Existing files are appended to, not truncated. A single tty object can be simultaneously directed into any number of files (as well as watched from any number of terminal windows).

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_tty_unredirect <object context path>
    [-debug] [-help]

Causes the Legion tty object currently set in the shell environment to stop streaming into the file object named in <context path>. If the tty object is not currently directing output to the named file the command is ignored.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_tty_watch [-l <tty LOID> | -c <tty context path>]
    [-debug] [-help]

Causes output written to a Legion tty object to be printed to standard output. If no command line parameters are specified, the current tty object set for the shell session is selected. Otherwise, the tty object named by <LOID> or <context path> is selected. Note, the command will not self-terminate: to stop the program send it a SIGINT (i.e., using ^C or "kill -INT"). Any number of legion_tty_watch sessions smay simultaneously watch the same Legion tty object.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

Start-Up and Shutdown Functions

legion_add_host_account
    {-l <host object LOID> | [-c] <host object context path>}
    {[-f <mapping file name>] | [<Unix user id> [-l <owner LOID> | -c <owner context path>]]}
    [-debug] [-help]

This command is used on PCD host objects. Adds a mapping between a Legion account and a Unix account and adds this mapping to a PCD host object's list of available accounts. The user's Unix user id is named in the <Unix user id> parameter. The host object is named in the <host object LOID>/<host object context path> parameter. The user's Legion user id can be given in the <owner LOID>/<owner context path> parameter.

The following optional parameters are supported:

-f <mapping file name>	Names a mapping file. The mapping file contains a list of Unix user id-Legion user name mappings for that PCD host object. There is no limit on the number of mappings that can be listed. One mapping per line. If a Unix id is listed but not mapped to a Legion user id, the account will be a guest account.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_create_class [-c <context path>] 
    [-sc <scheduler context path>] [-sl <scheduler LOID>]
    [-debug] [-help]

Creates a new instance of class VanillaMetaClass. The object will be placed in the current working context, unless specified with the -c flag. The following optional parameters are supported:

-c	Assign the new object the name given in <context path>
-sc <scheduler context path>	Specify the context path of the default scheduler object that the new class should use.
-sl <scheduler LOID>	Specify the LOID of the default scheduler object that the new class should use.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_destroy_host [-v] 
    {-l <host LOID> | -c <host context path>}
    [-debug] [-help]

Destroy a given host object. All contexts objects on that host will be destroyed and all active objects will be deactivated. Optional parameters do the following:

-v	Run in verbose mode.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_destroy_vault {-l <vault LOID> | -c <vault context path>}
    [-debug] [-help]

Destroy a given vault object. Legion will attempt to move all of the vault's current OPRs off of the vault object and then destroy the vault object. If any OPRs cannot be successfully moved the process will abort and an error message will be displayed.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_initialize
    [-debug] [-help]

Populates the Legion system with basic classes and implementations. This command should be run after a Legion system is started for the first time (using legion_startup). On subsequent activations of the system, the state created by this utility will already exist, so this command should not be run again.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_list_host_accounts
    {-l <host object LOID> | [-c ]<host object context path>}
    <user id> [-debug] [-help]-help]

This command is used on PCD host objects. It removes one or more account mappings from the host object's list of available accounts. The parameter is the user's Unix user id. If no host is named in the <host object LOID>/<host object context path> parameter, your current host object will be the default host.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_make_setup_script [-o <script basename>] [-OPR <OPR dir name>]
    [-L <$LEGION dir name>]
    [-debug] [-help]

Generates a Legion setup script for your system. This script sets the environment variables for Legion users.

The following options are supported:

-o <script basename>	Specify the basename for the resulting setup scripts (default is /home/xxxx/OPR/setup). This command will generate two setup scripts, one for /bin/sh derivative users and one for csh-derivative users. The scripts will be named <script basename>.sh and <script basename>.csh, respectively.
-OPR <OPR dir name>	Specify the OPR directory name that will be set up when the resulting scripts are run. This directory will contain the user's local copy of Legion-Class.config (default is "Legion-OPR"). The user's local version of the directory will be placed in the user's $HOME.
-L <$LEGION dir name>	Specify the value of $LEGION, which is the directory where the resulting scripts are run. The default is the current value of $LEGION.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_print_config
    [-debug] [-help]

Prints the "well-known" binding for LegionClass in the current Legion configuration.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_remove_host_account
    [-l <host object LOID> | [-c] <host object context path>]
    [-debug] [-help]-help]

This command is used on PCD host objects. It lists the available accounts on a host object. If no host object argument is provided, your current host object will be used as a default.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_setup_state [-i]
    [-debug] [-help]

Creates OPRs for the basic Legion system objects. This script should be run when starting a Legion system for the first time.

The following options are supported:

-i	Run the command in an interactive mode.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_shutdown [-local] [-f] [-i] [-h]
    [-debug] [-help]

Shuts down a running Legion system, preserving the state of all objects for subsequent reactivation of the system. Optional parameters allow users to shut down individual hosts and to specify an interactive shutdown.

Optional parameters do the following:

-local	Shuts down only a local host or vault.
-f	Forces the termination of a system, may leave processes running and prevent a system restart.
-i	Puts the shutdown in an interactive mode, which will provide prompts for user actions.
-h	Returns the command's complete syntax.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_shutdown_class 
    {-l <class LOID> | -c <context path>}
    [-debug] [-help]

Deactivates the class object named in <class LOID> or <context path> and all of its instances. This command operates recursively: if applied to a metaclass, for example, it would deactivate the metaclass, all of its class instances, all of their instances, etc.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_starthost 
    [-L <$LEGION>] [-O <$LEGION_OPR>] [-A <$LEGION_ARCH>] 
    [-B <path>] [-N <context name>] [-U <user id>] 
    <new host name> [<compatible vault list>]
    [-debug] [-help]

Creates a new host object on the specified <new host name>, using the legion_create_object_r command (which is automatically invoked on the host class). The <new host name> is the host's DNS name. The legion_starthost command selects the following default values for the new object:

<$LEGION_OPA>	= $LEGION_OPR/Host-$HOST.OPA
<binary path>	= $LEGION/bin/$LEGION_ARCH/UnixHostObject

Optional parameters do the following:

-L <$LEGION>	Specify $LEGION for host (default is "/home/Legion")
-O <$LEGION_OPR>	Specify $LEGION_OPR for host (default is current $LEGION_OPR)
-A <$LEGION_ARCH>	Specify the architecture type for the host (default is current $LEGION_ARCH)
-B <path>	Specify the basename of the host binary (default is "UnixHostObject")
-N <context name>	Specify the context name for the host object (default is "/hosts/<host name>")
-U <user id>	Specify the user id for host (default is current user id)
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_startup [-local]
    [-debug] [-help]

Starts up basic Legion services.

The following optional parameters are supported:

-local	starts up only a local host or vault
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_startvault 
    [-L <$LEGION>] [-O <$LEGION_OPR>] [-A <$LEGION_ARCH>] 
    [-N <context name>] [-U <user id>] <host name>
    [<compatible host list>]
    [-debug] [-help]

Creates a new vault object on the specified <host name>, using the legion_create_object_r command (which is automatically invoked on the host class). The <host name> is the host's DNS name.

The following optional parameters are supported:

-L <$LEGION>	Specify $LEGION for the vaults host (default is "/home/Legion")
-O <$LEGION_OPR>	Specify $LEGION_OPR for the vaults host (default is "/home/OPR")
-A <$LEGION_ARCH>	Specify the architecture of the vaults host (default is current $LEGION_ARCH)
-N <context name>	Specify the context name for the vault object (default is "/vaults/vault-<host name>")
-U <user id>	Specify the user id to use on the vaults host (default is current user id)
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

Scheduling Support

legion_add_sub_collection
    {-l <collection LOID> | -c <collection path>}
    {-l <member LOID> | -c <member path>} [-q <query>]

This command creates a new parent-subcollection relationship. A subcollection is a collection object that is polled by another collection object (called the parent collection) with a specified MESSIAHS-type query. If no query is specified, the default value of 'true' will be used. You can run this command multiple times to start multiple queries on a single subcollection.

A parent collection can have more than one subcollection and can run multiple queries on a single subcollection. A subcollection can have more than one parent as well as its own subcollections.

You must designate a parent collection (named in <collection LOID> or <collection path>). The member (named in <member LOID> or <member path>) is the subcollection. Both collections must already exist.

You can edit the collection_update_frequency_secs attribute with the legion_update_attributes command. E.g.,

$ legion_update_attributes -c /etc/Collection \
"collection_update_frequency_secs(600)"

will set the default collection to update itself every 10 minutes. The default setting is 300 seconds.

The following option is supported:

-q <query>

A MESSIAHS-style query that will be run on the subcollection. The default selection is 'true'. See legion_query_collection for details.

legion_class_host_list 
    [-l <class LOID> | -c <class context path>]
    [{-a | -d | -t} <host1> <host2> ... <hostn>] [-p] [-u]
    [-debug] [-help]

Manipulates the list of hosts upon which the class named in <class context path> or <class LOID> can place its instances. The list of acceptable hosts for a given class consists only of hosts that have been added to the list. The list therefore may not necessarily include all possible hosts. If there are no hosts listed as acceptable the user can assume that all hosts are acceptable.

The following optional parameters are supported:

-c	Use context paths to specify class and host
-l	Use dotted hex LOIDs to specify class and host
-a	Add named host to the class's acceptable host list
-d	Delete named host from the class's acceptable host list
-t	Test whether or not a host is on the class's acceptable host list
-p	Display the class's acceptable host list
-u	Print usage
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

The example below adds a new host to the list of acceptable hosts of BasicFileClass, using the -a flag.

$ legion_class_host_list -c /class/BasicFileClass \
  -a /hosts/newHost
** ADDED 1 host(s) to class's acceptable host set

The -p flag can then be used to check the listing.

$ legion_class_host_list -c /class/BasicFileClass -p
** ACCEPTIBLE HOST LISTING: 
**      1.01.07.d59d1a40.000001fc094e23...
$

You can use the -a, -d, and -t flags more than once when running the command but regardless of how you list them on the command line Legion will process them in a specific order when you run the command: first adding any new hosts, then deleting old hosts, then testing any hosts, and finally printing out the results. Note also that if you give the class's context name in the first parameter (i.e., with the -c flag) you must use the hosts' context names in the <host1>, <host2>, ...<hostn> parameter. Similarly, if you give the class's LOID (with the -l flag) you must use the hosts' LOIDs. In other words, if you were to enter:

$ legion_class_host_list -c /class/myClass \
  -t 1.01.07.d59d...

You would get an error message. Legion will treat the host's LOID as a context name.

legion_class_vault_list 
    {-l <class LOID> | -c <class context path>}
    [{-a | -d | -t} <vault1> <vault2> ... <vaultn>] [-p] [-u]
    [-debug] [-help]

Manipulates the list of vaults upon which the class named in <class context path> or <class LOID> can place its instances' OPRs. Optional parameters are:

-c	Use context paths to specify class and vault
-l	Use LOIDs to specify class and vault
-a	Add named vault to the class's acceptable vault list
-d	Delete named vault from the class's acceptable vault list
-t	Test whether or not a vault is on the class's acceptable vault list
-p	Display the class's acceptable vault list
-u	Print usage
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

You can use the -a, -d, and -t flags more than once when running the command but regardless of how you list them on the command line Legion will process them in a specific order when you run the command: first adding any new vaults, then deleting old vaults, then testing any vaults, and finally printing out the results. Note also that if you give the class's context name in the first parameter (i.e., with the -c flag) you must use the vaults' context names in the <vault1>, <vault2>, ...<vaultn> parameter. Similarly, if you give the class's LOID (with the -l flag) you must use the vaults' LOIDs. In other words, if you were to enter:

$ legion_class_vault_list -c /class/myClass \
  -t 1.01.07.01000...

You would get an error message. Legion will treat the vault's LOID as a context name.

legion_config_scheduler
    {-l <Scheduler LOID> | -c <Scheduler context path>} 
    [-get_enactor] [-get_collection] 
    [-set_enactor {-l <Enactor LOID> | -c <Enactor path>}] 
    [-set_collection {-l <Collection LOID> | -c <Collection path>}]
    [-debug] [-help]

This command can be used to query or configure the helper objects used by a basic Legion scheduler. Basic Legion Scheduler objects use a Collection helper object to obtain information about available resources upon which they can schedule objects. After constructing a schedule, basic Legion Schedulers use an Enactor helper object to implement scheduling decisions (to actually start up the scheduled objects). Use legion_config_scheduler to assign a particular Collection and Enactor to a basic Legion Scheduler or vice versa.

The following optional parameters are supported:

-get_enactor	Print the LOID of a basic Legion Scheduler's currently assigned Enactor helper object
-get_collection	Print the LOID of a basic Legion Scheduler's currently assigned Collection helper object
-set_enactor	Set the Enactor named in <Enactor LOID> or <Enactor path> to the Scheduler
-set_collection	Set the Collection named in <Collection LOID> or <Collection path> to the Scheduler
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_host_vault_list 
    {-l <host LOID> | -c <host context path>}
    [{-a | -d | -t} <vault1> <vault2> ... <vaultn>] [-p] [-u]
    [-debug] [-help]

Used to display and manipulate list of vaults with which the host named in <host context path> or <host LOID> can interoperate.

The following optional parameters are supported:

-c	Use context paths to specify host and vault
-l	Use dotted hex LOIDs to specify host and vault
-a	Add named vault to the host's acceptable vault list
-d	Delete named vault from the host's acceptable vault list
-t	Test whether or not a vault is on the host's acceptable vault list
-p	Display the host's acceptable vault list
-u	Print usage
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

To list the vaults that a host can operate on, for instance, you would type in:

$ legion_host_vault_list -c /hosts/HostName -p
** COMPATIBLE VAULT LISTING: 
**      1.01.03.d49d1a40.000001fc0a69cbb845...
$

You can use the -a, -d, and -t flags more than once when running the command but regardless of how you list them on the command line Legion will process them in a specific order when you run the command: first adding any new vaults, then deleting old vaults, then testing any vaults, and finally printing out the results. Note also that if you give the host's context name in the first parameter (i.e., with the -c flag) you must use the vaults' context names in the <vault1>, <vault2>, ...<vaultn> parameter. Similarly, if you give the host's LOID (with the -l flag) you must use the vaults' LOIDs. In other words, if you were to enter:

$ legion_host_vault_list -c /host/HostName \
  -t 1.01.03.d49...

You would get an error message. Legion will treat the vault's LOID as a context name.

legion_instance_host_list
    {-l <instance LOID> | -c <instance context path>}
    [{-a | -d | -t} <host1> <host2> ... <hostn>] [-p] [-u]
    [-debug] [-help]

Manipulates the list of acceptable hosts upon which the instance named in <instance LOID> or <instance context path> can be placed.

The following optional parameters are supported:

-c	Use context paths to specify instance and host
-l	Use LOIDs to specify instance and host
-a	Add named host to the instance's acceptable host list
-d	Delete named host from the instance's acceptable host list
-t	Test whether or not a host is on the instance's acceptable host list
-p	Display the instance's acceptable host list
-u	Print usage
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

You can use the -a, -d, and -t flags more than once when running the command but regardless of how you list them on the command line Legion will process them in a specific order when you run the command: first adding any new hosts, then deleting old hosts, then testing any hosts, and finally printing out the results. Note also that if you give the instance's context name in the first parameter (i.e., with the -c flag) you must use the hosts' context names in the <host1>, <host2>, ...<hostn> parameter. Similarly, if you give the instance's LOID (with the -l flag) you must use the hosts' LOIDs. In other words, if you were to enter:

$ legion_instance_host_list -c myInstance \
   -t 1.01.07.01000...

You would get an error message. Legion will treat the host's LOID as a context name.

legion_instance_vault_list
    {-l <instance LOID> | -c <instance context path>}
    [{-a | -d | -t} <vault1> <vault2> ... <vaultn>] [-p] [-u]
    [-debug] [-help]

Manipulates the list of acceptable vaults upon which the instance named in <instance LOID> or <instance context path> can be placed.

The following optional parameters are supported:

-c	Use context paths to specify instance and vault
-l	Use LOIDs to specify instance and vault
-a	Add named vault to the instance's acceptable vault list
-d	Delete named vault from the instance's acceptable vault list
-t	Test whether or not a vault is on the instance's acceptable vault list
-p	Display the instance's acceptable vault list
-u	Print usage
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

You can use the -a, -d, and -t flags more than once when running the command but regardless of how you list them on the command line Legion will process them in a specific order when you run the command: first adding any new vaults, then deleting old vaults, then testing any vaults, and finally printing out the results. Note also that if you give the instance's context name in the first parameter (i.e., with the -c flag) you must use the vaults' context names in the <vault1>, <vault2>, ...<vaultn> parameter. Similarly, if you give the instance's LOID (with the -l flag) you must use the vaults' LOIDs. In other words, if you were to enter:

$ legion_instance_vault_list -c myInstance \
   -t 1.38736c78.03.01000000.000...

You would get an error message. Legion will treat the vault's LOID as a context name.

legion_join_collection
    {-l <Collection LOID> | -c <Collection path>}
    {-l <member LOID> | -c <member path>}
    [-debug] [-help]

This command joins the objects named in <member LOID> or <member path> to the Collection named in <Collection LOID> or <Collection path>. Any Legion object can be added to a Collection.

Use the legion_query_collection command to get information (in the form of object attributes) about the given collection.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_leave_collection
    {-l <Collection LOID> | -c <Collection path>}
    {-l <member LOID> | -c <member path>}
    [-debug] [-help]

This command removes the object named in <member LOID> or <member path> from the Collection named in <Collection LOID> or <Collection path>.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_list_oprs {-l <vault LOID> | -c <vault context path>}
    [-debug] [-help]

Lists all OPRs currently stored in a given vault. The output includes information about inert objects' LOIDs, OPA, owner, and status.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_list_sub_collections
    {-l <collection LOID> | -c <collection path>}

List a collection's set of subcollections and queries.

legion_make_schedule
    {-c <class context path> | -l <class LOID>}
    [-n <number of nodes>] [-f <specification file>]
    [-q <query>] [-help]

This command creates a host file for running an instance of the class named in <class context path> or <class LOID>. The host file is printed to stdout. The output of legion_make_schedule may be redirected into a file and used with the -HF flag in legion_mpi_run.

The following options are available:

-n <number of nodes>	Specify the number of nodes required for this run. Default is 1.
-f <specification file>	Name a specification file that contains relative performance ratios for different architectures. E.g., the specification file could contain the lines: linux 1 alpha_linux 1.5 solaris 0.7
-q <query>	Specify a MESSIAHS query that can be used to prune the list of hosts on which the run can be scheduled.
-help	Print command syntax and exit.

legion_query_collection
    {-l <Collection LOID> | -c <Collection path>} <query>
    [-debug] [-help]

This command searches for information of the Collection object named in <Collection LOID> or <Collection path>. The format of the <query> string is described in the paper "Constructing Distributed Schedulers Using the MESSIAHS Interface Language," by Steve J. Chapin and Eugene H. Spafford.

Collection queries can be constructed using the interface below.

<query>	—>	<bool-expression>
<bool-expression>	—>	true | TRUE | True | false | FALSE | False
	—>	<comparison-expr>
<comparison-expr>	—>	<expr> == <expr>
	—>	<expr> <= <expr>
	—>	<expr> >= <expr>
	—>	<expr> < <expr>
	—>	<expr> > <expr>
	—>	<expr> <> <expr>
	—>	<expr> != <expr>
	—>	<expr> or <expr>
	—>	<expr> xor <expr>
	—>	<expr> and <expr>
	—>	not <expr>
	—>	match (<string>, <string>)
<expr>	—>	<comparison-expr>
	—>	<int-const>
	—>	<oct-const>
	—>	<float-const>
	—>	<string>
	—>	$<identifier>
	—>	- <expr>
	—>	~ <expr>
	—>	<expr> + <expr>
	—>	<expr> - <expr>
	—>	max (<expr>, <expr>)
	—>	min (<expr>, <expr>)
	—>	<expr> / <expr>
	—>	<expr> * <expr>
	—>	<expr> mod <expr>
	—>	int (<expr>)
	—>	float (<expr>)
	—>	(<expr>)
<int-const>	—>	__any valid integer constant__
<oct-const>	—>	0[0-7]*
<float-const>	—>	__any valid float constant__
<string>	—>	".*"
<identifier>	—>	[a-zA-Z]+

Variables are of the form $VARNAME (e.g. $system_arch). The official variable names will be those exported by resource objects in their attributes. To get some idea of the current set of attributes, consult the documentation on resource objects (for the most up-to-date information, invoke the retrieve_all_attributes() method on a resource object and examine the results).

Examples of query strings are:

'true'	This query would return the list of all objects contained in the Collection.
'match($host_os_name,"SunOS")'	This query would return the list of all objects contained in the Collection with an attribute of the form (host_os_name,"SunOS").
'match($host_os_name,"SunOS")' or 'match($host_os_name,"Linux")'	This collection would return the list of all objects contained in the Collection with an attribute of either (host_os_name,"SunOS") or (host_os_name,"Linux").

The following options are available:

-v	Run in verbose mode. The resulting list of objects matching the query will be displayed along with the attributes of each object. Otherwise, only the list of matching objects (without their attributes) will be displayed.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

The example below uses the default Collection (found in the /etc context), would be:

$ legion_query_collection -c /etc/Collection true
2 hits:
1.36ab9e4a.03.01000000.000001fc099204...
1.36ab9e4a.07.01000000.000001fc0d6e07...

The output shows two objects in the Collection (the bootstrap host and the bootstrap vault).

legion_remove_sub_collection 
    {-l <collection LOID> | -c <collection path>}
    {-l <member LOID> | -c <member path>} [-q <query>]

This command ends a parent-subcollection relationship. It does not destroy either collection. You must name the parent collection and the subcollection. If the parent collection is running multiple queries on the subcollection, use the -q flag to stop a specific query (use legion_list_sub_collections to see which queries are running on which subcollections). Otherwise, all queries will be stopped.

The following option is supported:

-q <query>

A MESSIAHS-style query that is being run on the subcollection. See legion_query_collection for details.

legion_set_default_placement 
    {-l <class LOID> | -c <class context name>}
    {-l <host LOID> | -c <host context name>}
    {-l <vault LOID> | -c <vault context name>}
    [-debug] [-help]

Sets the default placement for objects of the class named in <class LOID> or <class context name> to the given host/vault pair. Default placement is used when a class has no associated Scheduler object or cannot contact its associated Scheduler object. When a default placement is set the user should take care to ensure that an implementation for the default placement host's architecture is available.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_set_scheduler 
    {-l <class LOID> | -c <class context path>}
    {-l <Scheduler LOID> | -c <Scheduler context path>}
    [-debug] [-help]

This commands sets the Scheduler named in <Scheduler LOID> or <Scheduler context path> for the class named in <class LOID> or <class context path>. This will be the default scheduler for that class. The class will then use the scheduler to determine which hosts and vaults should manage its instances (i.e., determine placements for the class's instances).

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_set_scheduler_policy 
     {-l <class LOID> | -c <class context path>} 
     <policy> [-debug] [-help]

This command can be used to set a class object's policy for using its default scheduler. See also legion_set_scheduler.

The legal values for <policy> are:

0	This policy value specifies that the class named in <class LOID> or <class context path> should use its default scheduler if the scheduler is currently active. It is intended to protect bootstrap classes, which may be involved in activating Schedulers and Scheduler helper objects. Typically, this policy is not recommended for user class objects. Classes using this policy should have a default placement available. See legion_set_default_placement.
1	This policy value specifies that the class should always use its default Scheduler, even if the Scheduler is not active. This is recommended for user classes, which usually require help from a Scheduler object when making placement decisions.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_set_varch
    {-l <host LOID> | -c <host context path>} <arch>
    [-debug] [-help]

Set a virtual host object's architecture. A virtual host object lives on host A (the physical host) but actually represents host B (the virtual host). If the legion_set_varch command is not run, Legion will assume that the virtual host object's architecture is the same as its physical host.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_set_vrun
    {-l <host LOID> | -c <host context path>} <path>
    [-debug] [-help]

This command configures a virtual host object. A virtual host object lives on host A (the physical host) but actually represents host B (the virtual host). Running this command indicates where the physical host can find scripts for starting and managing jobs on the virtual host. The <path> parameter is the local path for those scripts.

To configure a T3E virtual host object, you could run something like this:

$ legion_set_vrun -c /hosts/my_T3E $LEGION/src/T3E/SDSC

This tells Legion that the scripts are in $LEGION/src/T3E/SDSC.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_vault_host_list
    {-l <vault LOID> | -c <vault context path>}
    [{-a | -d | -g} <host1> <host2> ... <hostn>] [-p] [-u]
    [-debug] [-help]

Display and manipulates the list of hosts with which the vault named in <vault LOID> or <vault context path> can interoperate.

The following optional parameters are supported:

-c	use context paths to specify vault and host
-l	Use LOIDs to specify vault and host
-a	Add named host to the vault's acceptable host list
-d	Delete named host from the vault's acceptable host list
-t	Test whether or not a host is on the vault's acceptable host list
-p	Display the vault's acceptable host list
-u	Print usage
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

To view the list of hosts that a given vault can operate on, you could use something like the example below.

$ legion_vault_host_list -c /vaults/VaultName -p
** COMPATIBLE HOST LISTING: 
**      1.01.07.d49d1a40.000001fc0c04724...
**      1.01.07.d59d1a40.000001fc094e23c...
**      1.01.07.d69d1a40.000001fc0b68108...
$

You can use the -a, -d, and -t flags more than once when running the command but regardless of how you list them on the command line Legion will process them in a specific order when you run the command: first adding any new hosts, then deleting old hosts, then testing any hosts, and finally printing out the results. Note also that if you give the vault's context name in the first parameter (i.e., with the -c flag) you must use the hosts' context names in the <host1>, <host2>, ...<hostn> parameter. Similarly, if you give the vault's LOID (with the -l flag) you must use the hosts' LOIDs. In other words, if you were to enter:

$ legion_vault_host_list -c /vaults/VaultName \
  -t 1.01.07...

You would get an error message. Legion will treat the host's LOID as a context name.

General Functions about the State of the System

legion_check_system [-v] [-q] [-fix CommandLine | -fix Contexts]
    [-debug] [-help]

Checks the status of the key elements of your Legion system: LegionClass, host objects, root context object, etc. The output will include a summary of warnings and errors currently running in your system.

The following options are supported:

-v	Run the command in a verbose mode.
-q	Run the command in a quiet mode, i.e., print only the summary of warnings and errors.
-fix CommandLine	Report any errors in a command-line object then delete the object.
-fix Contexts	Report any errors in a context object then delete the object.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_classof 
    {-l <object LOID> | -c <context path>}
    [-debug] [-help]

Displays the LOID of the class of the object named in <context path> or <object LOID>.

$ legion_classof -c Foo
The class of 1.01.66000000.01000000.000001fc0...
is 1.01.66000000..000001fc0d085b2c33...
$

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_create_stat_tree <base context path>
    [-debug] [-help]

Creates a database of current loads on all host objects in a system.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_host_stats {-l <host loid> | -c <host context path>}
    [-debug] [-help]

Prints the number of objects and current load for the given host object.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_list_objects 
    {-l <host LOID> | -c <host context path>}
    [-debug] [-help]

Lists the Legion objects currently managed by (i.e., running on) the host object named in <host context path> or <host LOID>. This may include each object's LOID, status, and its owner's LOID and OA.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_version
    [-debug] [-help]

Prints which version of Legion you are current running. For example, the output below indicates that the current system is a University of Virginia Legion system version 1.3.5.

$ legion_version
VaL Legion version 1.3.5
$

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_wellknown_class <wellknown class name>
    [-debug] [-help]

Gets the class LOID of a Legion "well-known" class. Possible values for <wellknown class> include:

LegionClass
BootstrapMetaClass
UnixHostClass
UnixVaultClass
CommandLineClass
ContextClass
ImplementationClass
UnixImplementationCacheClass
BindingAgentClass

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_whereis 
    {-l <object LOID> | -c <object context path>}
    [-debug] [-help]

This command returns a specified object's host and vault object. That is, the output gives the context path of the host and vault objects where the object and the object's persistent state are located. If the host or vault objects have been assigned aliases Legion will randomly return one of the context paths. Your output will look something like this:

$ legion_whereis -c Foo
Host   : /hosts/BootstrapHost
Vault  : /vaults/BootstrapVault
$

This example looks up the location of object Foo. The output shows that the object is located on BootstrapHost and its persistent state is on BootstrapVault.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_whoami
    [-debug] [-help]

You can use this command to find out which user id you are currently logged in as. Your output will look something like this:

$ legion_whoami
/users/nemo
$

This means that you are logged in as user nemo.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

Security

legion_add_acl [-l <object LOID> | -c <object context name>] {-s | <filename>}
    [-debug] [-help]

Adds an access control list to the object named in <object LOID> or <object context path> or, if no object is named, the current environment. This command resembles legion_set_acl, but it merges in a new access control list. For example, if the current access control set contains access control lists for methods A and B of class XYZ's instances, adding new access control lists for class XYZ's methods B and C will not change A, replace B, and add C.

The following options are supported:

-s	Read from stdin
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_add_implicit_params
    [-l <AuthenticationObject LOID> | -c <AuthenticationObject context path>]
    {-s | <filename>}
    [-debug] [-help]

Add an implicit parameter to the AuthenticationObject named in <AuthenticationObject LOID> or <AuthenticationObject context path> or, if no AuthenticationObject is named, the current environment. The arguments take the same input format as legion_set_implicit_params. New parameters merge into the existing implicit parameter set (i.e., new parameters override old ones of the same name). There is no way to remove or unset selected implicit parameters.

The following options are supported:

-s	Read from stdin
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_change_permissions [+-rwx] [-v] 
    <group/user context path> <target context path>
    [-debug] [-help]

Changes an object's read, write, and execute permissions so that you can allow the user or group named in <group/user context path> to use the object named in <target context path>. This tool manipulates an object's access control list (ACL) so that other users can call methods on your objects. For our purposes, "read" methods are defined as methods that obtain but do not modify an object's state, "write" methods are methods that modify an object's state, and "execute" methods are methods that run an object.

This command works on common Legion object types: context, file, class, tty, implementation, host, and vault objects all fall into this category.

The following optional parameters are supported:

-r	Deny read permissions to the target object.
+r	Grant read permissions to the target object.
-w	Deny write permissions to the target object.
+w	Grant write permissions to the target object.
-x	Deny execute permissions to the target object (note that this option is for class objects only).
+x	Grant execute permissions to the target object (note that this option is for class objects only).
-v	Run the command in verbose mode.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_create_user [-a <admin path>] [-z <password>] 
    [-h <new home context>] [-c <AuthenticationClass path>] 
    <user id path> [-debug] [-help]

This command is actually a simple wrapper around the legion_create_user_object command. The full command give more control to the creation of AuthenticationObjects.

The user id is the context name of an AuthenticationObject: the legion_create_object utility creates the object and assigns it the context name given in <user id path>. Please note that this argument is a full path (relative or absolute). Note also that the user id's context has nothing to do with that user's privileges in that context.

Once a user is created, the legion_login command is used to log in. The command will prompt for a password for the new user (unless you use the -z option), and will return the new object's LOID.

The following options are supported:

-a <admin path>	Specify the admin object's context path. Default is /users/admin.
-z <password>	Specify the new user id's password. The default setting will prompt for the password after the command has been run. This option is not recommended for casual use, since the password will be visible on the command line.
-h <new home context>	Specify the new user's home context. Default is /home/<user id>.
-c <AuthenticationClass path>	Specify the AuthenticationClass which you wish to instantiate. Default is /class/AuthenticationClass.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_create_user_object {-l <class LOID> | -c <class context path>}
    [-h <host for new object> | -v <vault for new object>]
    [-f <implicit parameter file>] [-z <password>] <user name>
    [-debug] [-help]

Creates a new object to represent a new Legion user id. The new object can be an instance of the AuthenticationObjectClass or another class that implements AuthenticationObjects.

The following optional parameters are supported:

-h <host for new object>	Specify where the new object should be created.
-v <vault for new object>	Specify which vault should store the new object's persistent state.
-f <implicit parameter file>	This option names a file containing implicit parameters to be stored in the newly created AuthenticationObject (handed out on legion_login). The filename can be "-", in which case the command reads the parameters from the standard input. Note that these are *not* the implicit parameters that control the behavior of the new AuthenticationObject. Upon login, the user's environment will be set to contain the latter set of implicit parameters, and they will affect the creation of all subsequent objects. This option is intended to make it easier to administer the system. In particular, admin can create user accounts that include implicit parameters that by default give the admin access rights to all of the users' subsequently created objects.
-z <password>	Include the user id's password in the command line arguments. This option is not recommended for casual use, as the password is potentially visible to other users in the system while the command is executing.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_get_acl [-l <object LOID> | -c <object context name>]
    [-debug] [-help]

Returns the access control list of the object named in <object LOID> or <object context path>, or, if no object is named, the default access control set associated with the current logged-in Legion session. This command returns 2 as its exit status if the object/session has no access control list.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_get_implicit_params [-l <object LOID> | -c <object context name>]
    [-debug] [-help]

Get the implicit parameters of the object named in <object LOID> or <object context path>, or, if no object is named, the current logged-in Legion session. The former is analogous to looking in a Unix .profile or .cshrc for which environment variables get set at login and the latter is analogous to Unix printenv.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_init_security
    [-debug] [-help]

Creates the initial user (called by default /user/admin) in a new Legion system. This command should be run immediately after legion_initialize when you are starting your system. The script creates a new context called /users, a new user object called admin. The context name admin is placed in the new /users context. You will be asked to give a password. You can change the admin's password with the legion_passwd command.

After running legion_init_security you must login as admin in order to use the system. Use the legion_login command, with /user/admin as the <user name> parameter. This command only needs to be run once, when the system is first started. Only one /user/admin should exist in a system.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_login [<user id path> | -l <user id LOID>]
    [-p <password>] [-debug] [-help]

Allows user to log in to the Legion system as a user, and sets up implicit parameters and security credentials for the user. Note that the command can be run without any arguments (although it will prompt for a user name if a user LOID or user id is not given). User names are context names for AuthenticationObjects (special objects that contain a user password, initial implicit parameters, and other information), created with the legion_create_user command. On a successful login, a credentials file (a user read-only file) is created in the local /tmp directory. The user's shell must be able to see the file, so that his/her command-line utilities can use it. The file will be removed when the user logs out with legion_logout.

The following options are supported:

-p <password>	Enter the password from the command line. This method is not secure.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_logout
    [-debug] [-help]

This logs out a user out of Legion. This command removes the credentials file that is created by the legion_login utility and has the effect of logging the user out of a secure Legion system.

We strongly recommend that users insert this command into a .logout file or some other script that is run when a user logs out. This ensures that credential files do not remain in the system for unnecessarily long periods.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_passwd {<user id context> | -l <user id LOID>}
    [-debug] [-help]

Changes a user's password: the command will prompt for the new password. You must be logged in as either admin or the user in order to successfully run this command. You must provide the full context path for the user id (e.g., /user/<user id>).

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_set_acl [-l <object LOID> | -c <object context path>]
    {-s | <filename>}
    [-debug] [-help]

Sets the access control list of the Legion object named in <object context path> or <object LOID>. The default will set the access control set for the current environment. The input file should be an implicit parameters file (see $LEGION/src/UserObjects/Security/SampleImpli-citParams for an example). The implicit parameters file will be scanned only for access control information pertaining to the specified object or environment; all other entries in the file will be ignored. This access control list is inherited objects newly created in the current login session (it roughly corresponds to a Unix umask).

The following option is supported:

-s	Read from standard input
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_set_implicit_params 
    [-l <object LOID> | -c <object context path>] 
    {-s | <filename>}
    [-debug] [-help]

Set the implicit parameters of a specified AuthenticationObject or, if no object is named, the current environment. Any parameters that were previously set are cleared. These are the parameters that the user inherits when he logs into Legion--they are passed along as different Legion commands are executed and are similar to environment variables that user might set up in a Unix .profile of .cshrc file. If no AuthenticationObject is specified, the current Legion login session's implicit parameters are modified (the changes will not persist to the next login session). The command reads the implicit parameters from a file (or the standard input). A sample file can be found in $LEGION/src/UserObjects/Security/SampleImplicitParams.

The following option is supported:

-s	Read from standard input
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_set_message_security
    [-c <AuthenticationObject context path> | -l <AuthenticationObject LOID>]
    {Off | Protected | Private} [-help]

This command updates the message layer security setting of an AuthenticationObject or the current environment by changing the "MessageSecurity" implicit parameter. There are three possible settings: Off, Protected, and Private. The setting determines the object's message encryption level. The default setting is Protected.

The arguments take the same input format as legion_add_implicit_params. New parameters merge into the existing implicit parameter set (i.e., new parameters override old ones of the same name).

You must include one of the following parameters:

Off	No encryption or digesting of messages
Protected	Message digested for verification and credentials encrypted for authentication
Private	Message and credentials encrypted for authentication and verification

The following option is supported:

-help

Print command syntax and exit

Application Development

legion_bfs 
    <file> [-o <out file>] [-BackEnd] [-help]

Parses Fortran programs containing Legion Basic Fortran Support (BFS) pseudo-comments to produce standard Fortran output, or parses Legion BFS IDL files to produce Mentat Programming Language (MPL) output. If the input <file> ends with .f, it is treated as Fortran with pseudo-comments. If the input <file> ends with .bfs, it is treated as BFS IDL.

The following options are used:

-o <out file>	Name of the file containing the resulting Fortran or MPL output
-BackEnd	Instructs the legion_bfs compiler to produce output for IDL files included in the Fortran input file (ignored when the input is a BFS IDL file)
-help	Print command syntax and exit.

legion_generate_idl [<flags>] <input file local path>
    [-debug] [-help]

This command generates Legion stub files for CORBA input IDL files. Optional flags allow you to include information about the preprocessor and the back end and to specify whether or not trans code, client stubs, and head files should be created. If you run the command with no flags, Legion will generate client-side and server-side stubs. For example:

$ legion_generate_idl your_file_in.idl

On the other hand, the example below will generate client-side stubs, a trans file, and header files.

$ legion_generate_idl -trans -client_stubs -header your_file_in.idl

The following options are supported:

-A...	Provide an implementation-specific escape.
-D<name>	Define a name for the preprocessor.
-E	Run the input file on the preprocessor only, print results to stdout.
-Idir <directory name>	Specify a directory to included in the search path for the preprocessor.
-U<name>	Undefine a name for the preprocessor.
-v	Run the command in a verbose setting. This will show the compilation stages.
-w	Suppress any IDL compiler warnings.
-trans	Generate trans code.
-client_stubs	Generate client-side stubs only (i.e., not server-side stubs).
-header	Generate header files.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_make [-v] [-a <architecture>] [-h <host context path>]
    [-e <make command>] [-OUT <remote file>] [<arg1> <arg2> ... <argn>]
    [-debug] [-help]

Compiles programs on a remote host. The command tars your current directory, copies it to a remote host, untars it, and executes a make command. The resulting compiled binaries can be registered with Legion via the directory's makefile or can be copied back to your current directory with one or more -OUT options. Be aware that legion_makewill tar everything in and below your current directory, so be sure that you are in the correct directory before running it.

If no remote host or architecture is specified (with the -h or -a flags) the command will run on a random host. For example, the following command would build the tar file on a random Alpha Linux host:

$ legion_make -a alpha_linux

To be more specific, use the -h flag:

$ legion_make -h /hosts/HostFoo

The following options are supported:

-v	Run in verbose mode (up to four of these flags may be used).
-a <architecture>	Specify what kind of platform should be used to execute the command.
-h <host context path>	Specify which host should execute the programd.
-e <make command>	Specify an executable command (other than make) to be run on the remote host
-OUT <result file>	Specifies the local path name of a file that should be copied out of the remote program's current working directory after the program terminates. The default setting does not copy anything back to your current directory.
<arg1> <arg2> ... <argn>	Optional arguments passed to the make commands: they can specify make targets or other build parameters.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

For more information, see the FAQ.

legion_make_idl [-notrans] [-noclient] [-v] [-noreg]
    [-s <suffix string>] [-run] <application name>
    [-debug] [-help]

This command compiles Legion stubs and implementation code of CORBA client and server classes. The resulting binary executable files can be run in Legion systems. You can use the -run option to compile and execute your code in one step. Unless specified, Legion will compile client-side and class code and will register the resulting binary executable files with Legion (with legion_mplc_reg_impl).

The following options are supported:

-notrans	Make client-side code only.
-noclient	Make class code only.
-v	Run command in verbose mode.
-noreg	Specify that the resulting binary executable should not be registered with Legion.
-s <suffix string>	Attach a suffix to the client and/or class names (i.e., a date, run number, etc.).
-run	Run the application in Legion. Note that this will override the -noreg option.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_make_multi [-v] [-a <architecture>][-e <make command>]
    [<arg1> <arg2> ... <argn>]
    [-debug] [-help]

Compile a program on multiple platforms. Like the legion_make command, this tars the current directory, copies it to a remote host, untars it, and executes a make command on it. The resulting compiled binaries can be registered with Legion via the directory's makefile. Optional flags let you specify different architectures and make commands.

The following options are supported:

-v	Verbose mode. Print actions as command executes.
-a <architecture>	Specify an architecture on which to run make. This option can be specified multiple times to request concurrent builds on multiple platforms. If no architectures are specified, a remote make for the current architecture ($LEGION_ARCH) is performed.
-e <make command>	Specify the make-command for the remote build (default is "make").
<arg1> <arg2> ... <argn>	These optional arguments are passed to the remote "make" command. They can specify make targets or other build parameters.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

For more information, see the FAQ.

legion_mplc
    [<flags>]

Compiles MPL (Mentat Programming Language) programs. There are several possible parameters to this command: please see the MPL Manual for more information (the MPL Manual is available from the Legion web site at http://legion.virginia.edu/documentation.html).

legion_mplc_reg_impl <class name> <binary path> 
    <stateless | stateful | sequential> <arch> [-help]

Registers the given binary, named in <binary path>, as a stateful, stateless, or sequential Mentat object for the architecture named in <arch>; and under the class object named in <class name>. This command is automatically run when you use the legion_mplc command (without the -nolegion option) to compile an MPL program.

In the example below, MentatObject is a stateful Mentat object in the local path /home/legion/bin on a linux or alpha_linux machine. To register it as belonging to a class with the context path name /ClassObject/MentatObject in linux or alpha_linux architectures, you would enter:

$ legion_mplc_reg_impl /ClassDirectory/MentatObject \
 /home/legion/bin/MentatObject stateful linux

or

$ legion_mplc_reg_impl /ClassDirectory/MentatObject \
 /home/legion/bin/MentatObject stateful alpha_linux

The following option is supported:

-help

Print command syntax and exit.

legion_output_state
    {-l <object loid> | -c <object context path>} | StartupState
    [-debug] [-help]

This command uses a special output device for debugging and information reporting. When output is sent using this mechanism, the object(s) will decide whether that type of information is to be displayed and where to display it. Users will be given a series of options to selectively filter what output is displayed to the screen. The output levels include:

     Warnings
     Information
     Low Level Debug
     High Level Debug
     Errors
     Fatal Errors

There are two ways to use this command. You can dynamically change which of a specified object's output types are filtered out and which are displayed. This option also allows the user to change the location of the output (from stderr, stdout, and any Unix file they want).

Or, you can use the StartupState option, in which case the command will print instructions for bringing up a new system with the desired output state.

Please note: if you use StartupState, legion_output_state does not contact Legion and therefore does not run as a Legion program. I.e., you can execute it outside of a running Legion system. Otherwise, it runs as a normal Legion command-line tool.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_record
    {-uf <local storage file name> | -c <recorder context path>}
    [-name <debug session name> ] [-t <interval>]
    <client application> [<arg1> <arg2> ... <argN>]
    [-debug] [-help]

Executes the application named in <client application> in record mode so that it can later be played back with the legion_replay tool. All objects started by the application will record all relevant event activity in a local file, named in <local storage file name>, or in a previously started Legion recorder object, named in <recorder context path> (see below). The utility also monitors the application and reports if it dies. Any application can be started with legion_record, but the command is most useful for Legion applications.

Only one execution of the application will be recorded in the storage file at a time. If you record again to the same storage file you will overwrite previous data.

If you wish to use a Legion recorder object to record your application's activity, you must start the recorder object separately (i.e., legion_create_object -c /class/RecorderObject).

If you wish to record a server object (i.e., one that is not created by the client application, but instead exists on its own), you must start the server object in record mode independently of the client application.

The following options are supported:

-name <session name>	Specify a name for the debug session. If this option is not used, a random name will be chosen.
-t <interval>	Specifies how much time (in seconds) the legion_record utility waits between health checks on its objects. These health checks are used to poll the recorder object to learn about object death. The default setting is 30 seconds.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_replay 
    {-uf <local storage file name> | -c <recorder context path> -name <debug session name>}
    {-list | [-cmd <debugger>] [-local] <session number>}
    [-debug] [-help]

Begins a replay or playback session for a recorded object. This command is used in tandem with the legion_record tool to debug a particular application. The legion_replay tool starts a debugging session for an object started in the application. If used with the -list option, the command returns a list of the sessions stored in the storage file, the session number for each object that was started, and the final states of the objects. These session numbers can then be used to debug the objects one at a time, by rerunning the command with the correct session number.

You must use one of the following sets of parameters to specify which session you wish to start. Sessions are named in legion_record. If you used a Legion recorder object, you'll need to provide the debug session name as well.

The following options are supported:

-uf <local storage file name>	The local file that was used to record your session.
-c <recorder context path>	The Legion recorder object that was used to record your session (must be accompanied by debug session name).
-name <debug session name>	The desired debug session name.
-list	Display the sessions in the storage file.
-cmd <debugger>	Specify a debugging program (i.e. gdb, xdb, etc.) to run on the storage file. Default is gdb.
-local	Indicates that the debugging session should be replayed on your local machine. The default will start a remote session on the machine which executed the original object.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_stateless_add_workers <class name>
    <worker name1> <worker name2> ... <worker nameN>
    [-debug] [-help]

Creates additional MPL stateless object workers. By default, when a stateless class is created or registered in context space it instantiates a single worker. That worker is used by all other objects wishing to call a remote method invocation on that class. Adding more workers allows message calls to be handled more efficiently.

The <class name> parameter should be the stateless class object's context name. The <worker name> parameters should be the desired context name of the new worker objects. Note that you can use full or relative path names.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_stateless_configure <stateless class context path> 
    [-n <number of replicas>] [-Ch <host context path>]
    [-w <max number work requests>] [-FlUsH]
    [-debug] [-help]

This command configures stateless Legion classes so that requests sent to a stateless class are first routed to a proxy object, which selects a worker to service the requests. You can use flags to control the number of replica workers, their placement, and the number of work requests that a worker may service at a given time.

The current version of the proxy object uses a self-scheduling algorithm. When N work requests have been farmed out, the proxy will store any pending requests in an internal queue: when a worker is available, the proxy assigns it a request from the queue. N here is given by the following formula:

N = <number of replicas> * <max number of workers>

The following options are supported:

-n <number of replicas>	Specify the number of workers to be used. Default is 1.
-Ch <context containing list of hosts>	Name a host where the work requests should be executed.
-w <max number of work requests>	Specify the maximum number of work requests that each worker should service at a time. Default is 5.
-update	Tell the proxy object that the worker interface has changed.
-Flush	Remove all work requests for this class.
-status	Display the command's status information (a tty must be on).
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_stateless_remove_workers <class name>
    <worker name1> <worker name2> ... <worker nameN>
    [-debug] [-help]

Removes MPL stateless object workers. The <class name> parameter should be the stateless class object's context name. The <worker name> parameters should be the context name of the unwanted worker objects. Note that you can use full or relative path names.

The following options are supported:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

Program Support

legion_link [-CC <compiler>] [-Fortran] [-FC <compiler>] [-pvm] [-mpi] 
    [-L<library path>][-l<library>] [-v] [-o <output file>] 
    [-bfs] <object file list> [-debug] [-help]

This command links together a set of object files and libraries to produce an executable program and automatically binds the produced executables to the Legion libraries. It is similar to the Unix ld command. It can be used with object files and libraries created from C, C++, or Fortran source code.

If any Fortran object files are linked, the -Fortran flag must be included. If you specify a Fortran compiler with the -FC flag, the -Fortran flag is automatically implied.

The following options are available with this command:

-CC <compiler>	Select a C++ compiler to perform linkage. The default value is based on the default compiler used by the Legion system on your platform.
-Fortran	If any Fortran object files are linked, the -Fortran flag must be included.
-FC <compiler>	Select a Fortran compiler. This flag implies the -Fortran flag, but the two can be used together. Currently supported <compiler> options are: fort Compaq Fortran compiler (Alpha Linux only) g77 Gnu g77 pgf77 Portland Group pgf77 compiler (Intel Linux) pgf90 Portland Group pgf90 compiler (Intel Linux)
-pvm	Link the produced executable to the Legion PVM compatibility library.
-mpi	Link the produced executable to the Legion MPI compatibility library.
-l<library path>	Include the in the set of directories searched for libraries.
-l<library>	Link against the specified library.
-v	Provide a verbose output as the command is running
-o <output path>	Specify the local path of the resulting program. The default is a.out.
-bfs	Link the produced executable to the Legion Basic Fortran Support (BFS) library.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_mpi_debug [-q] {-c <program instance context>}
    [-help]

A utility program that allows the user to examine the state of MPI objects and print out their message queues. The <program instance context> is the context that is holding your program's instances. Normally it is /mpi/instances/<program_name> or (in a secure system) /home/<user_name>/mpi/instances/<program_name>, unless you specified otherwise when you started the program (i.e., if you used the -p flag when you ran legion_mpi_run). This command will return a list of all of the program's instances and what each one is doing. This is a handy way to debug a deadlock.

There are a few limitations in legion_mpi_debug: If an MPI object doesn't respond, it will hang, and it won't go on to query additional objects. An MPI object can only respond when it enters the MPI library; if it is in an endless computational loop, it will never reply.

The following options are available with this command:

-q	List the contents of the queues.
-help	Print command syntax and exit.

legion_mpi_probe
     [-help] [-debug] [-v[erbose]]
     [-all ] [-list]
     [-in <context path name> ] [-out <context path name> ]
     [-IN <local file name> ] [-OUT <local file name> ]
     [-showscratch] [-stat <remote file name> ]
     <pid context name>

Checks an MPIprogram started on a remote host with legion_mpi_run. This command resembles legion_probe_run in that you can check on jobs, move input and output files between your local and execution hosts. It doesn't use a probe file, however, since you can contact your job through its pid context.

The following parameters must be used with this command:

<pid context name>

The context that contains the MPI instance LOIDs associated with the job.

The following options are available with this command:

-help	Print command syntax and exit.
-debug	Run in debug mode.
-v[erbose]	Run in verbose mode.
-all	Perform operation on all instances (default is instance 0).
-list	List all files in the remote program's working directory.
-in <context path name>	Context path of a Legion file object whose contents should be copied into the remote program's current working directory. The local file will have the same name as the <context path name> basename.
-out <context path name>	Context path of a Legion file object whose contents should be copied out of the remote program's current working directory. If the file doesn't exist, you will get an error message. The local source file will have the same name as the <context path name> basename. This tool will not check to see if the job has finished, so it may copy out an incomplete file
-IN <local file name>	Similar to the -in option, but operates on a file in legion_probe_run's local execution environment (i.e., the file named in <local file name>).
-OUT <local file name>	Similar to the -out option, but operates on a file in legion_probe_run's local execution environment (i.e., the file named in <local file name>).
-stat <remote file name>	Print the status of a particular file in the remote job's current working directory.
-showscratch	Print the archive context scratch space. If the run hasn't yet finished or if legion_mpi_run dies or is killed before the job finishes, this space will contain -OUT files that haven't yet been copied out.

legion_mpi_register 
    <class name> <binary local path name> <platform type>
    [-help]

MPI implementation generally require that MPI executables reside in a given place on a disk. Legion's implementation objects have a similar requirement. The legion_mpi_register command registers the executables of different architectures for use with Legion's MPI. The command creates MPI-specific contexts, a class object, and an implementation for the program, and registers the name in Legion context space. If Legion security has been enabled the newly created contexts will be placed in the user's /home/<user_name>/mpi context except if the user is the admin or not logged in. If Legion security has not been enabled, the newly created contexts will be placed in the /mpi context.

The command can be executed several times, if you have compiled your program on several architecture.

The following option is supported:

Print command syntax and exit.

legion_mpi_run
    {-f <option file> [<flags>]} |
      {-n <number of processors> [<flags>]
         <program class> [<arg1> <arg2> ... <argn>]}

Starts an MPI program. Note that the <program class> argument is the Legion context name for the class created by legion_mpi_register. Parameters used for this command are:

-f <option file>	Allows users to start multiple MPI applications via an option file. All applications must be previously registered through legion_mpi_register and have a common MPI_COMM_WORLD.
-n <number of processors>	Specify the number of processorss on which the program will run.

Supported <flags> (a set of special flags for running in a fault tolerant mode is listed below) are:

-v	Verbose option (up to four can be specified for increased detail).
-h <host set context path>	Specify the set of hosts on which the program will run. The context path should not resolve to a particular host but to a context containing the names of one or more hosts. The default setting is the system's default placement: i.e., the system will pick a compatible host pick and try to run the object. If it fails the system will try another compatible host.
-HF <local specification file>	Use a specification file in local file space for scheduling objects from the current execution. You must use a specific format when creating this file (see below).
-hf <Legion specification file>	Use a specification file in context space for scheduling objects from the current execution. You must use a specific format when creating this file (see below).
-in <context path>	Tells Legion to copy the contents of a Legion file object to the remote program's current working directory before execution. The remote file will have the same name as the file object. This flag can be used multiple times to indicate multiple input files. You can also use wildcards to specify groups of files.
-out <context path>	Name of an output file that should be copied from the remote program's current working directory into your context space after the program terminates. The new file object will have the same name as the original output file unless the -a flag is used, in which case the name will be <name>.<mpi object id>. This flag can be used multiple times. You can also use wildcards to specify groups of files. Output files that are not found in the program's current working directory will be copied but will appear as empty files. If the program crashes, the files will be left in the program's current working directory.
-IN <local file name>	Tells Legion to copy the contents of a local file to the remote program's current working directory before execution. The remote file will have the same name as the local file. This flag can be used multiple times to indicate multiple input files. You can also use wildcards to specify groups of files.
-OUT <local file name>	Name of an output file that should be copied from the remote program's current working directory into your local directory after the program terminates. The new file will have the same name as the original output file unless the -a flag is used, in which case the name will be <name>.<mpi object id>. This flag can be used multiple times. You can also use wildcards to specify groups of files. Output files that are not found in the program's current working directory will be copied but will appear as empty files. If the program crashes, the files will be left in the program's current working directory.
-a	Pass the files named in the -in/-out/-IN/-OUT parameters to all nodes. The default setting gives these files only to node 0. Files named in the -out/-OUT parameters will be copied to files that use the following conventions: <name>.<mpi object id>, where <name> is the <output file> given in the -out/-OUT parameters.
-stdin <context path>	Map stdin to the Legion file object named in <context path>. By default, this file object will only be passed to node 0, unless use the -A flag.
-stdout <context path>	Map stdout to the Legion file object named in <context path>. By default, this file object will only be passed to node 0, unless use the -A flag.
-stderr <context path>	Map stderr to the Legion file object named in <context path>. By default, this file object will only be passed to node 0, unless use the -A flag.
-STDIN <local file;	Map stdin to the local file named in <local file>. By default, this file object will only be passed to node 0, unless use the -A flag.
-STDOUT <local file>	Map stdout to the local file named in <local file>. By default, this file object will only be passed to node 0, unless use the -A flag.
-STDERR <local file>	Map stderr to the local file named in <local file>. By default, this file object will only be passed to node 0, unless use the -A flag.
-A	Pass the files named in the -std*/-STD* parameters to all nodes. The default setting gives these files only to node 0.
-p <context path>	Specify a context name for program's instance LOIDs. Default is: /mpi/instances/ program_name unless security is enabled, in which case the default is: /home/<user_name>/mpi/instances/<program_name> If the context does not exist it will be created.
-0 <host context name>	Runs the first process (i.e., process zero) on this node.
-d <Unix path name>	Specify that all children change to the specified directory before they begin to run.
-S	Print statistics at exit.
-D <variable_name>=<value>	Set the environment variable named in <variable_name> to a specified value on all MPI processes after they have called MPI_Init(). This option may be repeated multiple times to set additional environment variables.
-help	Print command syntax and exit.

Assuming that you do not use an option file, the MPI application named in the legion_mpi_run command will be started with the given flags. An example, here running MPI program vdelay on two hosts, would be:

$ legion_mpi_run -n 2 /mpi/programs/vdelay

Use legion_ls to examine the running objects of your application . The /mpi/instances/<program_name> context has an entry for each object in your application. E.g.,

$ legion_ls /mpi/instances/vdelay

If you are running multiple versions of an applications simultaneously, you can use the -p flag to specify an alternate context in which to put your instance LOIDs.

Specification file
A specification file is a text file that contains a list ofhosts and the number of Legion objects that can be scheduled on those hosts. Objects from your application(s) will be scheduled on these hosts. You can use legion_make_schedule to produce this file or write it yourself. List one host and one integer indicating the number of objects the host can create (default is 1) per line. List the host by its Legion context name. A host can be listed multiple times in one file, in which case the integer values accumulate. E.g.:

/hosts/BootstrapHost	5
/hosts/slowMachine1
/hosts/bigPBSqueue 	100
/hosts/slowMachine2 	1

Wildcards
You can also use wildcards to work with groups of input/output files. The following wildcards can be used with -in/-out and -IN/-OUT:

*	match 0 or more characters
?	match any one character
[-]	match any character listed between the brackets (use these to specify a range of characters)
\	treat the character as a literal

For example, if you wanted to identify done.1, done.2, done.3 ... done.9 as your inputs, you could use square brackets to identify them as a group:

$ legion_mpi_run -n 2 -IN done.[0-9] /mpi/programs/mpiFoo

You can use wildcards on the command line or in an option file. They can only be used with file names, however, not with directories.

Option file
The option file contains a list of the MPI applications that you wish to execute, as well as any necessary arguments, as they would appear on the command line. You will be starting all of the listed applications with a single legion_mpi_run. All applications must have been registered with Legion (through legion_mpi_register) and use a common MPI_COMM_WORLD. THe file must list one binary (and any arguments) per line. Each line can also contain one or more legion_mpi_run flags (but not -f). For example:

-n 2 /mpi/programs/mpitest
-n 3 /mpi/programs/mpitest_c

This would start a run of five instances (two of mpitest and three of mpitest_c).

If you use an option file, Legion will ignore the -n flag, program name, and any arguments given on the command line. Any <flags> will be treated as defaults and applied to all processes executed by this command (unless otherwise specified in the option file).

Fault tolerant mode
There is a set of special legion_mpi_run flags that can be used when running in a fault tolerant mode.

-ft	Turn on fault tolerance.
-s <checkpoint server>	Specifies the checkpoint server to use.
-R <checkpoint server>	Recovery mode.
-g <ping interval>	Specify a ping interval. Default is 90 seconds.
-r <reconfiguration interval>	Specify a period (in seconds) for detecting failure. If an object does not respond within the specified period, the application restarts from the last consistent checkpoint. Default value is 360 seconds.

These flags are used in specific combinations. You must use the -ft in all cases and you must use either -s or -R. The -g and -r flags are optional. Please see section 10.1.10 in the Basic User Manual for more information on running in fault tolerant mode. See also the FAQ.

legion_native_mpi_config_host [<wrapper>] [-debug] [-help]

This command sets native MPI properties on a host. The following options are supported:

<wrapper>	Specify a wrapper script that locates mpirun on the host. The default specifies the legion_native_mpich_wrapper script, which is for an MPICH implementation.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_native_mpi_init [<architecture>] [-debug] [-help]

This command installs the legion_native_mpi_backend class in a native MPI host. The following options are supported:

<architecture>	Specify an architecture for which an implementation for this class can be registered.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

legion_native_mpi_register <class name> <binary path> <architecture> 
    [-help]

Register a native MPI program with your Legion system. The example below registers /myMPIprograms/charmm (the binary path) as using a Linux architecture.

$ legion_native_ mpi_register charmm /myMPIprograms/charmm linux

You can run register a program multiple times, perhaps with different architectures or different platforms. If you have not registered this program before, this will create a context in the current context path (the context's name will be the program's class name -- in this case, charmm) and registers the name in Legion context space.

The following option is supported:

-help

Print command syntax and exit.

legion_native_mpi_run 
    [-v] [-a <architecture>] [-h <host context path>]
    [-IN <local input file>] [-OUT <local result file>]
    [-in <Legion input file>] [-out <Legion result file>]
    [-n <nodes>] [-t <minutes>] 
    [-legion] [-help] [-debug] <program context path> 
    [<arg 1> <arg 2> ... <arg n>]

Start a native MPI program. The following parameters are used for this command:

-h <host context path>	Specify the host on which the program will run. The default setting is the system's default placement, which is to pick a compatible host and try to run the object. If the host fails, the system will try another compatible host.
-v	Verbose option.
-a <architecture>	Specify the architecture on which to run.
-IN <local input file>	Specify an input file that should be copied to the remote run from the local file system.
-OUT <local result file>	Specify a result file that should be copied back from the remote run to the local file system.
-in <Legion input file>	Specify an input file that should be copied to the remote run from the Legion context space.
-out <Legion result file>	Specify a result file that should be copied out from the remote run into Legion context space.
-n <nodes>	Specify the number of nodes for the remote MPI run.
-t <minutes>	Specify the amount of time requested for the remote MPI run. This option is only meaningful if the host selected to run the remote program enforces time limits for jobs.
-legion	Indicate whether the application makes Legion calls (see section section 10.2.5 on page 64 in the Basic User manual).
-help	Print command syntax and exit.
-debug	Catch and print Legion exceptions.
<arg1> <arg2> ... <argn>	Arguments to be passed to the remote MPI program.

For more information, see the FAQ.

legion_pvm_register
    <class path name> <binary local path name> <platform type>
    [-help]

Registers a PVM task implementation. This setup is not necessary for tasks that will only be started from the command line (tasks that will not be "spawned"). Given the class named in <class path name>, the binary named in <binary local path register>, and the architecture type (currently Linux, Solaris, or SGI), this command creates an implementation object that can then be used by the Legion PVM Library.

Once you've registered an application, you can run it. If necessary, you can examine Legion context space with either

$ legion_ls /pvm

to list the Tids of running PVM tasks, or

$ legion_ls /pvm/tasks

to list the registered task classes. You can also use Legion class utilities to examine the class state (e.g., legion_list_instances).

To register a Linux binary named matmult in Legion, enter:

$ legion_pvm_register /pvm/tasks/matmult matmult linux

The following option is supported:

-help

Print command syntax and exit.

legion_probe_run
    [-help] [-debug]
    [-pwd] [-hostname] [-list] [-stat <remote file name] [-statjob]
    [-in <context path name>] [-out <context path name>] 
    [-IN <local file name>] [-OUT <local file name>] 
    [-setscratch <context path>] [-showscratch] [-kill]
    {-p[robe] <local file name> | -l <probe LOID>}

This command checks a program started on a remote host with legion_run. It can also pass input files to or pick up output files from the remote host, check individual files associated with the job, and clean up the remote host space. It can be used with blocking or nonblocking runs.

You must have used the -p option when starting legion_run in order to use this command: this option creates a local file called a probe file that can contact your remote job. If you do not have a probe file for your job, legion_probe_run will be unable to locate your job.

Note that if you start a nonblocking run, the remote host will hold the results for six hours after the job terminates. If you do nothing, the host will tar up the job's current working directory and move it into your context scratch space. If you run legion_probe_run at any point (whether to retrieve output files or just to check the job's status) during those six hours, the clock restarts and the remote host will wait for another six hours before tarring and moving the job's directory. If you do not use the -kill option to clean up the job's directory, it will eventually be tarred and moved.

One of the following parameters must be used with this command:

-p[robe] <local file name>	The name of the local probe file associated with the desired job.
-l <probe LOID>	The probe's LOID (may not be supported in all releases).

The following options are available with this command:

-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.
-in <context path name>	Context path of a Legion file object whose contents should be copied into the remote program's current working directory. The local file will have the same name as the <context path name> basename.
-out <context path name>	Context path of a Legion file object whose contents should be copied out of the remote program's current working directory. If the file doesn't exist, you will get an error message. The local source file will have the same name as the <context path name> basename. Output files that are not found in the program's current working directory are skipped.
-IN <local file name>	Similar to the -in option, but operates on a file in legion_probe_run's local execution environment (i.e., the file named in <local file name>).
-OUT <local file name>	Similar to the -out option, but operates on a file in legion_probe_run's local execution environment (i.e., the file named in <local file name>).
-pwd	Print the remote job's present working directory. This is useful if you set this directory with the -d option when you ran legion_run.
-hostname	Print the remote host's DNS name.
-list	Print a list of files in the remote job's current working directory.
-stat <remote file name>	Print the status of a particular file in the remote job's current working directory.
-statjob	Print a summary of the remote job's status. Possible values are "Running", "Error", and "Done".
-setscratch <context path>	Specify which part of your context space should be used as scratch space for this remote job. Default is /tmp.
-showscratch	Print the currently set context scratch space. This will be the most recently specified space.
-kill	Kill the remote job (if it hasn't yet terminated) and clean up its remote current working directory. Please note that if you have not yet retrieved output files, they will be lost. If you started legion_run in nonblocking mode and you do not clean up the remote directory after the job finishes, the remote host will wait six hours and then tar and move the entire directory to your context scratch space. If you started legion_run in blocking mode and you then kill the remote job, legion_run will hang and must be killed by hand.

legion_register_program 
    <program class> <executable path> <legion arch>
    [-debug] [-help]

This command allows uses to register a non-Legion executable program (specified by the <executable path> argument) and make the program available for use within the Legion system. The registered program will be associated with a Legion class object, named in <program class>: the class and the context path will be created, if the class was not already created by a previous execution of legion_register_program. The registered program will execute only on hosts of the architecture specified in .

Programs registered through legion_register_program can be executed with the legion_run command. See also legion_register_runnable for information about registering Legion programs.

The following parameters are used with this command:

<program class>	The Legion context path name of the class with which the registered program should be associated
<executable path>	The local file path of the executable program to register. This can be any program that could be run from the shell command prompt, including scripts, and binary executable generated by any programming language.
<legion arch>	The platform type that the program should be executed.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

For more information on this command please see the Reference Manual.

legion_register_runnable 
    <program class> <executable path> <legion arch>
    [-debug] [-help]

The legion_register_runnable command is similar to the legion_register_program command in that it allows programs to be registered for execution through the legion_run utility. However, whereas the legion_register_program tool is used to register non-Legion programs, legion_register_runnable is used to register programs that are linked against the Legion libraries and export the "runnable" object interface.

The following parameters are used with this command:

<program class>	The Legion context space path of the class with which the registered program should be associated
<executable path>	The local file path of the executable program to register. This program should be a valid Legion object implementation that has been linked with the Legion library, and that exports the Legion "runnable" interface.
<legion arch>	The platform type on which the program should be executed.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.

For more information on this command please see the Reference Manual.

legion_run
    [-w] [-v] [-a <architecture>] [-h <host context path>]
    [-nonblock | -block] [-d <remote host directory>] [-D <var=value>]
    [-in <context path name>] [-out <context path name>] 
    [-IN <local file name>] [-OUT <local file name>] 
    [-stdin <local file name>] [-stdout <local file name>] 
    [-stderr <local file name>] 
    [-f <option file>] [-novrun] [-t <minutes>] [-n <nodes>]
    [-p[robe] <local file name>] [-setscratch <context path>] 
    [-debug] [-help] <program class> [<arg1> <arg2> ... <argn>]

The legion_run command executes a single instance of a program associated with the program class specified in the <program class> argument. The command will randomly select a host to execute the program (observing the restriction that only hosts with an acceptable architecture may be selected). If the desired platform type is unavailable the command will fail and return an error message. Arbitrary command-line arguments may be specified for the remote program.

Note that any number of input and output files may be specified for a single execution of legion_run (i.e., the -in/-out and -IN/-OUT options can be repeated). The -f flag can be used to specify legion_run options in the file named in <options file>, rather than on the command line.

The following parameter is used with this command:

<program class>	Specifies the program class of which an instance should be executed. This program class should have been previously created with the legion_register_program or legion_register_runnable command.
The following optional parameters are supported:
-w	Directs legion_run's output to your current tty object. If you have not created and set a tty object for your current window you will not be able to see any output and an error message will appear.
-v[erbose]	Run command in verbose mode.
-a <architecture>	Allows users to specify what kind of architecture the program should be executed on.
-h <host context path name>	Specify which host should execute program.
-nonblock	Specify that legion_run be run in nonblocking mode. Once it starts your program, it will exit and free up your command line. The default setting is blocking.
-block	Specify that legion_run be run in blocking mode. The command will start your program and block at the command line until the program finishes. This is the default setting.
-d <remote host directory>	Specify that the program run in a particular directory on its remote host.
-D <var=value>	Set environment variable var to value value.
-in <context path name>	Context path of a Legion file object whose contents should be copied into the remote program's current working directory before execution begins. The local file will have the same name as the <context path name> basename.
-out <context path name>	Context path of a Legion file object whose contents should be copied out of the remote program's current working directory after the program terminates. The local source file will have the same name as the <context path name> basename. Note that output files are copied out regardless of the cause of program termination. Partial results will be available if the program crashes. Output files that are not found in the program's current working directory are skipped.
-IN <local file name>	Similar to the -in option, but operates on a file in the local execution environment of legion_run (i.e., the file named in <local file name>).
-OUT <local file name>	Similar to the -out option, but operates on a file in the local execution environment of legion_run (i.e., the file named in <local file name>).
-stdin <local file name>	Specify a local file from which the remote job gets its standard input.
-stdout <local file name>	Specify a local file to which the remote job writes its standard output.
-stderr <local file name>	Specify a local file to which the remote job writes its standard error.
-f <option file>	Allows users to specify options for running legion_run in a separate file rather than listing them on the command line. This is useful for programs that make extensive use of the -in/-out or -IN/-OUT options. The file can contain one or more of the legion_run options, delimited by spaces, tabs, or blank lines. The program class name and arbitrary command-line arguments may not be included in this file. No other information should be included.
-novrun	Do not run on a virtual host.
-t <minutes>	Specifies the amount of time (in minutes) needed to run the program. If this option is not used, the host will assign the job its default time block. This option is only meaningful if the host selected to run the remote program enforces time limits for jobs: otherwise this option is not required.
-n <nodes>	If the remote program is a native parallel job (e.g., a program written to use the local vendor MPI implementation), use this option to specify the number of nodes that should be allocated to the job. This option is not meaningful if the host selected to run the remote program is a uniprocessor or does not support multi-node allocations.
-p[robe] <local file name>	Store the remote job's tracking name in a file on the local host. You must use this option if you wish to run legion_probe_run.
-setscratch <context path>	Specify a portion of your context space to be used as context scratch space.
-debug	Catch and print Legion exceptions.
-help	Print command syntax and exit.
<arg1> <arg2>... <argn>	Allows users to provide arbitrary command-line arguments for the program.

For more information on this command please see How to start remote programs in Legion. You can also see the FAQ.

legion_run_multi [-v[erbose]] [-z[ero]] [-r[estart]] 
    [-e[xec] command] [-x <exceptions file path>] 
    {[-n <number of processors>] |
       [-s[chedule] <schedule file path>] |
       -n <number of processors> -s[chedule] <schedule file path>} 
    {-f <specification file path>}  [-help] [-debug]
    <program class name> 
    [<arg1> <arg2> ... <argn>]

This command runs a previously registered serial program, named in <program class name>, with all of the different input files, using a simple specification file, named in <specification file name>, to describe the names of the expected input and output files. You must provide the number of processors and/or a schedule file.

Before you run this command, you must have registered the program name and created a specification file. The specification file format is:

keyword		filename	pattern

You must fill in all three fields on each line. One file per line.

Specification file

The first field, the keyword, provides information about the file named in the second field. Possible keywords are IN/in, OUT/out, CONSTANT/constant, and stdin/stdout/stderr. The case determines the file's location (except for std*):

constant/in/out		Legion context space
CONSTANT/IN/OUT/	local file space
stdin/stdout/stderr

The CONSTANT/constant keywords indicate identical input for multiple runs (e.g., input that is used for each run, such as a password). The std* keywords refer to local files that stdin, stdout, and stderr use. A separate stdout and stderr are created for each run. If you do not indicate a stdout file, standard output will be sent to your Legion tty object. Multiple IN/in, OUT/out, and CONSTANT/constant files may be specified, one per line.

The second field is the name of an input or output file that your program expects to read or write to in the local directory of whichever host it runs on.

The third field is the naming pattern for input and output files. You may use "*" as a pattern holder for IN/in and OUT/out files. The pattern holder allows you to specify large groups of files in different directories for input and output.

For example, suppose that you want to run program Foo. Foo needs two input files, FooFoo and MyFoo, and produces one output file, Bar, and a password. Your specification file would look like this:

IN		FooFoo		/mylocaldir/foo*.ent
in		MyFoo		/mycontext/bar*.gif
OUT		Bar		/mylocaldir/output*.stuff
CONSTANT	secret		/etc/passwd

Legion looks in local space for files that fit the specified patterns and finds five sets of files:

  IN LOCAL SPACE	  IN CONTEXT SPACE
/mylocaldir/foo1.ent	/mycontext/bar1.gif
/mylocaldir/foo2.ent	/mycontext/bar2.gif
/mylocaldir/foo3.ent	/mycontext/bar3.gif
/mylocaldir/foo4.ent	/mycontext/barA.gif
/mylocaldir/foo5.ent	/mycontext/barB.gif

Notice that the first three files in each column have common patterns (1, 2, and 3) whereas the last two do not (4 and 5, A and B). The files with mismatched patterns are discarded, leaving three sets of input files, or three jobs that can be run:

  IN LOCAL SPACE	  IN CONTEXT SPACE
/mylocaldir/foo1.ent	/mycontext/bar1.gif
/mylocaldir/foo2.ent	/mycontext/bar2.gif
/mylocaldir/foo3.ent	/mycontext/bar3.gif

These jobs can be identified by their pattern: 1, 2, and 3. Before going any further, Legion checks for any previously created output files. It finds a file called /mylocaldir/output1.stuff, so it knows that job 1 has already been run. The remaining jobs, 2 and 3, have not. Legion then copies the remaining four input files to the two hosts that will run the jobs:

/mylocaldir/foo2.ent copied to -->	HostA/FooFoo
/mycontext/bar2.gif			HostA/MyFoo
/mylocaldir/foo3.ent			HostB/FooFoo
/mycontext/bar3.gif			HostB/MyFoo

The jobs are run and an output file called Bar is created on HostA and on HostB. HostA/Bar's contents are copied to a file in the original host's local directory space called /mylocaldir/output2.stuff, signalling that job 2 is finished. HostB/Bar's contents are copied to /mylocaldir/output3.stuff, signalling that job 3 is finished.

A more complex specification file might look like this:

IN		FILE1	 	/usr/localtmp/dump/pdb*.ent
in	 	NEXT2		/home/an4m/pictures/*.gif
OUT		THEN3		output*
out		FILE4		./dssp*log
CONSTANT	Crypt	 	/etc/passwd
constant	Salt-File	/home/admin/user-list

The program must be written so as to read/write the files named in the second field from its current directory. In this case, the registered program must read FILE1, NEXT2, Crypt, and Salt-File, and write THEN3 and FILE4. When legion_run_multi is called on the registered program with the above specification file, it looks for matching patterns:

/usr/localtmp/dump/pdb1egs2.ent		in your local directory
/home/an4m/pictures/1egs2.gif		in your Legion context

These are sent as input files for run 1egs2, which generates two output files:

output1egs2	in your local directory
./dssp1egs2log	in your Legion context

Exception file

The exceptions file is an addendum to the specification file. It specifies additional switches for specific patterns. This allows you greater flexibility and control when running large batches of jobs. The information in the exceptions file is passed directly to legion_run or, if you use the -e flag, to whichever command you have specified (legion_run_multi command is essentially a script that calls multiple legion_runs or whichever command specified).

For example, suppose that the following jobs match the patterns in your specification file:

ABC
DEFGH
123
9999
GIRAFFE

The specification file already provides input/output/constant information for all of these jobs and command line flags provide additional instructions. However, you wish to fine-tune these instructions for just jobs DEFGH and 123. In the exceptions files, you can specify these two jobs and give your additional instructions:

DEFGH -h /hosts/special_host_name
123 -v -IN /tmp/myJob/ExtraStuff

The first line tells Legion that you wish to run job DEFGH on a specific host. The second line says that job 123 requires an additional input file and that you wish to run the job in a verbose form.

These instructions combine with any other specifications that were provided on the command line and/or in the specification file.

Limitations, caveats, warnings

1. Be sure that you use legitimate syntax in the exceptions file. Do not specify flags that do not exist for that particular command (e.g., there are no -CONSTANT/-constant flags in legion_run).
2. If you specify a host in the exceptions file and an architecture on the command line (with the -a flag), be sure that they match. If you specify conflicting architectures Legion will be unable to process that particular job (but it will run any other jobs).

Parameters

You must specify at least one of the following two parameters:

-n <number of processors>	Specify the number of processes running at one time.
-s[chedule] <schedule file>	Name a file containing a set of host context paths and number of processes to be run on each host (e.g., /hosts/Foo 3 to run up to three jobs on host object Foo). The format of the schedule file is as below. One host per line. /hosts/firsthost 2 /hosts/secondhost 1 /hosts/thirdhost 7

You must specify the following two parameters:

-f <specification file path>	The specification file's Unix path name.
<program class name>	The program's Legion class name (created when the program was registered in Legion).

Options

The following options are available with this command:

-v[erbose]	Provide a verbose output as the command is running.
-z[ero]	Consider input and output files of zero size to be valid. If this option is used, a zero-sized input file can be used to start a job and a zero-sized output file can be used to signal a completed job.
-r[estart]	Restart incomplete jobs.
-e[xec] <command>	Run some other <command>. The default is legion_run.
-x <exceptions file path>	The exceptions file's Unix path path.
-help	Print command syntax and exit.
-debug	Turn debugging mode on. In this mode, legion_run_multi prints copious output regarding which patterns must be run. This flag also turns on the verbose mode (-v).
<arg1> <arg2>... <argn>	Provide arbitrary command-line arguments for the registered program.

For more information, see the FAQ.

Alphabetical list of Legion commands

legion_activate_instances legion_activate_object legion_add_acl legion_add_class_mapping legion_add_host_account legion_add_implicit_params legion_add_sub_collection legion_allow_activation legion_bfs legion_cat legion_cd legion_change_owner legion_change_permissions legion_check_system legion_class_host_list legion_class_vault_list legion_classof legion_combine_domains legion_config_scheduler legion_context_add legion_context_create legion_cp legion_create_class legion_create_implementation legion_create_object legion_create_object_r legion_create_stat_tree legion_create_user legion_create_user_object legion_deactivate_instances legion_deactivate_object legion_destroy_host legion_destroy_instances legion_destroy_object legion_destroy_vault legion_direct_output legion_exports_interface legion_export_dir legion_generate_idl legion_generate_domain_cookie legion_get_acl legion_get_host legion_get_implicit_params legion_get_interface legion_get_vault legion_host_stats legion_host_vault_list legion_import_tree legion_init_arch legion_init_security legion_initialize legion_instance_host_list legion_instance_vault_list legion_join_collection legion_leave_collection legion_link legion_list_attributes legion_list_domains legion_list_host_accounts legion_list_implementations legion_list_instances legion_list_invocations legion_list_names legion_list_objects legion_list_oprs legion_list_sub_collections legion_ln legion_login legion_logout legion_ls legion_make legion_make_idl

legion_make_multi legion_make_schedule legion_make_setup_script legion_make_hostlist legion_mkdir legion_mpi_debug legion_mpi_register legion_mpi_probe legion_mpi_run legion_mplc legion_mplc_reg_impl legion_mv legion_native_mpi_config_host legion_native_mpi_init legion_native_mpi_register legion_native_mpi_run legion_object_info legion_output_state legion_passwd legion_ping legion_print_config legion_print_domain_cookie legion_probe_run legion_pvm_register legion_pwd legion_query_collection legion_record legion_refresh_local_cache legion_register_program legion_register_runnable legion_replay legion_remove_host_account legion_remove_sub_collection legion_rm legion_run legion_run_multi legion_set_acl legion_set_backup_vaults legion_set_binding_agent legion_set_context legion_set_default_placement legion_set_host legion_set_implicit_params legion_set_message_security legion_set_scheduler legion_set_scheduler_policy legion_set_tty legion_set_vault legion_set_varch legion_set_vrun legion_set_worm legion_setup_state legion_shutdown legion_shutdown_class legion_starthost legion_startup legion_startvault legion_stateless_add_workers legion_stateless_configure legion_stateless_remove_workers legion_synch_vaults legion_tty legion_tty_off legion_tty_redirect legion_tty_unredirect legion_tty_watch legion_unset_worm legion_update_attributes legion_vault_host_list legion_version legion_wellknown_class legion_whereis legion_whoami

---

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: Thu Mar 22 16:49:27 2001

[Home] [General] [Documentation] [Software] [Testbeds] [Et Cetera] [Map/Search] legion@Virginia.edu http://legion.virginia.edu/