Skip to end of metadata
Go to start of metadata

This page describes the parser command, meaning the commands controlling the parser execution. Parser commands always start with a “!”. Note, that all other commands are submitted to the main command queue of the openBEB core program.

openBEB 3

Icon

openBEB 3 introduced changes and additional commands. Most important changes, which should be backwards compatible:

  1. Variables are now 1-dimeninal arrays.
  2. New commands to handle arrays (not implemented yet): !push, !remove, !doForElements

Including submacros

!include

The !include statement embedds an other macro. It is similar to the macro command used in the CORE program to start a macro.

Usage

!include::macroname[::parameter=Value]

  • macroname: name of the macro you want to include (macro name without the .macro extension)
  • Parameters (optional): A “::” separated list of parameters you want to pass with the "key=value”

Example

Icon

If variables are provided by the input command, they are not stored in the stack specific to the sub-macro, but in the actual stack of the calling macro.

Icon

A submacro calling itself will result in a endless loop!

Maco modules

!macroModule

Creates a macro module you can address using !tellmodule commands.

Usage

!macroModule::"ModuleName"

  • ModuleName: Unique module name. Use this name to send commands to using !tellmodule::"ModuleName"

More information and commands of macro modules are given on this page.

Variable commands

Every macro can have a stack of variables filled with values. In openBEB version < 3, every value is a single value. For openBEB version higher than 3, every named variable is an array.

Variables in openBEB 3 and higher

Icon

In openBEB 3 and higher, variables are always arrays of values. The implementation should be backward compatible.

 

Only commands directly accessing stack variables are listed here. You can retreive values with {name} in the macro. Starting a macro, variables can be passed with macroname::variablename1=value1::variablename2=value2.

Icon

Every macro started has its own stack. If you restart the same macro again, you have access to the stored variables again. If you include macros using the !include command, the submacros have access to the stack.

!store

Stores a value under the corresponding name in the macro stack. Note, if the variable already exists, the value is overwritten with the new one. Use !default if you want to prevent the overwriting of existing variables.

openBEB 3

Icon

openBEB 3 stores variables as arrays. You can store an array by separating the elements by a ";" (semicolon).

Usage

!store::name=value

  • name: Variale name, under which you can retrieve the value in a macro. Use {name} in the macro to get the corresponding value
  • value: Value you want to store, can be string or numbers. for arrays (openBEB 3 and higher), you can create an array directly by separating the elements by ";", e.g., 1;2;3

Example:

!push

openBEB 3

Icon

Starting in openBEB version 3.

Appends an element to a variable. Existing values in the variable array are not changed!

Usage

!push::name::value

  • name: Variale name, under which you can retrieve the value in a macro. Use {name} in the macro to get the corresponding value
  • value: Value you want to append

Example:

!CreateArray

openBEB 3

Icon

Starting in openBEB version 3.

Creates an array as a variable. Existing variables with the same name are deleted.

Usage

!createArray::name::size

  • name: Variale name, under which you can retrieve the value in a macro. Use {name[index]} in the macro to get the corresponding value.
  • size: length of array (number of elements).

Example:

!generate

openBEB 3

Icon

Starting in openBEB version 3.

Creates a a random variable.

Usage

!generate::name::stringsize[::arraysize]

  • name: Variale name, under which you can retrieve the value in a macro. Use {name[index]} in the macro to get the corresponding value.
  • stringsize: Number of ASCII symbols.
  • arraySize: Length of array stored in variable. Optional. If now value is provided a single random string is stored.

Example:

!replace

openBEB 3

Icon

Starting in openBEB version 3.

Replaces a subset of an array stored in a named variable.

Usage

!replace::name::start::values

  • name: Variale name, under which you can retrieve the value in a macro. Use {name[index]} in the macro to get the corresponding value.
  • start: First element to be replaced
  • arraySize: Semicolon separated list of values. The length of the part which will be replaced is detemined by the number of list entries.

Example:

!delete

Deletes the named variable.

Usage

!delete::name

  • name: Name of the variable to delete

Example

!deleteArraySubset

Deletes a subset in the array of a variable.

Usage

!deleteArraySubset::name::Start[::Size]

  • name: Variale name to look for
  • Start: First element to be deleted
  • size::Length of subarray to be deleted (optional)

Example:

!default

Looks for the variable with the name. If not found, a new variable with the name is stored using the default value.

Usage

!default::name=value

  • name: Variale name to look for
  • value: standard value you want to store

Example:

!showstack

Showstack displays a dialogue with all variables stored in the current stack. Note, that every macros has it’s own stack. This command is for debugging purpose.

!deleteStack

Deletes the stack of the currently executed macro. Note, that this does not affect parameters provided at the macro start-up.

Calculations

!calc

With !calc, simple calculations can be performed. It uses the standard formula node of labview to perform calculations. The syntax can be looked up here. However, the formula must fit on one line. A semicolon “;" is automatically added at the end of the command.

Usage

!calc::variablename=expression[:: precision]

  • variablename: Name the variable to store the result in
  • expression: Formula to evaluate. This formula can use variables in {}.The formula only can be one line maximally, see here for the syntax.
  • precision (optional): Give the precision for the results stored in the variable. Standard is 6 significant digits.

Example

 

User interaction commands

!ask

A modal dialog is presented with information. There is is an OK button and an abort or cancel button.

Usage:
!ask::question[::button1::button2::variableName]

  • question: Text string with the question you want to ask.
  • Button 1 and button 2: (optional)  label of buttons in the dialog window.
  • vriableName: (optional) Variable name to put the label of the pressed button into
Icon

A variable name is only stored if button 1, button 2 and variableName are defined.

Example:

!input

A modal dialog is presented requesting an input. The answer is stored in the stack with the name variablename. There is is an OK button and an abort or cancel button.

Usage:
!input::request::variableName

  • request: Text string with the question you want to ask.
  • variableName: variablename to store the answer in the stack

Example:

Flow statements

!do

Executes a block of commands in a loop. A block is indicated with a “.” at the beginning of the line (or several).

Usage

!do::X::variablename

  • X: Number of times a loop should be repeated
  • variablename: Name of variable to store the round index (starting at 0)

Example

 

!If

If statements have following form:

Example

Comparators

Strings and numbers must use different sets of comparators! Following comparators are implemented:

comparator

Description

==

Equal to, ==, only for number. Gives wrong results for strings!

=Compares two strings. Might give wrong results for numbers!

<

Smaller than (numbers)

>

Larger than (numbers)

=>

Larger or equal (numbers)

<=

Smaller or equal (numbers)

!==

not equal (numbers)

!=not equal (strings)

Example:

!moduleexist

Tests if a module exists or not (openBEB version 2.81 and higher).

Usage

!moduleexist::modulename[::TRUE/FALSE]

  • modulename: Name of module to be looked for
  • TRUE/FALSE:  If TRUE, he following block is executed, if FALSE, the following block is executed if module dies not exists. Standard is TRUE.

Example

!breakif

Breakif stops a loop if the conditions are true. This only affects the current block. For a list of comparators, see this table: #Comparators 

The condition testing is identical to the !if statement.

Example

!execute

Executes command line commands. The output is stored in variables.

Icon

openBEB version 2.8 and higher only.

 

Usage

!execute::commandPath::outputName[::Standardinput::workingPath::wait?::Minimized?::Buffersize]

The following description, is partially taken from the LabView help. Tip: Use variables to call this function.

  • CommandPath: command LabVIEW calls to run a program. If the executable is not in a directory listed in the PATH environment variable, the command line must contain the full path to the executable. (Windows) To use a command that must be executed directly from a command prompt window, insert cmd /c before the command.
  • Standardinput: standard input is the text to pass to the command line as standard input. Can be empty.
  • Following parameters are optional:
    • WorkingPath: Provides the working directory; the file system directory from which you want to execute the command. Can be empty.
      Note Do not use working directory to locate the executable you want to run. working directory applies to the executable only after it launches.
    • outputName: Name base to store the output of the system call. Important note: Wait the system call to complete. Following macro variables are created:
      • outputName_stdOut: Standard output returns information from the program you called if wait until completion is TRUE. If wait? (see below) is FALSE, System Exec returns an empty string.
      • outputName_stdError: Standard error returns errors from the program you called if wait until completion is TRUE. If wait? (see below) is FALSE, System Exec returns an empty string.
      • outputName_ErrorNum: return code indicates the system-dependent exit code that the command returns.
    • wait?:
      • 1 for TRUE: The parser waits until system command is completed before proceeding (standard and recommaned). Standard output and standard error are available when the command finishes running.
      • 0 for FALSE: The command is started and the parser immediately proceeds. The command runs in the background and its input and output are not available.
    • Minimized?: Only affects windows
      • 1 for TRUE: command prompt is not shown.
      • 0 for FALSE: Command prompt is shown.
    • Buffersize: Expected buffer size of output, to improve memory efficiency. Use a number slightly larger than the output size you expect. The command runs if you exceed this size, but  memory usage is less efficient. The default is 4096.

Example

Addressing modules, synchronization, requesting information

Icon

To avoid interferences with other macros or user interactions use semaphores at the beginning and end of a macro!

!tellmodule

Send the subsequent block of commands to the addressed module. Note, that these commands are directly send to the corresponding module. Be aware of race situations, use !waitmodule if needed. If you do not specify the addressed module, the commands are send to the core queue.

Usage

!tellmodule::Modulename

Modulename is the queue name of the state-meachine (here called module).

Example

!tellviewport

Sends the following block of commands to the active viewport. Similar to !tellmodule.

openBEB 3

Icon

!tellviewport is obsolete in openBEB version 3.

 

Usage

!tellviewport

Example

!Semaphore

Acquires or releases semaphores to send commands to a module. Best used at the begin and at the end of a macro to lock resources and avoid race conditions with other macros or the user interface.

Usage

!semaphore::mode[::modulename]

  • mode:
    • acquire: Waits until the resource is free and acquires a semaphore for the module.
    • release: Releases the semaphore and gives the resource free for other processes.
    • status: Prints the Semaphore status for debugging into the log file.
  • modulename: (optional) name of the modue to acquire or release the semaphore. If no module-name is provided, the module of the current macro-block is taken.

Example

!rendezvous or rendezvous

Creates a rendez-vous between different modules and/or parser.

rendezvous with or without!

Icon

If you use the rendezviud command without "!", the command is send to the active module. If you use it with "!", the rendezvous is performed in the parser!

 

Usage

!rendezvous::RendezVousCommand::Name::Parameter

  • RendezVousCommand: Command to perform
    • create: creates a rendezvous
    • resisze: Resiszes an existing rendezvous to the given size
    • wait: Waits for an rendezvous
    • destroy: Destroys a rendouvous. Triggers an error, if an other module is waiting for the rendezvous!
    • debug: Prints the status of the rendezvous with the name to the log-file
  • Parameter: The parameter depends of the RendezVousCommand
    • create and resize: Size of rendezvous
    • Wait: Timeout time in ms. −1: No time-out, standard is 30000ms 

!waitModule

Creates a rendezvous request at the end of the module queue. Is important for synchronization of parallel running tasks.

Usage

!waitmodule[::modulename::timeout]

  • modulename: name of module to wait for (optional)
  • timeout:Maximal wait time for notifier conformation in ms (optional) standard is 5s. -1: no maximal wait time.

If you do not provide a modulename, the notifier request is send to the actual module the block is ececuted in. Use !tellmodule to se the target module. If you did not spcify a target module (and did not provide a target module as parameter), the notifier request is send to the core module.

Example

!Get

Requests information from the current module. For openBEB metadata, see also this page.

Usage

!get::NotifierName::InformationRequested[::index::timeout]

  • NotifierName: Name of notifier name used in the subsequent waitNotifier command
  • InformationRequested: label of the information you asked for. See table below.
  • index (optional): index number for information you requested from an array. Depends of the information you requested.
  • timeout (optional): Timeout time in ms. If not provided, the standard time-out of the settings is taken.

Example

!sendNotifier

Sends a notfier and waits for response. The response can be stored in the macro stack.

Usage

!sendNotifier::Name::Message::TimeOut::StoreAnwerFlag

  • Name of notifier: This name will be also used to store the anwer in the macro stack (if requested)
  • Meassage: Message you want to send along with the notifier
  • Time out: Wait time for confirmation before triggering a warning in ms
  • Store answer flag (0 or 1): The confirmation can contain an answer, the flag indicates if this answer should be stored or not (0: no stored, 1: stored)

!WaitNotifier

Waits for an notifier. The notifier message can be stored. When the notifier is received, a conformation is send back (can contain a message). Upon request, the notifer message received can be stored in the macro stack.

Usage

!waitNotifier::Name::TimeOut::Message::StoreAnwerFlag

  • Name of notifier: This name will be also used to store the anwer in the macro stack (if requested)
  • Time out: Wait time for confirmation before triggering a warning in ms. use “standard” to take over the standard time set in the CORE preferences.
  • Meassage: Message you want to send along with the conformation notifier
  • Store answer flag (0 or 1): The confirmation can contain an answer, the flag indicates if this answer should be stored or not (0: no stored, 1: stored)

Pathmanipulations

Note that paths are platform specific. Do not store paths in macros which must be used on different platforms.

!askPath

asks for a path of an existing folder or file

Usage

!askPath:: prompt:: pattern::variablename

  • prompt: Text prompt in the file selection dialog
  • pattern: File-pattern, e.g. *.tif for tif files. Can be a semicolon separated list
  • variablename: Name of the variable to store the path in.

!pathFilename

Gets the filname (last path part) of a path and stores the name in the stack.

Usage

!pathFilename::variablename::path

  • varialename: vriablename to store the filename
  • path: Path

Example

!pathBuild

Extends a path with a filename or a relative path

Usage

!pathBuild::varialename::basePath::relativePath

  • variablename: Name of the variable to store the results in
  • basePath: Path which a relative path should be appended
  • relativePath: Relative path or filename to add

Example

!pathCompare

Compares two pathes.

Usage

!pathCompare::name1::name2:: path1:: path2

  • nam1: Variable name for the common path
  • name 2: Variable name for the path from path1 to path2
  • path 1: Path 1
  • path 2: path 2:

Example

Varia

!wait

Waits for a specified time. Best to use after synchronization command, such as !waitmodule.

Usage

!wait::X

  • X: Wait-time in ms.

Example

!logComment

Writes a comment into the log file.

Icon

New in openBEB version 3.

 

Usage

!logComment::logtext

  • logText: Text to be written into the log file

Example

The log entry looks as follows:

  • No labels
Write a comment…