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:

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:

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:

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:

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:

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:

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:

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:

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
$

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