INVOKE

invoke a method on an object and optionally return the result

<res=func,...,resn=funcN> - Tag/value pair or single function

Keyword Only Parameters:

[label] - Legacy tag for result, no longer needed
[func]  - Legacy tag for function, no longer needed


This command invokes a method on an object accessible from the NeXtMidas
framework.  The function parameter is either a results entry, registry entry,
or fully qualified class name (case sensitive).  Multiple return and function
arguments are supported of the form:

  invoke <res>=<func> ... <resN>=<funcN>

For example:

  nM>invoke pi=java.lang.Math.pi deg2rad=nxm.sys.inc.Constants.DEG2RAD

sets the results PI and DEG2RAD.

If the function name has no parentheses, or has an empty set of parentheses,
the function is assumed to be a void function.  If the parentheses contain
arguments, separated by parenthesis, then NeXtMidas will convert these
arguments into types and search for a method with the determined types in the
given order.

Commands are executed from left to right, chaining of method invocations is 
not supported.  A return value is needed to change a result inplace.  Thus

  nM> res str "a string"
  nM> invoke str.toUpperCase()  ! This DOES NOT CHANGE STR !!!

does not upper case the string 'str', but

  nM> res str "a string"
  nM> invoke str=str.toUpperCase()  ! This DOES CHANGE STR !!!

changes str to "A STRING"

Note: Currently it is impossible to invoke a method in Table, KeyVector, or 
other Keyable classes because everything goes through setKey/getKey.

Examples:
  * To determine the sin of 1.2
       nM> invoke D:x=java.lang.Math.sin(1.2)
         D: X               = 0.9320390859672263
  
  * To determine the pi and 
       nM> invoke D:pi=java.lang.Math.pi 
  
  * From inside a macro, clean the arguments to the macro:
       nM> invoke S:str=this.args.clean
  
  * To get the name of a layer:
       nM> plot/bg world
       nM> invoke name=PLOT.LAYERS.WORLD.NAME()
        5S: NAME            = WORLD
  
  * To get the mask value of the string X|Z
       nM> invoke L:maskVal=nxm.sys.lib.Parser.mask("X,Y,Z","X|Z",2)
         L: MASKVAL         = 5

  * Create a new instance of java.lang.Integer (note that "<init>" is the 
    internal Java name for the constructor) [Since NeXtMidas 2.1.0] :
       nM> invoke temp=java.lang.Integer.<init>(4)

     this is the same as using:
       nM> new java.lang.Integer(4) temp

Switches:
  /VERBOSE - Show more output

See Also:  NEW, SET, RESULTS