Other Commands

#cellread, #cellwrite, #cellerase, #cellcopy (cell operations)

Provide direct read or write access to specified cells of the test program.

Commands Overview

Command	Parameter
#cellread/#cr	{sheet=[string]:}<cell>
#cellwrite/#cw	{sheet=[string]:}<cell><value>
#cellerase/#ce	{sheet=[string]:}from=[string]:to=[string]

Parameter Description

Parameter	Type	Options
sheet	[string]	Source/target sheet name. Default: TEST
cell, from, to	[string]	Source/target cell specification. Cell can be typed directly or like an expression using column names, labels and offsets. Resulting column must be always in range "A" to "AMJ" (1 to 1024 column) and row must be in range 1 to 65536. Review possible cell formats below
value	[string]	Value which will be written into the target cell. If no value is passed, the target cell is cleared. If more than one value is passed, values are first merged together and the result will be written into the target cell.

Review possible cell formats below

Possible cell formats: Direct

• <column-letter(s)><row-number>

• "column-letter(s)" is from "A" (first column) to "AMJ" (last 1024th column)

• "row-number" is from 1 to 65536. Example: B5 - second column, fifth row Direct column with offset

• ($<column-letter(s)>+/-<offset>)<row-number>

• "column-letter(s)" and "row-number" are same like above

• "offset" is an integer number The dollar-sign ("$") must be present here and together with column letter(s) and offset must be surrounded by parentheses. Examples: ($A+2)4 = "C4" ($E-1)6 = "D6" ($B-2)1 => error, because first column is "A" and this expression points before the "A" column

  Using column names and labels

  • (<column-name{+/-<offset>})<label-name>( {+/-<offset>})

  • "column-name" is the name of column, column-names are defined by the first row in the sheet

  • "label-name" is the target label, specified by a column named "Label" in the test-program, label-name can be also a key-word "@this", which means the currently processed row by the funTEST. Label names can be used only on the TEST sheet.

  • "offset" is an optional parameter with the same functionality like above

  Expression can be combined. It means, you can use column name and direct row, or direct column and label-name like a row, etc... Examples: (following examples expecting a "test" label on line 10, "mycol" on column "H" and current line 20) A(test+1) = direct column, using label "test" with offset +1 => A11 (mycol-1)2 = using column name with offset -1 and direct row => G2 (mycol)(test) = using column name and also label, no offsets => H10 (mycol)(@this+1) = using column name and current line with offset +1 => H21 X(@this) = using direct column and current line, no offsets => X20 X(@this) on the line below => X21, etc... ($K+1)(test) = using direct column with offset +1 and label => L10

Examples

Example 1

Command	Parameter
#cellread	X1

Simple read a value from the cell "X1".

Example 2

Command	Parameter
#cellread	(mycol+2)(@this)

Read a value from the cell, specified by column-name "mycol" with offset +2 and currently processed row.

Example 3

Command	Parameter
#cellwrite	X1;"myvalue"

Direct write a value "myvalue" to the cell "X1

Example 4

Command	Parameter
#cellerase	sheet=example;from=A1;to=B5

Clears the cell-range from A1 to B5 on sheet "example".

Example 5

Command	Parameter
#cellcopy	dstsheet=VALUES:srcfrom=W2:srcto=X10:dst=A1:convert=double

Copy the range from W2:X10 from the TEST sheet (no srcsheet argument) to VALUES destination sheet starting the cell A1. Automatic conversion to double will be performed.

#retclear (Clear return values)

Clear a specified range of Return Value and Return Status column in the test-program spreadsheet. This should be usually done at the start of the test-program.

Commands Overview

Command	Parameter
#cellread/#cr	{from=[string]}{;to=[string]}

Parameter Description

Parameter	Type	Options
from	[string]	An expression to specify the starting line of range to be cleared. If omitted, the first row of the test program is used. Possible options: • line number greater than 1 • expression using variable @this or label name and offset using + or - sign
to	[string]	An expression to specify ending line of range to be cleared. If omitted, the last row of test-program is used.

Examples

Example 1

Command	Parameter
#retclear

Clear all return values in the whole test-program

Example 2

Command	Parameter
#retclear	from=@this

Clear return values in the current line (means line with #retclear command) to the end of the test-program

Example 3

Command	Parameter
#retclear	from=10

Clear return values in the fixed line number 10 to the end of the test-program.

Example 4

Command	Parameter
#retclear	from=labelA+5

Clear return values in 5 lines from line labeled "labelA" to the end of the test-program.

Example 5

Command	Parameter
#retclear	from=labelA;to=labelB

Clear return values in line labeled "labelA" to the line labeled "labelB".

#testfile (Test file control)

This command allows you to close, select new, save, or reload a test file directly from the test sequence

Commands Overview

Command	Parameter
#testfile	<parameter>

Parameter Description

Parameter	Desription
close	Closes the currently running test program. At this point, the execution of test-file is broken and no following instruction is executed.
selectnew	Shows up the test-file dialog to select a new test-file. The previous project is used. If no new test file is selected, the "Return Status" = 1 is set, and the following instructions are executed normally. If a new test file is properly selected, the execution of the current test file is broken.
save	Immediately saves the currently running test-file to a hard-drive.
reload	Close and re-open the project, using current test-file. At this point the execution of test-file is breaked and no following instruction is executed.
load{:<project>}:<test-file>{:force=[bool]}	Close current, load and start new test-file by specified name of test-file and optionally project. At this point, the execution of test-file is broken and no following instruction is executed. Force - project to be reloaded, even if it is the same as currently loaded. Default - no

#str (String operations)

Split string by separator(s) to spreadsheet columns/rows. Destination cells are always overwritten.

This command is usually used if the return value of a previous step is a string with multiple values

Example: IR ,PASS ,0,999kV, >50Gohm,T=002,0s

Command #str allows you to extract individual components separated by a separator (in this case ",")separator

Command Overview

Command	Parameter
#str	split/at}{:sheet=[string]}:cell=[string] {:sep0=[string]:..:sepN=[string]}{:rsep0=[string]:..:rsepN=[string]} {:convert=[enum]}

The difference between split and at sub-commands are:

• split output and overwrites cells with the results from split string

• at outputs only one selected components to a return value cellParameter Description

Parameter Description

Parameter	Type	Options
sheet	[string]	Target sheet to store splitted values. Default: TEST
cell	[string]	Target the top-left cell to store values. Absolute or relative format possible, same format like #cellread/#cellwrite/#cellerase functions.
sep, rsep	[string]	Column (sep) and row (rsep) seperator. One of them or both arguments can be used at the same time to split source string to columns or rows or both. There can be multiple (alternative) column or row separators.
limit, rlimit	[int]	Column and row limits. These arguments will limit a max number of columns and/or rows. Default: no limit
convert	[enum]	Automatic conversion of all values. If the conversion is not possible, the source value is passed to the cell. • int - convert to integer numbers • double - convert to double numbers Default: (no conversion)

Examples

Example 1

Command	Parameter
#str	split:sheet=VALUES:cell=A1:sep=";":convert=int

Split Return Value of previous valid step to "VALUES" sheet, starting by A1 cell. Automatic conversion of values to integer will be done.

Example 2

Command	Parameter
#str	at:src="text;to;parse\nnew;row":sep=";":rsep="\n":row=0:cell=0

Returns the value "text".

#catch (Wait for a specified response of device)

Repetitively send the command to specified device and block executing the program until return value match to expected value. When #oninput event occurs, the #catch will break. If any command execution to the device fails, the #catch loop breaks and error message of failed command is passed to Return Value and Return Status set to 1.

Commands Overview

Command	Parameter
#catch	dev=[string]:cmd=[string]:accept=[string]{:accept2=[string]:...:acceptN=[string]} {;timeout=[number]}{;interval=[number]}{;inv=[bool]}

Parameter Description

Parameter	Type	Options
dev	[string]	Target device alias.
cmd	[string]	Command to send to target device.
accept	[string]	Return value(s) of command to be accepted. The #catch command blocks executing the program until any of these strings match the return value. The accept argument supports wild cards (? for any one character and * for any number of characters).
timeout	[number]	Time limit in [ms] to wait to pass all accept strings. If the timeout is reached, the #catch command return status will be one and current state of inputs will be returned. Default: (no timeout)
interval	[number]	Interval in [ms] between executing of IO commands. Default: 100 [ms]
inv	[bool]	Inverts condition defined by parameter accept.

Examples

Example 1

Command	Parameter
#catch	dev="tester":cmd="finish?";accept="1"

Send the "finish?" command to the device with alias "tester" until the command returns "1". There is no timeout.

Example 2

Command	Parameter
#catch	dev="tester":cmd="finish?";accept="1":timeout=5000

Almost the same like previous, but with defined timeout of 5 seconds. If the command will not return "1" within 5 seconds the #catch command is terminated with error - Return Status will be set to 1.

Example 3

Command	Parameter
#catch	dev="com":cmd="read?";accept="PASS"

Wild-card example, the "read?" command is send to "com" device as long until the return value will contain "PASS" sub-string.

#extprocess (Run an external process)

Start a new external process.

This command is used when you need to run external software. This allows you to run 3rd party software without the need of developing dedicated plugin.

Commands Overview

Command	Parameter
#extprocess	start:<filename>{;args=[string]}{;waitforexit=[bool]} {;timeout=[number]}{;nowindow=[bool]} {;redirstdout=[bool]}{;redirstderr=[bool]}

Parameter Description

Parameter	Type	Options
filename	[string]	Path to an executable file to execute
args	[string]	Optional command-line arguments
waitforexit	[bool]	If true, block executing the program until the process exits. Default: false
nowindow	[bool]	Hide the window of executing application. Default: true
redirstdout	[bool]	Redirect process standard output ("stdout") stream. If true, the output is received to internal string buffer. This buffer can be accessed by "stdout" command. Default: false
redirstderr	[bool]	Redirect process standard error ("stderr") stream. If true, the error output is received to the internal string buffer (use the command "stderr" to access). Default: false

Examples

Example 1

Command	Parameter
#extprocess	start:"c:\test.bat"

The most simple use, just start the "test.bat" batch file. No arguments. No output(s) redirecting. No waiting for process exit.

Example 2

Command	Parameter
#extprocess	start:"c:\test.exe";args="-file abc.txt"; waitforexit=true;timeout=3000

Start the "test.exe" process and pass "-file abc.txt" command-line arguments. Command will block the program execution for a maximum of 3 seconds. If the started process will not finish its work in 3 seconds, the Return Status becomes log.1 (error).

Example 3

Command	Parameter
#extprocess	quit

Quit the running process immediately

Example 4

Command	Parameter
#extprocess	running?

Check if the started process is running.

Command	Parameter
#extprocess	retcode

Get return code of last exited process.

Example 5

Command	Parameter
#extprocess	stdout/stderr:read

Access the internal standard output (stdout) or error output (stderr) buffer. To use "stdout" command, the "redirstdout" parameter of start command must be set to true. To use "stderr" command, the "redirstderr" must be set to true.

#get (Get a value)

Using this function, it is possible to access system properties.

Commands Overview

Command	Parameter
#get	<source>:<property>

Parameter Description

Parameter	Type	Options
source	[enum]	Specify property source. Valid values: system, project, teststation, testfile, funtest
property	[enum]	Name of the property. It depends on property source.

Available system properties

Source	Property	Desription
system	tickcount	Get a number of milliseconds since operating system start. Note: "tickcount" is stored as a 32-bit signed integer. It will increment to a maximum positive integer value for approximately 24,9 days, then j ump to to a minimum negative number and increment back to zero during next 24,9 days.
	loggeduser	Login of currently logged user in the OS.
	machinename	Name of the computer.
	winverfull	Full version of the OS, including name, service pack, etc.
	winver	Short version of the OS, format a.b.c.d
funtest	netver	Full name of .NET framework version, used at the compile time.
	ver	Version of funTEST executable
	exepath	Full path to the funTEST's executable.
project	name	Name of currently loaded project
	dir	Directory of currently loaded project file
	path	Full path to currently loaded project file
teststation	name	Name of currently used teststation
	dir	Directory of currently used teststation file
	path	Full path of currently used teststation file
testfile	name	Name of currently loaded test-file
	dir	Directory of currently loaded test-file
	path	Full path of currently loaded test-file Note: when read-only test-files are used, the funTEST returns source path and directory of loaded test-file, not the local working copy

Examples

Example 1

Command	Parameter
#get	system:tickcount

Get a number of milliseconds since OS start, returns for example 45674961, which means the OS is running for about 12 hours, 41 minutes and 15 seconds.