Elements of the Dataplore ® Macro Language

Elements of the Dataplore ® Macro Language

Error, Warning and Debug Messages
Function Definition
Call by Value
Call by Reference
The return Statement
Comments
The Preprocessor Directive include
Macro Statements
Function Names
The Function Body
The export Specifier
The Return Type of a Function
Identifiers
Protected Names
The Fundamental Data Types
Type Conversion
The if Statement
The if-else Statement
The while Loop
The do-while Loop
Arithmetic Operators
Logical Operators
Hierarchy of Operators
Arrays

Error, Warning and Debug Messages

During compilation and execution of a macro, Dataplore ® outputs different kinds of messages:

Error and warning messages that occur during compilation are displayed in the Dataplore ® error window.
If the option Show function calls in the message window from the preferences Macro panel is selected, every call to a macro function from Dataplore ® is reported in the message window in the form
```
Start macro : macro_name
```
Depending on the debug level chosen in the same preferences panel, additional information about the execution of a macro, like values of variables and arguments passed to a function, etc., are shown in the report window.

Function Definition

A function has the following general syntax:

return_type FunctionName(argument_list)
{
   declarations of variables

   statements
 
   return return_value;
}

The function argument list follows immediatly after the function's name and is enclosed in parentheses ('(' and ')'). Each argument in the list is a type specifier followed by a variable name. If the function argument list contains several variables, commas are used to separate the different arguments. Arguments of data type signal have to be stated first, the order of all others is irrelevant.

void Test1()
{
   ...
}

int[3] Test2(signal s, int a, float b[2])
{
   ...
}

The arguments can be classified in two separate categories:

call by value
call by reference

Call by Value

Passing of a variable to a macro function in the following manner

return_type FuntionName(variable_type variable_name)

is refered to as call by value. In this case not the variable itself but an exact copy is generated and passed to the function during execution. Thus, after a call to the function the variable has still its old value.

For example:

void Fnct1(...)
{
   int a;

   a = 1;
   Fnct2(a);
   a = a + 3; // now a is 4 not 5
   ... 
}

void Funct2(int j)
{
   j = 2;
}

Call by Reference

Call by reference passes an argument to a function by reference to a memory address, and does not generate a copy of the variable. The syntax is:

return_type FuntionName(variable_type &variable_name)

After executing the function the call by reference variable has the value assigned to it in the function.

For example:

void Fnct1(...)
{
   int a;

   a = 1;
   Fnct2(a);
   a = a + 3; // now a is 5
   ... 
}

void Fnct2(int &j)
{
   j=2;
}

The `return` Statement

If a function returns a value of a given type, the function must instruct the compiler about the type of the value it is going to return. This is performed via the return statement that returns a variable of a type matching the specified return type in the function declaration. A function can return several variables in an array.

Comments

Two successive slash characters ("//'') inform the compiler that a comment follows which has to be ignored during compilation. A comment extends to the end of a line and may be placed inside or outside a function.

Example:

// A comment outside a function 
signal Fnct( int i, float f )
{
    // A comment inside a function
    float x; // x is a float variable 
    
    statement; // a comment behind a statement

    // This is 
    // another comment
    statement;
    ...
}// end of Fnct

The Preprocessor Directive `include`

Preprocessor directives are commands that are executed before the actual compilation. In the Dataplore ® macro language there is only one such directive, the include directive. It has the syntax

#include "filename.dpm"

The include directive instructs the compiler to read a file ("filename.dpm'') into the current source code file. This is necessary for the use of a non-compiled function in a macro from another source code file. If you try to compile this macro without including the other file, you will get an error message like this:

Error : In line 19 : Cannot find function (function_name)!

Pathnames are optional. For instance, one could specify the exact path for the file macro.dpm:

#include "C:\dataplore\dpm\macro.dpm"

The include directive must appear at the beginning of a source code file.

Macro Statements

Macro statements are the fundamental units of the macro language. The semicolon (";'') indicates the end of a statement. The compiler ensures that a statement is completed before the execution of the next statement begins. Warning: The semicolon is easily forgotten. Check therefore if every statement ends with a semicolon before compiling the macro program, otherwise an error will be produced during compilation.

Function Names

A macro function must have a name. In the declaration of a function this name must follow right after the return type. It may not exceed 80 characters and must begin with a capital letter. Except for these restrictions a function name may contain all small and capital letters, the underscore character '_' and the numbers from '0' to '9'. There are three protected names starting with a capital letter: TRUE, FALSE and NULL. These names have a special meaning in the macro language and cannot be used as function names.

Examples for valid function names are:

CreateSignal, Test_Function, Func123

The Function Body

The function body contains the macro code, i.e. the sequence of statements actually performing a function's task. The size of a function body in terms of macro statements is not limited. It must be enclosed in curly braces '{' and '}'. Every local variable of the function must declared after the opening brace. After that follows a sequence of commands. The function body ends with the return statement.

The `export` Specifier

The export specifier preceding a function name gives the function an export linkage. It can then be started from the Dataplore ® user interface whereas functions without an export specifier can only be used in other macro functions.
The argument list of an export function defines the dialog box that comes up when the compiled macro function is executed. The signal type arguments must be placed before all other types in this list. The non-signal type arguments, dialog box names, and default values may be specified optionally after the type and the name of an argument. The general syntax for the dialog items is:

<"Title">

for default value '0' or

<"Title","default_value">

for default value 'default_value'.

For int and string type arguments an option list may be created, too. The syntax for this is:

<"Title","text1","text2",...,"textn","default_value>.

This creates a choice item with the alternatives text1, ..., Textn in the dialog box and returns the selected label as a string type or the index of the selected label as type int. The default value gives the number of the alternative to be selected by default. The counting of the alternatives starts at zero. A value of '0' corresponds to the selection of text1, .... So if a default value is declared, it must be a positive integer less than the number of alternatives or zero.

For example, the parameter list of the function Fnct

export signal Fnct( int size <"Size","100">, 
                    float scale <"Scale of the signal","1.0">, 
                    int t <"Type","Maximum","Minimum","1"> )

will result in the following dialog box:

The Return Type of a Function

A macro function can return the result of internal operations to the calling instance. The type of the quantity it returns must be specified in the head of the function. It may be any of the fundamental data types void, bool, int, float, string or signal. Therefore a function can return numbers (types int, float), logical values (type bool), strings of characters (type string) or signals (type signal). If a function does not return anything, its return type is void.

Identifiers

Variable names or identifiers must be defined before they can be used. They must start with a small letter and may not exceed 80 characters. All letters from 'a' to 'z' and 'A' to 'Z', the underscore character '_' and the numbers from '0' to '9' are allowed. There are a few protected names that must not be used as identifiers. Examples for valid identifiers are:

n_1, numOfRows, a1b2c3

Protected Names

Names that have a special meaning in the Dataplore ® macro language are called protected names. They cannot be used as names for variables or functions.
The following names are protected:
array, bool, break, case, char, class, const, continue, do, double, else, export, extern, FALSE, float, for, if, include, int, long, matrix, NULL, return, static, short, signal, string, struct, switch, TRUE, vector, void, while.

The Fundamental Data Types

There are six fundamental data types in the Dataplore ® macro language.

void is only allowed for return type declarations of functions.
bool is the data type used for logical operations (False (0) - True (1)).
The int data type is used for integer numbers ranging from -2147483648 (-2E31) to 2147483647 (2E31-1).
The float type is used to represent floating-point numbers. It ranges from 1.7x10E-308 to 1.7x10E308.
string is a fundamental data type that represents characters and character strings.

The data type signal is used for the declarations of signals. It covers all signal formats, i.e. one or more dimensional signals, complex signals, wavelets, and plot signals.
In the vocabulary of the C programming language, the type signal is a structure since it has several members. The values of these members specify all characteristic properties of a signal including its type (member Type).
The 14 members of the data type signal are:

type	member
(int)	Size	number of data points
(int)	Dimension	number of dimensions
(float)	Scale	time scale
(float)	Shift	offset on x-axis
(int)	Type	signal type
(int)	Noct	number of octaves
(int)	Nvoice	number of voices
(float)	MinY	minimum on the y-axis
(float)	MaxY	maximum on the y-axis
(float)	MinX	minimum on the x-axis
(float)	MaxX	maximum on the x-axis
(string)	Title	title of the signal
(float)	ArcMaxY	x-value of (first appearance of)
		maximum on y-axis
(float)	ArcMinY	x-value of (first appearance of)
		minimum on y-axis

A member is accessed using the dot operator (".''). The general syntax for accessing a member is name.Member. For example:

  float max;  
  signal s;
  max = s.MaxY; // access member MaxY of signal s

Type Conversion

Automatic type conversion is implemented in the Dataplore ® macro language. The legal conversions without loss of information are:

bool -> int

bool -> float

int -> float

Those with loss of information are:

float -> bool

float -> int

int -> bool

Also allowed are type conversion of numbers into strings:

float -> string

int -> string

bool -> string

All other conversions give undefined results and should be avoided.

The `if` Statement

The instruction if evaluates the expression that follows in brackets. The general syntax of the if statement is

if ( expression )
{
   statements
}

The value of the expression must be boolean, i.e. it must be false or true. (In numeric values, false is 0, every other value is true). If the expression is true, the statements in curly braces are executed, otherwise not. The braces are obligate. If they are omitted, an error will occurr during compilation.

The allowed operations for the expression to be tested are

<: less than
<=: less than or equal to
>: greater than
>=: greater than or equal to
==: equal to
!=: not equal to

Example:

if ( a < 12 )
{
   sig = AddConst(sig,a);
}

The `if-else` Statement

This statement does almost the same as the if statement. The difference is that it includes an alternative. If the test of the expression following the if statement fails then the else alternative will be executed.
The general syntax for this statement is:

if (expression)
{
   statements
}
else
{
   statements
}

An example is:

if (a > 12)
{
   s = Derive(s,a);
}
else
{
   s = Integrate(s);
}

Warning: There is no else if alternative as in the C programming language. You must use several if statements instead!

The `while` Loop

Similar to the if and the if-else statement, also for the while loop an expression is tested in order to decide whether or not a statement or a sequence of statements will be executed. But in this case the execution will be repeated until the expression becomes logically false.
The general syntax of the while loop is

while(expression)
{
   statements
}

For example:

while(a < b)
{
   a = a+1; // increment a
   b = b-1; // decrement b
}

The `do-while` Loop

The do-while loop is very similar to the while loop. The general syntax is:

do
{
   statements
} while(expression);

Unlike the while-loop the do-while-loop is executed at least once independent of the value of expression.

Arithmetic Operators

The Dataplore ® macro programming language provides the same arithmetic operators as C. They are:

+: add
-: subtract
*: multiply
/: divide
%: modulo (gives the rest of a division of two integers)

+, -, *, and / may be applied to all variables of data type int and float. % can only be used for int variables.
The syntax for arithmetic operations is:

variable1 operator variable2

For example:

int n, m, p;
float f1, f2;
n = 5;
m = 2;
p = n\%m; // p = 1
f1 = 3.1;
f2 = m * f1; // f2 = 6.2

Logical Operators

Logical operators allow you to combine boolean (true-false) values logically. There are three logical operators provided by the macro language:

&&: logical AND
||: logical OR
!: logical NOT

For example:

if (m < 7  && m != 3)
{
   n = 1 / (m-3);
}

while ( (size <= 1000 || scale >= 0.1) && mean != 0.0)
{
   sig = GaussNoise(size, mean, scale);
}

Hierarchy of Operators

The following list gives an overview of all operators and their hierarchy:

!
* / %
+ -
< <= > >=
== !=
&&
||

Operators on the same line have the same hierarchy level. The lines are sorted according to decreasing hierarchical order. The operators * and / will be executed before + and -, for example.

Arrays

An array is a group of variables of the same type in which each element can be referenced individually. The general syntax for the declaration of an array is:

Type_specifier array_name[number_of_elements];

The array size (the number of elements) must be a constant defined before compilation. The maximum size is 15. Arrays start with the index 0.
For example:

int myarray[4];
int a[5],d[6],c[4],h;
signal s[4];

a[0]=d[1];       // correct
a=c;             // correct: copy all elements form c to a
a=d;             // error: array a has less elements than d 
a=[1,2,5,100];   // correct: copy the values to the four elements of a
c=[h,d[0],4];    // correct: copy the values to the first three
                 //          elements of the array
s[1]=ConstSignal(100,1.0,1.0);

Elements of the Dataplore ® Macro Language

Error, Warning and Debug Messages

Function Definition

Call by Value

Call by Reference

The return Statement

Comments

The Preprocessor Directive include

Macro Statements

Function Names

The Function Body

The export Specifier

The Return Type of a Function

Identifiers

Protected Names

The Fundamental Data Types

Type Conversion

The if Statement

The if-else Statement

The while Loop

The do-while Loop

Arithmetic Operators

Logical Operators

Hierarchy of Operators

Arrays

The `return` Statement

The Preprocessor Directive `include`

The `export` Specifier

The `if` Statement

The `if-else` Statement

The `while` Loop

The `do-while` Loop