TestController, scripting and programming

This page is a overview about the scripting and programming languages in TestController, it is not directly about how to use them, but how they are implemented and relate to each other.
On the command line all commands starting with # is a scripting commands, commands starting with = are programming statements and commands without are usually SCPI commands.

Contents
    Domains
        Programming
        Scripting
        #scpiCmd
    Usage
        Scripting
        Programming
        #scpiCmd
        #scpiCmd name #pgm#
Main page
Functions for use in calculator and definitions
Another documentation for the programming language, not related to TestController
Script commands


Domains

Programming

There is a a couple of main items used to to implement the programming language:

• VarList, this code handles variables in a thread safe way, it can handle arrays and structs in any depth. Any variable in TC is in a instance of this list and is usually access through a instance of Execute.
• Execute, the actual programming language processor, each instance will include a instance of VarList and have access to the global VarList, there may also be access to some parents VarList (Depends on how the actual Executor is instanced). This can be invoked in multiple ways, in TC two ways are used:
  • Expressions: This only allows a single expression that usually must return a value, this is used in most places in TC.
  • Statements: This allows full statements and programs to be processed, this can only be used in a few places in TC.
  There is usually many instances of Execute active in TC, each withs its own VarList and absolutely no connection to each other.
• FunctionList, this list contains as standard 100's of functions for a lot of stuff, but none specific for TC, they are added by TC.

Scripting

The scripting (Commands starting with #) is a module called CommandProcessor and is part of TestController, it always include a instance of Execute that can be invoked by using parenthesis (). The CommandProcessor sends all lines starting with = to Execute and lines without either to the selected SCPI device.
Execute can also be invoked by starting a line with =
To redirect all lines to Execute, use the command #Calc, this is terminated with a line containing #
It is possible to start a new instance of Scripting with #RUNSCRIPT or #RUNSCRIPTASYNC, in the first case the current script is stopped until the started script is done, in the second case they will run in parallel. These extra instances do not open a window, but will process the supplied commands in the background.

There is usually only one instance of CommandProcessor and that is the one controlling the command line in TC, starting a script will start a second instance. Running multiple scripts in parallel will start multiple instances (And each contains its own instance of Execute and VarList).



#scpiCmd

In some definitions it is possible to use #scpiCmd, the handler for that is part of the device driver, this means there are a multiple definitions for #scpiCmd, because the code is replicated in each driver, this also means there may be minor differences between them.  All #scpiCmd in a definition shares one common instance of Expression (Only for one device, multiple of the same device will get separate instances), this means they share their variables.
This is not part of the programming language (i.e. Execute), but a separate definition, that has access to Execute, like other stuff in the definition file.
Scripting cannot be used in definitions, except by using the Execute function runScript/runScriptAsync



Usage

Scripting

This is designed to do all kinds of task in TC, nearly anything that can be done from menus can be done with these commands, they can also do some stuff that is not supported from menus.

Some usages for scripts

• Restore to some specific configuration TC. Use popup menu in log window and select generate scripts, layout to generate a restore script, there is no reason to write it manually.
• Configuring a couple of connected devices. Use popup menu in log window and select generate scripts, Mode & Setup to generate a script, there is no reason to write it manually.
• Automate testing, this generally requires writing a script manually, but the popup "Log Event" can be converted to a script with popup menu (in log window) log event as script.
• Recreate a specific grid panel. Use popup menu in log window and select Grid panel when the grid panel is designed, there is no reason to write it manually.
• Setting up a specific chart layout. Use popup menu in log window and select chart layout to generate script for actual chart layout.
• Automate repetitive tasks, these will often require writing a script manually.

It is possible to save scripts for use as menu items in the popup menu in the log window, this way it is fast and easy to perform the above tasks.
When invoking extra instances of scripting it is required to select a device before doing any SCPI commands, this is done by a line with the device handle followed by a colon :



Programming

This allows more complex programming, but the access to specific TC functions and values is very different than scripting, to compensate for this it is possible to launch a instance of Scripting, it is also possible to launch other instances of Execute for some parallel processing or for reading a program from a file. Another possibility is to define new functions that can be used from all instances of Execute.
Neither variable or defined functions will be saved when TC is stopped and must be defined over at next restart (This can be automated by using/creating the file autorun.txt in ../Settings).

Mostly programming is useful in device definitions to handle transforming special values to something TC can handle and to support some advanced functions (Fetching logs and screen dumps). The more simple aspect of it can be used as a advanced calculator from the command line or the Calculator popup.



#scpiCmd

The purpose of #scpiCmd is to make fairly simple SCPI like commands from more complex commands. The more complex commands are mostly when using non-SCPI devices and some internal TC commands must be used.
The Expressions can be used to add parameters after the command, in its simplest form as (value), this will invoke the Expressions that will fetch the variable "value" and return it, but because it is Expressions doing it a lot of other stuff is possible like (value*5), (value==0?"-":value)
To define and set a variable the :setvar: tag must be used. To process the answer or input value use the :readmath: tag (:readmath is always performed after communication with the device).



#scpiCmd name #pgm#

This is a special version of #scpiCmd that makes it possible to do a full block of Expressions statements, i.e. a program. This has to use function calls (deviceWrite()/deviceRead()) if any device communication is required, there is no implied communication.
Like any commands the name must end with ? to get any value back, i.e. #scpiCmd name? #pgm# is expected to return a result, #scpiCmd name #pgm# is not and cannot.