Arrays functions in the display interpreter

(available in almost any device except for very old ones - see Feature Matrix)

1. Overview
2. Acessing values in an array
3. Arrays as arguments in a function call
4. Changing the dimensions of the array at run-time
5. Watching the contents of 'arr[][][]' in the programming tool

• Arrays in the script language (not to be confused with the display-interpreter's array described in this document)
• Manual for the programming tool (general)

Overview

In some of MKT's programmable terminals, the built-in interpreter supports a numeric array. The array function has been implemented in Summer 2004 as a storage memory for a special extension to the terminal's diagram function (polygon overlays), but it can be used for other purposes also. More powerful arrays are supported by the script language, but the array functions in the display interpreter are still available for compatibility. Last not least, the old global array described in this document can also be accessed via script (display.arr[row][column][component]) to ease migration from 'display events' to the script language.

Some properties of the numeric array are:

• One array can store up to 4000 single floating point values, due to CPU- and compiler limits in early devices (C166: 16 kByte per memory object, 4 byte per 'float')
• Three array dimensions (let's call them row, column, and component)
• Per default, the interpreter's global array uses the dimensions specified in chapter 4 (max number of rows, columns, components).
  
• initial value of all cells is 0.0 (zero, float)
• Arrays can be used to pass many numeric values in function calls

To find out if your terminal supports numeric arrays, look into the Feature Matrix. Details about arrays in the script language are here.

Accessing values in an array

The values in the global array (named "arr") can be accessed like normal floating-point variables. The array indices must be appended after the array's name in squared brackets.

The terminal's numeric array is three-dimensional by default (may be changed with the "dim"-command one day). For simplicity, let's assume our three dimensional array is arranged in rows, columns, and components (=single values) as in the following 10*5*4-array (10 rows, 5 columns per row, 4 components in each column). The four components in each column may be considered the coordinates of a point. Here, it doesn't matter what the indexes are used for and how you call them in your application.

Note:

It is common practice to call the first dimension "rows", the second "column", the name for the third dimension is up to you. If you use the array to draw polygons into a diagram, the third dimension is used to store the X- and Y-component of a coordinate.

For the examples below, let's assume there are already some values stored in the array:

Please note that like in the "C" programming language, array indices run from ZERO to <max size minus one>. For the 10*5*4-table shown above, the row index runs from 0 to 10, the colums from 0 to 4, and the components from 0 to 3.
The basic syntax to access an array is:
 arr[<column>][<row>][<component>]

Accessing single values in an array

arr[0][0][0]

accesses the first row, first column, first component in a three-dimensional array (as part of a numeric expression).

arr[0][1][2] := 6.123

assigns a single numeric value to the first row, second column, third component in a three-dimensional array. In the sample array shown above, this will replace the value '6.0' by '6.123'.

Accessing a range of cells in an array

To save space in the program memory, you can set multiple values in one command by referencing a whole range of indexes in a single command. For example, you may want to clear everything in row 0 (all columns in that row, and all components of the columns), use a command like this:

arr[0][0..4][0..3] := 0.0

This causes the interpreter to run through two "automatic loops" to access five columns (0 to 4) and four components per row (0..3). In this simple example, all values are will be the same.

Accessing a complete row may be abbreviated by leaving the column- and component-index-range away like this:

arr[0] := 0

This clears everything in the first row of the array, regardless of how many columns and components are in it. You don't have to bother with the dimensions of the array. In a similar way, all components in a particular column can be set:

arr[7][0] := 0

Clears all four components in row 7, column 0 which formerly contained the values 140,141,142,143.

For special applications, you may need the index when accessing values in the array. For this purpose, up to three automatic variables (one for every dimension) can be used. The names of such automatic variables consist of a lower-case letter like in these examples:

arr[i=0..9][j=0..4][k=0..3] := 20*i + 4*j + k

In this example, "i" is the row index running from 0 to 9, "j" is the column index running from 0 to 4, and "k" is the component index (think of X,Y,Z,..) running from 0..3. The sample table shown above was filled with this instruction.
In the numeric expression (right of the assignment operator) the assigned value is calculated, depending on the three indexes (i,j,k). The whole term is calculated 200 times in the internal loops, which is the reason why the interpreter needs a bit longer for this (compared to a "simpe" assignment).

Note: The "to"-operator (..) can be abbreviated with a tilde (~), so

arr[i=0~9][j=0~4][k=0~3] := 20*i + 4*j + k

will do exactly the same as

arr[i=0..9][j=0..4][k=0..3] := 20*i + 4*j + k

Here are some more examples for filling a range of cells in an array:

arr[0][i=0..3][j=0..1] := sdo(0x2941.(3+j+2*i),FLT) : rem read 4 pts

This instruction reads eight floating-point values through the CAN bus from a remote node through an SDO channel (service data), using different CANopen subindices for each element. The CANopen object's subindex is calculated from the array indices. Without the automatic loop feature, the same could be done with the following eight instructions:

arr[0][0][0] := sdo(0x2941.3,FLT) : rem read column 0, row 0, X-coord
arr[0][0][1] := sdo(0x2941.4,FLT) : rem read column 0, row 0, Y-coord
arr[0][1][0] := sdo(0x2941.5,FLT) : rem read column 0, row 1, X-coord
arr[0][1][1] := sdo(0x2941.6,FLT) : rem read column 0, row 1, Y-coord
arr[0][2][0] := sdo(0x2941.7,FLT) : rem read column 0, row 2, X-coord
arr[0][2][1] := sdo(0x2941.8,FLT) : rem read column 0, row 2, Y-coord
arr[0][3][0] := sdo(0x2941.9,FLT) : rem read column 0, row 3, X-coord
arr[0][3][1] := sdo(0x2941.A,FLT) : rem read column 0, row 3, Y-coord

Finally, you can initialize a number of rows and columns in a single command, assigning individual values to the cells:

arr[0][0..3][0..1] := {{-20,0},{0,30},{20,0},{0,-30}}

which assigns four columns in the array, with two cells per column (like two components of a coordinate). Note the curly braces as separator for the rows and columns ! In this examples, two nested levels of curly braces are required, because two array dimensions are assigned (similar to the "C" programming language). To do the same cell-by-cell, the following eight assignments would be required:

arr[0][0][0] := -20
arr[0][0][1] := 0
arr[0][1][0] := 0
arr[0][1][1] := 30
arr[0][2][0] := 20
arr[0][2][1] := 0
arr[0][3][0] := 0
arr[0][3][1] := -30

back to the overview

Arrays as arguments in function calls

Arrays can be used as parameters, when a lot of "values" must be passed to a subroutine (function call). Some of the built-in functions expect a number of points (with X- and Y-coordinate) passed in the argument list, for example a command to draw polygons as "overlay" into a diagram. An example:

dia.poly(arr[0~8][0~3])

In natural language, this command would say, "hello diagram, draw a polygon, taking the coordinates from an array named "arr", but only look at rows 0 to 8, and for each of these rows draw a polygon using rows 0 to 3". So there will be nine polygons with four corners each. What you don't see in this call is where the X- and Y-component are taken from - in fact "X" is taken from component index 0 and "Y" from component index 1 (if they are not specified). To make it clear where a point's X and Y - coordinate are taken from, put it this way:

dia.poly(arr[0~8][0~3][0~1])

In this complete array reference it is easier to see that nine rows, four columns per row, and two components per column are passed to the subroutine.

Note:

At the moment, there is only one single "global" array in the interpreter. Despite that, pass the array name (here: "arr") to the callee in the function argument list.

back to the overview

Changing the dimensions of the array

• 100 rows
• 10 columns per row
• 4 components per column

The total number of values in an array cannot exceed 4000, due to an unfortunate limitation of the CPU (size of an "object" limited to 16384 byte, while a single "float" value occupies 4 byte). So the product of <row_count> * <columns_per_row> * <components_per_column> can never exceed 4000.

Note:

At the moment, there is only one single "global" array in the interpreter. Despite that, pass the array name (here: "arr") to the string function (like "dim").

To change an array's dimensions during run-time, use the interpreter's "dim" command, before entering any values into the array.

Syntax:

dim <arrayname>[number of rows][columns per row][components per column]

Example:

dim arr[10][40][3]
Declares an array named "arr" with 10 rows, 40 columns per row, and 3 components per column.

There is a complete example for the array and the "dim"-command in the programs directory in the terminal application arraytest1.cvt . In that example an array with 40 columns per row is defined, which will filled with 40 corner coordinates for a polygon. The polygon will then be drawn into an X/Y-diagramm.

back to the overview

Watching the contents of 'arr[][][]' in the programming tool

arr[0]

Shows as many elements as possible from the array's first line (row).

arr[0][0]

Only displays the content of the array's first row, first column (but possibly with multiple 'components').

arr[0][0][0]

Only displays the content of the array's first row, first column, first component.

arr[0][0~NumSamples-1]

Also shows content of the first array row, but only column indices zero to NumSamples minus one.
(In this example, "NumSamples" is a user-defined variable with the 'number of samples' acquired from somewhere. Because array indices starts at zero, the highest column index is "the number of columns", here: NumSamples minus one.)

Legal Terms

See main manual.

back to the overview