IBM Visualization Data Explorer User's Guide

[ Bottom of Page | Previous Page | Next Page | Table of Contents | Partial Table of Contents | Index ]


10.6 Defining Macros

Macros are higher level processing functions that are constructed from simpler ones. A macro definition consists of two parts:

The following sections define these parts.

Macro Header

The macro header defines the macro's name, its formal parameters, and the names of values that it returns. The syntax of a macro header is

   macro MacroName (inputs) [ -> (outputs) ]
where:

Macro Body

The macro body consists of a sequence of assignment statements and function calls surrounded by braces { }. The functions referred to in these statements need not exist when a macro is defined; however, they must exist when it is executed.

Recursive and mutually recursive macro invocations are detected and prevented from executing. Statements are not guaranteed to execute in the order given in the macro's declaration, although some partial ordering is always preserved. Calls to modules that cause external side effects (such as Display) are always executed in the order in which they were specified.

Macro Examples

The first example macro, Sum, takes two arguments. The macro computes and returns their sum.

macro Sum (arg1, arg2) -> (sum)
{
    sum = arg1 + arg2;
}

The second example macro, PrintSum, also takes two arguments and computes their sum. However, unlike the macro Sum, it does not return the computed value. Instead, it prints out using the Echo module. This example illustrates a function call (to Echo) that either does not return a value or whose return values are ignored.

macro PrintSum (arg1, arg2)
{
    sum = arg1 + arg2;
    Echo (sum);
}

The third example macro, VectorManip, implements a function to compute the cross product, dot product, and cosine of two 3-vectors. Note that the returned values do not need to be computed in the order in which they are declared.

macro VectorManip (vectlist1, vectlist2) -> (dot, cross, cos)
{
    cross = Compute("cross($0, $1)", vectlist1, vectlist2);
    dot = Compute("dot($0, $1)", vectlist1, vectlist2);
    cos = Compute("$0/(mag($1)/mag($2))", dot, vectlist1, vectlist2);
}

Note that the Data Explorer script language does not allow nested function calls. The following example illustrates a syntactically invalid function call:

Echo ( Sum (arg1, arg2) );


[ Top of Page | Previous Page | Next Page | Table of Contents | Partial Table of Contents | Index ]
[Data Explorer Documentation | QuickStart Guide | User's Guide | User's Reference | Programmer's Reference | Installation and Configuration Guide ]

[Data Explorer Home Page | Contact Data Explorer | Same document on Data Explorer Home Page ]


[IBM Home Page | Order | Search | Contact IBM | Legal ]