Variable References

(only available for terminals with 32-bit CPU, for example "MKT-View II")

Caution:: Not finished yet ! As of 2008-11-05, the function described here was in an early development stage.
Please visit the MKT website and check for an update.

This document describes a rarely used, "special" function of some programmable CAN display terminals by MKT Systemtechnik.

The "var"-function allows to pass a reference to a variable between display pages (see example below), and -possibly- between subroutines.

As a programmer, you certainly know variable references from programming languages (like "C"), where special operators are used for references. For example, in the "C" programming language, the asterisk (*) is used for the dereference operation, while the ampersand (&) is used for the reference operation .

Here, in the UPT display interpreter, no special operators are used to reference a variable, but a quite simple (?) principle explained in the next chapter.

Principle

The var command/function is used to reference a variable by its name. The keypoint is that the name itself doesn't need to be constant, but variable .

Syntax :: var(<var-name>)

When called as a function, "var" locates the global variable with the specified name, and returns the value of that variable. The name itself can be stored in another variable (a string variable), or be the result of a function call, or any other expression which returns a string.

When called as a procedure, "var" permits a write-access to the specified variable (of course, only if that variable itself it writeable, too). The following examples will clarify the principle.

For the following example, let's assume that 'VName' is a string variable which is, for the moment, not connected to a communication channel (in other words, it's "purely internal" and exists only inside the terminal). 'X' is another variable, declared as integer or floating point.

Example 1:: @X = 12345 : REM set 'X' to 1234 @VName = "X" : REM set 'VName' to "X" (a STRING of characters) var(VName)=123 : REM actually sets 'X' to 123 (write-access) @X = var(VName)+1 : REM actually increments 'X' by one

Looks trivial... but imagine what you can do with this mechanism :

You can set VName to the name of a variable on display page A,
then call display page B to "do something" with var(VName), for example showing or editing it in a 'special' way,
and then return to the caller.

This way, you can use the same display page to edit dozen of different variables, called from different display pages, just by passing the name of the variable to the "Edit"-page instead of putting the name of the edited variable on the edit-page itself.

A sample application

There is a simple example for the 'var'-function in \programs\MKTview2\MV2_Demo.CVT (these demos are located in the "programs" folder of the programming tool, not in the "Programs" folder of 'windows'). On the page named "ParSel", there is a list of parameters selectable for editing.

Screenshot "Variable Reference Demo", part 1

When selecting any of these parameters with the rotary knob, and pressing the knob (or ENTER-button) to edit them, the program switches to another page named "NumEdit", where the selected parameter can be edited on a special screen with a touch-sensitive numeric keyboard .
Important: The edited 'parameter' on that page is the expression var(VName) but not a fixed, "hard-coded" variable.
The name of the currently edited variable is displayed (here: "X"), and -of course- the current value using larger digits :

Screenshot "Variable Reference Demo", part 2

How does this work ?

To retrieve the name of the variable to edit, the following event definition is used (on the page "ParSel" in the demo application):

Screenshot "Variable Reference Demo", part 3

The event "mm==2" detects that an edit field on the current display page has been switched into EDIT mode.
In the reaction method for this event, the program takes the name of the variable connected to the current edit field, and stores it in the (string-) variable 'VName'. Then, the display program calls the 'NumEdit' page. Let's look a bit closer at this event definition, because it's the key point here:


Reaction:: @VName=disp.li[mi].vn : c"NumEdit" : REM call the "editor"

The variable 'VName' is used to pass a reference (here: "the name of") another variable from one display page to another. Here's how we retrieve the name of the variable in the currently selected line. It's a bit tricky, but make sure you understand every bit :

The 'mi' function of the interpreter returns the currently selected line number (aka "menu index").
Let's assume mi = 6, i.e. the 6th line of the current display page is currently selected . Remember that all elements on a display page are internally structured like an array. The 'mi' function just returns an index into that array. And that's what we need here: access the mi-th array element on the current display page. It doesn't matter if the selected element is really a "menu" item, or a text line with numeric output, a graphic button, an icon, or whatever. All these elements are arranged in a (kind of) array, and have a unique array index.
The "disp" function then accesses the mi-th line of the current display page. Developers familiar with C and simimar programming language will recognise the squared brackets around the array index. So disp.li[mi] returns a reference to the mi-th display line. It doesn't matter which kind of display element is defined in this line. Here, it's just a simple text, used for a menu, but it could also be a button, icon, or other graphic element.
From the display element referenced as described above, we read the name of the variable associated to it (using the vn component = "variable name").
The name of that variable is copied (as a string) into 'VName' (which is an internal variable, defined as "String" in the variable definition table).
After that, we call a display page named 'NumEdit'. In this demo program, that page contains an editor for numeric variables. The name of the variable to be edited on that page is passed in a fixed global variable called 'VName'. Note that all these names are self-defined (we could have used any strange name like "Var1" or "Page5" for them), but we picked short and self explaining names for them, so we know what this code does even looking at it after many years.
(The author of this document has seen horrible names for variables and display pages, which don't give any clue about their purpose.
Try to avoid crap like "Var1", "Var2", "Page5", "Page6", and invest a few seconds to find 'talking' but short names for your variables and display pages. )

On the 'Editor' page, the expression var(VName) is entered in the Var/Expr colum of the display page definition table.
There's nothing special about the keyboard on this page, except that all numeric keys are defined as graphic buttons, which can be operated via touchscreen (if the device has a touchscreen). The buttons send an ASCII character into the keyboard buffer, so they behave like "real" keys on a "real" keyboard.

Screenshot "Variable Reference Demo", part 4

To make the parameter editable, the access is set to "Read/Write" on the display page property tab. This is possible, because "var" is not just an interpreter function (which returns a value), but also an interpreter command (which, in this case, sets a new value).

< To Be Continued ... >