• Programming Tool
• A-Z
• Pages
• Simulator
• CAN
• Scripts
• 

Script language for programmable displays

Author: Wolfgang Büscher, MKT Systemtechnik
Date   : 2021-05-05 (ISO 8601)
Master file: <WoBu><ProgrammingTool>..help\scripting_01.htm
Online: www.mkt-sys.de/MKT-CD/upt/help/scripting_01.htm
      ( Note: In the printable version of this file,  ?/Doku/art85122_UPT_Scripting_*.pdf, many external links don't work.)

Contents

1. Introduction
   1. Principle
   2. Unlockable Features (extended script functions)
2. Script Editor with Debugger
   1. Editor Toolbar
   2. Hotkeys and Context Menus of the Script Editor
   3. Debugging
      1. Breakpoints, Single-Step
      2. Disassembly
      3. Trace History
      4. Error messages / Error History
      5. Stack Display
      6. Symbol Table with variable display
      7. Watch List (shows values of a selection of variables)
      8. List of memory blocks dynamically allocated by the script
      9. Testing the application in the target's RAM (instead of FLASH)
3. Interaction between script and display ("programmable display pages")
   1. Calling a script procedure when pressing a button
   2. Modifying display elements via script (texts, colours, etc)
4. Language Reference
   1. Numbers
   2. Strings
      1. Strings with different character encodings ("DOS", "ANSI", "Unicode")
      2. String usage and storage format
      3. String constants with special characters
      4. Strings with backslash sequences
      5. String processing (functions) :
         append chr ansi_chr unicode_chr CharAt char_encoding
         atoi atof itoa ftoa hex HexString BinaryString
         strlen strpos strpos2 stripos strrpos strripos substr
         ParseInteger ParseFloat ParseHexString ParseBinaryString CAN.ParseString
         
   3. Constants
      1. Built-in constants
      2. User-defined constants
      3. 'Calculated' constants
      4. Constant tables (arrays)
   4. Data Types (built-in and user-defined)
      1. int, float, double, string,   byte, word, dword, bool, tColor
      2. anytype
      3. tMessage, tCANmsg, tScreenCell, tCanvas, tTimer, tTable, tDirEntry
      4. Explicit type conversions (typecasts)
   5. Variables
      1. Variable declarations in the script
         1. Global variables
         2. Local variables
         3. Pointer variables
         4. The attributes 'private', 'public', 'logged' and 'noinit'
      2. Accessing "script" variables from a display page
      3. Accessing "display" variables from the script
   6. Arrays
      1. Maximum size (capacity) versus momentarily used length (.len) of an array
      2. Other elements of an array-header
         
         1. Arrays used as FIFO (ring buffer with 'first in, first out'-principle)
         2. Sampling interval and timestamp of the newest array element
      3. Examples for the use of arrays
   7. Operators
   8. User-defined functions and procedures
      1. User-defined procedures
      2. User-defined functions
      3. Invoking user-defined script functions from a display page
      4. Invoking script procedures from display interpreter commandlines
      5. Input- and output arguments
      6. Recursive calls
   9. Program flow control (loops and branches)
      1. if, then, else, endif
      2. for, to, step, next
      3. while .. endwhile
      4. repeat .. until
      5. select, case, else, endselect
   10. Other functions and commands
       1. Numeric functions, "Math", and digital signal processing
       2. Timers and 'Stopwatches'
       3. Displaying text on a multi-line text panel (cls, gotoxy, print & Co)
       4. Canvas functions (painting on a tCanvas)
       5. File I/O functions (file.create, file.open, file.write, file.read, file.close, directory.open, directory.read, ...)
       6. Transmission and reception of CAN messages (via script), CAN diagnostics
       7. Controlling the programmable display pages from the script / Controlling diagrams / display variables
       8. "System" functions (read the current timestamp, keyboard, LEDs,
              onboard I/O, supply voltage, temperature, frequency counter, etc.).
       9. Date- and time conversions (modified Julian date, etc)
       10. Commands for the GPS receiver
       11. Functions to control the trace history
       12. Functions to control the virtual keyboard
       13. Interaction between Script and the Internet Protocol stack
               Internet Application Interface ('socket'-like API) :
                 socket bind listen accept connect send recv close
               Internet socket state diagram
               JSON (Javascript Object Notation)
               Internet / Ethernet-related troubleshooting
           
       14. Interaction between Script and the CANopen Protocol stack
       15. Extensions to the script language for SAE J1939
       16. Extensions to the script language for ISO 15765-2 (aka "ISO-TP")
   11. Preprocessor Directives
       1. #pragma
       2. #include
   12. Keyword List (with built-in commands, functions, data types, etc)
   13. Error messages
   
   
5. Event Handling in the script language
   1. Low-level system event handlers (OnKeyDown, etc)
   2. Events originating from UPT display elements ('Control Events')
   3. Timer Events
   4. CAN Receive Handlers
   5. Event handler for the virtual keyboard
   
   
6. Examples : CAN gateway, CAN 'ASCII' logger, calculate PI, display control, moving average, numeric integrator, thermometer (using NTCs), timer events, control events, file I/O, INI files, Internet,Ethernet,TCP/IP, text screen, loops, arrays,
   error frames, operator test, reaction test, Quad-Blocks, trace test, CANopen, J1939, ISO 15765-2, detect bus-sleep-mode,
   VT100/VT52-Emulator, custom 'popup' menu,
   Internationalisation (multi-language demo using a string lookup table for translation), 'App-Selector', Include files.
   
   
7. Bytecode (information for advanced users; not required to use the script language)
   1. Compilation of the sourcecode into bytecode
   2. The Stack (for subroutines, intermediate results, function calls, arguments, and local variables)
   3. Bytecode specification, Mnemonics and Opcodes
   
   
8. Latest Revisions

See also (links to external documents, only work in HTML but not in the "printable" (PDF) version of this document) :

• Manual for the programming tool
• main index (of the programming tool's help system)
• feature matrix (to check if scripting is supported for a particular device/firmware)
• display interpreter commands
• display interpreter functions .

Introduction

This document describes a scripting language, which has been implemented in some programmable display terminals by MKT Systemtechnik.

The script language can be used to ...

• Combine signals (i.e. generate "calculated" signals), or supervise signals received from CAN or other buses,
• implement protocols (also for CAN), which are not directly supported by the device-firmware, for example J1939, ISO 15765-2 ("ISO-TP");
• process events, which (due to their complexity) cannot be achieved in the display pages' 'Event'-definitions,
• programmatic file access, for example to implement custom specific event-logs, automatically generated error reports, etc;
• realize simple (SPS-like) flow controls, even though not for 'hard' real time (no guaranteed cycle time),
• implementation of algorithms which are too complex for the diplay's 'Event'-definition (which doesn't support loops, etc).

For most applications, you will not need the scripting language described in this chapter, because the functions for which the display terminals were originally intended can be realized without scripting. But in a few cases, the display's programmable 'Event' handlers  ("page events" and "global events") will not be sufficient. This is where the scripting language can help.

The script language doesn't have anything to do with the older display interpreter. This document describes the script language, not the display interpreter (the latter was used to define 'global and local events' for the display which were relevant for the display application). The script language is compiled once (not interpreted while it runs), using a proprietary bytecode which makes it much faster than the display interpreter, but  a bit less flexible.

Here is a simple but complete example (script sourcecode) which calculates the display variable 'Power' by continuously multiplying variables 'Voltage' and 'Current':

   while(1)
     display.Power := display.Voltage * display.Current;
     wait_ms(50); // wait for 50 milliseconds, during this time the display is updated
   endwhile;

Throughout this document, sourcecode means the text which you typed into the script editor. The sourcecode will be compiled into bytecode. The bytecode is then executed on the target device, or in the programming tool's simulator.

Certain 'extended' script functions may have to be unlocked (after been paid for).

Principle

From a user's point of view, the script is just a list of instructions and program flow control commands, entered with a simple text editor which is integrated in the programming tool. As a user, read the chapter about the script editor (integrated in the UPT programming tools), study a few examples (listed at the end of this document), and use the language reference to write your own scripts. If you are already familiar with programming languages and know what procedures, operators, arrays, strings, integer and floating point numbers are, you will only need to look at the keyword list occasionally. Otherwise, follow the hyperlinks in this document for more info ... and remember to use your browser's "back"-button to return to the point where you started reading.

After booting the programmable device, or starting the built-in simulator in the programming tool, the script will start to run in the first line of sourcecode. Typically, the first part of your script program will contain a few initialisations, like setting script variables to their default values, etc. The end of the initialisation sequence should be marked in the script by invoking init_done. This command enables event handlers, and allows calling the script from programmable display pages as soon as the script is 'open for business'.

After that, a typical script will just sit and 'wait' for something special to happen, for example the reception of CAN messages, or if any of the programmable display pages sets a signal for the script to "do something". We'll get back to the aspects of signalling and event handling later.

Unlockable Features for the script language

Only the standard script functions which were originally developed during the author's spare time (for a his own 'hobby' purpose) are available without an extra fee. The extended functions, added to the script language for MKT Systemtechnik during the author's working hours at MKT Systemtechnik, must be unlocked (for a moderate fee, to cover MKT's development expenses) before they can be used. These extended script functions include, but are not limited to, the following "unlockable" features:

• Reception and transmission of CAN messages through the script language (CAN.xyz)
• File access functions for the script language (file.xyz), which includes the serial port(s) and other objects which can be accessed "like a file".
• Functions to communicate via TCP/IP or UDP
• Frequency- and event counters for the onboard digital inputs
• other hardware-dependent, specialized functions .... planned

As long as these functions are not unlocked, they will simply "not work". For example, if the script in the programmable terminal tries to send a CAN message, the message simply won't be sent. Trying to open a file, or a serial port, will return an invalid handle.

All the above features must be unlocked for the firmware, for each device on which you want to use these features. How to request an unlock-code from the manufacturer for a particular function, in a particular device, is described in this extra document.

We apologize in advance for any inconvience caused by the unlock procedure, but the company (MKT) cannot offer all these new features for free. On the other hand, customers who don't need these functions are not forced to pay for something which they will never need.

Script Editor and Debugger

The script editor is on the 'Script' tabsheet of the programming tool. If that tab is invisible, your hardware doesn't support scripts, or the programming tool is too old.

Script editor toolbar, sourcecode (left), and debugger panel (right)

By default, the editor uses syntax-highlighting. When enabled, the language's built-in keywords are shown in bold black characters, comments are blue, etc. Note that the syntax highlighting is not always updated while you type. In fact, the syntax highlighting function needs a valid symbol table (to identify the names of user defined procedures, variables, etc), which only exists after the program has been compiled. So after entering new sourcecode in the editor, you may have to click the 'STOP / RESET / RECOMPILE' button to update the  syntax highlighting. If you find this feature too annoying, turn it off in the script editor menu (see next chapter). The editor will use plain 'black-on-white' characters then.

The size of the script sourcecode may be limited to 32 or 64 kByte (in some cases 256 kByte), depending on the target system. The maximum size of the bytecode (produced by the compiler) is 32 kByte on most targets. The script editor isn't aware of such target-specific limitations, unless you inform the programming tool about the capabilities of the target device (on the 'General Settings' tab, "Max. size of script sourcecode in kByte").
You can see the amount of source- and bytecode memory occupied by the script in the status line on the bottom of the 'Script' tab after compilation. For example, after a successful compilation, the status line will show something like:

After compilation of the script (on the PC), it can be tested with the debugger. The debugger supports breakpoints, single-step, a disassember, the trace history, and a display for the symbol table with variable values.

To simplify the development of scripts, the editor contains several tools explained in the following chapters. These include, for example:

• the Toolbar (buttons above the sourcecode editor)
• the sourcecode editor's context menu (right-click into the sourcecode)
• the sidebar's context menu (right-click into the line numbers)

The Script Editor Toolbar

The toolbar contains the usual editor functions like find, copy, paste, and cut (using the windows clipboard like any other text editor). In addition, there are these graphic buttons:

RUN

Starts execution of the script, or continues execution at the last position. If the script wasn't compiled after the text was modified in the editor, it will be recompiled.
Execution may stop when the program hits a breakpoint, or an error occurrs.

STOP / RESET / RECOMPILE

Stops execution (if running), or resets / recompiles the code (if already stopped). Clicking this button with the PC's shift key held down sets the execution pointer into the line of the cursor ("caret" in the editor text).

SINGLE STEP (F7, aka 'Step In')

Executes the next command (which is marked with a green arrow on the left side of the editor text). Especially useful after hitting a breakpoint.
If the current line (marked by the green arrow) contains the call of a subroutine (procedure or function written in the script language), this command will step into the subroutine.

STEP OVER (F8)

Also used to single-step through the script under debugger control. In contast to the normal single step command (F7, aka 'Step In'), 'Step Over' executes a complete subroutine (procedure or function written in the script language), inclusive anything called 'from there'.

STEP OUT

Executes the rest of the current subroutine (function or procedure), until 'returning to the caller'. Typically used in combination with the 'Single Step' aka 'Step-In' command.

View "CPU" (debugger code window)

Opens the disassembly view on the right side of the script editor tab. Used for hardcore-debugging (to track down stack problems, etc).
While the disassembly-view is open, the single-step function executes one (virtual) machine code instruction per step, not one script-line !

Script editor menu

Opens a popup menu with the less frequently used 'special functions', most related with debugging and editing (e.g. line markers, breakpoints, trace history, watches,.. - see screenshot further below).
In this menu, you can also enable/disable the editor's syntax highlighting, select fonts for editor and debugger, and configure a few other script-editor related parameters.
Hint: When available on your PC, 'DejaVu Sans Mono' often results in a better readable display than 'Courier New'.

Find text

Finds a string of characters in the script editor. The string to find is entered in the usual 'find' dialog. Then click the 'Find Next' button ("Weitersuchen" in german).
See also: 'Global Search' on all display pages, and in the entire script sourcecode,
invoked via context menu after right- or double-click on the to-be-searched word in the sourcecode editor.

Import script from a file

Imports a script sourcecode from a plain text file. All breakpoints in the previous script will be lost.

Export script as a file

Exports the script sourcecode as a plain text file. Breakpoints will be lost when saving and re-loading the program ! Note that the script is saved as part of the terminal's display application (*.upt or *.cvt), so usually you don't need this function. It can be used to transfer (copy) a script from one application to another (as plain text), or to export the script (with syntax highlighting) for documentation (as RTF oder HTML).
Hint: When exporting a script as *.HTM (HTML), links to the documentation will automatically be inserted. The author made heavy use of this option when writing this documentation, especially in the 'Examples' chapter.

The left border of the script editor shows sourcecode line numbers,
indicators for 'lines with executable code', breakpoints, etc.
Possible indicators on the left side of the sourcecode editor are:

(green arrow pointing right)

Current instruction pointer .
Shows the next line to be executed. Used during single-step debugging.

(small hollow gray circle)

There is executable code in this line but the program has "not been here yet" .
Code was produced for this line when compiling, but it has not been executed yet (since the script program was started).
During debugging, you can set a breakpoint in this line by clicking on this indicator.

(blue solid circle)

"Been here since the program started".
Code was produced for this line by the compiler, and it has been executed at least once since the program started.
During debugging, you can set a breakpoint in this line by clicking on this indicator.
The 'Reset' function clears all 'been-here' markers (see toolbar buttons above).

(large red solid circle)

A breakpoint has been set in this line, and the program has not "been here" yet.
If the 'running' program hits this breakpoint, it will stop.
You can easily inspect variables then (because their values won't change while stopped).

(red circle with blue center)

A breakpoint has been set in this line, and the program has 'been here' since it was last reset.

(yellow triangle with black border)

Warning or error in this line .
Something went wrong in this line, either during compilation, or during runtime. Check the error message in the status line !
To get more details about the error, point the mouse on this symbol, and watch the text in the status line. Additional info about certain errors or warnings may be displayed on the programming tool's Errors & Messages tab.

Note that while editing, especially when inserting new lines in the sourcecode, the code indicators will disappear. Breakpoints remain on their fixed positions (unfortunately they cannot "move around automatically" when the sourcecode is modifed, or moved to another location).


Clicking into the sidebar (line number or symbols shown above) with the right mouse button opens the sidebar's own context menu. It contains functions like 'Show execution point', 'Show first error in line xyz', 'Toggle breakpoint in line xyz', etc. Details about the sidebar's context menu are in the next chapter.


Clicking on the 'Menu'-Button ('wrench' icon) in the script editor's toolbar opens the following menu, which is mainly used while debugging:

Screenshot of the 'debug menu' on the script editor tab

Hotkeys and Context Menus of the Script Editor

CTRL-C

Copy selected text into the windows clipboard

CTRL-V

Paste text from the windows clipboard

CTRL-F

Find text (opens the usual non-modal 'Find' dialog)

CTRL-Z

Undo last editing step

SHIFT-CTRL-Z

Redo ("undo undo")

F1

Extended help about a keyword in the script editor (sourcecode window).
Point the mouse on a keyword, and wait until the bubble hint shows a brief information.
If the brief information is not sufficient, press F1 (while the bubble is visible) to get more help, displayed in the web browser.
Unfortunately this only works with a 'good' browser, which can jump to (scroll to) a text mark (anchor) after loading the HTML document.
At the time of this writing (2013-08), Firefox and Iron/Chrome appeared to be 'good' browsers.

F7

Single step (for debugging; details in the next chapter)

Right-click into the script editor (sourcecode) to open its context menu. For certain special functions, the 'word' in the sourcecode (under the mouse pointer) will be evaluated then, for example to add the name of a global variable as an 'expression' to the watch list, or to get help about a certain keyword, function or variable:

Screenshot of the script editor with context menu, after right-click on a certain word

Screenshot of the sidebar's context menu, opened by right-clicking on a line number

Debugging

No non-trivial program will be free of errors right from the start. The programming tool has some basic debugging capabilities, listed below. To debug the code, you must run it in the programming tool. A bit of 'remote debugging' on the real target is possible via web browser (HTTP).
During a debug session, the screen may be split into two areas, with the sourcecode in the left half, and some other information in the right half (e.g. Bytecode, Symbole, or single Variables). The blue-coloured splitter (between sourcecode and debugger) can be moved with the mouse.
The 'kind' of debugger display can be selected via menu, hyperlink (as in the symbol table), or with the combo box on the right side of the toolbar:

Selecting a debugger display mode via combo box,
with "BACK"- and "FORWARD" button as in a web browser.

• Breakpoints :
  Breakpoints can stop the execution of the script. To set or delete a breakpoint, click on one of the 'excutable code markers' on the left side of the editor window.
  The left mouse button simply toggles a breakpoint (on/off), the right mouse button opens a context menu with advanced options.
  
  
• Single step :
  Stop the script using the 'Stop' (or single step) button in the editor's toolbar, and continue execution step-by-step (with the single-step button) .
  
  
• Inspect variables :
  Move the mouse over the name of a global variable in the sourcecode, and wait for half a second. The program will look up the word 'under the mouse' in the list of global script variables, and show the result if it finds one. This even works while the script is running ... at least for global variables.
  Note: Inspecting local variables is not as easy as global variables, because during runtime, global variables don't have a name - just an address in the current stack frame - and thus it's extremely difficult to retrieve their values because (in contrast to global variables) their memory location cannot be found in the symbol table. Therefore, the debugger can only look up local variables if the program is currently 'pausing' in the user-defined function or procedure to which a local varible belongs. If user-defined functions & procedures call each other recursively, the debugger can only inspect local variables within the current stack frame (which is the stack frame to which the base pointer currently points).
  
  In devices with a sufficiently large screen (MKT-View), script variables can also be examined in the device's system menu :
  In the main system menu, scroll down to 'Script:', press ENTER (or similar) to open a submenu, and select 'Variables ..' there.
  Scroll through the list via cursor up/down or rotary encoder. The list only shows the variable's name (left) and current value (right). For more details on a certain variable, press ENTER (or the rotary encoder knob) to select it and switch to the 'Script Var Details' (menu) on the programmable device.
  
  
• Symbol table display :
  The symbol table is generated by the script compiler. You can show the entire table, or only the global variables, or only the names of user-defined functions and procedures on the right side of the main window. Names, sourcecode line number, or code addresses shown in the symbol table can be clicked like a 'hyperlink' to scroll ("navigate") in the sourcecode.
  
  
• Stack display :
  While single-stepping, the status line of the editor may show the topmost elements on the script's stack. This function was mainly used during implementation of the script language, but you can use it to examine the stack - especially if your application makes heavy use of subroutines, and you want to find out "how the program got to the current point" (call stack).
  
  The top of the stack (a few elements) can be displayed in the status line, or as a multi line text on the right side of the script tab.
  Example for a single-line display, with six elements on the top of the stack displayed in the status line:
  

  Stack[6] : tCANmsg 0 return_to_822 1 65230 0

  Details about the stack display (also as a multi-line list) can be found here.
  
  
• Memory Usage Display :
  After a test session in the simulator, you should occasionally check your application's memory consumption - especially if you use a lot of strings, especially when using strings in arrays.
  To show the memory usage in the simulator / debugger, click on the script editor's menu button, and select Show Memory Usage .
  The status line will now show the memory usage (continuously updated, while the script runs), for example:
  

  Memory Usage : 5 of 256 stack items, peak=33; 7 of 200 variables; 62 of 1000 data blocks, peak=85

  which means:

  5 out of 256 items on the RPN stack are currently used;
  the peak stack usage (since the script was started) was 33 out of 256 possible entries;
  7 out of a maximum of 200 global variables are used;
  62 out of a maximum of 1000 data memory blocks (with up to 64 bytes per block) are currently used;
  the peak memory usage (since the script was started) was 85 out of 1000 possible entries.
  

  This is a typical 'non-critical' example because all peak values are way below the maximum allowed sizes.
  If any of the three parameters (stack usage, number of global variables, or number of data blocks) gets critically close to the maximum, try to ...

  • reduce the 'stack' size by using less local variables, and less recursive procedure calls;
  • reduce the 'block' memory consumption by decreasing the array sizes;
  • reduce the 'block' memory consumption by using less strings, or assign empty strings to string variables if you don't need their values anymore, like:
    Info := ""; // clear this string to release its memory block
    

  Note: The Memory Usage display on the Script tab only shows the memory used by the script.
  This hasn't got anything to do with the memory used for the UPT's programmable display ( for icons, display pages, etc) ! The script uses its own memory pool, so the UPT display will remain operational even if the script runs out of resources, and stops due to a programming error.
  The memory usage can also be checked in the script itself, using the function system.resources .
  To check the target's remaining Flash memory space (after subtracting the size occupied by script, display pages, bitmaps (icons), display-variables, and other special items, use 'View' (in the tool's main menu), menu item 'Target Flash memory usage'.
  

  Details about the current usage of dynamically allocated memory can be shown (in the debugger) as explained here.
  
  
• Disassembly display (code window) :
  Shows the bytecode in disassembled ("human readable") form. While this display is open, single-step in the debugger doesn't step through the sourcecode line-by-line, but instruction-by-instruction through the bytecode. More details in chapter 2.3.2.

  
  Script editor toolbar, sourcecode (left), and debugger/disassembler (right)

• Trace History :
  Shows the last 255 events (or even more) with ...
  • CAN messages which have been sent (transmitted) by the device
  • CAN messages which have been received by the device
  • Error messages and warnings (by the device firmware or simulator)
  • Text messages and 'info lines' generated by the trace.print command
  • Debug info from the Internet-related script functions (optional)
  Details about the Trace History follow in chapter 2.3.3.
  
  
• Watch Expressions :
  Shows a user-defineable selection of 'expressions' (at the moment, limited to global script variables) on the debugger panel. These can be the current values of 'simple variables', but also complete arrays and user-defined types (structs) can be inspected this way. Details about the watch list follow in chapter 2.3.6.

Hint:

In a debug session, it helps a lot to have two monitors connected to the development PC. Move the programming tool's main window to one monitor, and the LCD simulator window to the other. If you're not that lucky (only one monitor), make the size of the simulator just as large as it needs to be (to see all pixels), and use the option 'stay on top' for the LCD simulator window. You can then move the simulator into the upper right corner of your screen where it doesn't obscure any 'vital parts' of the script editor. The simulator will remain visible, even after maximizing the tool's main window, and even when the keyboard focus is not on the simulator (but inside the script editor).

See also: Debugging via Embedded Web Server (and HTML Browser)

Breakpoints and Single-Step mode

Breakpoints can stop the execution of the script. To set or delete a breakpoint, click on one of the 'excutable code markers' on the left side of the editor window.

For Single step operation, you can either stop the script using the 'Stop' (or single step) button in the editor's toolbar, or use a breakpoint to let it stop there.
After that, continue execution step-by-step (with the single-step button) .
If the script stops (in the simulator) due to hitting a breakpoint, or after an error occurred, the status line shows the the line number in which the program stopped (and some more info). Example:

Status bar of the script editor after hitting a breakpoint

Hint:

Some devices (like MKT-View II / III, with Ethernet port and embedded web server) support debugging without the UPT programming tool.
That 'remote' debugger is operated via web browser (and TCP/IP, HTTP, HTML, Javascript); it also supports setting multiple breakpoints during normal operation and single-stepping.
To operate it, enter the device's host name or numeric IP address in the browser's address bar, followed by /script/d ('d' is the option for "Sourcecode Debugger").
For some stupid browsers you may have to add the transport protocol (before the address), for example: http://upt/script/d .
Details about remote debugging are here (external link).

Disassembler display (code window)

Only for advanced users !

The disassembly view can be opened through the script editor's toolbar ("chip" icon). It's an extra display panel on the right side of the editor, which shows the bytecode in disassembled ("human readable") form. While this display is open, single-step in the debugger doesn't step through the sourcecode line-by-line, but instruction-by-instruction through the bytecode. This makes it possible to see how numeric expressions ("formulas") are evaluated in the RPN (Reverse Polish Notation), and how subroutines (functions) are invoked with parameter passing via the stack.

Screenshot of script editor (left) with disassembly (right)

Trace History

The trace history can be used any time to check the events listed below, in chronological order. It is implemented in the firmware of most devices (if the device supports scripting), but also in the programming tool (simulator). Typically, up to 255 entries can be stored in the history; more (newer) entries will overwrite the oldest part (as in a FIFO - first in, first out).
Events which can be recorded in the history are:

1. CAN messages which have been sent by the terminal ("Tx")
2. CAN messages which have been received by the terminal ("Rx")
3. Error messages and warnings by the system (device firmware or simulator)
4. Messages which have been "printed" into the history by the user application (script)
5. Other events, when enabled by the trace.enable flags

Chapter overview: Trace History display format, Trace History usage, Trace History invocation .

Trace History display format

The display format of CAN messages in the Trace History is half-way compatible with Vector's widespread "ASCII" format for CAN logfiles. Thus, even for devices without an integrated CAN logger / snooper, it is possible to trace CAN-bus related problems (which is especially helpful when implementing 'exotic' CAN protocols in the script language).

CAN message format in the Trace History:

Timestamp

Bus

CAN-ID

Rx/Tx

d

Length

Byte 1

Byte 2

Byte 3

Byte 4

Byte 5

Byte 6

Byte 7

Byte 8

57.211

1

12345678

Rx

d

8

F2

68

11

76

EE

86

6C

9D

A similar format can also be used when converting CAN messages (tCANmsg) into strings, depending on CAN.string_format .
CAN-Identifiers with 11 bit (standard frames) are displayed with 3 digits. 29-Bit-Identifier (extended frames) are shown with 8 digits as in the example. LIN-Bus-Frames are (optionally) displayed like CAN messages in the trace history.
Messages (text lines) entered into the history by command ('trace.print') can have any format; only the timestamp (in seconds, with three decimal places) are added automatically at the begin of each line. The second counter starts at zero when the device is turned on, or when the simulator is started / reset.

Trace History usage

In the simulator (integrated in the programming tool), the Trace History can be displayed on the right side of the 'Script' tab. To achieve this, select 'Show Trace History' in a combo box on the script toolbar:

Trace History displayed in the programming tool

After selecting 'Show Trace History, paused' you can scroll back through the history, as long as the limited trace memory permits.
Switching to 'Show Trace History, running' will permanently append new entries at the end of the display, and the vertical scroller will automatically be moved to the end of the list, so the newest entry is always visible.
Right-click into the Trace History (in the programming tool) opens the following context menu:

Context menu to control the Trace History in the programming tool

The menu shown above can be used to suppress certain CAN message identifiers in the Trace History. This feature is often used to avoid 'flooding' the display with non-important, but frequently transmitted CAN frames.

On a real target device, the Trace History can be accessed (inspected) through the system menu. Select 'Diagnostics' .. 'TRACE History' there. Details about the system menu are in document #85115 (System Menu and Setup in programmable CAN display terminals by MKT).

See also: 'Trace History invocation' in this document, Wireshark-compatible Packet Capture
.

Excluding certain CAN message identifiers from the Trace History

To suppress ("blacklist") a certain CAN message identifier for the display, click on its hexadecimal identifier with the right mouse button in the trace display, and select 'Exclude CAN-ID from the trace history'.
Alternatively items in the blacklist can be edited (in hexadecimal form) via context menu, sub menu titled 'CAN IDs excluded from the trace history'. This menu also shows a complete list of all currently black-listed CAN message identifiers.
Suppressing certain CAN identifiers as described above only affects the trace history display in the programming tool (simulator), but not the 'real' device (i.e. hardware like MKT-View III which also has a built-in trace history).

In a 'real' device (but also in the simulator), the script itself can access the CAN-ID-blacklist via trace.can_blacklist[i] .

Accessing the Trace History via web browser

The easiest method to check the Trace History in a real device is through your web browser (for all devices with Ethernet and embedded web server). In most cases, you can access the device easily through its host name (which is "upt" by default, but the name may have been changed in the device's network setup). The full URL would be "http://upt/trace.htm", but the protocol name (http) is usually added by the web browser internally, and not shown in the address bar. Here for example the Trace History displayed in the author's favourite browser:

Trace History read via embedded web server, and displayed in a web browser

In case of problems with the network connection (or the web browser), see 'Troubleshooting' in the description of the embedded web server.

Reading the Trace History via serial interface

Alternatively, and depending on the hardware, the trace history can be read as plain text through a serial port, and saved as a text file on the PC.
To read the trace history via serial interface (RS-232 or Virtual COM Port), use a terminal program like 'Hyperterminal', and enter the command ***trace*** followed by carriage return ("Enter" key). The default baudrate for the serial interface is 19200 bits/second for most devices with a 'real' RS-232 port (like MKT-View 2). For device which only have a Virtual COM Port (looks like an USB device adapter from outside), try 115 kBit/second.
Since the serial port might have been reconfigured by the application (script), theres no easy way to tell the correct communication parameters here. Usually either "115200 8-N-1" or "19200 8-N-1" should work.

Trace History read via serial port, and displayed in 'HyperTerminal'

Saving the Trace History as a file

Last not least, if your PC (or your local network) refuses to establish a TCP/IP connection to the terminal, you can alternatively retrieve the Trace History as a plain text file by saving it on the memory card: First invoke the trace history on the device's own screen, press the 'Menu' button (softkey) there, and select 'Save Trace as file'. The firmware will dump the trace memory as plain text files, beginning with the name 'TRACE000.TXT'. With each new call of the 'Save as file'-function, a new file will be written (TRACE001.TXT, TRACE002.TXT, and so on).

The same function can be invoked directly from the script (trace.save_as_file).

The Trace History (in RAM) will be deleted when turning off the device, because it is only buffered in RAM for performance reasons. It cannot (and shall not) replace the CAN logger / 'Snooper' which is integrated in certain devices.


The trace accumulated in the simulator (i.e. the programming tool) can be copied into an own document (and thus be saved 'as a file' on the PC) as follows:

1. Set the focus into the trace history display (via mouse click, etc)
2. press CTRL-A (select all) or mark the interesting part of the trace via mouse
3. press CTRL-C to copy the selected text into the windows clipboard (as usual)
4. set the focus into your own document, and press CTRL-V to paste (insert) the text from the clipboard

Trace History invocation

There are several methods to invoke the Trace History Display locally, i.e. show it on the terminal's own screen.
Here, for example, how to invoke the Trace History Display in the MKT-View II / MKT-View III :

1. Draw the gesture 'U' on the touchscreen to enter the device's shutdown / system popup window.
   Alternatively (for devices without a touchscreen), press F2 + F3 simultaneously to enter the system menu.
2. Select 'SETUP' (in the 'shutdown' window) if not already there.
3. In the 'Main system setup', select 'DIAGNOSTICS'.
4. Select 'Trace History'. The number in parenthesis (after the menu item) shows the number of entries which are currently stored in the Trace History.

    ---->    
Invocation of the Trace History via system menu, and display on the device's "local" screen

Menu with Trace History Options, here in an MKT-View III

Exit Trace Display

Leave the trace history display, and return to the caller (which is usually the system menu)

Back to Trace Display

Leave the 'Options' menu, and switch back to the trace history display

Save Trace as file

Saves the trace history buffer as a plain text file on the memory card. Details here.

Show messages from CAN1 = {0,1}

1 (Default): Show CAN-messages sent to, and received from, the first CAN interface.
0: Don't show these messages (and don't enter them into the history buffer, from now on).

Show messages from CAN2 = {0,1}

1 (Default): Show CAN-messages sent to, and received from, the second CAN interface. 0: Don't show these messages.

Show messages from CAN-via-UDP = {0,1}

1: Show CAN-messages 'tunneled' via UDP (Ethernet). 0 (Default): Don't show these messages.

Stop when buffer is full

Special option to trace problems during startup / network boot / initialisation.
TRUE : The trace history will be stopped when the history buffer is full. Thus only the 'oldest' entries are available.
FALSE: The trace history will continue running (even when the buffer is full), thus only the 'newest' entries are available.

The default setting is 'FALSE', i.e. the trace historie will not be stopped (at least not automatically), and (depending on the firmware) only the last 255 or 511 entries can be viewed or exported.

Error messages / Error History

Stack Display (with caller addresses and local variables)

Stack[005]*: tCANmsg={ 1CEA00FF 3 CE FE 00 }
Stack[004] : 0
Stack[003] : return to line 822
Stack[002] : 1
Stack[001] : 65230
Stack[000] : 0

Symbol Table with variable display

In the programming tool, the symbol table can be displayed on the right side of the main window. Select the item 'Symbol table, complete' or 'Symbol table, global variables' in the combo box in the scipt editor's toolbar. The 'complete' symbol table also shows the names and locations of local variables (which cannot be inspected). The display with 'global' variables only shows global symbols (global variables of the script, functions, procedures, and constants).
In the tabular display, all symbols are sorted by name, which makes this display a valuable tool for 'navigation': Click on the 'Line number' (which is shown like a hyperlink) to scroll the script editor to the line in which a variable (or function, procedure, constant, etc) is defined.

Screenshot of the script symbol table in the programming tool

Hints:

For devices with Ethernet connector and embedded web server (like MKT-View III), global script variables can also be inspected via HTML browser.

In devices with a sufficiently large screen (e.g. MKT-View III/IV/V), script variables can also be examined in the device's system menu. Follow this link for details.

Watch List (shows values of a selection of variables)

In contrast to the symbol table display, the watch list only shows a user-defined selection of global script variables. This works with 'simple' script variables, arrays and user defined types.
  (for experts: the evaluation of arbitrary expressions is not supported yet)
New items can be added to the watch table is via the symbol table, as explained in the previous chapter, or via the script editor's context menu.

Screenshot of the script editor's Watch List in the programming tool

Delete entry

deletes the previously clicked item from the watch list

Hide entry

temporatily hides the display of the value, without deleting the item from the list.
For arrays and larger structures, this can save a lot of screen space in the watch display.

Show entry

Makes the value visible again, after it was hidden as explained above.

Delete all entries

Quickly removes all entries in the watch list. Usefull after switching from one project to another, before adding new items to the watch list.

Append more entries from symbol table

Switches to the symbol table, from which you can select more items (usually global script variable) to be displayed in the watch list.

List of memory blocks dynamically allocated by the script

Dynamic memory blocks
Block[0000] :   64 byte, Timer1
Block[0004] :   64 byte, Info
Summary: 2 blocks in 2 objects, 4094 blocks free.

( sample display of dynamically allocated memory blocks )

Similar as in most other debugger views, you can switch to the declaration of the variable by left-clicking on the blue underlined ("link-like") variable name.

Testing the application in the target's RAM (instead of FLASH)

To save precious time during the development phase, an application (incl. script) can be uploaded directly into the target system's main memory (RAM), without storing it permanently in "Flash" memory.
This eliminates the time for erasing and reprogramming the FLASH memory (which may take dozens of seconds, depending on the FLASH memory technology), thus the "modify - download - test" cycle is significantly faster this way, regardless of the transfer medium.
To transfer the application from the programming tool into the target's RAM ('without Flashing'), select the following function in the main menu:
  Transfer .. Send application to terminal without flashing .

Note:

We strongly recommend to test new applications not only in the simulator, but also on the 'real' hardware on which the application is supposed to run !
The execution speeds depend a lot on the CPU. For example, a script which runs 'fluenty' and without any problems on an MKT-View IV (with 200 MHz Cortex-M4) may be much slower on an MKT-View II (with 72 MHz ARM7TDMI), causing timeouts as explained in chapter about event handling.

Back to the overview about 'Debugging'

Interaction between script and display ("programmable display pages")

In some applications, the script only works "silently in the background", for example process signals from received CAN messages, or run protocols which are not implemented in the firmware.
In most applications, the script and the "programmable display pages" directly interact with each other. Examples:

• The operator presses a button (on the touchscreen), and the button's "reaction" (interpreter command line) modifies the value of a script variable (which is then, a few milliseconds later, processed in the script's main loop);
• The operator presses a button (on the touchscreen), and the button's "reaction" (interpreter command line) invokes a procedure written in the script language;
• The script detects a critical value in one of the 'display variables' (connected to CAN) and changes the background colour of a display element from green to red (just as an example);
• The script can intercept certain user actions by an event handler (advanced topic "for later")

See also (links to other chapters in this document) :

• Accessing display variables from the script
• Accessing script variables from the display interpreter
• Accessing display elements (on the current display page) from the script
• Invoking script procedures from the display interpreter
• Invoking script functions from display pages (to retrieve a text strings for the display, used for internationalisation)
  

Calling a script procedure as reaction when pressing a button

Before the implementation of the script language, the 'reaction' on pressing a button was specified as a display interpreter command (for example, g(pn+1) to switch to the next page).
For compatibility reasons, that is still possible. But for more advanced applications, a graphic button's "reaction" (when the button is operated via touchscreen or rotary encoder knob) should better be implemented in the script.
To achieve that, there are several possibilities (listed in the introduction of chapter 3).
In the following example, we will define a graphic button on one of the UPT's display pages, and let that button call a user-defined procedure when the button is pressed.

 
Screenshots from the programming tool, details in the document
about programmable buttons

Screenshots from the programming tool, "Display Line Properties" for a Button

proc StartTest // Called from the DISPLAY (a button's "reaction"). Starts the "test"....
  iStartTest := TRUE; // here: only SET A FLAG, and do the rest in the script's MAIN LOOP
endproc;
       

Modifying display elements via script (texts, colours, etc)

The script has 'full control' over all elements on the current display page.
As already mentioned in the introduction of chapter 3, the script can access any display element to modify its colour, text, position, size, etc.
For advanced users, this topic is explained in chapter 4 (use display.elem[] or display.elem_by_id[] to access the display element).

The recommended way to access a certain display element is either by its name (as in the example below), or by its symbolic control ID.
The following code snippet from a script's main loop changes the background colour of a button, using an if..then..else condition :

while(1)  // endless loop for the script's MAIN THREAD

  if( iStartTest ) then
    if( ReadIniFile( "memory_card/IniDemo1.ini") ) then
       display.elem["ReadIni"].bc = clGreen; // paint the button with a GREEN background
    else  // could NOT read the ini-file :
       display.elem["ReadIni"].bc = clRed;   // paint the button with a RED background
    endif;
    iStartTest := FALSE;
  endif; 

  // ... insert other main task activities here ...

  wait_ms(50);  // give the CPU to someone else for 50 milliseconds
endwhile; // end of the main thread loop
       

Language Reference

The scripting language was once a subset of the BASIC programming language (without line numbers), and was later modified to be more 'PASCAL'-like. Some elements were borrowed from other programming languages. From  PASCAL, BASIC, and IEC 61131 "Structured Text", this language inherited the case-insensitivity, so it's up to you to write keywords in upper or lower case (but please don't mix upper and lower case for keywords, and don't use "Camel Casing" if it makes no sense..). If there are CamelCased symbols in your program, they should be self-defined variables, data types, self-defined functions or procedures but not standard language keywords . Top-level keywords of the script language are (just for example, but also as a quick reference):

if..then..else..endif     for..to..next    while..endwhile   repeat..until   select..case..else..endselect

proc..endproc    func..endfunc    

const..endconst    var..endvar    typedef..endtypedef

addr    append    float    int    local    ptr    string

int    string    CAN    cop.(CANopen)    display.    file.    gps.    inet.    Math.    system.  

time.    trace.    tscreen.    wait_ms   wait_resume

For compatibility with the original BASIC-like language, colons ( : ) can be used to separate commands in one line. But we recommend to use only one command (function call, variable assignment, loop statement, etc) per line. Using one line per command also simplifies debugging, because you can set breakpoints only at the begin of a line.

The hash mark (#) at the begin of a line marks the begin of a compiler directive. For example, the compiler can be instructed to accept only declared variables (directive #pragma strict).

To mimick more 'modern'  programming languages, a semicolon can also be used to separate two commands in one line. But unlike "C", Pascal, and Java, the end of a line has a syntactic meaning (it also separates two commands or statements), so in most cases, neither the colon nor the semicolon should be necessary if you follow the style recommended above ... use ONE LINE PER STATEMENT . A few examples with the recommended style follow below.

Leading spaces have no syntactic meaning for the compiler, but you should generously use leading spaces (indentations) to increase the readability of your code. For example, with a bit of imagination it's obvious what this code does :

Sum := 0.0; // calculate PI ...
for Loop:=1 to 10000  // do 10000 iterations
   if (Loop & 1) <> 0 // odd or even loop count ?
     then Sum := Sum + 4.0 / (2 * Loop + 1); // odd
     else Sum := Sum - 4.0 / (2 * Loop + 1); // even
   endif;
next Loop;
print( "PI is roughly ", Sum );


Suggestions about the coding style (not mandatory, but the highly recommended by the author):

• Use at least two space characters per indentation level.
  Any function body (between 'proc' and 'endproc') shall be indented, too.
  Only the 'main code' (typically at the begin of the script, executed immediately after program start), and the keyword pairs const/endconst, var/endvar, proc/endproc, func/endfunc shall not be indented (because they always sit at the script's 'main level' - there are no nested functions as in Pascal).
• It's not necessary to write keywords in upper case. Keywords were sometimes written in upper case in this document, when it seemed important to mark them as such (because bold or italic characters don't work in a plain text file). Since the script editor can automatically highlight keywords, the author of the script language uses keywords in lower case, and only user-defined CONSTANTS in UPPER CASE . This is what most "C" programmers prefer.
• Don't ever use tabs in sourcecode, because different editors use different default settings (some editors use 8 characters per tab, some use 4, others 3 by default, etc...), so using tabs in sourcecodes will sooner or later turn everything into a mess, which can often be seen in open-source projects. Use two or three spaces per nesting level, and align the 'ending' statement (like next, until, endif) to the same column as the matching 'beginning' statement (like for, repeat, if) as in the example shown above.
  If you consider comments and indentation (leading spaces to emphasize nesting) a useless waste of time, stop developing software.

The following subchapters explain most of the script language's syntax elements. Special commands, keywords, and runtime library functions are explained later.

See also: Keyword list, Operators (numeric),  User-defined Functions and Procedures, Program Flow Control, Other Functions and Commands .

Numbers and numeric expressions

Numbers are integer by default. Their notation is usually decimal, but hexadecimal and binary is also possible (see examples below). Numbers may be integer or floating point. A number's data type is stored internally, along with the value.

• 1234     is an integer number in decimal notation (which is the default)
• 1234.0 is a floating point number (because the compiler recognizes the decimal point)
• 0xABCDEF is an integer number in hexadecimal notation (thanks to the "0x" prefix)
• 0b10000001 is an integer number in binary notation (the prefix "0b" means "binary").

Use integer numbers wherever possible. But, if an expression uses some floating point variables as input, you should also use floating point numbers (constants) because the compiler will emit floating point constants as such if it's obviously a floating point notation. This eliminates type conversions at runtime, and makes the script run faster. Example (with Sum being a floating point variable, and Loop an integer):

    Sum := Sum + 4.0 / (2 * Loop + 1);

does not calculate the same result as

    Sum := Sum + 4 / (2 * Loop + 1);

Look at the right term in the above formula: It contains only integers. When the compiler produces bytecode for the right term, it will use integer numbers because they were much faster on older target systems (without hardware floating point unit). This also includes the DIVIDE instruction : If both operands are integers, the division will be an integer, too. If one, or both, inputs for the DIVIDE operation are floating point numbers, the division itself will be performed using a (slow) floating point operation. If you definitely need a floating point operation, use floating point numbers (constants) as in the upper example shown above. BTW, the example is taken from the application 'ScriptTest2.cvt', contained in the installation archive, which calculates the number 'PI' using the Gregory-Leibniz formula.

To convert 'binary data' (like received CAN messages)  from a sequence of bytes into floating point numbers, use functions like BytesToFloat, BinaryToFloat, or BytesToDouble.

See also: Numeric functions, "Math", DSP.

Strings

String constants must be enclosed in double quote characters, as in most programming languages (except Pascal).
To declare a variable as a string, use the keyword string, or (if you prefer not to declare variables as in ancient BASIC dialects), use the 'dollar suffix' ($) to let the compiler know that your variable is a string.
In most places where the compiler expects strings, you may also use a string expression like A$+" some text "+B$ .

Example (using a properly declared string variable)

var
   string MyString;
endvar;
...
 MyString := "This is another string";

For certain applications, static byte-arrays (i.e. in global script variables) can be treated like strings. Beware, the character encoding gets lost then, and the receiver (or reader) of the string doesn't know if the characters must be treated as ASCII, "ANSI", or UTF-8. Example:

        TP_Transmitter.buffer := "Test string sent via ISO 16765-2 'TP' .";
        TP_Transmitter.iTotalSizeInByte := strlen( TP_Transmitter.buffer );
        IsoTP_StartSending( &TP_Transmitter ); // start sending an ISO-TP message
      

(in that example, TP_Transmitter.buffer is a struct component declared as 'BYTE buffer[1024]', and TP_Transmitter.iTotalSizeInByte is the total 'payload size', measured in bytes.
When copying the string, an trailing zero-byte is appended, which strlen() does NOT count as a character. Beware, when copying strings into static arrays this way, the string may be truncated.)

The script language contains a few string processing functions, like itoa ("integer to ASCII"), hex (integer to hexadecimal ASCII), chr (turns an ASCII value into a single-character string) .

Strings with different character encodings

For simple string variables (not strings in arrays or structs), the character encoding of a string may vary, depending on the assigned value.
For simple string variables, the 'string' data type contains internal flags which specify the encoding. For example, if a string was read from a Unicode text file (using the function file.read_line), the string will contain a sequence of UTF-8 encoded characters. This way, the character encoding type is passed along with the string when calling subroutines and functions, or when assigning the string to another variable. If necessary, a string's character encoding can be queried as in the following example :

select( char_encoding( MyString ) )
   case ceDOS : // string contains "DOS"-characters (codepage 850)
       ...
     
   case ceANSI : // string contains "ANSI"-characters (Windows-1252)
       ...
     
   case ceUnicode : // string contains "Unicode"-characters (encoded as UTF-8)
       ...
     
   case ceUnknown : // the string's character-encoding is unknown
      // This means the encoding type has not been specified,
      // or doesn't matter because all characters in the string
      // have code values below 128
      // (in that case "DOS", "ANSI", and Unicode are almost identical)
        ...

endselect;

The same constants can be used to define the file type / file format when creating new text files via file.create. Specifying e.g. char_encoding=ceUnicode (as an optional named parameter for file.create) causes any string appended to the file later to be converted to UTF-8.

Note: Just because the script language supports Unicode (to be precise, UTF-8 encoded strings) doesn't mean your application will be able to render those characters on the display ! The fonts used by MKT's LCD driver date back from the days of DOS, and only contain glyphs for the 255 characters defined in the old 'DOS' character set (Codepage 850) !
When showing an UTF-8 encoded string on the display, the firmware will try to find a match for the Unicode 'code point'. Thus, at least the common western characters (like German 'Umlauts') will appear correctly on the display, regardless of the string's character encoding type ( ceDOS, ceANSI, ceUnicode ).

Arrays and struct members of type 'string' are always stored as UTF-8 internally, because there are no individial character-encoding flags stored in memory for each array element.
If, for example, a 'DOS'- or ANSI-encoded string is assigned to an array element, all characters with codes > 127 will be converted to UTF-8 sequences automatically. Thus, when reading those strings from the array, they have the encoding type ceUnicode !

If necessary, the character encoding of string literals (i.e. string constants in the script sourcecode) can be specified by the following single-lowercase-letter prefixes. When not speficied, the compiler may decide to use ANSI, or (more likely) UTF-8:

• a"Text"
  "ANSI"-encoded characters (precisely: Windows CP-1252, 8 bits per character)
• d"Text"
  "DOS"-encoded characters (precisely: DOS Codepage 850, 8 bits per character)
• u"Unicode-Test"
  Unicode (precisely: characters encoded in UTF-8, with a variable number of bytes per character)

Note: The double-quote character, which marks the begin of a string constant (literal), must follow immediately after the prefix character (a,d,u) !

Example (assigns a Unicode string literal to a string variable) :

   MyString := u"Falsches Üben von Xylophonmusik quält jeden größeren Zwerg.";

Wherever possible, special characters (as in the german pangram above) will be translated into their proper encoding by the compiler.
The character encoding of the script sourcecode is assumed to be "ANSI" (Windows CP-1252), not "DOS"-encoded characters !
This may change in the far future, if the script editor in the programming tool can be convinced to emit its content in UTF-8 instead of Windows CP-1252.
Until then, use Unicode escapes (after backslash-u) for all characters which you don't find on your PC's keyboard. Example:

   MyString := u"Falsches \u00DCben von Xylophonmusik qu\u00E4lt jeden gr\u00F6\u00DFeren Zwerg.";

More examples can be found in the 'String Test' application.

String usage and storage format

Most characters in a string are internally stored as an 8-bit number. A zero-byte marks the end of a string (but you don't need to care about this, because the compiler adds the zero automatically when encountering a string constant in the sourcecode). Depeding on the string's character-encoding type, characters with a code value above 127 (!) may occupy one or more bytes in memory. 8-bit "DOS" or "ANSI" characters are stored as such in memory. A few of those 255 possible codes are reserved for special control characters, line "carriage return" and "new line" - see 'backslash sequences' further below. In addition, strings can be stored as UTF-8 sequences in memory.

During runtime, string memory is dynamically allocated from a common memory pool. The amount of memory required depends on the number of strings used in your application, and their individual lengths. For example, consider an array of structures, declared as :

typedef tStringTableEntry = // user defined data type..
   struct // structure for an entry in a "string table"
      int valid;    // 0: invalid or "deleted" entry, 1:valid
      int iRefNo;   // string reference number (integer)
      string sInfo; // the string itself (any length!)
   endstruct; // end of a structure definition
endtypedef; // end of type definitions


var // declare GLOBAL variables, here: an array of structs
   tStringTableEntry StringTable[1000];
endvar; // end of variable declarations



Initially, each tStringTableEntry only occupies 12 bytes (2 * 4 bytes for the integers, plus 4 bytes for a pointer to a string object in some other memory area).
Later, when the sInfo entries in the 'StringTable' array are filled (and the strings are not "empty" anymore), each string will require additional memory .
In other words, the amount of memory used by your script may increase at runtime. Thus, to make sure your application doesn't run out of memory later, consider how many strings may be used by your application at runtime at worst case, and how long each of those strings may grow (because the compiler doesn't know this). Let your application run in the programming tool's simulator, and test every function in your script. When finished, examine the peak memory usage in the debugger, and make sure the 'data memory' usage isn't critically close to the maximum.

String constants with special characters

The compiler doesn't know for what a string will be used later. It doesn't know anything about languages, fonts, character sets. For this reason, it doesn't try to convert any special characters (especially not German umlauts, etc). If you know the string will be displayed on the LCD screen later, using one of the DOS-compatible fonts, replace the Umlaut (etc) with the hexadecimal equivalent ( backslash x followed by two hex digits, in the double-quoted string constant ), or use the prefix 'd' ("DOS") before the double-quoted string to let the compiler convert the string from the sourcecode format (which is usually 'ANSI') into DOS.

Examples:

Test$ := "\x99rtliche Bet\x84ubung \x9Abelkeit"; // string with hex codes for Ö, ä, Ü if a 'DOS font' is used for rendering
Test$ := d"Örtliche Betäubung kann Übelkeit hervorrufen"; // string converted into 'DOS characters' by the compiler

Hexadecimal codes for certain 'special' characters in DOS fonts (as used in most of MKT's programmable displays) :

Beware: The script language isn't aware of the font used to render a character on the screen. The compiler doesn't know what 'will happen' with a string later (if you will print it on the screen later, write it into a file, etc). Thus, \x94 may print a German 'ö' (o diaeresis, or "o Umlaut") on the screen, but only if the font used to render the string is the old-fashioned 'DOS font', aka 'codepage 437' or 'codepage 850'.

A complete 'DOS' character table ("Codepage 437") can be found here . Rows and columns use hexadecimal numbers, making it very easy to find the 8-bit hex code for any desired 'special' character. The Text Screen example uses some of those characters to draw lines and boxes on the text screen.

Strings with backslash sequences

Besides the sequence \x to insert a special character (by its hexadecimal code), the following backslash sequences have a special meaning in the script sourcecode:

\\

Inserts a *single* backslash in the string .

\r

Inserts a carriage return character ( aka CR, chr(13) ) .

\n

Inserts a new line character ( aka "linefeed", chr(10) ) .

\x

Inserts an 8-bit character by its hexadecimal code (not Unicode!).
See details in chapter 'string constants with special characters' .

\u

Inserts a Unicode "character" (code point), specified as 4-digit hexadecimal value.
The compiler (!) replaces the unicode value with an UTF-8 sequence. 
Note that only very few of those 1114112 possible Unicode code points can later be rendered on the display !
Details in chapter 'strings with different character encodings' .

\"

Inserts a double quotation mark in the string (without a backslash, the double quote is the string delimiter, so it cannot be a part of the string itself ) .

Don't confuse the backslash sequences inside the script language (listed above) with the backslash sequences in the display interpreter ! The simple control characters (like 'new line', etc) have the same meaning in both types, but the internal functions are entirely different !

See also: Invoking script functions from a backslash sequence on a display page

String processing

Strings can be concatenated with the '+' operator (formal "addition"). Example:

  var
    string Info; // Declaration of a string variable
  endvar;
  Info := "First part";
  Info := Info + " second part";

The following string processing functions had been implemented at the time of this writing (2013-11-05) :

append( <destination>, <source> [, <index_variable>] )

Appends a string ('source') to the end of another string ('destination'), or to an array of bytes.

Example 1: Appending a string to another string

        var 
          string s1,s2; // declare two string variables
        endvar;
        s1 := "Don't mix apples";
        s2 := " and oranges";
        append(s1,s2);  // Append s2 to s1, result in s1 : "Don't mix apples and oranges"
        print( s1 );    // show result on a text panel

In the example above (with destination = string), the third function argument ('index') is neither required nor recommended.

Example 2: Appending multiple strings to a 'binary block' (array of bytes)

        var 
          byte TxBuffer[1024]; // declare an array of bytes
          int  TxByteIndex;    // index variable for 'TxBuffer'
        endvar;
        
        TxByteIndex := 0;  // begin filling TxBuffer[0] here
        append( TxBuffer, "First string.\r\n", TxByteIndex );
        // Note: append() will increment TxByteIndex by the 
        //       NUMBER OF BYTES appended to the buffer !
        TxBuffer[TxByteIndex++] := 0x00;   // append a ZERO BYTE as string-end-marker
        append( TxBuffer, "Second string.\r\n", TxByteIndex );        
        TxBuffer[TxByteIndex++] := 0x00;   // append another ZERO BYTE
        append( TxBuffer, "Third string.\r\n", TxByteIndex );                
        StartSendingBlock( TxBuffer, TxByteIndex/*nBytes*/ ); // user-defined procedure

In this example, the 3rd function argument ('index_variable') is an integer variable which is incremented by the number of bytes appended to the destination in each call of the 'append' command. The array 'TxBuffer' is filled with multiple strings, which are delimited by a ZERO byte (as in the "C" programming language).
Because in the script language, a zero-byte also marks the end of a string, the trailing zero cannot be part of the 'netto' contents of the string itself. Thus, in the example shown above, the string delimiter is appended to the binary data block with the command
  TxBuffer[TxByteIndex++] := 0x00;
The post-increment-operator '++' increments 'TxByteIndex' by one after the access.
Concatenating strings via append() is faster than 'adding' them (i.e. use append(s1,"Hello")   instead of   s1 := s1+"Hello"), because in many cases append() doesn't need to free and re-allocate a block of memory for the string (due to the internal memory management, which allocates strings in chunks of N times 64 bytes, leaving a reserve of up to 63 characters in memory).

chr( N )

Converts an integer code (N, 0..255, usually from the "DOS" character set) into a single-character string.
If 'N' is above 255, it is assumed to be a UNICODE value, but you should better use unicode_chr( N ) for that purpose.
Example: chr(32) returns the 'space' character.
If 'N' originates from a stream of characters in ANSI code (e.g. from a serial port / terminal), use ansi_chr() instead.

ansi_chr( N )

Converts an integer code (N, 0..255, usually from the "DOS" character set) into a single-character string.
If 'N' is above 255, it is assumed to be a UNICODE value, but you should better use unicode_chr( N ) for that purpose.
Example: ansi_chr(176) returns the 'degree'-character aka 'ring' (°), as in '°C' for 'degrees Celsius'.

unicode_chr( N )

Almost the same as chr(N), but unicode_chr(N) converts an integer code (N, 0..0x10FFFF) into a single-character unicode string, regardless of whether this character can be rendered on the screen or not ! Example: unicode_chr(0x20AC) returns a string with the internal representation (which is UTF-8) of the 'Euro Sign' character.

CharAt( string s, int char_index )

Returns the code of the N-th character in the string s. As usual, the index starts counting at zero for the first character. The result is a 32-bit Unicode value, which, for 'normal' western characters, is the same as the ASCII value (codes 1 to 127). The 'CharAt' function is aware of the string's character encoding type, and supports UTF-8. Note that for UTF-8, there is a big difference between the 'character index' and the 'byte index'. CharAt always treats the 2nd parameter as a character index, not a byte index. If <char_index> is negative, or exceeds the length of the string, CharAt returns zero which means "there is no character at this index".

char_encoding( string s )

Returns the string's character encoding type. The result will be one of the following constants:
ceDOS ("DOS"-characters),  ceANSI ("ANSI"-characters), ceUnicode, or ceUnknown .

ftoa( float value, int nDigitsBeforeDot, int nDigitsAfterDot )

"floating-point to ascii" .
Converts a floating point value (1st argument) into a decimal string, using the specified number of digits 'before' and 'after' the decimal dot. Example:
   Info := "Tire Pressure="+ftoa(fltTirePressure, 4, 1)+" bar";
If the 'number of digits before the decimal dot' is larger than required, the string returned by ftoa() will be padded with leading spaces (not zeroes). If the 'number of digits after the decimal dot' is larger than required, the string returned by ftoa() will be padded with trailing zeroes (not spaces). If the 'number of digits after the decimal dot' is zero, the decimal point ('.') will also be omitted.

itoa( int value [, number of digits])

"integer to ascii" .
Converts an integer value (1st argument) into a decimal string, using the specified number of digits (2nd argument). Example:
   Info := "Timestamp="+itoa(system.timestamp,8);
If the value doesn't fit into the specified number of digits, the result (string) will only contain the least significant digits. Example:
   itoa(1234,2) returns 24 (as string), not "1234" !
If the number of digits is not specified, or zero, itoa will produce just as many digits as required (without leading zeroes).
See also: ftoa, which emits leading spaces instead of zeroes.

atoi( string value [, int number_of_digits [, int start_index]] ),
atof( string value [, int number_of_digits [, int start_index]] )

"ascii to integer"   , "ascii to float" .
Converts a decimal string into an integer or floating-point number (a numeric value), using the specified number of digits (2nd argument, optional), or the entire string.
An optional third argument can be used to specify the start index (=index of the first character to be parsed).
If the optional parameter 'start_index' is passed by reference (using the address-taking operator before an integer variable), then that variable will receive the zero-based index of the next character after the parsed number.
Examples:
   atoi("1234567");     // returns 1234567 as an integer value.
   atoi("1234567",3);   // returns 123 (parse 3 digits, beginning at char-index 0).
   atoi("1234567",3,2); // returns 345 (parse 3 digits, beginning at char-index 2).
   start_index := 0; // begin parsing here (start_index must be declared as int somewhere)
   value := atoi("1234567",10, &start_index); // increments start_index by 7 (# parsed chars).
Indices start counting at ZERO, not ONE. The first character in a string is at index zero.
Both atoi and atof recognize a trailing 'minus' character for negative numbers.

hex( int value, int number_of_digits ) alias HexString( .. )

Converts an integer value (1st argument) into a hexadecimal string, using the specified number of digits (2nd argument)

BinaryString( int value, int number_of_digits )

Converts an integer value (1st argument) into a binary string, using the specified number of digits (2nd argument)
Example:
BinaryString( 0x12345678, 32 )returns 00010010001101000101011001111000 as string.

strlen( string s )

Returns the number of characters in the string (not 'the number of bytes', especially not for UTF-8).
Example:
strlen("How long is this string ?") returns 25 .

strpos( string haystack, string needle[, int startindex] ),
stripos( string haystack, string needle[, int startindex] ),
strrpos( string haystack, string needle[, int startindex] ),
strripos( string haystack, string needle[, int startindex] ),
strpos2( string haystack, string needle[, int start_index] )

Finds the first (or last) occurrence of a search string (needle) in a larger string (haystack), beginning at the optionally defined start-index (zero-based character index).
The functions strpos and strrpos are case-sensitive ('a'..'z' are different from 'A'..'Z'), stripos/strripos are not (i="insensitive").
The functions strpos and stripos try to find the first occurrence of the needle, strrpos/strripos try to find the last (r="reverse").
The return value is a character index (index zero = first character in 'haystack'), or a negative integer if the needle couldn't be found in the haystack.

In contrast to strpos(), strpos2() doesn't return the character index of the needle's first character within the haystack, but the index of the next character after the needle. In other words, strpos2() skips the needle if it finds one. With strpos2(), a parser can easily process the trailing string as shown in the examples further below.

If the 3rd argument (start index) is omitted, strpos/stripos start searching at index zero, i.e. at the first character in the 'haystack'. This can be used for a simple string parser. Example:
 haystack := "This test string is 38 characters long";
 needle   := "is"; // string to be found in the haystack
 i := strpos(haystack,needle);     // find the first needle (result: i=2)
 i := strpos(haystack,needle,i+1); // find the next needle (result: i=17)
After finding the keyword, the trailing value can be converted to int or float using atoi(ascii-to-integer) bzw. atof(ascii-to-float):
 i := strpos2(haystack,"VBat=");   // find index of the next char AFTER the needle
 if( i>0 ) then // found the needle (keyword) in the haystack, parse the following value
    iValue := atoi( haystack, 5/*digits*/, i/*start*/ ); // parse number after keyword
 endif;
Because atoi and atof also accept the start index as optional (3rd) parameter, it's unnecessary to copy strings in the example shown above.

substr( string s, int start [, int length] )

Returns a sub-string of the first argument, beginning at the zero-based character index 'start', and consisting of 'length' characters.
If the parameter 'length' is omitted, the returned string (result) includes all characters from 'start' up to (and including) the end of the source string.
If 'length' is specified and positive, the result will never have more than 'length' characters.
If 'start' or 'length' are negative, the result will be an empty string.

ParseInteger( string value [, int max_digits [, int start_index]] )

Alias for "C"-function atoi() ("ASCII to integer"), with a few extensions.
If the argument 'start_index' is not specified, parsing starts at the first character (same as start-index zero).
If the argument 'max_digits' is also not specified, parsing ends after the last digit, end-of-string, etc.
If the optional parameter 'start_index' is passed by reference (using the address-taking operator before an integer variable), then that variable will receive the zero-based index of the next character after the parsed number.
This also applies to the other string-parsing functions listed further below. For an example, see ParseFloat().

ParseFloat( string value [, int max_digits [, int start_index]] )

Alias for "C"-function atof() ("ASCII to float"), with a few extensions.
Similar to ParseInteger(), but returns a floating point value, and accepts fractional parts after a '.' (dot).
Example:
  sLine := "U=23.4V T=22.7°C";
  start_index := strpos( sLine, "U=" );
  Ubat := ParseFloat( sLine, 10/*max_digits*/, start_index+2 );
  start_index := strpos( sLine, "T=" );
  Temp := ParseFloat( sLine, 10/*max_digits*/, start_index+2 );

ParseHexString( string value [, int max_digits [, int start_index]] )

Inverse to HexString. For an explanation of parameter 'start_index', see atoi().
If the string (value) begins with 0x (prefix for 'hexadecimal' as in "C" or Python), these two characters will be skipped. They are also included in the count of 'max_digits' just like any other character 'consumed' by the parser.

ParseBinaryString( string value [, int max_digits [, int start_index]] )

Inverse to BinaryString. For an explanation of parameter 'start_index', see atoi().
If the string (value) begins with 0b (prefix for 'binary' as in Python), these two characters will be skipped. They are included in the count of 'max_digits' just like any other character 'consumed' by the parser.

string( value [, number of characters] )

"Convert whatever it is into a string, using the default format" ^(*) .
If the value (first argument) is a byte array, it will be treated like an UTF-8 encoded string.

(*) For certain source data types, the string format can be customized,
  e.g. CAN.string_format if 'value' is a tCANmsg.

string( source_array, iFirstByte, iMaxBytes )

This string-constructor function also converts the contents of a byte array (first argument), beginning at the specified zero-based array index (second argument), with a maximum of N bytes (third argumet), into a string of characters (return value).
Also in this case, the content of the byte array is assumed to be UTF-8 encoded. Example:
  s := string( b256ReceivedData, iBeginOfPayload, iPayloadLength ); // inefficient call-by-value

As already mentioned in chapter 4, large objects (like structs and arrays) should better be passed as pointer ('call by reference' instead of 'call by value'). This way, the unnecessary and wasteful duplication of the array (to 'call by value') can be avoided:
  s := string( &b256ReceivedData, iBeginOfPayload, iPayloadLength ); // more efficient call-by-reference

More examples for the string processing functions listed above can be found in the 'String-Test' application .

< To Be Completed >

See also : Keyword list ,  file I/O,  table of contents .

Constants

Built-in constants

A few constants are hard-coded inside the script compiler. Don't rely on the actual value (that's why we don't show them in the table below).

For the sake of readability, most constants are prefixed with a lower-case 'c' (for constant). Despite that, the script compiler is case-insensitive !

User-defined constants

In addition to the fixed constants shown above, you can define your own constants.
This sometimes improves readability, especially when you need the constant's value more than once in your script.
The keyword 'const' begins a list of constant definitions, the keyword 'endconst' ends such a list.

Each constant is defined using the following syntax :

<constant_name> = <value> ;

or (with the definition of the data type, which may be necessary if the value isn't easily recognizeable, or ambiguous) :

<data_type> <constant_name> = <value> ;

or (to define a constant array, as described further below) :

<data_type> <constant_name> [array_size] = <value> ;

Example (please note the coding style - indentation between const & endconst) :

const // define a few constants...
   C_HISTORY_BUF_SIZE = 1000; // a decimal integer
   C_CANID_RX_A   = 0x333;    // a hexadecimal integer
   C_CANID_RX_B   = 0x334;
   C_CANID_TX_ACK = 0x120;
endconst; // end of 'constant' definitions

User-defined constants must be defined at the begin of the script (or, at least, before they are used).

Notes:

• Use constants instead of 'magic numeric values' which no-one else (besides you) will understand,
  especially in long select..case statements, and as control identifiers in message handlers.
• Like the names of variables, data types, and similar elements, the name of any constant is limited to 20 characters.
• A script may use a maximum of 256 different const...endconst blocks. The number of constants (in these blocks) is only limited by the available bytecode memory, which is target specific (usually 64 kByte total bytecode memory).
• The old UPT display interpreter can access user-defined script constants without the need to prefix the constant's symbol by "script." .
  But this only works if the symbol does not exceed the maximum length of a display variable (!), which is usually 8 to 16 characters.
  The maximum length of a constant's name in the script itself is virtually unlimited.

'Calculated' constants (constants 'calculated' at compile-time, not at runtime)

To force the evaluation of simple expressions as numeric constants at compile-time, use the hash character before the constant expression in parentheses.

Example:

The expression in the command

N := #(1+2+3)

will be evaluated (calculated) at compile-time (by the compiler itself),
In contrast to that,

N := 1+2+3

will be calculated at runtime, resulting in a slightly reduced execution speed.

The compiler's own formula-evaluator is reduced to very basic calculations; it doesn't support parentheses, it doesn't support different operator precedences; and it only works with integer constants ( symbolic or numeric ).

Constant tables (arrays)

For some applications, it was necessary to store constants in arrays. One could use an array variable for this purpose, and fill the array at runtime using a long list of assignments. But there is a more elegant method to achive this: Constants can be defined like a formal array (and thus be accessed like an array with "read-only" access at runtime). Such constant-arrays could then be used to initialize (fill) variables-arrays in a loop, etc; because each element of the array can be accessed through an index.

Example (actually taken from the 'quadblocks' demo) :

CONST
  int BlockColors[7] = // seven block colours : BlockColors[0...6] !
    { clBlue, clRed, clCyan, clYellow, clGreen, clMagenta, clWhite };
ENDCONST;

See also : constants (overview), variable arrays, displaying tables (graphic/control element).

Built-in and user-defined data types

The script language supports the following three 'basic' built-in data types :

• int (alias "integer") : signed 32-bit integer .
  This is the preferred data type for most numeric operations, and also to identify files (handles) and internet communication endpoints (sockets).
• float : 32-bit 'single precision' floating point. Contains an 8-bit exponent, a 23-bit mantissa, and a sign bit.
  This type can store fractional decimals like 0.12345. In numeric operations, it was slower than integer due to the lack of a floating point unit in older target systems (without a hardware floating point unit).
  If necessary, a floating point value can be 'constructed' from single bytes (with exponent and mantissa) via BytesToFloat() or BinaryToFloat(). Floating point numbers can be formatted into strings via ftoa() ('float to ASCII').
• double : 64-bit 'double precision' floating point. Offers a higher accuracy in numeric calculations than 'float', at the expense of speed.
  Thus this type should only be used if single precision float is not sufficient, for example...
  
  • to store date and time with with high resolution in a single value, e.g. as 'Unix time' (fractional seconds),
  • for calculations using latitude and longitude from precise GPS receivers (with spatial resolution in the centimeter range),
  • to store the value returned by function BytesToDouble(), if you really need the maximum resolution.
• string : A string of characters. The characters of a string are stored in a separate memory region, the length may vary during runtime.
  (In struct- and array size calculations, a string only seems to occupy four bytes in memory, but this is just a *pointer* to the actual characters.
  Details about the string type are here ).
• char : A single character (8 bit). Typically used as an array for strings with a fixed length, for example when describing data structures (more on that later).
  

In addition to the above 'basic' types, the following 'simple' types can be used in struct- or array declarations. When used in calculations (formulas, expressions), they are automatically converted to integer:

• byte : unsigned 8-bit integer (value range 0 to 255) .
  This type occupies one byte in arrays or structures. It's actually the smallest 'integer' type which can be used for arrays.
• word : unsigned 16-bit integer (value range 0 to 65535) .
  Occupies two bytes when used in arrays or structures.
• dword : unsigned 32-bit integer (cannot be converted into 32-bit integer without 'losses' - only used for storage !) .
  Occupies four bytes when used in arrays or structures.
• bool : Similar as integer, but optimized to store the 'boolean' values TRUE (1) or FALSE (0). Up to date (2019-01) treated like int in expressions and comparisons (e.g. TRUE plus TRUE gives 2 (two!), which is quite nonsense but 'works' because when testing the result (e.g. in an if-condition), all that matters is if the integer value is zero or nonzero. Thus, 2 (two) will have the same effect as 1 (TRUE). In future revisions of the script compiler, arrays of type 'bool' may have a more compact storage format (using only one bit per element) than arrays of integers.
• tColor : Also an integer, but with the special meaning 'colo[u]r'. Used by some functions, for example to draw polygons into diagrams. The function rgb(red,green,blue) returns a tColor 'mixed' from the three colour components.
  

Type conversions between the 'basic' and 'simple' types listed above are performed automatically during runtime as necessary. Example:

        var 
          int   i;  // declaration of an integer variable
          float f;  // declaration of a floating-point variable
        endvar;
        
        i := 1234;    // integer value assigned to an integer variable
        f := i;       // integer value automatically converted to float 
        // (in older versions, an explicit conversion was required here, like
        //  f := float(i);   // convert integer to float, then assign to 'f' )
      

• tScreenCell : Data type describing one cell of the text screen buffer . Components of this structure are:
  .bChar : character code, usually ASCII or even DOS character set, 0..255
  .bFlags : Bit 7 = Flags to force redrawing this cell.
  .bFontNr : reserved for future use
  .bZoom : reserved for future use
  .fg_color : foreground colour (each character cell has an individual colour ! )
  .bg_color : background colour
  
  
• tCanvas : Data type for a 'painting canvas', which the script can use to create graphics at runtime.
  Component names were unknown at the time of this writing (12/2017) - they may be similar as in HTML5 (width,height,data).
  Directly accessable components of a tCanvas:
  .width : width in pixels,
  .height : height in pixels.
  A pointer to a canvas can be used in OnPageUpdate() for Z-ordered painting into the framebuffer.
  See also: Canvas functions and methods for 'painting'.
  
  
• tMessage : Data type used by the message handling functions. Components are:
  .receiver : identifies the receiver of the message (if any, may be zero for 'broadcast' messages)
  .sender : identifies the sender of the message. If the sender is not a windowed control (but the system), this value may be is zero.
  .msg : message type code (integer). Should be one of the 'wm' ("windows message") constants, or user defined .
  .param1 : first message parameter. Usage depends on the message type.
  .param2 : second message parameter. Usage depends on the message type.
  .param3 : third message parameter. Usage depends on the message type.
  For details about tMessage, see the chapter on message handling .
  
  
• tCANmsg : Data type for a single CAN message . Not to be confused with the 'tMessage' type !
  Used (as 'pointer to tCANmsg') as function argument to pass a received CAN message to a self-defined CAN-receive handler, and (optionally) as function argument for the can_transmit commmand.
  Components of the data type tCANmsg are:
  .id : Combination of bus-number (in bits 31+30), Standard/Extended-Flag (in bit 29),
           and the 11- or 29-bit CAN-ID (in bits 10..0 or 28..0).
  .tim : Timestamp (for received CAN messages, this field contains a precise timestamp filled out by the CAN driver)
  .len : Length of the 'netto' data field in bytes. For CAN messages, only 0 (zero!) to 8 bytes are possible, for CAN FD up to 64.
  .b[0] .. b[7] : Data field as byte array (eight times 8 bits)
  .w[0] .. w[3] : Data field as word array (four times 16 bits)
  .dw[0] .. dw[1] : Data field as doubleword array (two times 32 bits)
  .i32[0] .. i32[1] : Data field as array of two 32-bit integer values, little endian ("Intel")
  .f32[0] .. f32[1] : Data field as array of two 32-bit floating point values, little endian
  .f64[0] : Data field as array of 64-bit 'double precision' floats, little endian (for CAN, only one element)
  .bitfield[ <Bit index of the LSB> , <number of data bits>] : Bit field as in 'can_rx_msg' and 'can_tx_msg'
  
  To simplify communicating via J1939 protocol, the following aliases for parts of the 29-bit CAN ID were added:
  .PRIO: 'Message Priority'. Alias for CAN-ID Bits 28 to 26.
  .EDP: 'Extended Data Page'. Alias for CAN-ID Bit 25.
  .DP : 'Data Page'. Alias for CAN-ID Bit 24.
  .PF : 'PDU Format'. Alias for CAN-ID Bits 16 to 23.
  .PS : 'PDU Specific'. Alias for CAN-ID Bits 8 to 15.
  .SA : 'Source Address'. Alias for CAN-ID Bits 0 to 7, at least for J1939.
  .PGN: 'Parameter Group Number', with up to 18 bits. Alias for 'DP'+'PF'+'PS'.
  
  To simplify communicating via ISO-TP / ISO 15765-2, even more aliases for parts of the 29-bit CAN ID were added.
  Beware: ISO 15765-2 supports an awful lot of different addressing modes, and the following aliases only apply
     to "Normal fixed addressing" (but not "Normal addressing"), and "Mixed addressing with 29 bit CAN identifier" !
  .ID28_26 : Bits 28 to 26 in a 29-Bit-CAN-ID. For ISO-TP with "normal fixed addressing", usually contains 0b110 (binary) .
  .ID25_24 : Bits 25 to 24 in a 29-Bit-CAN-ID. For ISO-TP with "normal fixed addressing" almost always contains 0b00 (binary) .
  .ID23_16 : Bits 23 to 16 in a 29-Bit-CAN-ID. For ISO-TP with "normal fixed addressing, TAtype=physical", contains '218' (decimal).
                    Etc, etc, etc. You see, ISO 15765-2 can be awfully complex.
  .ISO_TA : ISO 15765-2 'Target Address'. Alias for CAN-ID Bits 15 to 8.
  .ISO_SA : ISO 15765-2 'Source Address'. Alias for CAN-ID Bits 7 to 0. Note the surprising similarity with J1939.
  
  If a variable of type tCANmsg, or a pointer to (aka 'the address of') a variable type tCANmsg, is converted into a string, the result may be a string in Vector ASCII Format (depends on CAN.string_format). This can be used for logging a moderate amount of CAN traffic (via script, even in devices without a built-in CAN logger). An example is in the CAN 'ASCII' Logger demo.
  For devices with CAN-FD compatible controllers, the script language also supports the new tCAN_FD_msg type with up to 64 bytes per data field, in contrast to the older tCANmsg where the data field was restricted to 8 bytes (aka "classic CAN").
  
  
• tTimer : Data type for a programmable timer, with the following components:
  .period_ticks : Cycle duration of the timer, measured in 'Ticks' of the timestamp generator
  .expired : >=1 (TRUE) if the timer is expired, otherwise 0 (FALSE)
  .ts_next : Current value of the timestamp generator (system.timestamp) at the next planned expiration of this timer
  .running : >=1 (TRUE) if this timer is currently 'running', otherwise 0 (FALSE). See note further below.
  .user    : A freely useable 32-bit integer value assigned to this timer,
        for example an event counter or an index (see timer event demo)
  The tTimer type is used by the setTimer command, and (passed as 'pointer to tTimer' in the argument list) when periodically calling a timer event handler.
  A timer's "user"-field can also be used to store a pointer to a user-defined data type. This allows accessing user-defined data inside the timer event handler without global variables.
  Note: Trying to start a timer by setting 'timerX.running := TRUE' is meaningless.
            A non-running timer can only be started by calling setTimer.
            Reason: An assignment to 'timerX.running' doesn't reload the timer's counter.
  
  
• tTable : Data type for the graphic display of a 'table' (tabular data) on the screen.
  An instance of a 'tTable' doesn't contain the data shown in the table itself; it merely connects a data source (e.g. array, etc) with a visible control element ("\table").
  Details about tables (as graphic control- or display elements) are in an extra document (table_01.htm).
  
  
• tDirEntry : Data type for reading directories from a file storage (memory card, etc). Details in the chapter about reading 'disk' directories.
  
  

The keyword 'ptr' or '*' (in addition to the data type) allows the declaration of pointers in der script language. In contrast to Pascal (etc), 'ptr' is not a data type itself, but must be combined with other data types, resulting in "typed pointers".

Some of the script language functions may return different data types as their 'return value'. If the caller needs to examine the type of the result, he can use the typeof operator (operating on the returned value), and use a select..case statement to implement different processing for each data type. For this purpose, use symbolic constants like dtFloat, dtInteger, dtString, etc in the case marks; and declare the variable (for the return value) as 'anytype':

• anytype : Placeholder for the data type to declare a variable (or function argument) which can accept 'any type'.
  After assigning a certain value to such a variable, the actual type can be examined with the typeof() operator.
  Example:
  

  
  var
       anytype result;     
  endvar; // end of variable declarations
       ...
       result := cop.sdo(0x1234, 0x01);  // read something via CANopen (Service Data Object)
       select( typeof(result) )  // what's the TYPE OF the returned value ?
          case dtInteger:  // the SDO transfer delivered an INTEGER
             ...
          case dtByte:     // the SDO transfer delivered a BYTE
             ...
          case dtString:   // the SDO transfer delivered a STRING
             ...
          case dtError:    // the SDO transfer returned an ERROR CODE
             ...        
       endselect;
  

Besides the data types listed above, own data types can be defined. Example:

 typedef
   tHistoryBufEntry = // this is the name of a user-defined data type
      struct         // begin of a user-defined data structure
         int iRefNo;     // 1st member: an integer variable
         int iSender;    // 2nd member: another integer
         float fUnixTimestamp;  // 3rd: a floating point variable
         string sInfo;   // 4th member: a string
         int x,y,z;      // 5th to 7th: 3 members widh the same type
      endstruct;     // end of the user-defined data structure
 end_typedef; // alias endtypedef, end of the data type definition

Notes:

• A block of 'typedefs' may define more than one data type; the semicolon is required to separate the entries.
• Types must be defined before they can be used to declare variables. Put all typdefs at the begin of your program.
• using a lower-case 't' as suffix for own type definitions is not mandatory, but recommended to make the script easier to read.
• components within a type definition must be separated with semicolon (a colon doesn't work here) .
• The keyword typedef begins a type definition, the keyword end_typedef (alias endtypedef) ends it.
• The keyword struct begins a structure definition, the keyword endstruct ends it.
• Structures can only be accessed component wise. Copying a complete struct to another as in "C" is not possible (yet?).

Explicit type conversions (typecasts)

In a few situations, it may be necessary to explicitly convert one data type into another.
The syntax of the typecast-operator is similar as in the "C" programming language:
    (<data type name>)<value to be converted>

As an alternative to the 'typecast'-style shown above, explicit type conversion can also be made 'like a function call', using the data type as function name, and passing the to-be-converted value like as argument in parentheses:
    <Data type>( <value to be converted> )
Example from application programs/script_demos/StringTest.cvt :
    s1 := string(n); // default method to convert "anything into a string"
The type converter function returns a type of the same name (here: string).

Caution: If a 32-bit integer value is converted into a pointer, the script runtime system cannot (always) find out if the result is valid. Internally, pointers also contain the type of the object, and the memory class to which they point (code, constant, variables, other data). All this information gets lost when converting a pointer into a 32-bit integer and back !
That's why explicit type conversions with pointers should be avoided wherever possible !

Rules for converting certain built-in data types into strings:

• int: uses the format also used by itoa() (decimal, sign only emitted when negative)
• tCANmsg: Format configurable via CAN.string_format:
  CAN.string_format := sfVectorASC produces a Vector ASC Format compatible string, but without Carriage Return and New Line.
  The timestamp (1st column in a Vector ASC file) can be shifted by CAN.timestamp_offset.
  An example is in programs/script_demos/CAN_ASC_Logger.cvt .
  

Variables

The script language supports local and global variables (more on local vs global in the next chapter).
In addition, the script can also access variables of the display interpreter (defined for the UPT display application).

As in most programming languages, variables should be declared before using them, but this is not necessarily the case (for BASIC-compatibility).

Deprecated (not recommended for new developments): For non-declared 'automatic' variables, the data type was defined by their suffix, like '%' for "integer", '&' for "long integer", '$' for "string", and '!' for floating point.

Again, using 'non-declared' variables is deprecated, and should be avoided. Instead you should declare variables properly (with data type) before using them, as explained in the following chapters.

The directive #pragma strict (in a single line) instructs the compiler to use declared variables only, and reject the 'deprecated' stuff mentioned above with an error.
Rationale: In the past, those 'automatically created' global variables caused hard-to-find bugs, for example if a single character was missing when referencing global variable (a "typo"), the compiler 'automatically' created a second variable (with the name used in the "typo").

Hint for developers:

Global variables can be inspected at runtime by the built-in debugger (values listed in the symbol table) or remotely using the device's embedded web server / 'script' page.
Local variables cannot be inspected that way because they only exist during a function call, and may exist in multiple instances on the stack.

Variable declarations in the script

As mentioned in the previous chapter, any kind of variable should be declared along with its type, prior to using it.

Hint:

With the option '#pragma strict', variables must be declared before being used.

Global script variables

#pragma strict // 'strict' compilation: ANY variable must be declared before being used !

var // global variables (accessable from all subroutines) ...
   int nHistoryEntries;    // declares an integer variable
   tHistoryBufEntry History[100]; // declares an array of tHistoryBufferEntries
    // Note: the indices for an array with 100 entries run from 0 (ZERO) to 99 !
    
 logged: // The following variables may be recorded by the built-in CAN logger:
    // Signals from J1939 PGN 61443 = "Electronic Engine Controller 2" :
    int   AccelPedalKickdown;   // SPN 559  "Accelerator Pedal Kickdown Switch"
    int   AccelPedalPosition1;  // SPN 91   "Accelerator Pedal Position 1"

 private: // The following variables shall NOT be 'logged':
    int   iSomeInternalStuff;
    ...
endvar;

private:

The subsequent variables shall only be accessable inside the script;
they shall not appear in the selection lists for defining display pages,
and they shall not be logged.

public:

The subsequent variables shall be accessable outside the script, too.
The programming tool will include them in the selection list for defining display pages.

logged:

The subsequent variables may(*) be recorded by the logger which is integrated in certain devices.
To end a list of 'loggable' variables, use the attribut 'private:'.

(*)  The 'logged' attribute doesn't mean subsequent variables are always logged.
In addition, the option + script variables declared as 'logged' must be set in the CAN- Logger Configuration to log such variables, besides CAN-messages and GPS data.

noinit:

Variables declared with this attribute shall, if possible, not be automatically initialized when executing a new application via system.exec().
This is only possible with simple data types like int, but not with dynamically allocated types like string, because before the script is compiled, and when initialising the script runtime is (re-)initialized, all dynamically allocated memory blocks are freed.

Local script variables

proc Test
   local int x,y,z; // define three local integer variables
      ....
    print( x,y,z );
endproc  // local variables (x,y,z) cease to exist at this point

See also: Debugging ... Stack Display

Pointers (pointer variables and address operations)

• the manipulation of 'binary data blocks' (which are neither simple array nor described as a structure)
• passing large data blocks 'by reference' (to avoid lengthy and slow block-copy operations)

• use them with caution !
• make sure the pointer's address is still valid when you de-reference ("use") it
• beware that the address of any local variable gets invalid, as soon as the function (in which the local variable was declared) returns to the caller
• thus, only set pointers to global script variables (which remain at fixed addresses throughout their lifetime)

Assigning the address of a variable to a pointer

Passing function arguments (parameters) via pointer

When passing arguments to functions, procedures, or event handlers, pointers are often used instead of passing larger structures directly ('pass by reference' instead of 'pass by value'). The reason is that a pointer only occupies four bytes in memory, thus a pointer can be passed to a subroutine much faster than copying an entire structure in memory. More on this in the chapter about User-defined functions and procedures.

For example, a CAN-Receive-Handler uses a pointer to a CAN message as argument, which actually points to the CAN message in the system's CAN-receive-FiFo, rather than copying the entire CAN message to the stack (i.e. call-by-reference, not call-by-value).

Another example where pointers must be used (in a function's argument list) are the event handlers OnGetCellText, OnGetEditText, and OnSetEditText for the UPT 'table' element, because especially the OnGetCellText event may be fired many thousand times per second, and thus the text is passed as a pointer (not as a huge memory copy, see 'out').

In the argument list of certain commands, the 'addr' can be ommitted (for example, if the compiler knows that the called function always expects 'the address of something').
Experienced "C" developers may use the '&' operator instead of 'addr', for example when calling can_receive or can_transmit (in the CAN gateway demo):

  if (can_receive( &my_can_message ) ) then ...

The above code actually has the same effect as without the ampersand, because the compiler "knows" that can_receive, if used with a function argument list, always expects a "pointer to a CAN message".

Accessing script variables from a display page

Using the prefix "script.", any 'simple' variable in the script can be read or modified by the display application (display interpreter).
For example, when the user presses a button, the button's reaction (a display interpreter command) may set a script variable, which is then polled in the script's main loop to complete the operation (for example, modify a parameter in a CAN-controlled ECU using a self-defined CAN protocol).

Beware: The display application and script are not synchronized per se.
The script runs 'in the background', possibly in a multitasking environment, and the display application 'doesn't know what the script is doing' when it accesses the script's variable). Some of the script examples use this feature to inspect variables on the terminal's screen.

See also:

• Synchronisation between script and display by pausing the display (while the script 'calculates a new set of results')
• Interaction between script and display application : Chapter 3

Accessing display variables from a script

   if ( ! display.Oeldruck.va ) then      
      print( "Oil pressure isn't valid !");
   else if ( display.Oeldruck < 1.2345 ) then
      print( "Oil pressure is too low !");
   endif;
      

• Special components of a display variable (flags, counters, non-scaled "raw value on CAN", scaling parameters, value table, etc.)
• Controlling the programmable display pages from the script (page switching, etc)
• More about interaction between script and display application:
  • Accessing display variables from the script
  • display.GetVarDefinition (access the definition, not the value, of a display variable)
  • Accessing display elements (on the current display page) from the script
  • Accessing script variables from the display interpreter
  • Invoking script procedures from the display interpreter
  • Invoking script functions from display pages (to retrieve a text strings for the display, used for internationalisation)
• Keywords
• Examples
• Overview (of this document)
  

Arrays

Squared brackets (not parentheses!) are used for array sizes, and -later, when accessing the array elements- as the array index.

As already mentioned in the chapter about variable declarations, array indices run from zero to < array-size MINUS ONE > !

Example: 3D-Array, organized in "pages", "lines", and "columns"

var
  int ThreeDimArray[10][20][30];
endvar;
    ...
  z := 1; // "page" index, valid: 0..9
  y := 2; // "line of page", valid: 0..19
  x := 3; // "column of line", valid: 0..29
  ThreeDimArray[z][y][x] := 1234;

Notes on arrays:

• The maximum number of dimensions in an array is THREE.
  Four-dimensional arrays are impossible.
  Arrays of arrays are also impossible, pointers to arrays are impossible, and pointers inside arrays must be treated carefully.
• Certain data types (like strings) are problematic in arrays, because a 'string' is in fact just a pointer to a different memory area.
  Thus, the contents of an array cannot easily block-copied :
  Block-copying an array of strings would only copy their addresses, but would not duplicate their contents (copy characters).
• For that reason, partial array references (as in C) are forbidden.
  Trying to "copy" an entire page (1st dimension of the sample 3d-array shown above) like
     ThreeDimArray[z] := ThreeDimArray[z+1]
  is impossible (at least, as of 2010-10-14) .
• The content of an entire array can be inspected at runtime in the programming tool:
  Enter the name of the array (as a global script variable, without indices) in the Watch List.
• An array of BYTES can be used as a storage for any kind of 'binary' data. The append() command can be used to append strings of characters (without the trailing zero, which is specific for the script language) to such an array.
• When filling an array element-by-element, consider using the '++' operator to increment the index variable:
    TxBuffer[TxByteIndex++] := 0x00; // append a ZERO BYTE to the array
• To pass arrays to functions or procedures without copying elements, use an empty pair of array brackets in the declaration (argument list) after the argument name as in the example shown below. Knowning the array's basic element type (here: byte) and knowing that 'SrcBitmap' is an array allows the compiler to check the syntax. The callee can use the reference (here: "SrcBitmap[]") like an array:

       func DrawSprite( tCanvas ptr pDestCanvas, byte SrcBitmap[] )
            pDestCanvas.drawImage( SrcBitmap );
       endfunc;
  

  Passing arrays this way (by reference, i.e. without copying) consumes very little CPU time. But the callee (called function) can modify the array data, which may not be the caller's intention.
  

Maximum size (capacity) versus momentarily used length (.len) of an array

Other elements of an array-header

Arrays used as FIFO (ring buffer with 'first in, first out'-principle)

Sampling interval and timestamp of the newest array element

<array-name>.t_sample

Sampling interval in seconds. Internally stored as a floating point value (float). The sampling interval (aka sampling period) is the inverse of the sampling rate (sampling frequency), which is more common in digital signal processing.
After a (forward-)FFT, this component contains the FFT bin width in Hertz instead of the sampling interval.

<array-name>.unix_time

Timestamp of the first ("oldest") sample stored in the array, at index zero.
As for system.unix_time, the unit is defined as "number of seconds elapsed since January 1st, 1970, 00:00:00 UTC". Since this value is internally stored as a 64-bit integer in microseconds, the value read from <array-name>.unix_time will always be a multiple of 1e-6. This resolution should be succicient for all sampling rates achievable with an MKT-View (a few kHz).

Examples for the use of arrays

An example demonstrating the use of arrays can be found in the test application "ScriptTest4.cvt" (contained in the installer, subfolder 'programs').
A more sophisticated example using arrays of constants and variables is in the 'quadblocks' demo.
Another example with arrays used for signal analysis (FFT), displayed as diagrams is in application programs/DAQ_Test.cvt.
The application script_demos/diagrams.cvt uses arrays to store polygon coordinates plotted into diagrams.

To efficiently convert byte-arrays into strings, use the constructor string( <byte-array>, <start index>, <length> ). This way, even without slicing the array, a part of the array can be converted into a string. This is typically used when processing data from a receive-buffer (byte array) as strings.

Operators

The script language uses almost the same  numeric operators as the UPT display interpreter (even though the internal evaluation of those operators are totally different - see the chapter about bytecode if you are curious about the details). At the time of this writing (2013-11-08), the following operators have been implemented :

(*) Avoid using a single '=' character as the 'compare-equal' operator. You should also avoid using the single '=' character as the assignment operator.

Suggestion to resolve this ambiguity :

Use ':=' to assign a value (right of the operator) to a variable (left of the operator). This operator is borrowed from PASCAL.
Use '==' to check for equality. This operator is borrowed from the "C" programming language (which also inspired Java many years later).

Without this, the compiler would have to guess if '=' means "assign" or "compare for equality". It usually makes a correct guess, at least in the obvious cases.

In case of doubt about operator precedence, use parentheses. Don't leave anything to fate ! Especially for the bitwise and boolean "AND" and "OR" operators, there are no different precedence levels (there is no "AND" before "OR" as in 'C' yet), so you are forced to use parenthesis in cases like this:

Warning :=  EngineRunning AND (  ( WaterTemp < 5 ) OR ( WaterTemp > 95 )  )

The 'address taking operator' ('&' or 'addr')

Note:

When passing arrays as function argument, address-taking operators are not required, because arrays are generally passed by reference (avoids wasting CPU time).

Increment- and Decrement-Operator ('++', '--')

      j := i++;  // first copy 'i' to 'j', then increment 'i' by one

      j := i;   // copy 'i' to 'j'
      i := i+1; // increment 'i' by one

      TxBuffer[TxByteIndex++] := 0x00;   // append another ZERO BYTE      

User-defined functions and procedures

Procedures should replace the ancient 'gosub-return'-subroutines. Their main purpose is to give a script a cleaner structure, allow parameter passing (through a well-defined argument list after the procedure name), and allow recursive algorithms (by virtue of local variables on the stack). Details about efficiently passing arrays to functions or procedures, see chapter 4.6.
Unlike user-defined functions, procedures do not return a value directly to the caller, and thus cannot be used in expressions.

User-defined procedures

Here is a simple example for a user-defined, recursive (*) procedure which prints a decimal number to the text screen (taken from the TScreenTest example).
Please note the indentation between 'proc' and 'endproc', and use a similar coding style in your own scripts. The compiler doesn't care for these leading spaces, but they make the sourcecode much easier to read.

//--------------------------------------------------------
proc PrintDecimal( int i )
  // Simple RECURSIVE procedure to print a decimal number .
  if( i>10 ) then
      PrintDecimal( i / 10 );    // print upper digits, recursively
  endif;
  print( chr( 48 + (i % 10) ) ); // print least significant digit
endproc; // end PrintDecimal()

Example to call the procedure defined above (explained in the chapter about recursive calls) :

N := 123456;
PrintDecimal( N );  // call user-defined procedure

Internally, shortly before the call of the procedure, the value of N is read, pushed to the stack. The procedure (or function) uses the value on the stack like a local variable. Inside the procedure, 'i' (=name of the local variable, here: function argument) has its own storage location for each new call.
If you're interested in the details: The virtual machine which executes the script code uses a register called BP (base pointer) to access function arguments as well as local variables.

In contrast to the rule 'exactly one line of sourcecode per instruction', the headline of a user-defined procedure or function (~~ 'function prototype' in "C") may extend over more than one line of sourcecode. Example (from the 'TimeTest' demo) :

//--------------------------------------------------------
proc SplitUnixSeconds(
        in int unix_seconds, // one input, six outputs...
        out int year, out int month, out int day,
        out int hour, out int min, out int sec )
// Procedure to split 'Unix Seconds' into
// year (1970..2038), month (1..12), day-of-month (1..31),
// hour (0..23 ! ), minute (0..59), and second (0..59) .


4.8.2 User-defined functions

User-defined functions work almost the same as user-defined procedures. The main difference is that a function returns a value to the caller.
Simplistic example: User-defined function to add two integer values.


//--------------------------------------------------------
func Sum2( int a, int b) // adds two integers, returns the sum
   return a+b;
endfunc;

Summe := Sum2( 1, 2 );   // invoke the user-defined function  


Note that the function header doesn't specify a type for the return value ! The reason is just a future plan:
Script functions may return different types of results, similar to JavaScript (not Java).

In a user defined function, the 'return' command, followed by a value, will return to the caller with the specified value as the function's "result" (aka "return value").

If the program counter reaches the end of a function ("endfunc") without a 'return' instruction, the function returns 0 (zero) as an integer value.

Functions with certain 'special names' can be called as event handlers. In that case, the function call will interrupt the normal program flow (at any point), and the event-handler's return value defines whether the event shall be processed by the system (using the system's default message handler) or not.

You will find other (less simplistic) user defined functions and procedures in the script examples.

Invoking script functions through a backslash sequence from a display page

User-defined functions (written in the script language) can be invoked from a display page, to replace the text in one of the display page's format strings. For the display interpreter, the function call must be embedded in a backslash sequence in a display format string (so the display interpreter recognizes it as a function call, not ordinary text).

Syntax (in the format string of a display line definition):

\script.<function_name>(<arguments>)
where <function_name> is the name of a user defined function (defined in the script language);
 and  <arguments> are the arguments passed to the function. The number of arguments, and their data types, must match the called function - see example below.

Example (for the format string in a display page definition):

\script.GetText(123)
where GetText is the name of a user-defined function, written in the script language, which takes an integer argument (here: a 'text reference number') as input, and returns a string. The maximum string length returned to the display-interpreter this way is 1024 characters (limited by the display's static string types, not by the script language). This example is based on the 'multi language demo' (script_demos/MultiLanguageTest.cvt) :

//------------------------------------------------------------
func GetText( int ref_nr ) // User defined function .
// Returns strings in different languages .
// Input: ref_nr = reference number for a certain text,
//        may run from zero to 9999 .
// Currently selected language in variable 'language',
//    which may be 10000(=LANG_ENG) or 20000(=LANG_GER), etc.
  select( ref_nr + language )
.... 
    case #(123 + LANG_ENG): return "onehundredandtwentythree";
    case #(123 + LANG_GER): return "Einhundertdreiundzwanzig";

....
    else: return "missing translation, ref_nr="+itoa(ref_nr);

  endselect;
endfunc;

Note: Similar as for event handlers, the function invoked from a backslash sequence should return 'as fast as possible' to the caller. Long loops, file I/O, and other slow operations must be avoided. Otherwise the device would appear to be non-responsive (or, from the operator's point of view, "reacts sluggish" or even "crashes"). A watchdog in the runtime system terminates the function call, if the function doesn't return to the caller within a few hundred milliseconds (time specified in the chapter about event handling). This also applies to functions invoked from the display interpreter via backslash sequence, etc. Such a limitation does not exist in the normal script context ("main loop"), due to the pseudo-multitasking. If the maximum time is not sufficient for whatever-your-function-needs-to-do, and if nothing else helps, you can avoid this by feeding the watchdog in the script yourself - but beware of the consequences (sluggish response to user actions, protocol timeouts, etc).

See also: More about interaction between script and display application :

• Accessing display variables from the script
• Accessing script variables from the display interpreter
• Invoking script procedures from the display interpreter

Invoking script procedures from the display interpreter

Definition of a button (in the UPT display application):

\btn($2,"German",60,script.SetLanguage(LANG_GER))

The prefix 'script.' tells the display interpreter that a procedure (or a function) written in the script language shall be called.
In the example shown above 'SetLanguage' is the name of a user-defined procedure, called when the button is pressed.

There a some restrictions of 'what may be done' in a procedure (or function) called from the display interpreter. Most important: The procedure must not block the caller for more than a few dozen milliseconds, as explained for Event Handlers written in the script language. Reason: In contrast to the normal script execution, the display interpreter cannot 'wait for a long time' when updating a display page, or checking for display-events - the system would seem to 'freeze' from the operator's point of view. For details about the maximum time spent in the called function, see system.feed_watchdog.

A complete example can be found in the 'Multi-Language-Test'.

See also: More about interaction between script and display application :

• Accessing display variables from the script
• Accessing script variables from the display interpreter
• Invoking script functions from display pages (to retrieve a text for the display, used a backslash sequence in the display element's format string)
• Event handling in the script language (as a replacement for the 'events' defined in the UPT display pages)

Input- and output- arguments

proc AddInteger( in int A, int B, out int Result )
  Result := A + B;
endproc
...
var
  int N;
endvar;
AddInteger( 1,2, N ); // CALL of the procedure. Output copied to 'N' when returning .

The 'in' keyword was only added for clarity, to emphasize that an argument is NOT an 'output' but 'input' (read-only from the procedure's point of view) .

Note that the parameter passing mechanism for arguments declared with the 'out' keyword doesn't have anything to do with pointers, or 'call-by-reference' as known from other programming languages. In fact, arguments declared as outputs are 'written back' to the variable (from which they were read before the call) by the caller ! This has the side effect that the modified output value does NOT have an effect on the caller's variable until the procedure (or function) returns. In other words, all 'outputs' become effective at the same time --- in the moment the function / procedure returns to caller !

Recursive calls

To understand recursive function calls, look at the PrintDecimal example from a previous chapter again :

proc PrintDecimal( int i ) 
  if( i>10 )
    then PrintDecimal( i / 10 );
  endif;
  print( chr( 48 + (i % 10) ) );
endproc;

In a sample call, PrintDecimal( 123456 ), the first instance is created with i = 123456 (as a local variable on the stack). Because 'i' is greater than ten, the procedure calls itself ( = recursion ! ) with i = 12345 . For the second (recursive) call, a new instance is created, occupying additional stack space. In that instance, 'i' is still greater than ten, so the recusion continues, until 'i' is less than ten (actually, it will be one then, which is the most significant digit, which is printed to the screen first). This results in the following 'call history'  ( -> means "calls", <- means "returns to caller" ) :

PrintDecimal( 123456 )
  -> PrintDecimal( 12345 )
      -> PrintDecimal( 1234 )
          -> PrintDecimal( 123 )
              -> PrintDecimal( 12 )
                  -> PrintDecimal( 1 )
                       (no further recursion; prints "1")
                  <- (procedure returns to the caller)
                 (caller now prints 12 modulo 10 = "2")
              <-
             (caller now prints 123 modulo 10 = "3")
          <-
         (caller now prints 1234 modulo 10 = "4")
      <-
    (caller now prints 12345 modulo 10 = "5")
  <-
 (first instance finally prints 123456 modulo 10 = "6")
<-



Recursive calls can also involve more than one procedure, calling each other. Even though they may be an elegant solution in some cases, their stack usage is hard to predict. So, in many cases, loops and similar constructs (see next chapter) are a better, more 'robust' alternative.

Program flow control

• if..then..else..endif
• for..to.. [step] .. next
• while .. endwile (checks the condition at the begin of the loop body)
• repeat .. until (checks the condition after the loop body, i.e. loop runs at least once)
• select .. case .. else .. endselect
• goto (jumps to a label within the same function ... please forget about line numbers!)
• gosub .. return (deprecated, use procedures wherever possible)
• stop : stops the execution of the script's "main program". Only special calls (from event handlers) are possible after this command.
• end_script : Optional text marker for the "end of the main script". Generates a special bytecode instruction which (at runtime) prevents the program counter from unintentionally running into the first subroutine (procedure or function). If this marker isn't explicity specified, the script compiler will generate it automatically (bytecode instruction inserted before the first implementation of a function or procedure).
  

Note: As in BASIC and IEC 61131 "structured text" (and in contrast to languages like "C" and Java), built-in commands and keywords are case-insensitive. Some users prefer to write keywords in all UPPER CASE. See notes about case-insensitivy and recommended coding style.

In the broader sense, user-defined functions and procedures are also suitable (very suitable) to control the program flow. Since the introduction of procedures and functions, you should not use 'goto', 'gosub' and 'return' in a new appication. They only remain part of the language for backward-compatibility.

if-then-else-endif

Simple example:

      if A<100 then
          do_something_if_a_is_less_than_onehundred ;
           ...               
      else
          do_something_else ;
           ...
      endif; 

In contrast to the rule 'exactly one line of sourcecode per instruction', the condition between if and then may extend over more than one line of sourcecode. This allows complex and nested constructs as presented in the 'examples' section of this document.

To simplify a chain of 'else','if' and 'endif', the 'elif' (else-if) command can be used as in the following example:

      if ( A < 0 ) then
          print( "Negative !");
      elif ( A==0 ) then
          print( "Zero");      
      elif ( A==1 ) then
          print( "One");      
      elif (A >= 2) and ( A <= 3 ) then
          print( "Two to Three");
      elif (A == 5) or (A == 7) then
          print( "Five or Seven");
      else
          print( "Some other value (",A,")" );
      endif; 

for-to-(step-)next

The name of the loop variable (in the above example: 'Loop') after the keyword 'next' may be omitted, but it's recommended to improve readability (especially with deeply nested loops). If the name of the loop variable is specified after 'for' as well as after 'next', the compiler can check if there is a matching 'next' for each 'for'.
When using the option '#pragma strict', the compiler shows a warning if the name of the loop variable is not specified after 'next'.

Optionally, the stepwidth of the index variable can be specified, using the STEP keyword:

for Loop:=0 to 200 step 2
  do_something_a_couple_of_times
next Loop;

If the counter-variable shall be decremented rather than incremented, use a negative STEP value (the compiler cannot use a negative stepwidth automatically, because he doesn't see the start- and end value at compile time). For more examples, study the 'LoopTest' application.

while..endwhile

while <condition>
  <statements>;
endwhile;

Loops while the condition, checked at the beginning of each loop, is TRUE (non-zero) .

Simple example:

I:=0; // make sure 'I' starts at some defined value
while I<100
  I := I+1 ;
  some_other_statements ;
endwhile; // .. or END_WHILE for IEC61131-similarity

Note that the statements inside a while - endwhile loop may be executed ZERO times (if the condition is initially FALSE).

With the condition set to 1 (one, i.e. 'always TRUE'), while(1) .. endwhile forms an endless loop. As in the example from the introduction, this is often used for the 'main loop' in the script. In such cases, the loop speed should be limited by calling wait_ms(50), which means the script waits for 50 milliseconds in each loop, during which the display is updated.
Otherwise, the script would waste a lot of CPU time in the loop.

repeat..until

Loop with a STOP-condition, checked at the end of the loop  (specified after the keyword "until" ).

Example:

I:=0; // make sure 'I' starts at some defined value
repeat
  I := I+1;
  some_statements
until I>=100; 

Note that the statements inside a REPEAT-UNTIL loop are executed at least once !

goto

if divisor==0
  then GOTO ErrorHandler;
  else quot := dividend / divisor;
endif;

  ... some other code in the same subroutine ....

ErrorHandler: // we shouldn't get here...
  Info$ := "Something went wrong"; 
  STOP

gosub..return

Note: Unlike user-defined procedures, stoneage gosub-return subroutines don't have their own stack frame; therefore you cannot define local variables in such subroutines.
Wherever possible, use procedures, and avoid gosub-return (as well as you should avoid 'goto').  'Gosub' only exists for compatibility reason.

select..case..else..endselect

This construct may replace a long nested sequence of if-then-else statements, but only compares INTEGER- OR STRING CONSTANTS in the case-marks.

In contrast to "C", the 'case' construct supports an extended syntax. A complete range of values can be specified as "case <Value1> to <Value2>". The code after that case-label is executed if the select-value is between (and including) 'Value1' and 'Value2'. Thus, "case 4 to 6:" in the following example checks if 'X' is 4, 5, or 6.

Simple example using a bit of pseudo-code ("do_something") :

 X := can_rx_msg.id;
 select X
    case 1 :      do_something_if_X_equals_one();
    case 2 :      do_something_if_X_equals_two();
    case 3 :      do_something_if_X_equals_three();
    case 4 to 6 : do_something_if_X_is_between_four_and_six();
    else   :      do_something_if_X_is_none_of_the_above();
 endselect; 

Important: In contrast to the "C" programming language, there is no 'break' statement required at the end of each case-block, if the case-block is not empty. The program doesn't "fall through" from one case to the next, with the exceptions listed below:

• If there are two or more case marks, with nothing in between (empty case-block with no 'executable instruction'), the first statement after the case-marks is executed.
  Here is a (rather braindead) example:
  select X
  case 1 : // same handler for cases 1, 2 and 3 ...
  case 2 : // with no code between cases, 'fall through' as in "C"
  case 3 : // we could use "case 1 to 3" instead
     print("X = One,Two,or Three");   
  case 4 :
     print("X = Four");   
  else   :
     print("X is less than one, or larger than four");   
endselect;

  
• The keyword 'enter_next_case' at the end of a case-block forces "fall through" into the next case (as the "C" programming does by default):
  

  for A:=0 to 6
     print("A=",A,": ");
     select A
        case 4 :    // "fall through" from one case to the next ..
        case 5 :    // .. only if there is nothing in between
           print("four or five.");
        case 3 :
           print("larger than two, ");
           enter_next_case; // aka 'fall through' to the code after the next case label, as in "C"
       case 2 :
           print("larger than one, ");
           enter_next_case;
       case 0 to 1 :
           print("non-negative.");
       else   :
           print("negative, or larger than five.");
     endselect;
     print("\r\n"); // carriage return + new line (-> nächste Zeile)
  next A;

  Output:
  A=0: non-negative.
  A=1: non-negative.
  A=2: larger than one, non-negative.
  A=3: larger than two, larger than one, non-negative.
  A=4: four or five.
  A=5: four or five.
  A=6: negative, or larger than five.
  

If a case-mark without following executable code shall actually 'do nothing', use the break statement. When used inside a select-endselect block, break actually jumps to the next endselect. Example:

select X
  case 1 :
     break; // do nothing
  case 2 :
     break; // do nothing as well
  case 3 :
     print("X = Three");   
  case 4 :
     print("X = Four");   
  else   :
     print("X is less than one, or larger than four");   
endselect; 

wait_ms  ..  wait_resume

Waits for "something to happen", while the CPU can perform other tasks (like updating the display).

wait_ms( N )

blocks the normal script execution for the specified number of milliseconds (N) .
While the script is 'waiting', the normal display program runs faster because all CPU time can now be used for the display.
Without waiting in the main loop (endless loop), script and display-update would still run side-by-side, but the script's main loop would consume an unnecessarily large amount of CPU time.
Recommended waiting intervals (for the script's main loop) are 10 to 50 milliseconds.
Do NOT call wait_ms() from event handlers and other 'interrupt-alike' functions !
See also: system.timestamp.

wait_ms(0) : Special case to 'give the CPU to someone else', e.g. an event handler.

With a delay of "zero milliseconds", wait_ms() lets the system handle any pending timer event (etc), similar to co-operative multitasking.
The purpose of wait_ms(0) is similar to sched_yield() in Linux, or Sleep(0) in the windows API.
It is intended to be called from the main loop to reduce the latency of timer events. Example:

  while( ! file.eof(fh) )    // repeat until end of file...
      temp := file.read_line(fh); // read next line of text
      ImportFromCSV( temp ); // process text line from CSV (may take some time)
      wait_ms( 0 );          // let event handlers work (co-operative multitasking)
  endwhile;

Note: wait_ms(0) will not wait for a display update (which could consume dozens of milliseconds).

If no timer event is pending, and the previous call of wait_ms(0) is less than 10 ms ago, wait_ms(0) will do nothing.

wait_resume

lets the blocked script continue, even if the interval specified in the wait_ms command has not expired yet.
Because the normal script execution is blocked, the only place where wait_resume makes sense is an event handler.

See also: system.timestamp, Contents, Keyword List, Quick Reference .

Other functions and commands

In addition to the program flow control commands from the previous chapter, the script language also contains functions and commands for special purposes.

Some of them will be explained in this chapter, while others (like the obvious math functions; random; etc) are only mentioned in the keyword list .

See also:  Contents , string processing,  file I/O functions, CAN bus functions, screen output, system functions, date- and time conversions,
               User-defined functions and procedures .

Numeric functions, "Math", and digital signal processing

Simple numeric functions

limit(variable,min_value,max_value)

Limits the value stored in <variable> to the specified range.
This is a shorter and more efficient replacement for the following statements:

         if ( variable <  min_value ) then
              variable := min_value;
         endif;
         if ( variable >  max_value ) then
              variable := max_value;
         endif;
      

random

Returns a pseudo-random number between zero and <N> minus one.

Math.abs(x); Math.abs(x,y)

Returns the absolute value, or (with two arguments) the length of a 2d-vector.
Implements the formula abs(x,y) := sqrt( x^2 + y^2 ) .
Together with Math.atan2, Math.abs is used to convert cartesian into polar coordinates.

Math.atan2(y,x)

Returns the four quadrant arctangent value in radians.
This function is often used to convert cartesian into polar coordinates, without the need for case distinctions of the ancient 'atan' (where only y/x was passed as argument, which was very unpractical). Details at Wikipedia on atan2.

Math.fmod(x,y)

Returns the floating point remainder of x/y.
If both arguments are integers, use the modulo-operator ( % ) instead.

Math.log(x)

Returns the natural logarithm (base 'e') of 'x'.

Math.log10(x)

Returns the base 10 logarithm of 'x'.

Math.pow(base,exponent)

Returns 'base' taken to the power of 'exponent'.
Both inputs, and the return value, are floating point numbers.
Example (from script_demos/MathTest.cvt): f := pow( 2.0, 0.5 ); // actually the square root of two

Math.sqrt(x)

Returns the square root of 'x'.
'x' must be a non-negative floating point number.

Math.sin(x)

Returns the sine of argument (angle) 'x'.
'x' must be a floating point number. The unit is radians (not degrees) !

Math.cos(x)

Returns the cosine of argument (angle) 'x'.
'x' must be a floating point number. The unit is radians (not degrees) !

Advanced math functions for digital signal processing

Math.cfft(input,output)

Forward Fast Fourier Transformation with complex in- and output.
The input may be a array with 256, 512, 1024 or 2048 floating point elements (must be a power of two).
The output must be an array with the same size as the input. Example:

   float  fltFFTin[1024];  // FFT input (complex time domain samples, aka I/Q signal)
   float  fltFFTout[1024]; // FFT output (complex frequency bins)
     ...
   Math.cfft( fltFFTin, fltFFTout ); // Fast Fourier Transform with complex in- and output

If (as in the example) in- and output are simple arrays of type 'float', the complex values are interleaved as follows:
    real part of 1st sample, imaginary part of 1st sample,
    real part of 2nd sample, imaginary part of 2nd sample, ... .
If the input signal had been acquired with 10000 samples per second, the complex FFT in the example shown above would deliver a spectrum with 512 complex 'frequeny bins'. Each bin represents a narrow frequency band, approximately 10000 Hz / ( 2 * 512 ) = 9.8 Hz wide.
See also: Math.rfft (forward FFT with real input), Math.ComplexToMagnitudes, data acquisition .

Recommended reading about the FFT and DSP in general :
The Scientist and Engineer's Guide to Digital Signal Processing by Stephen W. Smith.

Math.rfft(input,output)

Forward Fast Fourier Transformation with real input, and complex output.
The input may be a array with 2^N floating point elements (size must be a power of two).
Even a 'real FFT' produces a complex result (complex spectrum of the input signal) ! For example, a real FFT with 1024 input samples in the time domain produces 512+1 complex frequency bins. With two array elements per complex frequency bin, the output array must be at least the same capacity:

   float  fltFFTin[1024];    // FFT input (real time domain samples)
   float  fltFFTout[1024+2]; // FFT output (complex frequency bins, with 'Nyquist bin')
     ...
   daq.read_channel( 7, fltFFTin );  // read input for the FFT from the DAQ into an array
   Math.rfft( fltFFTin, fltFFTout ); // Fourier Transform with real input, complex output

See also: Suggested reading about the complex FFT and DSP in general.

Math.ComplexToMagnitudes(input,output,reference)

Converts an array with complex value pairs (typically the output from an FFT, i.e. complex spectrum) into "Decibels" of any flavour. The 'reference' value (scalar) can be used to adjust the 'dB' output to include the gain of a sensor (e.g. sound pressure level), and to compensate the FFT 'gain' (which depends on the FFT length as explained further below).
In the 'DAQ-Test' application (programs/DAQ_Test.cvt), this function is used to convert a complex spectrum into dBfs (*) for a combined spectrum/spectrogram display in a diagram with background image:

   ...
   Math.rfft( fltFFTin, fltFFTout ); // forward FFT with real in- and complex output
   ref := 32767.0 * C_FFT_SIZE;      // reference for 0 dBfs (*) from 16-bit A/D converter
   Math.ComplexToMagnitudes( fltFFTout, fltLogSpectrum, ref ); // logarithmize spectrum (-> dB)

(*) dBfs : "decibel over full scale"

0 dBfs is the magnitude where the peaks of a single, pure sine wave would just touch the clipping point at the input of the A/D converter (here, a 16-bit converter with an output range of +/- 32767 - thus the left factor in the reference value).
A pure sine wave with amplitude A, fed into a FFT with <C_FFT_SIZE> samples in the time domain, will give a peak in the frequency domain of A * C_FFT_SIZE (!) - thus the second part (factor) in the reference value.

For each complex value pair (re,im) in the input, Math.ComplexToMagnitudes() performs this operation :
output[i] := 20 * log10( sqrt( re^2 + im^2 ) / reference );   // principle - not the implementation

Timers and Stopwatches (in the script language)

Timers to fire events or periodic intervals

      var
        tTimer timer1;  // Declare an instance of a timer as a global variable of type 'tTimer'
      endvar;
         ...
      setTimer( timer1, 200 ); // Start 'timer1' for a 200-millisecond interval,
                               // here without a timer event handler
         ...
      

      if ( timer1.expired ) then
        timer1.expired := FALSE;  // clear the 'expired' flag; will be set again 200 ms later
        system.beep( 1000, 1 );   // short beep (1000 Hz, 1 times 100 ms duration)
      endif;
      

StartStopwatch / ReadStopwatch (simple interval-polling 'stopwatch' timers)

In some cases, the timer described in the previous chapter (using setTimer( tTimer ) ) is certainly 'Overkill'.
If all you need is measure the time (in milliseconds) between to actions (or script operations), with out firing events, you can use a simpler alternative described below.
It works like simple old-fashioned stopwatch on a running track:

• when the runner passes the start point, start the stopwatch. In the script: call StartStopwatch();
• when the runner reaches the track's end, read the time from the stopwatch: ReadStopwatch_ms() returns the number of milliseconds.
  (a stopwatch doesn't need to be "stopped" just to read it - in contrast to a bulky dot-net-component, we can read it on-the-fly)

• by calling StartStopwatch( < Integer-Variable > ), the current value of the timestamp generator (system.timestamp) will be copied into the specified value (passed in 'by reference', i.e. address).
• when calling ReadStopwatch_ms( < Integer-Variable > ), the system first calculates the difference between the current timestamp generator value and ("minus") the value stored in the integer variable, and converts it into milliseconds.

 var
   int MyStopwatch;  // Declare a simple (but global) integer variable
 endvar;
    ...
   StartStopwatch( &MyStopwatch );
   Do_Something();
   if( ReadStopwatch_ms( &MyStopwatch ) > 500 ) then
       print("Surprise: 'Do_Something()' took over 500 milliseconds !");
   endif;
    ...

print, gotoxy, cls & Co (output into a multi-line text panel)

The following commands can be used to display text on a multi-line text panel (on any of the programmable display pages, using a "\panel" element in the display page definition).

cls : "clear screen"

Here: Clears the contents of the text "screen" buffer. Precisely, the buffer is filled with space characters, and all cells are set to the current foreground- and background colour. The script doesn't have direct access to the (graphic) video RAM.

clreol : "clear to end of line"

Clears the rest of the current text buffer line, beginning at the current output cursor position. The cursor position itself is not affected by this command.

setcolor(foreground,background) : Set the drawing colours for following text output into the text buffer.

Sets the colour for subsequent calls of print, cls, and clreol. You should not use numeric colour values (because the colour codes may be hardware dependent), but any of the colour-constants listed here, or use rgb to compose a colour.
If any of the two colours shall not be modified, pass a negative value as function argument (e.g. -1 = "don't modify").

rgb( red, green, blue ) : Function to compose a colour from three components.

Besides the colour constants (like clBlack, clWhite, etc), this is the only recommended method to define colours in your script program. The value range for each of the three colour components is 0 to 255, regardless of the display's actual number of "bits per pixel". Depending on the display's colour model, not all of the 2 ^ 24 possible colour combinations can be exactly realized ! In such cases, the firmware will try to pick the 'best possible' colour.
Don't assume anything about the format of the colour returned as tColor by the RGB function - it's hardware dependent ! The 'Loop Test' application uses rgb() to produce a colour pattern in a text panel.

gotoxy(x,y) : sets the text output cursor into column 'x', line 'y'.

The first argument is the zero-based 'X' coordinate (text column, ranging from 0 to 79), the second argument ('Y') is the text line number (ranging from 0 to 24).
For example, gotoxy(0,0) will place the text output cursor in the upper left corner of the text screen / text panel.

print : prints a list of values (numeric and/or strings) to the text screen / text panel.

The output cursor position (X) will be incremented for each printed character. If the cursor reaches the end of a line, it wraps to the next.
To 'print' more than one value in a single call, separate the values in the argument list with commas, as in this example:
print("\nResults A,B,C = ",A," ",B," ",C)
(Remember: backslash-n in a string constant means "new line").
For numeric values (integer or float), print always uses the shortest possible notation, without leading zeroes. If you want fixed lengths, or leading zeroes (as in date and time displayed on the screen), use the itoa function (integer-to-ascii) to convert the numbers into strings with leading zeroes and a fixed width. Example (from 'TimeTest.cvt', shows a calendar date in ISO 8601 format) :
print( itoa(year,4), "-", itoa(month,2), "-", itoa(day,2) );

tscreen : wrapper object for the 'text screen buffer'.

tscreen.cell[Y][X]

accesses the character cell in the Y-th line, and X-th column of the text screen buffer as a tScreenCell structure.
Most built-in fonts use DOS-compatible character sets from 'codepage 437' so the text screen has limited graphic capabilities - see TScreenTest example !

tscreen.cell_width

Width of a single text cell in pixels, as currently rendered on the screen.

tscreen.cell_height

Height of a single text cell in pixels, as currently rendered on the screen.
If a display page was automatically scaled for a new screen resolution,
cell_width and cell_height may be different from the 'designed' values.

tscreen.cx

returns the text output cursor's current 'x' coordinate (zero-based column index).

tscreen.cy

returns the text output cursor's current 'y' coordinate (zero-based line index).
tscreen.cx and cy are read-only. To modifiy the cursor position, use gotoxy(column,line) .

tscreen.cs

Cursor Shape / Cursor Style. Defines if and how the text output cursor shall be displayed.
The script can use a bitwise combination of the following constants for this purpose:
csOff (Cursor off; default), csUnderscore, csSolidBlock, csBlinking.
The VT100 Emulator example uses this feature to emulate an old-fashioned virtual terminal's cursor display.

tscreen.xmax

returns the max. allowed 'x' coordinate of the text buffer (column index).
tscreen.xmax is also writeable - see details in tscreen.ymax !
The default value of tscreen.xmax is 79 (i.e. 80 characters per line, indexed 0..79).

tscreen.ymax

returns the max. allowed 'y' coordinate of the text buffer (line index).
Per default, tscreen.xmax is 79, and tscreen.ymax = 39; but the 'geometry' of the text screen buffer can be adjusted (within certain limits) by assigning new values to tscreen.xmax (first) and tscreen.ymax (second). Most devices are limited to the following values:

• tscreen.xmax must not exceed 99 (i.e. up to 100 characters per line)
• The product of (tscreen.xmax+1) * (tscreen.ymax+1) must not exceed 8000
  (because the text screen buffer was limited to 8000 tScreenCell elements in 2013-03-20)

When modifying the 'geometry', first set the lower of the two dimensions (usually tscreen.xmax), so the product never exceeds the maximum. Example:
  tscreen.xmax := 39; // only need 40 characters per line (index 0..39), but..
  tscreen.ymax := 99; // 100 lines (0..99) in the text screen buffer !
Note that (unlike the two functions below), tscreen.xmax and tscreen.ymax do not depend on the visible text panel element on the current display page .

tscreen.auto_scroll

This flag can be set to TRUE by the display application to enable automatic scrolling of the text screen buffer, whenever tscreen.cy exceeds tscreen.ymax .
By default, automatic scrolling is disabled (tscreen.auto_scroll := FALSE), which causes excessive lines to get lost (not printed into the text buffer at all).
An example for an automatically scrolling text panel is in the Internet demo application.

tscreen.vis_width

Returns the currently visible width (in characters) of the text screen, which depends on the size, borders, and font of the first visible text panel element on the current display page. For example, if the text panel is 320 pixels wide (without borders), and uses an 8-pixel wide fixed font, the visible width of the text screen will be 40 characters.

tscreen.vis_height

Returns the currently visible width (in characters) of the text screen, which depends on the size, borders, and font of the first visible text panel element on the current display page. For example, if the text panel is 240 pixels high (without borders), and uses a 16-pixel wide fixed font, the visible width of the text screen will be 15 characters.
The 'QuadBlocks' demo uses this function to automatically adjust the size of the 'playing field' (actually a text panel) to the size of the screen, if the application (which was designed for a 320*240 pixel screen) is loaded into a device with 480*272 pixels.

tscreen.scroll_pos_x,
tscreen.scroll_pos_y

Contains the current horizontal and vertical scrolling position for the display of the 'virtual' text screen on a text panel.
With tscreen.scroll_pos_x=0 and tscreen.scroll_pos_y=0, the upper left corner of the text panel will show the character in the first column (x=0), and the first line (y=0) of the virtual text screen (text buffer). An example for the usage of the scroll position can be found in the application 'ScriptTest3.cvt', function 'ScrollIntoView'. By calling the user defined function 'ScrollIntoView' in that demo, the last line 'printed' into the text buffer is made visible, by bringing the scroll-position close enough to the current cursor position. By virtue of a bargraph with 'write access', the vertical scroll indicator can even be used as an interactive control element to scroll the text manually (as far as the size of the screen buffer permits).

tscreen.modified

is TRUE as long as the screen buffer has been modified, but not updated on the LCD yet.
The script can set it ( tscreen.modified := TRUE ) to let the system redraw the (text-) screen as soon as possible, for example after modifying the screen buffer with the tscreen.cell property. The system will automatically clear this flag when a text-screen-update is 'done'. This function is also used in the TScreenTest example to force an update of the screen, and to find out if (and when) the screen has been updated.

Note:

The output will be 'printed' into the text buffer for a multi-line text panel. If no such panel is visible on the current display page, you will not see it on the screen immedately. But despite that, the text will become visible (immediately without further print-calls) as soon as the display program switches to a page which contains a 'Multi-Line Text Panel'.
In the programming tool, the contents of the text screen buffer can be displayed in der right half of the Script tab. In the combo box in the upper right corner, select 'Show buffer for Text Panels' instead of 'Hide debug view'.

To create such a text panel (in the definition of one of your display pages), enter the backslash sequence panel in the format string column on the display page definition tab, or change the type of an already existing display line from 'Text' (which means a single-line text display) to 'Multi-Line Text Panel'.

Definition of a text panel on a display page

The colour of the character cells inside the text panel is controlled by the script, not by the display page definition. Each character can have its unique foreground- and background colour. The sample application 'LoopTest' contains an example which uses foreground- and background colours composed with the rgb() function. The example 'TScreenTest' uses the text array as the 'playfield' for a simple video game ('snake' moving on the screen, controlled via cursor keys), which requires read- and write-access to the characters in the text buffer, without modifying the colours.

See also: multi-line text panel in the display page definitions (external link, only works in the HTML-based help system, not in a PDF document).

Canvas functions (painting on a tCanvas)

Rudimentary 'canvas' painting functions were already implemented at the time of this writing, but still in an early state - too early to be described here.
Please check the online version of this file for the most recent information about painting on a canvas.

Objects of type tCanvas must be declared as global variables, i.e. between var and endvar in the script. Only in that case, they will be recognized by the programming tool, and their names listed where applicable (e.g. as background image in diagrams and similar display elements.
Example from application 'DAQ-Test.cvt', where a tCanvas (name "spectrogram") is used as a diagram's background image:

var
   tCanvas spectrogram; // graphic time / frequency representation of spectra ("waterfall")
     ...
endvar;

Pixel-wise access (tCanvas method)

   for y:=0 to spectrogram.height-1  // spectrogram: variable of type tCanvas
      for x:=0 to spectrogram.width-1
          spectrogram.pixel[y][x] := rgb(x,y,x+y);
      next x;
   next y;

Filled rectangle (tCanvas method)

Horizontal scroll (tCanvas method)

Vertical scroll (tCanvas method)

   xmax := spectrogram.width-1;  // spectrogram: variable of type tCanvas
   ymax := spectrogram.height-1;
   spectrogram.vscroll( 0,0, xmax, ymax, 1/*scroll DOWN by one pixel*/ );

File I/O functions

... are only implemented on systems with a suitable hardware - not necessarily a memory card slot, because the file I/O functions can also access other media (for example, a ramdisk in some devices, or a part of the built-in data FLASH memory in other devices). All file access functions begin with the keyword 'file.' to avoid namespace pollution. The file I/O functions in the script language may have to be unlocked before use (at least on devices like MKT-View II).

File I/O function overview (follow the links for details) :

• file.create(name, max_size_in_bytes) : creates a new file with the specified name (for write access)
• file.open(name, o_flags) : opens an existing file (only for read access)
• file.write(handle, data) : writes data to a file
• file.read(handle, destination_variable) : reads data from a file (usually 'binary')
• file.read_line(handle) : reads a line of characters from a text file, and returns it as a string
• file.seek(handle, offset, fromwhere) : sets the file pointer
• file.eof(handle) : checks for end-of-file
• file.close(handle) : closes a file, and releases the file handle .
• file.size(handle) : returns the size of an opened file, measured in byte.
  
• file.delete(name_or_pattern) : Deletes file(s) in certain volumes, e.g. file.delete("ramdisk/*.*").
  
  
• directory.open(path_and_mask, options) : Opens a directory to read it. Returns a handle when successful.
• directory.read(handle, dir_entry) : Reads the next entry from an opened directory. Returns TRUE when successful.
• directory.close(handle) : Closes the directory after reading it. Don't forget !
  
  

Don't miss the notes on the pseudo-file-system about restrictions of writing and deleting files, and how to simulate the pseudo-file-system in the programming tool.
See also: 'File Test' demo (uses most of the file I/O-functions listed above).

Most of MKT's programmable devices don't really support subdirectories or "folders". Many devices don't even have a memory card interface built inside. Despite that, some of the internal memory (FLASH ROM and/or RAM) can be accessed like a file storage medium ("disk volume"). The principle of pseudo directories is the same as used for the file transfer. In fact, files created this way can be accessed through the file transfer utility or via embedded web server :

• "font_flash"
  This is another onboad FLASH memory chip (not a FLASH memory card) used to store user defined fonts (*.fnt), but it can be used to store a few other files, too. When creating a file in this directory, the maximum expected size must be specified in the 2nd argument of the file.create function. When closing the file again, unused FLASH sectors will be available for other files again. This also applies to the other "..._flash"-folders listed here.
• "audio_flash"
  Yet another onboard FLASH memory chip (not a FLASH memory card) used to store audio files (*.wav), but it can also be used to store a few other files.
  Note: In a few devices which support audio output, but don't have an extra FLASH chip to store the digitized audio, the contents of the 'font_flash' and 'audio_flash' directory may physically be the same. Files placed in this directory can be played back using the interpreter command 'audio.play' .
• "data_flash"
  This is an internal FLASH memory chip (not a FLASH memory card) used for internal data storage (display pages, imported bitmaps, etc).
  Except for an upload of a single *.upt or *.cvt file (via a modified YMODEM-protocol), this directory is not accessable.
• "memory_card"
  This pseudo-directory can be used to access the removable memory card. If this entry is missing in the pseudo root directory, the device (or firmware) doesn't support such a storage medium. The contents of the 'memory_card' folder will be empty if no card is inserted, or the card's file system is not supported.
  In the programming tool, the device 'memory_card' is simulated by default as a subdirectory named 'sim_mc' (simulated memory card) on the local harddisk. The path to that device is configurable.
• "ramdisk"
  This pseudo-directory can be used to store temporary files, for example bitmap files which may be displayed on the screen without permanently saving them in FLASH memory. When creating a file in this directory, the maximum expected size must be specified in the file.create function. The ''File Test' demo uses this pseudo-disk-drive to create a text file, write a few lines into it, close it, open it for reading, and read back the lines which had previously been written. Note that all files in the 'ramdisk' get lost when the device is turned off, or switched into power-down mode.
  When simulating a device (with RAMDISK) in the programming tool, the RAMDISK is emulated internally - it is not mapped into the host's (PC's) own file system ! To check the contents of the RAMDISK during a simulation, select this entry in the tool's main menu:
    View .. Simulated file system .. RAMDISK .
  

In addition to the storage media listed above, the following devices may be accessed like files (whether they exist depends on the hardware):

• "serial1"
  Allows accessing the device's first serial port (RS-232) like a file; at least for read- and write operations.
  In rare cases, the script may need to change the serial port settings when opening it. This can be achieved by appending a string with the port settings after the pseudo-devicename, for example:
       hSerial1 := file.open("serial1/9600"); // try to open 1st serial port, and configure it for 9600 bits/second .
  Other examples for accessing the serial port(s) from the script language can be found here ("GPS Simulator").
  Like all other 'extended' script functions, accessing the serial ports (through the file I/O functions) is only possible if the 'extended script functions' (auf deutsch: "Erweiterte Script-Funktionen") have been unlocked !
  If a serial port is used as a LIN bus interface, then it should not be accessed 'like a file'. Instead, to transmit and receive LIN frames, use the CAN-bus-API (Application Interface). Details in the LIN bus documentation.
• "serial2"
  Similar for the second serial port (if such a port exists, otherwise file.open("serial2") will return zero, which is an illegal handle value.
  An example for accessing this particular port from the script language can be found here ("GPS Simulator").
  In the 'MKT-View II', the second serial port is a dedicated port for a GPS receiver.
  This is not a standard RS-232 port ! Do not try to connected it to the PC with a standard 9-pole "Null-modem cable" ! You may damage your PC, because the 9-pole GPS connector feeds the supply voltage into the external GPS receiver ! Refer to the hardware manual for details, or (if you are unable to find the hardware manual), look here (pinouts of a few 'serial port' connectors).

Important Notes on the Pseudo File System (PFS)

The PFS is not a normal file system (not FAT, NTFS, ext2,3,...) . Except for the "memory_card" device, each file is stored as single contiguous block on the storage medium, so they can be directly accessed via pointer by the CPU - without the need to copy them, sector by sector (at least for read access).
For that reason, certain operations (which you may know from a 'normal' file system) are impossible here:

• For FLASH files, the expected file size must be specified upon creation .
  It may be closed with a 'shorter' size later, but the file cannot 'grow' larger than the pre-allocated size while writing.
• Write-operation is only possible for 'new' files (i.e. after file.create, not after file.open)
• Deleting a single file may be possible, but due to the large FLASH sector sizes (64 kByte or even 128 kByte), the space occupied by the file cannot be freed, because there may be multiple files stored in a single FLASH sector (much in contrast to a normal file system, where each file occupies at least one (disk-) sector of 512 bytes).
• Deleting a single file in a RAMDISK cannot move the other files in memory (because other files may be accessed via pointer for reading, as explained above). Deleting a single file in a RAMDISK (without re-formatting the RAMDISK) is only possible if that file is still the last file written to the disk.
  For this reason, delete temporary files which your script may have created on the ramdisk as soon as possible. Deleting it 'too late' will not free the memory.
• Remember that the RAMDISK is not battery-buffered: It will automatically be reformatted whenever the system is booted, and all files in it will be lost !

To simulate the various STORAGE MEDIA in the programming tool, real 'disk files' are used. The directories ("folders") used for those files can be configured on the 'Settings' tab in the programming tool. Double-click into the table to open a file selector if you need to change these entries:

Directiories for the simulation of storage media in the programming tool

For example, to access files in the "audio_flash" folder, copy the required files into that directory, or change the directory location (inside the programming tool) to the place on your harddisk where the program tool can find the files.
It is very advisable that while developing your application, you make a list of all files which your application may need later (during runtime on the "real target"). Such files may include (but are not limited to) the following:

• The display application itself (*.cvt or *.upt)
• user-defined fonts (*.fnt)
• bitmaps (*.bmp) which your application may load from a storage medium, i.e. from one of the pseudo-file folders (not the "normal" bitmaps, which are imported in the programming tool, because those icons will be saved and transferred along with your *.cvt or *.upt file)
• audio files (*.wav)
• text files (*.txt) in different languages. For example, see the 'MultiLanguageTest': In that application, the script reads the texts from an external file, to separate the display program and the displayed text strings.
  

Remember to backup and distribute all those files along with your application !

file.create(name, max_size_in_bytes) : creates a new file with the specified name (for write access)

If the file already exists, it will be overwritten. If it doesn't exist, it will be created, with an initial length of zero.
The second parameter ('maximum size in bytes') is used for files in the RAMDISK, to pre-allocate the maximum required file size in advance. This avoids fragmentation, if multiple writeable files are opened simultaneously. When successfull, the function returns a positive 'handle' (= an integer value which identifies the file).
Otherwise, the function returns a negative error code.
The filename may contain a pseudo-directory to specify the storage medium.
The parameter 'max_size_in_bytes' (maximum expected size of the file, measured in byte) must already be specified when creating the file, to avoid fragmentation of the storage medium (see notes about the RAMDISK).
Example to create and write a small file in the RAMDISK, with minimum error checking :
  var
    int fh; // file handle
  endvar;
  fh := file.create("ramdisk/test.txt",4096); // max 4096 bytes
  if( fh>0 ) then   // successfully created the file ?
    file.write(fh,"First line in the test file.\r\n");
    file.close(fh); // never forget to close files !
  endif;


file.open(name [, o_flags] ) : opens an existing file or a device

When successful, the function returns a positive 'handle' (= an integer value which identifies the file or device).
Otherwise, the function returns a negative error code.
Depending on the storage medium, some (not all, depending on the medium) of the following optional 'open flags' are supported:

• O_RDONLY : Open for read-only, i.e. the file can only be read but not written. Works on all media.
• O_WRONLY : Open for write-only, i.e. the file can only be written but not read. Not supported yet.
• O_RDWR : Open for read- and write access. At the moment (2011-09), doesn't work with FLASH memory !
• O_TEXT : Open the file as a text file, and check for a BOM (byte order mark) to find out the encoding-type automatically.
  
• O_CREATE : If the to-be-opened file doesn't exist yet, create it. UNIX purists may use the glorious abbreviation 'O_CREAT' instead of 'O_CREATE'.

Regardless of the file-open mode (O_RDONLY, O_WRONLY, O_RDWR, O_TEXT, O_CREATE), the file pointer will be set to the begin of the file. This behavious equals the _rtl_open command, which may be familiar for 'C' developers. To append new data at the end of an existing file (after re-opening it), the file pointer must be set to the end of the file, before writing data to it. Use the function file.seek for this purpose.

Example to open a text file, read it line-by-line, and dump the lines to the screen:
  var            // declare global variables: 
    int fh;      // an integer for the file handle
    string temp; // a string named 'temp'
  endvar;
  fh := file.open("ramdisk/test.txt",O_RDONLY | O_TEXT);
  if( fh>0 ) then // successfully created the file ?
    while( ! file.eof(fh) )
      temp := file.read_line(fh);
      print( "\r\n ", temp ); // dump the line to the screen
    endwhile;
    file.close(fh);
  endif;


After successfully creating or opening a file, the file's handle (integer value returned by file.create or file.open) can be used to write to, or read from the file.
The following script functions can be used for this purpose.

file.write(handle, data): writes data to a file

In most cases, 'data' will be a string, one or more a string variables, or a string expressions.
(In fact, binary data are not supported yet, because they always turn into a nightmare because you need to worry about the host's endianness aka "byte order", different storage formats for all kinds of data types, etc etc - so forget about binary files for a while).
An example for the file.write function can be found under file.create .

file.read(handle, &dest1, separator1, &dest2, ...) : reads structured data from a file

The file.read function can read one or more data fields from a file (in a single call). Compared to file.read_line, it's more complex, but very flexible. When successfull, it returns the number of data bytes read from the file. The format (structure) of the data in the file can be specified by the function's argument list. Each datum (singular of data) must be passed by reference (preferrably with the address-taking operator & as prefix before the variable name), e.g.:
    nBytesRead := file.read(handle, &sName, ",", &sAddress,",", &sInfo,"\r\n" );
Constant strings between the names of the to-be-read variables are interpreted as 'separators' between data fields.
Alternatively, to read files with fixed field widths, those widths can be speficied in the function call after the name of the variable to which the width applies, separated by colon in the argument list. Example:
    nBytesRead := file.read(handle, &sName,20, &sAddress,40, &sInfo,"\r\n" );
In the above example, the string-variable 'sName' will be read with a fixed width of 20 characters (bytes), and 'sAddress' with 40 characters. The rest of the text line (up to the separator "\r\n", which means Carriage Return + New Line) will be stored in variable 'sInfo'.
For strings read from a file, it's sometimes necessary to restrict the character set to certain classes of characters. This can be achived in the argument list of file.read by appending the following tokens (beginning with a colon) directly after the name of the string-variable with restricted character set:

• :NAME
  Valid characters are A..Z, a..z, '_' (underscore), and -except for the first character in the name- the digits '0' to '9'.
  Spaces and control characters like Carriage Return (\r) and New Line (\n) are not allowed.
• :NUMBER
  Valid characters are only the digits '0' to '9', the decimal point ('.'), and the character 'e' or 'E' which indicates the exponent (in scientific notation like 472.5e3).
  

Simplified excerpt from the INI file demo, to read test file IniDemo1.ini :

        if( file.read( handle, "[", sSection:NAME, "]", "\r\n" ) > 0 ) then 
           // entered a new SECTION in the INI file :
           // ..
        elif( file.read( handle, sKey:NAME, "=", sValue, "\r\n" ) > 0 ) then
           // successfully read a key=value pair from the INI file :
           select (sSection) 
              case "FileInfo" :     // ..
              case "SensorConfig" : // ..
              case "CAN1Setup":     // ..
              // ... 
           endselect;
        elif( file.read( handle, sGarbage, "\r\n" ) > 0 ) then 
           // successfully read a line with "something else" (possibly an EMPTY line) :
           // ..
        else // didn't read anything so guess we reached the end of the file:
           file.close( handle );
           return TRUE;
        endif;

Explanation of the above example:

With the three calls of file.read(), all possible syntaxes of a line in an INI file are 'tried'. Only one of those three calls will return a positive result, when reading an INI file line-by-line (loop not shown here).
The third call ( file.read( handle, sGarbage, "\r\n" ) ) will 'skip' any line which fits neither a section header [Section-Name] nor <Key>=<Value> .
Because the character set for variable 'sKey' is restricted to 'NAME', 'sKey' will only contain single names, but not multiple lines like the comment lines which may be placed anywhere in an ini file.
Reason: Comment lines (in INI files) begin with a semicolon, which is not a valid character for a 'NAME'. Without this precaution, the variable 'sKey' might be filled with data read from multiple lines, up to the first "=" (separator between 'key' and 'value').

In each call of file.read, a maximum of 2048 bytes can be read (parsed) from the file. Each call of file.read is either completely successfull or won't read (skip) anything from the file at all. This feature is used in the example explained above to tell comment lines, section header lines, and data lines from each other.

Complete examples for the file.read function can be found in the 'VT100-Emulation' and in the INI-file reader application.

file.read_line(handle) : reads a line of characters from a text file (or a serial port), and returns it as a string

An example using 'file.read_line' can be found under file.open .
To read the lines of a text file line-by-line, you should open the file with the O_TEXT flag as explained in the file.open command,
because strings read from a file read that way will have the proper character encoding type ( ceDOS, ceANSI, or ceUnicode ).

file.eof(handle) : checks for end-of-file

Returns FALSE (0) as long as the end of the file has not been reached yet,
and TRUE (1) when the end-of-file has been reached (for example, after file.read_line has read the last line of a file).
An example using 'file.eof' can be found under file.open .

file.seek(handle, offset, fromwhere) : sets the file pointer.

'offset' is the absolute or relative file position, measured in bytes.
'fromwhere' (aka 'origin') specifies the meaning of 'offset'. This parameter may be one of the following constants:

• SEEK_SET   Position file relative to the beginning (offset 0 = first byte in the file)
• SEEK_CUR   Position file relative to the current position
• SEEK_END   Position file relative to the end (offset 0 would be the end of the file)

The value returned by file.seek indicates the new, absolute file pointer, measured in bytes from the beginning.
For 'SEEK_END', the offset may be zero (i.e. warp to the end of the file) or negative ! Positive offsets in combination with 'SEEK_END' would reference a position past the file's end, which is illegal.
An example using 'file.seek' is in programs/script_demos/FileTest.cvt .

file.close(handle) : closes a file, and releases the file handle .

An example for the file.close function can be found under file.create .
Never forget to close files ! Especially after a file has been 'written' but not been closed yet, there may be data waiting in an internal buffer which have not been flushed to disk yet. Closing the file will flush all buffers, and (if it's a "real disk file") update the directory and the FAT (file allocation table).

By default, text files are assumed to be 'plain text with 8 bits per character'. Esoteric formats like *.doc or *.docx are not, and never will be, supported. When specficying the O_TEXT flag in file.open(), the runtime library will examine the file for a so-called Byte Order Mark (BOM), to find out if the file's encoding types automatically (and skip the BOM, so the BOM will not be read by the first call of file.read_line) :

• UTF-16 with big-endian byte order (BOM = 0xFE, 0xFF)
• UTF-16 with little-endian byte order (BOM = 0xFF, 0xFE)
• UTF-8 (BOM = 0xEF, 0xBB, 0xBF, not really a byte order mark in this case)

If the file contains Unicode text (in one of the encodings listed above), the strings returned by the file.read_line function will be re-encoded as UTF-8 (not UTF-16 !).
For more info about the byte order mark in text files, see Byte order mark on Wikipedia.

To retrieve a list of files on the memory card (or similar storage media accessable via ), the following functions were added in the script language (2015-03):

directory.open( string path_and_mask)

Opens a directory for reading. Returns a positive handle (integer value) when successful.
Don't assume anything about the value of the handle - just store it in an integer variable and use it in subsequent calls of directory.read().

directory.read( int handle, tDirEntry *dir_entry)

Reads the next entry from an opened directory.
The second argument must be a pointer to a tDirEntry (see example further below).
Returns TRUE when successful.

directory.close(int handle)

Closes the directory after reading it, and frees resources. Don't forget !

Reception and Transmission of CAN messages (via script)

Note: Not all programmable terminals support the reception of 'raw' CAN messages (or LIN frames) as explained in this chapter.
Devices with CANopen do not support the functions mentioned below (except CAN.status, which is always available) .
The CAN functions in the script language may have to be unlocked before use (on devices like MKT-View II,III,IV).

  Overview with the most important CAN functions : can_add_id, can_receive, can_transmit .
Use the command can_add_id or CAN.add_filter to register some CAN- or LIN-bus identifiers for reception through the can_receive function (or via CAN-receive-handler).
For LIN (instead of CAN), bitwise OR the mask cCanIdBit_LIN to the message identifier. Besides that, the treatment of LIN frames is almost identical to the treatment of CAN messages throughout this document.

After registering CAN messages (or LIN frames) for reception, you can use the can_receive function to poll for messages waiting in the FIFO, and to read the next message from the FIFO.
If can_receive returns TRUE, it has read another message (aka "telegram") from the FIFO, and copied it into a global variable (structure) named can_rx_msg where your script can process it.

CAN reception via polling or events

can_add_id( [bus=N,] <CAN-ID> [,handler] ) : Register a CAN message ID for reception

Adds the specified CAN message identifier to an internal list (in the CAN driver), so it will be received from now on, and put in the script's CAN receive FIFO.
The script program only receives such messages with the can_receive function. CAN-Messages which are *not* registered for reception this way may be processed somewhere else (for example in the "CAN-signal-decoder" or in the CANopen stack, but not in the script).
The maximum number of CAN messages identifiers which can be registered for reception by the script is 32. If that's not enough, register whole ranges of CAN message identifiers via CAN.add_filter().

The most significant bits (31..29) of 'CAN-ID' specify the bus number and the 11/29-bit-flag ("Extended ID"). For better readability, bitwise-or the constants cCanIdBit_Bus2, cCanIdBit_Bus3, cCanIdBit_Extd as required to the message-ID (in bits 10..0 or 28..0 of the parameter).
Examples:

   can_add_id(  0x123 );                                  // start receiving 11-bit ID 0x123 on CAN1
   can_add_id( cCanIdBit_Bus2 | cCanIdBit_Extd | 0x123 ); // start receiving 29-bit ID 0x123 on CAN2

   can_add_id( bus=cCanBusAny, 0x123 ); // start receiving 11-bit ID 0x123 on any available CAN bus

CAN.add_filter( <filter>, <mask>, <receive_handler> )

Similar to can_add_id, but this command registers an entire range of CAN message identifiers for reception.

The CAN-receive-filter operates as follows:

The CAN identifier of a received message is bitwise ANDed with the 'mask' parameter.
The result is then compared with the 'filter' parameter.
If all bits (which are not zero in 'mask') match, the received message will be passed on to the script (either to the optional receive-handler, or placed in the script's CAN-receive-Fifo).
In other words: All cleared bits in 'mask' are considered 'don't care' (i.e. ignored by the filter);
all bits set in 'mask' must match (between received ID and the 'filter' value).

Examples:

CAN.add_filter( 0x2ABCD00, 0x2FFFFF00 ); // receive extended IDs 0x0ABCD00 to 0x0ABCDFF
CAN.add_filter( 0x000, 0x000, addr(MyCanRxHandler) ); // receive standard IDs with a handler
// Note: As in other CAN functions of the script language,
// the 'extended' flag which indicates a 29-bit-ID is encoded in bit 29,
// and the bus number (0..3) is encoded as a two-bit value in bits 31..30 of the ID.

can_receive (function to poll for CAN reception)

Tries to read the next received CAN message from a FIFO.
When successful, the message is copied into can_rx_msg, and the result is 1 (one) .
Otherwise (empty FIFO), can_rx_msg remains unchanged, and the result is 0 (zero) .

Note: If received CAN messages are not 'polled' but processed in a user-defined CAN-receive-handler, it's not neccessary (and, in fact, illegal) to call 'can_receive' from the handler ! The received CAN message will be passed via pointer (as argument) to the handler, and -if the handler returns with exit code 1 or 'TRUE'- the message was intercepted by the CAN message handler, and will not be copied into the CAN-Rx-FIFO at all !
Using a CAN-receive handler is the preferred method (if extra processing of received messages is necessary in the script at all) because it wastes less CPU time than "polling".

can_rx_fifo_usage (function)

Returns the number of CAN messages still waiting in the receive FIFO (without reading a message).
A return value of zero means "the FIFO is completely empty at the moment".
A return value of 2047 (!) means "the FIFO is completely full" (and, if another message was received by the CAN controller, it would be lost for the script).

can_transmit (procedure)

Command to send a CAN message (directly, layer 2). This command comes in three different variants (without and with a parameters in the argument list):

Variant 1: can_transmit without an argument list:
Tries to send the contents of can_tx_msg (CAN message structure defined below). The global variable 'can_tx_msg' is filled with contents by the script, and transmitted my calling can_transmit:

   can_tx_msg.id  := 0x334;  // set CAN message ID (and bus number in the upper bits)
   can_tx_msg.len := 2;      // set the data length code (number of data bytes)
   can_tx_msg.b[0] := 0x11;  // set the first data byte
   can_tx_msg.b[1] := 0x22;  // set the second data byte      
   can_transmit;  // send the contents of can_tx_msg to the CAN bus
      

 //--------------------------------------------------------------------
 func CAN_Handler_A( tCANmsg ptr pRcvdCANmsg )
   // A CAN-Receive-Handler for a certain CAN message identifier.
   // Must be registered via 'can_add_id', along with the CAN message ID.
   // Interrupts the normal script processing, and must RETURN to the caller 
   //  a.s.a.p. ! Uses a LOCAL variable for transmission (not can_tx_msg).
   // Thus can_tx_msg can safely be used in the script's main loop,
   // even if the main loop may be interrupted at any time by this handler.
   local tCANmsg responseMsg;    // a local variable with type 'CAN message'
   responseMsg := pRcvdCANmsg[0];      // copy the received CAN message into the response
   responseMsg.id := pRcvdCANmsg.id+1; // response CAN ID := received CAN ID + 1
          // Note: The upper two bits in tCANmsg.id contain the zero-based BUS NUMBER !
   can_transmit( responseMsg );  // send a response via CAN immediately
   return TRUE;
   // returning TRUE means: "the received message was processed HERE, 
   //              do NOT place it in the script's CAN-receive-FIFO".
 endfunc; // end CAN_Handler_A
 
      ... somewhere in the initialisation : ...
      
   // Register a received CAN ID, and install a CAN-receive-handler for it:
   can_add_id( C_CANID_RX_A, addr(CAN_Handler_A) );  
 
      

       can_transmit( responseMsg, cCanTx_Normal );  // if necessary, wait before transmission
       can_transmit( responseMsg, cCanTx_NoWait );  // don't wait here if TX-buffer is full
      

• cCanTx_Normal : If necessary, wait for a few milliseconds until the CAN bus can transmit another message.
  Due to the CAN driver's transmit buffer (FIFO), this feature allows the script to produce a CAN bus load of almost 100 %, with the main loop slowed down by the 'blocking' call of can_transmit() so that all messages get through without a transmit FIFO overflow.
  
• cCanTx_NoWait : Don't wait if the CAN transmit buffer is completely full, but simply discard it.
  This may happen if the script tries to send more messages than the bus can accept, or if there is no-one out there (yet) who can acknowledge the CAN transmission.
  The option CAN_TX_NOWAIT should be used if can_transmit is called from an event handler, for example a script timer event.
  

can_rx_msg, can_tx_msg

From the script's point of view, the 'can_rx_msg' structure holds the last received CAN message for processing. It was filled by the previous call of the can_receive function. If the script doesn't call can_receive, and as long as can_receive doesn't return TRUE (=success), the contents of can_rx_msg will not change. The following components of can_rx_msg (and similar, can_tx_msg for transmission) can be accessed like variables by the script program:

.id

holds the CAN-bus-identifier in the least significant 11 (or 29) bits of this 32-bit integer variable, plus an optional 11/29-bit flag ("extended CAN identifier flag") in bit 29, and the zero-based CAN BUS NUMBER (!) in the most significant bits (bits 31..30). Please note that bit numbers are always start at zero, thus a 32-bit integer value (such as can_rx_msg.id) contains bit 0 (least significant bit) to 31 (most significant bit). There is no "bit 32" in a 32-bit integer !
For LIN, the 6-bit 'frame ID' ranges from 0 to 63 = 0x3F; in addition it should be bitwise OR-ed with the constant cCanIdBit_LIN to inform the CAN API that this is a LIN frame, not a CAN message.

.len

Length of the DATA FIELD in bytes. CAN frames can have 0 (zero) to 8 byte data fields, LIN allows 1 to 8 data bytes per frames.
The upper bits of this field may contain special FLAGS like cCanRTR (Remote Transmission Request, see example ScriptTest3.cvt, SendRTR() ).

.tim

Timestamp of the received CAN message, using the CAN driver's hardware specific timestamp frequency. This 32-bit integer value will roll over from 0xFFFFFFFF to 0x00000000 after about 29 hours, because the CAN driver's timestamp clock frequency is 40 kHz (at least for the ARM-7 CPUs with an internal CPU clock of 72 MHz). If you *really* need to convert a timestamp difference (as 32-bit integer value) into seconds or similar, divide the difference by the constant 'cTimestampFrequency' to get a timestamp difference in seconds. Note that other script timer functions use the same 'timestamp'. See also: system.timestamp ("current time", using the same unit) .

.b[N]

Accesses the N-th byte in the CAN data field as an 8-bit unsigned integer (value range 0 to 255).

.dw[N]

Accesses the N-th Doubleword (N : 0..1) in the CAN data field. A doubleword ('DWORD') contains 32 bits, the value range is 0x00000000 to 0xFFFFFFFF (hex).
Note that (in contrast to the components listed further below) the array-index is a 'doubleword'-index, not a byte-index. Thus the only allowed indices are 0 (=first doubleword) and 1 (=second doubleword).
Example to copy the entire 8-byte CAN data field (taken from 'ScriptTest3.CVT') :

  // The 8 databytes are copied as two 32-bit integers,
  // because that's faster on an ARM-CPU than a byte-copying-loop:
  response.dw[0] := can_rx_msg.dw[0]; // copy first doubleword (4 bytes)
  response.dw[1] := can_rx_msg.dw[1]; // copy second doubleword (4 bytes)
     

Unlike the components of 'can_rx_msg' and 'can_tx_msg' listed further below, the DWORD-wise access explained above is also possible for 'normal' varibles declared as type tCANmsg (also via pointer).

.i16[N]

Accesses the N-th and N+1-th byte in the CAN data field as a 16-bit signed integer, using 'Intel' byte order (aka Little-Endian, or 'least significant byte first).
The sign is expanded from bit 15 into the upper bits of the 32-bit integer result, so the range is -32768 to +32767.

.u16[N]

Accesses the N-th and N+1-th byte in the CAN data field as a 16-bit unsigned integer, using 'Intel' byte order (aka Little-Endian, or 'least significant byte first). Unlike 'i16', the sign bit is not expanded, so the result ranges from 0 to 65536.

.i32[N]

Accesses the N-th to N+3-th byte in the CAN data field as a 32-bit signed integer, using 'Intel' byte order (aka Little-Endian, or 'least significant byte first).
Note that the above three methods to access a CAN data field are very fast, but they cannot cross 'arbitrary' bit boundaries (thus, their syntax mimicks a BYTE-ARRAY, not a BIT-ARRAY). The "bitfield" method explained further below is slower, but more versatile.

.m16[N]

Similar to '.i16', but uses big endian byte order aka 'Motorola' format.

.m32[N]

Similar to '.i32', but uses big endian byte order aka 'Motorola' format.

.bitfield[ <index of the signal's least significant bit in the CAN-message> , <number of bits> ]

Accesses a part of the data field in a CAN messages as a 'bitfield', containing an unsigned integer value in 'Intel' byte order (least significant byte first).
Note that regardless of the signal type, bits in a CAN message are always numbered according to the following table. As usual for binary numbers, the most significant databit is on the left side in this graphic representation; the numbers for 8 bits within a byte always runs from 0 (=LSB, right) to 7 (=MSB, left).
The green cells in the following table show an example defined as  can_rx_msg.bitfield[ 18, 15 ]
 ("Intel" byte order, LSBit at bit 18 in the CAN frame, and 15 bits for this bitfield ).
Support for signals with 'Motorola' byte order (most significant byte first) was not projected by the time of this writing.

Numbering of bits in a CAN- or LIN- data field
(green: 15-bit signal example; .bitfield[ 18, 15 ] )

	bit 7	bit 6	bit 5	bit 4	bit 3	bit 2	bit 1	bit 0
byte[0]	7	6	5	4	3	2	1	0
byte[1]	15	14	13	12	13	10	9	8
byte[2]	23	22	21	20	19	18	17	16
byte[3]	31	30	29	28	27	26	25	24
byte[4]	39	38	37	36	35	34	33	32
byte[5]	47	46	45	44	43	42	41	40
byte[6]	55	54	53	52	51	50	49	48
byte[7]	63	62	61	60	59	58	57	56

The global variable 'can_tx_msg' has exactly the same structure as 'can_rx_msg' . The only difference is that can_rx_msg is used for reception, while can_tx_msg is used for transmission (from the script's, i.e. the device's, point of view). Typically, both are used in the implementation of a simple 'CAN protocol handler'.

The script test application 'ScriptTest3.cvt' contains a few examples for the reception and transmission of CAN messages through the script interpreter.

Notes and hints:

To test the script's CAN functions in the programming tool, connect your PC to the CAN bus using one of the supported CAN interfaces. The script language's CAN RX FIFO also works in the simulator, using live data received from the CAN bus.
If that is not possible (no CAN bus available in the lab, or no suitable CAN interface on the PC), use the programming tool's CAN playback utility. It allows you to play back recorded CAN messages (stored in a simple text file) into the simulator/emulator, as if they were received from a 'real' CAN interface.

A valuable tool for the development of CAN protocols in the script language is the Trace History, which most devices support (also those without an integrated CAN logger / snooper). The history can be read out remotely via web browser, for example using the URL http://upt/trace.htm . In contrast to external CAN diagnostic tools, the trace history display distinguishes between sent and received CAN messages (from the device's point of view), which an normal external CAN bus monitor can't (from his point of view, all CAN messages are received).

CAN.DecodeMessage( tCANmsg ptr msg )

Input:

Address of the to-be-decoded CAN message (aka CAN frame with up to 8 data bytes).

Output:

All display variable (display.XYZ) which are connected to CAN signals,
depending on the imported CAN database (.dbc file).

Note:

CAN.DecodeMessage() is typically used in CAN receive handlers.

Test / Example:

See CAN.EncodeMessage() .

CAN.EncodeMessage( int msgID, tCANmsg ptr msg )

• CAN.EncodeMessage() doesn't transmit send a CAN message. It only encodes it in memory !
• For transmission, you can pass the address of the message to the CAN Transmit command.
• If you need to know which variables are actually contained in the message, call CAN.MessageIDToVarName with the same ID used to encode the message.

  // Test CAN.EncodeMessage( int msgID, tCANmsg ptr msg ) :
display.ThreeSines1 := 1; // set display variable (input for CAN.EncodeMessage)
display.ThreeSines2 := 2;
display.ThreeSines3 := 3;
pVarDef := display.GetVarDefinition( "ThreeSines1" ); // get database entry for this display variable
CAN.EncodeMessage( pVarDef.CAN_Msg_ID, MyTxMessage ); // encode CAN message (but don't transmit it yet)
  // Check the encoded CAN message (which contains 3 signals here):
if( (MyTxMessage.w[0] != 1) or (MyTxMessage.w[1] != 2) or (MyTxMessage.w[2] != 3) ) then
  print("\nSomething wrong in the database, or CAN.EncodeMessage() ?");
endif;
  // At this point, the values from 'ThreeSines1' to 'ThreeSines3'
  // have been mapped into the CAN message (MyTxMessage) by CAN.EncodeMessage().
  // On this occasion, also check the inverse function, CAN.DecodeMessage():
display.ThreeSines1 := 0; // clear to see if CAN.DecodeMessage() really sets these...
display.ThreeSines2 := 0;
display.ThreeSines3 := 0;
CAN.DecodeMessage( MyTxMessage ); // TEST, should overwrite display.ThreeSines1...3 
if( (display.ThreeSines1 != 1) or (display.ThreeSines2 != 2) or (display.ThreeSines3 != 3) ) then
  print("\nBug in CAN.DecodeMessage() ?");
endif;

CAN.VarNameToMessageID( string sVarName )

Queries the CAN database (imported from a DBC file) for the CAN message identifier used to received or send a certain (display-) variable.
When successful, CAN.VarNameToMessageID returns the numeric CAN message identifier, otherwise cCanInvalidID (= 0xFFFFFFFF, which is not a valid CAN message ID).
Notes:

• In many cases, a CAN message doesn't transport only ONE, but MULTIPLE signals.
• To retrieve a list of ALL variables which are transported in the same CAN message, repeatedly call CAN.MessageIDToVarName(), beginning with n=0 for the first variable (signal) contained in the message.
• Bits 31 and 30 of the return value (message ID) contain the zero-based CAN-bus-number !
• To retrieve other parameters of the CAN-signal related with the display variable (e.g. CAN message layout and scaling), use display.GetVarDefinition() .

CAN.MessageIDToVarName( int iMessageID, int n )

Queries the CAN database (imported from a DBC file) for the name of the n-th display variable contained in a certain CAN message.
When successful, CAN.MessageIDToVarName returns the name of the n-th display variable in the message, otherwise an empty string.
Notes:

• In many cases, a CAN message doesn't transport only ONE, but MULTIPLE signals. Argument n=0 retrieves the FIRST name, n=1 the SECOND, etc.
• To find out the CAN message ID for a given display variable name (like "EngineRPM"), use CAN.VarNameToMessageID().
• Bits 31 and 30 of the CAN message ID (iMessageID) contain the zero-based CAN-bus-number !

Special CAN-bus diagnostic functions

Most of the following 'special' CAN functions only work on certain targets, but not in the programming tool / simulator . The first function argument is usually the CAN port number. Use one of the following integer constants for the port number:
  cPortCAN1  (1st CAN bus),
  cPortCAN2  (2nd CAN bus) .

The application script_demos/ErrFrame.CVT uses some of these functions to test a CAN bus with error frames.

CAN.status( <port> )

Returns the current status of the CAN bus controller on the specified CAN port (cPortCAN1 oder cPortCAN2).
The return value is a bitwise combination of the following flags (constants):

cCANStatusOK (0)	'no problem' (at least not with this CAN port)
cCANStatusHWFault (1)	unspecific problem with the CAN hardware or this port
cCANStatusRxOverflow (2)	CAN receive buffer overflow
cCANStatusTxOverflow (4)	CAN transmit buffer overflow
cCANStatusIRQFailed (8)	Only occurred on old systems ("too many interrupts per second").
cCANStatusTxError (16)	Error while trying to send a CAN frame (no Acknowledge, nothing connected, missing terminator ?)
cCANStatusBusError (32)	One of the 'more serious' CAN bus errors (possibly now 'error passive', i.e. no active transmission until error counters decremented)
cCANStatusWarning (64)	Warning (the precise definition of a 'CAN warning' depends on the controller)
cCANStatusBusOff (128)	'BUS-Off'. This is the most serious CAN error status bit. The controller doesn't try to communicate with the bus anymore, neither active (transmit) nor passive (receive). A brute-force method to recover from the Bus-Off state is the command system.reboot .

In contrast to the CAN functions listed further below, CAN.status is also available in firmware variants with CANopen protokoll.

CAN.rx_counter( <port> )

Retrieves the number of CAN messages received through the specified port, since power-on.
In the programming tool, the result includes the number of messages 'simulated' with the CAN Logfile Player.

CAN.tx_counter( <port> )

Retrieves the number of CAN messages sent through the specified port, since power-on.

CAN.tx_enable

Accesses the 'transmit enable'-flag for all periodically transmitted CAN-signals (from the device's point of view), which have been imported from a CAN-database for transmission. This is the same flag as 'signals.tx_enable' in the display interpreter. Details in the document about 'CANdb'.
Note: Even with CAN.tx_enable = FALSE, the script command can_transmit can transmit !
CAN.tx_enable only affects the 'scheduler' for periodic or event-driven transmission of CAN signals.
CAN.tx_enable is usually set during the script initialization, shortly before calling init_done:

CAN.tx_enable := TRUE;  // allow transmission of CAN-signals assembled from imported databases
init_done;              // let the system know "we're open for business" (enable event handlers)
     

CAN.rx_timeout

Accesses the global 'CAN message/signal receive timeout' parameter, here: scaled into milliseconds.
For details, see the description of CAN Signal Timeout Monitoring in the document about CAN database support.
Example:

if( CAN.rx_timeout == 0 ) then
    // Timeout monitoring for rcvd messages/signals not enabled -> enable it:
    CAN.rx_timeout := 2000; // CAN message/signal timeout in ms
endif;

CAN.err_counter( <port> )

Retrieves the number of any errors and warnings, counted by the CAN-driver's interrupt service handler since power-on.
The counter includes 'comparably harmless' errors, for example bit-stuffing errors, which sporadically occur even in a 'good' CAN network. This function is only intended for diagnostic purposes; the expectable error rate depends largely on the bus load and on the environment (EMC) !

CAN.err_register( <port> )

Retrieves the last content of the CAN controller's 'error register', captured by the CAN-driver's interrupt service handler when the last CAN error interrupt occurred.
Because the format of the CAN controller's error register is extremely hardware dependent, specifying the meaning of the bits in that register would be far beyond the scope of this documentation.

• For MKT-View II (with CPU = LPC2468), see NXP's "UM10237" (LPC24XX User Manual), Chapter 18.8.4, "Interrupt and Capture Register";
  
• For MKT-View III (with CPU = LPC1788), see NXP's "UM10470" (LPC178x/7x User Manual), Chapter 20.7.4, "Interrupt and Capture Register", pages 514 to 517 in UM10470 Rev. 1.5;
  
• For devices with other controllers, and in the programming tool (simulator), the value returned by CAN.err_register() is meaningless !

CAN.err_frame_counter( <port> )

Retrieves the number of "error frames" received on the specified port, since power-on.
Strictly defined, it's the number of "bit stuffing errors" signalized by the CAN bus controller.
A bit-stuffing error means six or more dominant bits on the physical layer.
Ideally, there should be no error frames on a CAN at all. The error-frame-counter allows to check this.

CAN.ParseString( string source, tCANmsg destination )

Inverse to the string()-constructor with source data type tCANmsg. Can be used to convert ("parse") a string into a binary CAN message (destination type tCANmsg). Similar as when converting a tCANmsg into a string, the format is specified using the built-in global variable CAN.string_format (e.g. sfVectorASC). An example is in the CAN-ASCII-Logger demo.

CAN.PulseOut( <port> , <duration in microseconds> )

Generates a pulse (dominant state) on the specified CAN port, with the specified length (duration) in microseconds.
Rarely used; for example to send CAN error frames (= six dominant bits, which is impossible with a 'normal' CAN controller.
The function only works on a suitable target (LPC / ARM-7), not on a PC, and not on any Linux-based system. A sample script which uses this procedure is in the 'ErrFrame' application in the script_demos folder. It was designed to send CAN error frames, to check if certain CAN testers were able to detect such CAN bus errors. For example, see the ErrFrame.CVT application.
Do not use this function in a critial environment (vehicle, etc),
unless you are absolutely sure about the possible consequences !

CAN.timestamp_offset

This variable can be used to 'move' the timestamps when converting CAN messages (type tCANmsg) into text. The internal timestamp generator starts at zero when booting the system.
But when recording received messages in a file (via script), the timestamps shall often be 'relative' to the trigger point (which is also determined via script). This can be achieved as follows:

  CAN.timestamp_offset := system.timestamp; // offset for converting to Vector ASC format

Note: The timestamps delivered by the CAN driver are not affected by CAN.timestamp_offset .
CAN.timestamp_offset only affects the conversion of type tCANmsg into a string ("Vector ASC") with the string() function.
The unit of CAN.timestamp_offset is the same as for system.timestamp (timer ticks, frequency=cTimestampFrequency).

CAN.string_format

Specifies the format for converting CAN messages (script data type tCANmsg) into strings, using the string()-function (if 'value' is a tCANmsg, or a pointer to a tCANmsg). Example:

  CAN.string_format := sfVectorASC; // when converting tCANmsg to string, use "Vector ASC" format

CAN.string_format also controls the conversion of strings into CAN messages via CAN.ParseString().

CAN.test_id := <CAN-Message-ID>

Special command for hard- and software tests. Only available in devices with a special firmware (available on request for the MKT-View IV). Details only available in the german document.

CAN.test_action := <N>

Defines 'what to do' on reception of a CAN-message with identifier = CAN.test_id.
This action is already performed in the CAN interrupt, thus the latency is extremely small.
Details only available in the german document.

Controlling the programmable display pages from the script

Any procedure or function beginning with the keyword "display" controls the programmable display pages in some way.

display.<var-name>

Accesses a display variable via script. Here, <var-name> must match exactly one of the names defined in the programming tool's 'Variables' tab. In most cases, such variables are used to communicate with a network, thus a display variable contains network-specific information that don't exist in normal script variables.

display.app_info

Returns the 'application info' aka 'file description', specified here.
This is a string of characters (single line), defined by the application's developer, contained in the *.cvt- or *.upt file copied into the devices internal Flash memory.

display.goto_page( <page> )

Switches to the specified display page.
The new page can be specified either as a page number (integer, deprecated), or as a page's name (string, favourized).

display.page_name

Retrieves the name of the current display page (read-only).

display.page_index

Retrieves the zero-based index of the current display page (read-only).
Remember, the "first" page of every display application has index "zero", not "one" !
To switch to a different display page (from the script), use display.goto_page .

display.num_pages

Retrieves the number of pages which exist in the display application (read-only).
This function can be used to let the script run through a 'loop with all display-pages', as used in the 'page menu' example.

display.num_lines

Retrieves the number of lines on the current display page (read-only).
This function can be used to let the script iterate through 'all elements on the current display page'.

display.page[n].name

Retrieves the name of the n-th display page (read-only).
Note that the page index 'n' runs from zero to display.num_pages minus one !

display.exec( < command string > )

Lets the display-interpreter execute any display command. This command must be used with caution ! It should be avoided if not absolutely necessary, because it may severely slow down the script. This may happen because the display commands are interpreted, not compiled . Example:
  display.exec( "bl(0)" );  // turn the display's backlight off via display interpreter
To avoid calling the display interpreter from the script, use 'flag variables', which can be polled in global or local events by the display. This way, the script will not be slowed down (or even blocked for dozens of milliseconds) by the execution of the display command. A safe example for the display.exec command can be found in the 'traffic light' demo.

display.pixels_x

Retrieves the width of the LC display, measured in pixels (read-only). Used in the QuadBlocks demo to switch to a display page designed for 'landscape' or 'portrait' mode of the screen.

display.pixels_y

Retrieves the height of the LC display, measured in pixels (read-only).

display.fg_color

Returns the default foreground- aka text-colour of the current display page.
In the programming tool, this colour value is defined in the im 'Display Page Header' (Default Text Colour).

display.bg_color

Returns the default background colour of the current display page.
In the programming tool, this colour value is defined in the im 'Display Page Header' (Default Background Colour).

display.night

Read- and write access to the boolean day/night colour switching flag. Example:

  display.night := TRUE;  // use colour scheme 'Night'
  display.night := FALSE; // use colour scheme 'Day'

display.menu_mode ,  display.menu_index

This is the script language's equivalent to the display interpreter's "mm", and "mi" function.
(Entspricht der Funktion "mm" bzw "mi" des Display-Interpreters.)
Examples in the application 'DisplayTest.cvt' .
Possible menu modes are defined as built-in constants in the script language:
   mmOff : neither 'navigating' nor 'editing'
   mmNavigate : navigating between different fields on the page
   mmEdit : editing the (usually numeric) value in an input-field

display.EditValueMin, display.EditValueMax

Specifies the limiting range when editing a numeric value via 'up/down' (increment/decrement the value using cursor keys or rotary encoder) in an edit field on any programmed display page. This function was added in 2016-06, because (unlike 'display variables') a simple script variable does not contain any information about the permitted value range. Use the 'Begin Edit' event in your script's OnControlEvent-handler, to set those limiting values whenever the operator begins to edit such a field.
Both display.EditValueMin and display.EditValueMax can be read or written by the script at any time, but their values may be overwritten by the system when beginning to edit a normal display variable, using the min- and max values as defined in the 'Variables' definition table in the UPT programming tool. This happens shortly before OnControlEvent is called with event=evBeginEdit. So even when editing display variables, your script can still override the edit field's limiting range.

display.elem[<Element-Name>].visible

The script can show or hide a display element by setting or clearing the 'visible'-flag. Example:
   display.elem["Arrow"].visible := TRUE;  // show the element named "Arrow"
   display.elem["Popup"].visible := FALSE; // hide the element named "Popup"
Note: When a display page is loaded from ROM (due to a 'page switch'), all elements are visible by default.
Making an element invisible which was previously visible causes an automatic update of the entire display page.

display.elem[<Element-Name>].xyz    or
display.elem[<Element-Index>].xyz

This is the script language's equivalent to the display interpreter's function "disp.<Element>.xyz" (follow the link for a list of accessable components, here simply called 'xyz').
Examples (more in the 'display test' application):

// Show the NAME of the currently selected element :
print("\r\n Name:", display.elem[ display.menu_index ].na );

display.elem[i].bc := rgb(255,127,127); // set background to lightred

The element can be addressed by its index as in the above example, or by its name. Example:
display.elem["BtnNext"].bc := rgb(0,i,255-i); // modify 1st background colour
display.elem["BtnNext"].b2 := rgb(0,255-i,i); // modify 2nd background colour

In the last example, "BtnNext" is the name of a UPT display element, specified in the page definition table. The script runtime determines which of the two addressing modes is used by the data type of the argument between the squared brackets: [Integer] = by index, [String] = by name. In conjunction with events like evClick, evBeginEdit, evEndEdit, an array element may also be addressed by its index (within the current display page). To simplify this, the element-index is passed as function argument 'param1' to the script's control event handler (OnControlEvent).

Note (also applies to display.elem_by_id[ ] ):

If there is no display element with the specified name, index, or identifier on the current display page,
the read- or write access to the non-existing element will not cause a runtime-error, and the script won't stop.
A write-access will simply 'do nothing' (the assigned value is discarded).
A read-access will return zeroes or empty strings, depending on the component type.

display.elem_by_id[<Control-ID>].xyz

Similar as above (display.elem), but accesses a display element by its control-ID (which needs to be defined in the page definition table).
Accessing a display element this way simplifies modifying it in an event handler (in the script language), because the control-ID is passed in the handler's function argument list. Details about this "advanced" topic are here .

display.dia.XYZ

Invokes one of the commands to control the Y(t)- or X/Y-diagram on the current display page.
Details are in a separate document about the display interpreter's 'diagram' commands.
'XYZ' is the token listed in that document, for example clear, run, ready, ch[N].min, ch[N].max, sc.xmin, sc.xmax, unix_time, etc.
At the time of this writing (2018-12-13), controlling diagrams via script was 'under construction' again, and up-to-date info was only available in german language.

display.arr[row][column][component],
display.arr.dim(n_rows, n_columns, n_components),
display.arr.n_rows, .n_columns, .n_components

Allows direct access to the old display interpreter's 'global' array, which (in the interest of downward compatibility) can still be used to draw polygons into diagrams (see above, display.dia.XYZ). Details about the display interpreter's 'global' array (arr[][][]) are here.

display.pause := TRUE;

Stops updating the screen (with the current "programmed display page"). This can be used for a crude way of synchronizing the display to the script application: Pause the display before calculating a new set of 'display values' in the script, and resume when finished with that.
This command is typically used to pause the display output temporarily, for example to ensure the consistency (auf Deutsch: Widerspruchsfreiheit) of the screen while the script prepares some values which "always belong together". Without such precautions, due to semi-multitasking of the script and the display, some of those values shown on the display may be "old", and others may be "new".

display.pause := FALSE;

Resumes updating the screen, i.e. switches back to normal periodic screen update (screen updated 'in the background', while the script runs).
The test/demo application "LoopTest.cvt" uses the display.pause flag to avoid flicker, while filling the text-screen with new data.

display.redraw := TRUE;

Sets a flag to let the UPT display interpreter update the current display page as soon as possible. On completion, the flag display.redraw will be cleared automatically.
It is usually not necessary to force a display update this way, because the display interpreter periodically compares the values of all (numeric) variables associated with the elements on the current display page; and -if a value has changed since the last update- automatically redraws the element.

display.UpdateDiagram

This command may be issued after calculating new values (in an array), to let a diagram update the curve display (showing the array data). If a diagram channel uses an array as "data source" as described here, then the 'UpdateDiagram'-command will also copy the data from the array into the diagram's own channel memory ("double buffering" to keep the display consistent).

display.GetVarDefinition(<variable>)

Special function to query the definition of a display variable.
Allows retrieving almost any parameters specified on the tabsheet "Variables" (in the programming tool) via script during normal runtime. For simple display-applications, this function is not required.
Input argument : <variable> = name of the variable (as string) or definition table index (as integer value).
If successfull, the returned value is a pointer to (= "the address of") a structure of type tDisplayVarDef .
Otherwise (no display-variable found for the specified name or index), GetVarDefinition returns a NULL pointer.
Some of the components of structure tDisplayVarDef are direct equivalents of similar-named columns on the tabsheet 'Variables' in the programming tool:

.Name

Name of the Display-Variable (without prefix "display.")

.AccessRights

Access rights; in certain cases this also defines the 'direction' of a transfer ("write"=transmit or "read"=receive from the terminal's point of view).

.BusNr

Bus number. For CAN signals, this parameter is defined when importing a DBC file.

.CAN_Msg_ID

CAN message identifier (if this variable is connected to a "CAN signal", which turns it into a 'Network Variable').
In contrast to tCANmsg.id, this component does not contain bus numbers encoded in the upper bits !

.CommChannel

Kommunication channel. Contains the channel number from column "Channel" on the programming tool's 'Variables' definition table.

.CopIndex

CANopen Object Index (1..65535). Matches the first part of column 'OD-Index' in the 'Variables' table.
If the value is nonzero, the display variable becomes part of the CANopen device's Object Dictionary, and can be accessed externally via SDO.

.CopSubindex

CANopen Sub-Index (0..255). Used in combination with the OD-Index. Details in the description of the Object Dictionary.

.CycleTime_ms

For CAN signals ("CANdb"), this parameter is used as periodic transmit cycle, or for receive timeout monitoring.

.MinValue

Minimum value of the scaled variable. Sometimes used as 'limit' for the display or in numeric edit fields.

.MaxValue

Maximum value of the scaled variable. Sometimes used as 'limit' for the display or in numeric edit fields.
In most cases, both 'MinValue' and 'MaxValue' are zero, which means 'no limits'.

.MuxValue

Numeric (integer) value of an optional MULTIPLEXER / "Multiplexor" from the CAN database ("CANdb", importied from *.DBC).

.MuxLSBit

Zero-based Index of the multiplexer's least significant bit in the CAN data field (0..63). For details, see 'CANdb'.

.MuxNumBits

Number of data bits of the multiplexer in the CAN data field (1..16).

.MuxByteOrder

Byte order of the multiplexer in the CAN data field, if this contains more than 8 bits (extremely rare!) .
Encoded as a single character: M=Motorola (big endian), I=Intel (little endian).

.RawSigType

Type of the 'raw' signal transferred via CAN ("CANdb") : (U)nsigned, (S)igned, (F)loat, or (I)nvalid.

.RawSigByteOrder

Byte order of the 'raw' (CAN-) signal: (M)otorola, (I)ntel.

.RawSigLSBit

Zero-based index of the raw signal's least significant bit (0..63). For details, see 'CANdb'.

.RawSigNumBits

Number of data bits of the 'raw' signal (on the CAN bus, or similar) .

.ScaleFactor

Scaling factor. The 'raw' CAN Signal is multiplied with this floating point value, to convert it into the 'display' unit.

.ScaleOffset

Skaling offset. After the multiplication (see above), this floating point value is added to the result.

.SDO_Data_Type

Data type 'a la CANopen'. Required to transfer values via SDO (Service Data Object), and for proper PDO mapping (Process Data Object).

.Unit

A string of up to 8 characters with the physical display unit. Usually originates from the imported database (DBC file).

.UpdateTime_ms

Update time in milliseconds (for the display).

.ValueTable

A string of value/text pairs for the display, using the format specified here.

Please note: Almost all of the components listed above (in tDisplayVarDef) must be treated as 'read-only' by the script !
If you need to modify the definition of display-variables via script at the normal runtime (for 'extremely special applications'), please get in contact with the software development engineer at MKT Systemtechnik.
An example using display.GetVarDefinition() is in the application ScriptTest3.cvt:

      var
         string             sVarName; // name of a display-variable
         tDisplayVarDef ptr pVarDef;  // definition of a display-variable
      endvar;

      ...

     sVarName := "FourSines1";        // name of a display-variable

     // Show CAN message layout of this *DISPLAY*-variable:
     pVarDef := display.GetVarDefinition( sVarName );
     print("\n  ", sVarName, " : bits ", pVarDef.RawSigLSBit, "..",
                   pVarDef.RawSigLSBit + pVarDef.RawSigNumBits - 1 );

See also ... about interaction between script and display application :

• Accessing display variables from the script
• Accessing script variables from the display interpreter
• Invoking script procedures from the display interpreter
• Invoking script functions from display pages (to retrieve a text strings for the display, used for internationalisation)
• Asynchronous event handling (and how to intercept certain events in the script language)

'System' functions, etc

Built-in procedures or function begin with the keyword "system". They access some low-level system parameters. For normal applications, the following 'system' functions are available:
   system.analog_in .amb_light .audio_ptt .audio_vol .beep .click_vol .dwInputs .dwOutputs .dwFirmware .dwVersion
   system.exec .feed_watchdog .led .nv[0..31] .reboot .resources .serial_nr .shutdown .temp .timestamp .ti_ms
   system.unix_time .unix_time_boot system.vsup system.vcap
   system.show_help .

Functions intended for 'special uses' and software tests (e.g. system.test) are deliberately not specified here.

system.analog_in[0] .. system.analog_in[3]

These functions read the current value for the specified onboard analog input. The MKT-View III has two analog inputs (indices 0 and 1), the MKT-View IV four 'onboard' analog inputs (indices 0 to 3). Details about how to connect the analog inputs can only be found in the device specific datasheet. In the MKT-View III, the analog inputs are connected to pins 12 and 13 of the 14-pin Lemo connector; the "analog ground" is on pin 14. In the MKT-View IV, the two additional analog inputs on connector 'X3' can be polled by the script via 'system.analog_in[2]' and 'system.analog_in[3]'.
In contrast to the old display interpreter functions "ain1" and "ain2", the script funktion system.analog_in[] returns a floating point number, ranging from 0.0 to 1.0, regardless of the voltage divider (populated on the board), and regardless of the A/D converter's resolution ("number of bits"). Even future devices with high-resolution A/D converters, or with digital signal processing and oversampling, will stick to this scale range.
By default, the voltage dividers in MKT-View III / IV are designed for a maximum input voltage (scale end) of 15 Volts.
Only converters that support negative input voltages (which didn't exist in any MKT-View at the time of this writing) will deliver values ranging from -1.0 to +1.0. The same applies to analog inputs sampled with the DAQ Unit (fast-sampling Data Acquisition).
In the programming tool / simulator, the analog input values can be set as explained here.
A simple example using the analog inputs can be loaded from programs/script_demos/AnalogIn.cvt. It uses digital lowpass filters to 'smooth' the samples read from the analog inputs, and plots the results along with the non-filtered 'raw' samples as an Y(t) diagram on the screen:

Screenshot from sample application 'AnalogIn.cvt' on an MKT-View III.
Red: Ch. 1,raw; orange: Ch. 1,filtered; blue: Ch. 2,raw; purple: Ch. 2,filtered

An example for the analog inputs (measuring temperatures in °C with simple 22 kOhm NTCs as external sensors) is in the demo application programs/script_demos/Thermo.cvt .
Depending on the hardware, the script language may support additional commands to poll other 'internal' A/D converter channels, e.g.:

• system.vsup : DC input supply voltage (in Volts, as a floating point value)
• system.vcap : Voltage measured at the internal UPS (Ultracap power bank, result in Volts)
• system.amb_light : Last 'Ambient Light Sensor' reading as a floating point value (0 .. 1.0)
• system.temp : Internal temperature in degrees Celsius (floating point value)

system.amb_light

This script function returns the last 'Ambient Light Sensor' reading as a floating point value, ranging from 0.0 ("complete darkness") to 1.0 ("bright sunlight").
In newer devices like the MKT-View V, the sensor is 'logarithmizing', and located inside the membrane keyboard.
Since different generations of MKT-Views have used different sensors, some of them mounted deep inside the enclosure, a direct conversion of the A/D conversion result into a physical unit like 'Lux' is difficult, and unnecessary for the sensor's main purpose: Controlling the display brightness depending on the ambient light. But such a conversion can be done via script (if necessary), e.g. using a lookup table or an individually crafted polynomial interpolation.
An example to display the measured value (numeric and as curve / "trend") is contained in the 'Analog Input' test applikation, programs/script_demos/AnalogIn.cvt, on the display page titled Internal Analog Sensors.

system.audio_vol

Reads or writes the audio output volume aka "Speaker Volume". The same parameter can be modified (and permanently saved) in the terminal's system menu. The function is only implemented in certain terminals with an analog audio output - see feature matrix . A similar command also exists in the display interpreter. Unfortunately, the value range and scaling depends on the hardware. For example, the CVT-MIL 320 used a digital potentiometer with 128 linear steps (not logarithmic!), value range 0 to 127. See also: Audio settings and signal paths in the MKT-View III / IV.

system.audio_ptt

Controls a relais for the audio output's 'Push-To-Talk'-feature. Only exists in a few 'special' devices.

system.beep( frequency [,time [,volume [,freq_mod [,ampl_mod] ] ] ] )

Produce a simple sound using the system's built-in 'beeper' (buzzer, piezo speaker, or similar). Similar as the 'beep' command in the older display interpreter.
frequency : Tone frequency in Hertz. A value of zero turns the tone off.
time:   length of the tone, measused in 100-millisecond-steps. If this and all following parameters are missing (or zero), the tone will be "endless" until you turn it off with the command system.beep(0).
volume: Relative volume (loudness) in percent, ranging from 0 to 100. The beeper is controlled with a pulse width modulator which can be used to produce different output levels, but the harmonic spectrum of the generated tone is also affected by the PWM duty cycle. A volume of 100 produces the loudest possible tone with a 1:1 duty cycle. freq_mod: Frequency modulation. Can be used to produce siren-like sounds, or "chirps" and "whistles". Unit is "Hertz per 100 milliseconds". If the value is positive, the frequency increases as long as the sound is audible; if the value is negative the frequency decreases.
ampl_mod:  Amplitude modulation. Can be used to produce sounds which start with a low volume and then get louder. Not very effective because of the pulse-with modulation, where a volume of 10% can hardly be distinguished from a volume of 50% .
Example: system.beep(150,20,50,100)
    produces a 2-second, "chirped" tone which rises from 150 Hz to 2150 Hz (=150  Hz + 2 seconds * 100 Hz/0.1sec)

system.play_notes( string )

Similar as (but a bit more versatile than) system.beep. Uses the same 'beeper' (buzzer, piezo speaker, etc) to play a short string of notes. The format (syntax of the 'note string') is the same as for the old interpreter command "play" (follow the link for examples with short 'melody' strings).
The command already returns before playing has finished, i.e. it doesn't consume significant time, and can safely be used in event handlers.

system.click_vol

Only for devices with touchscreen. Reads or writes the 'touchscreen click' volume. The same parameter can be modified (and permanently saved) in the terminal's system menu.

system.backlight

Only for devices with backlit display. Sets (or reads) the normal backlight intensity / day, same as in the system setup under "Display Setup" / "Brightness".
Value range (same as for other 'LED pulse width modulators'): 8 Bit, 0 (off) ... 255 (max).

system.backlight_low

Only for devices with backlit display. Sets (or reads) the dimmed backlight intensity / night time or after backlight-timeout ("power saving mode"), same as in the system setup under "Display Setup" / "Low Brightness".

system.bl_timeout

Only for devices with backlit display. Sets (or reads) the timeout-setting in seconds after which the backlight switches from "on / bright" to "off or dimmed", same as in the system setup under "Display Setup" / "LCD-Off-Time".

system.dwInputs

Access the system's onboard digital inputs as a 32-bit 'doubleword'. Depending on the target hardware, up to (!) 32 digital inputs can be read in a single access (MKT-View III / IV have two onboard digital inputs). Bit zero reflects the state of the first input, etc. Use a formal assignment to read the current state of the digital inputs, for example:
iDigitalInputs := system.dwInputs; // poll all onboard digital inputs
if( iDigitalInputs & 0x00000001 ) then // check bit zero = first input
  print("DigIn1 = high");
else
  print("DigIn1 = low");
endif;
An example for measuring (low) input frequencies on a digital input can be found in the application programs/script_demos/DigitalInputFrequency.cvt .
See also: Frequency- and event counter for the digital inputs .

system.dwOutputs

Access the system's onboard digital outputs as a 32-bit 'doubleword'. Depending on the target hardware, up to (!) 32 digital inputs can be set in a single access (of course, not all devices have onboard digital I/O lines at all, and for most devices, it's impossible to set all digital outputs exactly at the same time, due to hardware restrictions / internal 'I/O-bus'). Bit zero drives the first output, etc. Use a formal assignment to read, modify, and write the current state of the digital outputs, for example:
system.dwOutputs := system.dwOutputs | 0x0001;    // set the first onboard-output
system.dwOutputs := system.dwOutputs & (~0x0001); // clear the first onboard-output
system.dwOutputs := system.dwOutputs EXOR 0x0001; // toggle the first onboard-output
A sample script which uses digital onboard I/O is the 'TrafficLight' application .

system.dwFirmware

Retrieves the hardware-specific firmware 'article number' as a 32-bit integer value.
Example:
    print("FW-Art-Nr.=",system.dwFirmware);

Output (when the above example is executed on different target systems):

  FW-Art-Nr.=11314       (on an MKT-View II with 'CANdb' firmware)
  FW-Art-Nr.=11315       (on an MKT-View II with 'CANopen' firmware)
  FW-Art-Nr.=11392       (on an MKT-View III with 'CANdb' firmware)
  FW-Art-Nr.=11393       (on an MKT-View III with 'CANopen' firmware)
  FW-Art-Nr.=11222       (when running on a PC in the 'simulator')

system.dwKeyMatrix

Returns the current state of the keyboard matrix as bit combination (up to 32 bits in a 'DWORD').
Each key is represented by a single bit, thus this function can be used to poll 'exotic' key combinations, for which which getkey doesn't have an equivalent code (for example, Shift-Enter, etc).
The bit combination returned by system.dwKeyMatrix is similar to the display interpreter funktion km and (for devices with CANopen V4) Object 0x5001:

• Bit 0..7 : Function keys F1 (bit 0) to F8 (bit 7) .
• Bit 8..15 : Cursor left (bit 8), right(9), up(10), down(11);
        ENTER (bit 12), ESCAPE (bit 13), first shift key (bit 14), second shift key (bit 15) .
• Bit 16..23: Numeric keys '0' (bit 16) .. '7' (bit 23) .
• Bit 24..31: Numeric keys '8' (bit 24) .. '9' (bit 25),
        "Dot" (bit 26), "Plus" or "Plus/Minus" (bit 27),
        Tab key or 'two horizontal arrows'-key (bit 28),
        Questionmark, Help, or similar 'help' key (Bit 29),
        "A to Z", "Alpha", or similar special key for 'alphanumeric input' : Bit 30,
        "Backspace" or "special arrow pointing left" : Bit 31 .
  

To improve the readability of the script, use only the following symbolic constants in bitwise AND-combinations with the keyboard matrix (and in the 'OnKeyMatrixChange'-handler):

  kmF1 .. kmF8 : Function keys F1 to F8
  kmLeft    :  Cursor keys..
  kmRight
  kmUp
  kmDown
  kmEnter   : ENTER key
  kmEscape  : ESCAPE key
  kmShift1  : 1st Shift key
  kmShift2  : 2nd Shift key
  kmDigit0 .. kmDigit9 : decimal keys (exist in a few devices only)
  kmDot     : decimal separator (dot, sometimes comma)
  kmPlus    : "PLUS" (sometimes labelled "+/-" or "* +")
  kmTab     : TAB key, or "two horizontal arrows"
  kmMode    : Questionmark, HELP, HELP/MODE, or similar labelled key
  kmAtoZ    : key labelled "ABC"/"A"/"Alph" (for TEXT INPUT)
  kmBackspace: Backspace,"special arrow pointing left", or similar labelled key

To react quickly on any change of the keyboard matrix (without wasteful polling system.dwKeyMatrix), implement the OnKeyMatrixChange handler in your application.
An example is in the application script_demos/KeyMatrix.cvt .

system.dwVersion

Retrieves the firmware version number (in the target device) as a 32-bit integer value.
Format:
  bits 31 .. 24 = major version number (Hauptversionsnummer)
  bits 23 .. 16 = minor version number (Nebenversionsnummer)
  bits 15 ..  8 = revision number
  bits  7 ..  0 = build nummer
Example:
    print("FW-Version=0x"+hex(system.dwVersion,8));
 -> output: FW-Version=0x01020304  (if the firmware version was "V1.2.3 - build 4")

system.exec( filename )

Loads the speficied file (*.cvt or *.upt, aka 'App') from the memory card, or the specified pseudo-filesystem-path into RAM (not FLASH!), recompiles the script (which is contained in the new application), and finally launches the new application. The application in the device's internal FLASH (for example, the 'App Selector') remains intact, so by calling
  system.reboot
the 'reloaded' application can switch back into the 'App Selector'.

Screenshot of the 'Application-Selector'. Click on the image for details.

In simulator mode ("running the app in the programming tool"), system.exec() is only enabled if the running program was saved (on disk) since the last modification.

Note: This function only exists in devices with a "large" RAM, like MKT-View III / IV. It is not available in older devices like MKT-View I / II !

See also (helpful for 'reloaded' scripts): Variable declarations with the 'noinit' attribute.

system.show_help( filename, options )

Loads the specified file (typically *.htm or *.txt) into the 'Help Browser' integrated in devices with sufficiently large screens and sufficiently large on-board Flash. This browser is normally used to show built-in help pages only, but you can use it in your own application to show application-specific help. Such custom help pages can be created with a plain text editor, and uploaded into the device's onboard Flash memory via File-Transfer-Utility. Details about the file format are here.
The 'options' parameter (2nd, optional function argument) is reserved for future use (like showing the help window in maximized, or minimized state; etc). Use options=0 for the default size and appearance of the help window.

system.counter_mode

Operation mode of the optional ^(*) frequency- or event counter. At the time of this writing (2017-10-11), the following modes were implemented:

• 0 : Counter off (passive). This is the default state after power-on.
• 1 : Simple counter for positive edges on digital input #1
• 2 : Simple counter for positive edges on digital input #2
• 3 : Two independent frequency- or pulse counters on the digital inputs
• 4 : Complex counter with quadrature input, suitable for most incremental encoders.
  The phase between input 1 and 2 indicates the direction (increment or decrement).
  The counter value increments or decrements on any edge (rising or falling) on any of the two inputs.
  The same applies to the measured frequency, which may become negative when the encoder is turned counter-clockwise.

  

  5 : Up/down-counter with pulse input (trigger on rising edge) on digital input #1, and direction control on input #2 (LOW=increment, HIGH=decrement).

  

system.counter_gate_time

Gate time for frequency measurements with the 'digital counter' described above.
Unit: Milliseconds.   Default: 1000 [ms].

system.counter_frequency[0]

Returns the measured frequency in Hertz (first input, thus array index zero). Thanks to the measuring principle, even with gate times below 1000 milliseconds the frequency resolution may be better than one Hertz. Thus the result is always a floating point number (float) !

system.counter_frequency[1]

Frequency measured on the second digital input. Only available in mode 3 ('two independent frequency- or pulse counters').

system.counter_value[0]

Number of pulses or events counted on the first input (thus array index zero). In contrast to the frequency, this value is always read- and writeable (even without stopping the counter), and doesn't depend on the gate time.
In some counter modes (e.g. up/down counter), the result may be negative.

system.counter_value[1]

Number of pulses or events (edges) counted on the second digital input. Only available in mode 3 ('two independent frequency- or pulse counters').

---

^(*) The frequency- and event-counter was initially implemented in an MKT-View III / IV in October 2017.
    In older devices (like MKT-View II) it is not available.
    Input voltage and maximum frequency are specified in the device's datasheet.
    Typical values are: Vin_low <= 3.0 V, Vin_high >= 6.5 V, f_max = 20 kHz (with modified input lowpass).
    On request, the digital inputs (voltage dividers with lowpass filters) can be modified
    for 'TTL'-levels (threshold approx. 3 V) and higher frequencies (MKT-View IV: up to 200 kHz without lowpass).
    Please note: The counter is one of the 'extended', unlockable script features.
An example for measuring frequencies on the digital (onboard) inputs is in the application programs/script_demos/DigitalInputFrequency.cvt .

---

system.feed_watchdog( < number of milliseconds > )

This command should only be used if really necessary, for example if an event handler, or a function invoked via backslash sequence in a display element's format string, is expected to require more than 400 milliseconds for execution. Fortunately, in most applications this is hardly ever necessary, because any 'long-lasting' operations can easily be moved into the script's main loop (main task), and in the event handler, you will only set a flag (variable) which can be polled in the main loop. Setting a variable takes much less than a millisecond, so you don't need to feed the watchdog in a well-designed event handler.
In the following paragraph, the term 'event handler' also applies to a function invoked via backslash sequence in the format string of a display element (as in the 'GetText' example).
Technical details follow...
Endless loops, and long calulations must be avoided in event handlers, because they will render the device inoperable (or, from an operator's point of view 'it crashes'). To avoid this (in case of an erroneous script), the run time system will terminate the function call, if the function (event handler) doesn't return to the caller fast enough (i.e. in less than 200 milliseconds). In the normal script context, there is no such limit because the pseudo-multitasking guarantees that the device stays 'responsive' even if the script gets stuck in an endless loop without calling any 'waiting' function.
If the maximum event handler execution time is not sufficient, the forced termination can be avoided with a command like this:

  system.feed_watchdog(500); // Feed the script's watchdog for another 500 milliseconds

As already mentioned, this consequence of doing this may be a sluggish user response, but also protocol timeouts (because as long as the event handler is busy, the device will not do much else). So whereever possible, avoid this command, and re-write your event handlers so they return to the caller as fast as possible. Then you won't need to feed the watchdog at all.

system.led( index, pattern, red, green, blue )

Only for devices with multi-colour LEDs. Sets the blink-pattern and RGB colour mixture for the specified LED (as usual, indices begin at zero, not one).
Parameters:

  index :  0=first LED (topmost on the MKT-View 2)  ... 2=third LED
  pattern: 8-bit blink pattern. Each bit controls a 100-millisecond interval.
           After a cycle of 8 * 100 ms the whole cycle starts again.
           The 8-bit blink patterns of all LEDs are synchronized.
  red, green, blue: specifies the 3 * 8-bit colour mixture (see examples).
     

If a certain LED parameter (pattern, red, green, blue) shall not be modified, pass -1 (a negative value) instead.
Examples:

  system.led( 0, 0xFF, 0xFF, 0x00, 0x00 ); // 1st LED permanently on, RED
  system.led( 1, 0x0F, 0x00, 0xFF, 0x00 ); // 2nd LED slowly blinking GREEN
  system.led( 2, 0x55, 0x3F, 0x3F, 0xFF ); // 3rd LED rapidly flashing BLUE
  system.led( 2, 0x00, -1,   -1,   -1   ); // 3rd LED off without changing the colour
  system.led( 2, 0xFF, -1,   -1,   -1   ); // 3rd LED on without changing the colour
     

Some devices only have a GREEN and a RED LED (sometimes combined as a CANopen-Status-Indikator as in HBG-18 und HBG-22). For such devices, these LEDs are assigned as follows:

• The 'first LED' (index 0) shall emit GREEN light.
• The 'second LED' (index 1) shall emit RED light.
• Both LEDs (or colour components) together are ORANGE (which some folks say is yellow..)
• Since these LEDs can be driven independently, a complementary bit pattern like 0x55 and 0xAA lets a bicolour LED flash green/red.

system.nv[ 0..31 ]

Accesses one of the 32 'non-volatile values', like the nv-function in the UPT display interpreter. The same restrictions concerning EEPROM cell endurance apply. Details here. Setting a new value as in the following example doesn't immediately 'write' the value into the system's configuration EEPROM, but into a latch:
   system.nv[0] := 12345; // write 32-bit integer into the non-volatile memory latch
To store the contents of the 32 'latches' (integer values) permanently in the EEPROM, and you are really sure that no other nv[]-values need to be set in future, carefully invoke the following command to write the contents of he latches into the sluggish EEPROM (which may take a considerable amount of time, depending on temperature and 'fitness' of the EEPROM chip):
   system.nv_save; // write all modified nv locations into the EEPROM.

See also: Defining the initial values for the nv[]-array in the programming tool,
how to prevent overwriting values in the nv[]-array when loading a new application.

system.reboot

Reboots the system (including a complete hardware reset). Can be used to recover from errors which cannot be 'cured' by other means, for example after the CAN-controller entered the 'bus-off' state.
This command is also used to switch back from any application launched by the 'App-Selektor' into the 'App-Selektor'.
Note: Your script should close any file that it had opened before calling system.reboot.
Otherwise, you may get an error message like
  "System has not been shut down properly - this may damage the memory card".

system.resources

This function is just an aid for debugging. It returns a combined indicator of 'remaining system resources', measured in percent.
The value is the minimum of the following script-related system parameters:

• Remaining stack space (used for local script variables, etc)
• Remaining dynamic memory ("heap") available for the script

If the system resources drop below 10 percent, the script may contain a bug (for example, illegal recursion, allocate too many strings or arrays, etc).
The reason can be examined in the debugger/simulator (memory usage display), integrated in the programming tool.
The function system.resources works the same way in the 'real' target as well as in the programming tool.

system.serial_nr

Retrieves the device's serial number as an integer value.
If a device doesn't support unique serial numbers (stored in an EEPROM), the result is zero.
Example:
    print("Serial Number="+itoa(system.serial_nr,5));

system.shutdown

Forces the system to shut itself down ("programmatically").
This is the script's equivalent for the display interpreter command sys.poff ("power off").
Depending on the hardware and the system configuration, the device can be powered on again (after this) via keyboard, CAN-activity, or via supply voltage cycle. Details are in document Nr. 85115 (PDF), chapter "Power on/off" .
In the bus sleep mode demo, this command is used to turn an MKT-View (II/III/IV) off after 60 seconds without any activity on the CAN bus.
The script may be informed about any kind of system-shutdown, if it contains the OnSystemShutdown handler. The handler will receive the reason for being shut down as an integer parameter (iReason):

      1 = "manual" shutdown (by the operator, via key or shutdown screen)
      2 = automatic shutdown because the supply voltage got too low
      3 = automatic shutdown due to temperature (usually "too hot")
      0 = shutdown for some other reason
     

A simple example for an OnSystemShutdown-handler can be found in programs/script_demos/SystemTest.cvt .

system.temp

Returns the current temperature inside the device, measured in the vincinity of the TFT display (which is the least 'heat-tolerant' unit). It can be displayed on the screen for testing purposes, or copied into a variable for logging, etc.
In contrast to the older display interpreter function 'sys.temp', the script function 'system.temp' returns a floating point value, scaled into °C (degrees Celsius).
Note: The same temperature is also used for the 'automatic shutdown on excess temperature', as explained in a chapter with that title in MKT's document number 85115 .

system.timestamp

Retrieves the system's local timestamp generator value. The same generator also produces the timestamps for the CAN driver, thus by comparing system.timestamp with the timestamp in a received CAN message, you can tell, down to the fraction of a millisecond, how much time has elapsed since the reception of that message. Together with the wait_ms() command, you can also use this function to synchronize the activity of the script.
Example: Send a precisely timed 'answer' for a CAN message :
display.pause := TRUE;  // don't let the display-interpreter interfere for a short time
Tdiff := can_rx_msg.tim - system.timestamp; // timestamp difference between 'now'
                                           // and a certain CAN message reception
Tdiff := (1000*Tdiff)/cTimestampFrequency; // convert to milliseconds
wait_ms(100-Tdiff);    // wait until 100 ms have passed since CAN msg reception
can_transmit;
display.pause := FALSE; // resume normal display operation
Note: This example isn't 100 percent bullet-proof. It only works if this code is executed within 100 milliseconds after the time of a CAN message reception. To mininize the risk of wasting too much time for the display-update, the display should be paused immediately after reception of the CAN message which shall be 'answered'. Remember that the display terminal isn't a programmable logic controller with 'guaranteed' maximum latencies, even if there is a fast pre-emptive multitasking kernel running "under the hood".

The 32-bit timestamp is generated by a hardware timer, which starts at zero during power-on, and then increments at a hardware-depending frequency specified as constant cTimestampFrequency. The timer frequency is typically in the range of 40 kHz, so a signed 32-bit number will overflow from 0x7FFFFFFF (large positive value) to 0x80000000 (very negative value) after about 2^31 / 40000 Hz = 53687 seconds, or 14 hours. Despite that, the 32-bit integer arithmetic (as in the example shown above) will still give a valid DIFFERENCE between two timestamps, even if a timestamp wrapped from 0x7FFFFFFF to 0x80000000 or from 0xFFFFFFFF to 0x00000000 . This is the reason why you must not convert a timestamp into seconds (or any other unit) before calculating a timestamp-difference. First calculate the difference (as in the example above, "Tdiff := can_rx_msg.time - system.timestamp"), then convert the timestamp difference into any unit you like (as in the example, "Tdiff := (1000*Tdiff) / cTimestampFrequency").

See also: programmable timers, timer events, CAN.timestamp_offset, StartStopwatch(), ReadStopwatch_ms() .

system.timestamp_sec

Retrieves the system's local timestamp generator value (system.timestamp), converted into seconds.
In contrast to system.unix_time, the local timestamp generator alway starts at zero when turning on the device. Thus, when stored in a 32-bit float value with a 24-bit mantissa, it delivers a better resolution than the Unix time: After running for 24 hours, the mantissa must store a value of 24*60*60 seconds. Divided by 2^24, the resulting resolution is approximately 5 milliseconds. If a better resolution is required, the timestamp must be stored in a double (64 bit).
The same unit for 'time' ("number of seconds since power-on") is also used when accessing the DAQ unit, and to synchronize the display of Y(t)-diagrams (also for event handlers in the script).

system.ti_ms

Returns the system's timestamp generator value, scaled into milliseconds.
Uses the same internal source as system.timestamp. With a timer clock frequency of 40 kHz (as used in MKT-View II,III,IV), the 32-bit timer rolls over to zero after approximately 2^32/( 40kHz * 60 * 60 ) = 29.8 hours, causing a 'step' in the value returned by 'ti_ms'. After such an overflow, or after power-on, the timer starts counting at zero. It is not affected by the battery-backed-up real time clock.
In the display interpreter, ti_ms is an equivalent function.

system.unix_time

If the system is equipped with a battery-buffered real time clock (RTC), this function returns the system's current date and time in 'Unix Time' format.
The 'Unix Time' aka 'Unix Second' is defined as
      the number of seconds since midnight January 1st, 1970  (1970-01-01 00:00:00)  .
Beware of the "Unix Millenium Bug" (Year 2038 Bug) which will affect any system which (as many of today's Unix / Linux systems) use a signed 32-bit integer to store the Unix Time ! Since November 2018 system.unix_time doesn't return an int anymore, but a double with fractional part and a resolution in the range of a few microseconds.
For details, see the TimeTest.cvt example .
The 'system' (terminal) doesn't care about timezones, so we suggest you let the built-in real-time clock run in UTC (universal time). Only in that case, system.unix_time (and system.unix_time_boot, see below) can really return date and time in UTC, as it should.
See also: time.unix_to_str, Date and time conversions, Modified Julian Date (MJD),
              timestamps in array headers, timestamps for Y(t)-diagrams.

system.unix_time_boot

Returns the system's date and time in 'Unix Time' format, at the time the system (programmable display) was booted, and when the timestamp generator (system.timestamp) was zero.

system.vsup

Returns the device's current supply voltage, measured in Volts.
The voltage is tapped "after the reverse-protection diode" and thus isn't very accurate. The function can be used for diagnostic purposes, for example if the device is powered from a vehicle's onboard DC mains.
In contrast to the older display interpreter function 'sys.vsup', the script function 'system.vsup' returns a floating point number (V).

system.vcap

Similar as system.vsup, but this function returns the voltage at the device's integrated UPS (Uninterruptable Power Supply) when equipped with such.
The unit is Volts. The maximum (for MKT-View II, III, IV) is slightly below 5 Volts when the Ultracaps are fully charged.
In devices without an integrated UPS, this function returns zero.

getkey

Reads the next key from the UPT's keyboard buffer. The same buffer is also used by the display interpreter's kc function (!), so reading a key through getkey also removes it for the 'kc'-function, and vice versa !
If the keyboard buffer was not empty, getkey will return a non-zero value. Usually, this value is one of the key-constants which you can use in a select-case list to implement "handlers" for the individual keys. Note that not all keyboards support all possible keys ... some of MKT's keyboards only have function keys (keyF1 to keyF3), others have only cursor keys (keyUp, keyLeft, keyRight and keyDown) and / or keyEnter and keyEscape (Enter alias "Return", sometimes this key is generated by pressing the rotary button).
For numeric keyboards, use key0 to key9 .
Don't make any assumption about the actual key values, they may be hardware-specific ! Only use the key-constants ! The only value returned by getkey which will definitely never change in future is 0 (zero), which means "no key has been pressed since the last call" .
An example for the getkey function, used in a select-case list, can be found in the test application TScreenTest.cvt , and in the 'QuadBlocks' demo (to control the game via keyboard).
For more advanced control (for example, to detect when a key has been pressed and released), use the low-level event handlers OnKeyDown and OnKeyUp instead.

See also : display (functions), keywords, contents .

Date and Time conversions

The following built-in functions and procedures can be used for basic date- and time conversions aka "calendar" functions :

time.unix_to_str(string format, int unix_date_and_time)

This function converts a date (precisely, date and time in Unix seconds) into a string. The format is specified by means of a format string (first argument), like:
  "YYYY-MM-DD hh:mm:ss"   :   produces an ISO 8601-compliant representation with date and time.
        (without a 'T' between date and time because the 'T' is ugly ... see next example)
  "YYYY-MM-DDThh:mm:ss"   :   would be fully ISO 8601-compliant, but looks ugly
  "DD.MM.YYYY"   :   produces an 'unlogic' date format which is unfortunately common in Germany.
  "MM-DD-YYYY"   :   another 'unlogic' but unfortunately common date format.
  "MMM-DD-YYYY" :   similar but less ambiguous: Three letters (not digits) for the month.
        (MMM, all in upper case, expands to JAN, FEB, MAR, APR, MAY, JUN, JUL, AUG, SEP, OCT, NOV, DEC)
  "Mmm DD, YYYY" :   similar as the traditional american date format, but only three letters for the month.
        (Mmm, mixed upper/lower case, expands to Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec)

We suggest to use ISO-compatible date- and time formats only; especially if you are a German company with customers on the other side of the pond.
What do you, and what would your customer make of 3/12/2001 ? The 12th day of March, or the 3rd day of December ?

Example:
   print("It is now ", time.unix_to_str("YYYY-MM-DD hh:mm:ss",system.unix_time) );

time.date_to_mjd(in int year, in int month, in int day)

This function converts (combines) a date consisting of year (1858..2113), month (1..12), and day-of-month (1..31) into the Modified Julian Date (MJD, defined futher below). The function result ("return value") is the MJD.

time.mjd_to_date(in int mjd, out int year, out int month, out int day)

This procedure converts (splits) a Modified Julian Date number (MJD) into a normal Gregorian date, consisting of year (1858..2113), month (1..12), and day-of-month (1..31) .
All outputs are specified as 'outputs' in the argument list, there is no 'function result' aka 'return value'.

The Modified Julian Date (MJD)  is commonly defined as

  the number of days since midnight November 17, anno 1858  (1858-11-17 00:00:00 in ISO 8601 format) .