2.0 Command-line functions

2.1 Calls on objects

legion_exports_interface
      {[-c] <context name> | -l <LOID>}
      {-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. The set can be listed via the legion_wellknown_class tool (see page 56).

For this tool's purposes, 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 /class/LegionClass \    
   -w ClassObject
1
$
$ legion_exports_interface /class/LegionClass \
    -w CommandLineObject
"CommandLineObject" is not a well known class. Exiting.
-1
$
$ legion_exports_interface /class/LegionClass \
   -w LegionClass -w ClassObject
1
$
$ legion_exports_interface /hosts/BootstrapHost \
   -w UnixHostClass
1
$
$ legion_exports_interface /hosts/BootstrapHost \
  -w ClassObject
0
$
$ legion_exports_interface /class/LegionClass \
   -f "     LegionLOID ping();"
1
$
$ legion_exports_interface /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 
      {[-c] <class context name> | -l <class LOID>} [-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.

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

$ legion_get_interface 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(
		ObjectAttribute-List);
	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 
      {[-c] <object context name> | -l <object LOID>} 
      [-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.

$ legion_ping foo
Pinging:  1.01.66000000.14000000.000001fc0a72...
Returned: 1.01.66000000.14000000.000001fc0a72...
$

If the object is not accessible by the tool, the command will return an error.

$ legion_ping foo
"foo" does not resolve to a valid loid in my context.

The following optional parameters are available:

-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 
      {[-c] <object context name> | -l <object LOID>} 
      [-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 Foo
Foo:
  (ALL)
Total attributes retrieved 1
        favoritecolors('puce', 'apricot')
$
legion_list_invocations 
      {[-c] <object context name> | -l <object LOID>} [-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 name> | -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] <instance context path> | -l <instance LOID>}

This command tells Legion that the specified object no long has 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 upper case 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
$

Directory of Legion 1.7 Manuals
[Home] [General] [Documentation] [Software]
[Testbeds] [Et Cetera] [Map/Search]

Free JavaScripts provided by The JavaScript Source

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