10.6 Defining Macros

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

• A macro header
• A macro body

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) ]

• The keyword macro indicates that a new macro definition has started.

• MacroName is an identifier of the name that is being associated with the macro definition.

• The inputs portion of a macro header is a list of identifiers separated by commas. The list may be empty. These identifiers act as place holders for the arguments passed to the macro when it is called. If the macro does not require any arguments, then you can omit the list (but not the enclosing parentheses). The right-arrow symbol is needed only for macros with outputs. The following are examples of valid headers for macros without outputs:

  macro MyMacro(x,y)
  macro MyMacro()
  

  You can also specify default values for the inputs. Consider the following example:

  macro X (a = "no input", b = 4)
  {
    Echo (a, b);
  }
  

  The values of the arguments a and b vary, depending how the macro is invoked. For example:

  X();                // a and b are set to the defaults, "no input" and 4
  X("new value", 3);  // a is set to "new value", b is set to 3
  X(NULL);            // a and b are set to the defaults, "no input" and 4
  X(b = 6);           // a gets default of "no input", b is set to 6
  

  See 10.5 , "Invoking Data Explorer Macros and Modules" for further explanation of the function-calling mechanism.

• The outputs portion of a macro's header is a list of identifiers separated by commas.

  These identifiers act as place holders for the values returned by the macro when the macro is executed. If the macro does not return any values, then the right-arrow portion, -> (), is not necessary.

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) );