User's Guide - Invoking Data Explorer Macros and Modules

10.5 Invoking Data Explorer Macros and Modules

This section describes the procedures and features for invoking macros and modules. It describes function call arguments and attributes.

Function Call Arguments

Data Explorer provides a flexible function-calling mechanism for invoking macros and modules.

A macro's definition includes a list of identifiers that are used as its input formal parameters. The formal parameters act as names and place holders for the arguments that you supply when the macro is called.

Modules (functions that are compiled into the system) have named formal parameters. The general form of a function (macro or module) call, whether used as the right hand side of an assignment statement or on its own, is:

Name (arglist)[attribute_name:value,...]

where Name is the name of the function being called and arglist is a list of arguments that are separated by commas (the list can be empty). Following the function may optionally be a list of attribute_name:value pairs enclosed in square brackets. Each argument's value can be either a variable identifier, a constant value, an expression, or the special identifier NULL. Note that nested function calls cannot be passed as arguments. The argument values can be passed either by position or by name, as described in the following sections.

Positional Arguments

The positional argument-passing mechanism is similar to the mechanism found in most programming languages that use subroutines. Given a function declared with n input formal parameters, the first n values supplied in the function call are assigned to the first n formal parameters. If you supply i < n values in the function call, then only the first i of the function's formal parameters are assigned the supplied values.

The missing arguments are assigned the value of NULL.

By-Name Arguments

The "by name" argument-passing mechanism provides more flexibility in specifying arguments. When an argument is passed by name, the following syntax is used for the argument:

Fname = value

Fname is an identifier that corresponds to one of the function's input formal parameters. Value is one of the types of values that are valid for that argument to the function. If the function is a macro, the arguments are named in the definition of the macro in the script. If the function is a module, the argument names are provided in the description of the module in Chapter 2. "Functional Modules" in IBM Visualization Data Explorer User's Reference.

Notes:

Positional arguments can be supplied only prior to by-name arguments, because the positional context is lost once a name has been supplied.
If an argument is supplied both by position and by name, then the value given by name takes precedence.
If an argument is supplied by name more than once in a given function call, then the value associated with the last (rightmost) instance of the input formal parameter is used.
A name that does not correspond to one of the function's formal parameters and its associated values is considered a semantic error.

Missing Arguments

Any formal parameter of a module that has not had a value passed to it, either by position or by name, is initialized to the value NULL. If NULL is explicitly passed into the module, the module may still use the default value, provided it is designed to do so. The NULL value allows modules to use internal defaults for those values that are not specified in a function call. The default value must be specified in the code of the module (see IBM Visualization Data Explorer Programmer's Reference for information).

If the function is a macro, a missing argument or an argument explicitly specified as NULL causes the default value to be used. If no default is specified, the parameter is set to NULL.

Example

The module Camera takes the following arguments:

to
The position in space to which the camera is pointed. The default is [0, 0, 0].
from
The position in space where the camera is located. The default is [0, 0, 1].
width
The width, in user units, of the camera's view. The default is 100.
resolution
The horizontal resolution, in pixels, of the image generated by the camera. The default is 640.
aspect
The aspect ratio of the image generated by the camera (i.e., its height divided by its width). The default is 0.75.
up
The direction, in the world coordinate system, that the camera considers "up" The default is [0, 1, 0].
perspective
The projection method. The default is 0, indicating orthographic projection.
view angle
The viewing angle. This applies only in perspective projection, and the default is 30.
background
The image background color. The default is "black".

The following function calls are all equivalent and construct the default Camera Object:

c1 = Camera ([0, 0, 0], [0, 0, 1], 100, 640, 0.75, [0, 1, 0], 0, "black");
c2 = Camera (NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL);
c3 = Camera ();
c4 = Camera (NULL, NULL, NULL, NULL, NULL, [0, 1, 0], NULL, NULL);
c5 = Camera (up = [0, 1, 0]);
c6 = Camera ([5, 5, 5], [0, 0, 1], NULL, to =  [0, 0, 0]);
c7 = Camera (width = 512, width = 640);

Function Call Attributes

Functions may optionally have attributes associated with each invocation of the functions, and attributes may also be associated with specific outputs of a module. The Data Explorer scripting language provides three function call attributes:

instance
Identifies the instance of a function call. This can help you locate errors in scripts. To use the instance attribute, follow the function call with instance and the instance number separated by a colon and enclosed in brackets. For example:
out1 = Color(surface,"blue") [instance:1]; out2 = Color(surface,"green") [instance:2];

In this example, each instance of the Color module is identified uniquely. If an error occurs, the error message will report the module name, in this case Color, plus its instance number. If the instance numbering was not used, the error message will only report the name of the module.
cache
Specifies whether the system writes the outputs of a module into the cache. The cache is a portion of memory in which results of previously executed functions are stored. If the inputs to a module do not change the module will not be invoked in subsequent executions, rather the module results are retrieved from the cache. If the module results are not found in the cache, because they were purged in order to make room for some other result or they were never stored in the cache, the module will be reexecuted.
The cache attribute can have one of three values:

[cache:0] - Do not cache the module outputs
[cache:1] - Cache all the results of the modules outputs
[cache:2] - Cache only the results of the modules outputs for the last execution of the module

The cache attribute can be associated with the individual outputs of a module, with the entire module (affecting all the outputs) or a combination of both. When output-associated and module-associated cache attributes are used in combination the output-associated attributes override the effects of the module-associated attributes.
The following two examples illustrate how the cache attribute can be used. In the first example the attribute is associated with the module. In the second example the attribute is associated with the module output. The results of both of these examples are identical since Isosurface has only one output.
iso = Isosurface(data,value) [cache:0]; iso [cache:0] = Isosurface(data,value);

The following examples look similar to those above, but there is a difference because DivCurl produces two outputs. In the first example, only the last result of both outputs of DivCurl are stored in the cache. In the second example the last result of div is placed in the cache, but all results of curl are placed in the cache.
div, curl = DivCurl(data) [cache:2]; div [cache:2], curl = DivCurl(data);

In the following example all outputs of Statistics are not cached except for min. Since a cache attribute with a value of 2 was associated with min, the last result of the min output of Statistics will be stored in the cache.
mean, sd, var, min [cache:2], max = Statistics(data) [cache:0]

If no cache attribute is associated with the module, all results of the outputs will be cached unless an individual output has a cache attribute associated with it. The following example is similar to the one above, except that all results of module outputs are cached with the exception of min. Since a cache attribute with a value of 2 was associated with min only the last result of the min output of Statistics will be stored in the cache.
mean, sd, var, min [cache:2], max = Statistics(data);

group
Identifies which execution group a module belongs to. This attribute is used to distribute parts of a visualization across multiple workstations. This attribute does not bind a module to a specific workstation, but identifies it to be a member of a group that may be assigned to a workstation. The assignment of an execution group to a workstation is done using the Executive module (see Executive in IBM Visualization Data Explorer User's Reference).
The following example illustrates how the group attribute can be used.
cwater = Import("cloudwater"); iso = Isosurface(cwater); wind = Import("wind") [group: "group2"]; x = Compute("$0.x",wind) [group: "group2"]; mapped = Map(iso,x); colored = Color(mapped); camera = Camera(colored); Display(colored,camera);

The second Import and the Compute will be placed into an execution group called "group2". All other modules will be placed into one default execution group.
You can combine the various attributes for a single function call by separating them with commas, as in the following examples:
wind = Import("wind") [instance:2, group: "group2"]; Colored = Color(iso,"blue") [instance:1, cache:2]; Colored = Color(iso,"green") [instance:2, cache:2, group:"group"];

one shot
Represents the script language implementation of the Reset interactor in the user interface. It sets the value of a variable to one value for the first execution and a different value (resetvalue) there after. The syntax is:
x[oneshot:resetvalue] = value;

[ OpenDX Home at IBM | OpenDX.org ]

`to`	The position in space to which the camera is pointed. The default is [0, 0, 0].
`from`	The position in space where the camera is located. The default is [0, 0, 1].
`width`	The width, in user units, of the camera's view. The default is 100.
`resolution`	The horizontal resolution, in pixels, of the image generated by the camera. The default is 640.
`aspect`	The aspect ratio of the image generated by the camera (i.e., its height divided by its width). The default is 0.75.
`up`	The direction, in the world coordinate system, that the camera considers "up" The default is [0, 1, 0].
`perspective`	The projection method. The default is 0, indicating orthographic projection.
`view angle`	The viewing angle. This applies only in perspective projection, and the default is 30.
`background`	The image background color. The default is "black".

instance	Identifies the instance of a function call. This can help you locate errors in scripts. To use the `instance` attribute, follow the function call with instance and the instance number separated by a colon and enclosed in brackets. For example: out1 = Color(surface,"blue") [instance:1]; out2 = Color(surface,"green") [instance:2]; In this example, each instance of the Color module is identified uniquely. If an error occurs, the error message will report the module name, in this case Color, plus its instance number. If the instance numbering was not used, the error message will only report the name of the module.
cache	Specifies whether the system writes the outputs of a module into the cache. The cache is a portion of memory in which results of previously executed functions are stored. If the inputs to a module do not change the module will not be invoked in subsequent executions, rather the module results are retrieved from the cache. If the module results are not found in the cache, because they were purged in order to make room for some other result or they were never stored in the cache, the module will be reexecuted. The cache attribute can have one of three values: [cache:0] - Do not cache the module outputs [cache:1] - Cache all the results of the modules outputs [cache:2] - Cache only the results of the modules outputs for the last execution of the module The `cache` attribute can be associated with the individual outputs of a module, with the entire module (affecting all the outputs) or a combination of both. When output-associated and module-associated `cache` attributes are used in combination the output-associated attributes override the effects of the module-associated attributes. The following two examples illustrate how the `cache` attribute can be used. In the first example the attribute is associated with the module. In the second example the attribute is associated with the module output. The results of both of these examples are identical since Isosurface has only one output. iso = Isosurface(data,value) [cache:0]; iso [cache:0] = Isosurface(data,value); The following examples look similar to those above, but there is a difference because DivCurl produces two outputs. In the first example, only the last result of both outputs of DivCurl are stored in the cache. In the second example the last result of `div` is placed in the cache, but all results of curl are placed in the cache. div, curl = DivCurl(data) [cache:2]; div [cache:2], curl = DivCurl(data); In the following example all outputs of Statistics are not cached except for `min`. Since a `cache` attribute with a value of 2 was associated with `min`, the last result of the `min` output of Statistics will be stored in the cache. mean, sd, var, min [cache:2], max = Statistics(data) [cache:0] If no `cache` attribute is associated with the module, all results of the outputs will be cached unless an individual output has a `cache` attribute associated with it. The following example is similar to the one above, except that all results of module outputs are cached with the exception of min. Since a `cache` attribute with a value of 2 was associated with min only the last result of the min output of Statistics will be stored in the cache. mean, sd, var, min [cache:2], max = Statistics(data);
group	Identifies which execution group a module belongs to. This attribute is used to distribute parts of a visualization across multiple workstations. This attribute does not bind a module to a specific workstation, but identifies it to be a member of a group that may be assigned to a workstation. The assignment of an execution group to a workstation is done using the Executive module (see Executive in IBM Visualization Data Explorer User's Reference). The following example illustrates how the `group` attribute can be used. cwater = Import("cloudwater"); iso = Isosurface(cwater); wind = Import("wind") [group: "group2"]; x = Compute("$0.x",wind) [group: "group2"]; mapped = Map(iso,x); colored = Color(mapped); camera = Camera(colored); Display(colored,camera); The second Import and the Compute will be placed into an execution group called "group2". All other modules will be placed into one default execution group. You can combine the various attributes for a single function call by separating them with commas, as in the following examples: wind = Import("wind") [instance:2, group: "group2"]; Colored = Color(iso,"blue") [instance:1, cache:2]; Colored = Color(iso,"green") [instance:2, cache:2, group:"group"];
one shot	Represents the script language implementation of the Reset interactor in the user interface. It sets the value of a variable to one value for the first execution and a different value (resetvalue) there after. The syntax is: x[oneshot:resetvalue] = value;