In the strictest sense, Ogrescript tasks do not have return values: the ITask.execute method returns void. However, return values can be emulated by a post-processing routine which side-effects the environment by assigning a set of named values representing the "returnable" results of the task.

If the task extends OgreScriptTask, it automatically accepts any number of return-value placeholder elements (return-value). The internals of the task should declare a set of default names for any values it makes available to be returned; the script code can then select to return any, all or none of these, either under the default name or a reassigned name.

All return values are processed as implicit assign rather than declare operations, so the variable names to which their values are to be assigned must exist in the scope of the task's call.

Here is a simple illustration:

<ogrescript>
	<declare name="withZeros"/>
	<add-leading-zeros number="${someCounterNumber}" places="7">
            <return-value assignedName="withZeros" defaultName="zerosAdded"/>
	</add-leading-zeros>
</ogrescript>

As a further example of how an OgreScriptTask processes return values we provide the following code snippet for the add-leading-zeros tag above:

ncsa.tools.ogrescript.tasks.string.AddLeadingZeros
public static final String TAG_SELF = "add-leading-zeros";
public static final String TAG_RETURNS = "zerosAdded";
	
private Object       number;
private int          places;

public AddLeadingZeros()
{
   number = null;
   places = 0;
   defaultReturnValueNames = new String[]{ TAG_RETURNS }; // DECLARE THE DEFAULT VALUES HERE
}

protected void wrappedExecute( IProgressMonitor monitor )
		throws ScriptExecutionException
{
   String adjusted = StringUtils.addLeadingZeros( number, places );
   setReturnValue( TAG_RETURNS, adjusted );  // SET EACH ONE OF THEM UPON COMPLETION
}
...

Note that wrappedExecute should terminate by calling setReturnValue on all possible return values; the user indicates whether they should be exported or not by adding the corresponding <return-value> elements (ncsa.tools.ogrescript.tasks.OgreScriptTask provides for checking which ones indeed get exported).

In general, the containers discussed in the Control Flow section do not have return values; call is a special case which does allow for return values defined on procedures to be returned to the calling frame (see 2. Call and 1. Define for further explanation).

Implicit Return Values

It is always possible to code any particular Ogrescript task to return a value or set of values directly to the environment. In particular:

  1. If there is only one value, give the task assign and declare attributes of type String (indicating the variable name for this value), and a boolean attribute for global. For instance, cf. the <section> type under <string-cut>.
  2. Alternatively, use boolean attibutes for both declare and global; cf. <format-number>.
  3. For multiple attributes, especially those which are indeterminate until run-time, one can stipulate as part of the contract of the task that the names must not collide with any other in scope; in which case, they can be declared, either globally or locally, using the names they already have; cf. <properties>.

Other schemes are, of course, possible. The return-value functionality merely attempts to provide a standardized way for handling the general case where the values are potentially multiple, and all potential values to be returned are known prior to execution.

  • No labels