Skip to end of metadata
Go to start of metadata

Macro command structure

The language is case insensitive and consists of a list with “::" separated items and parameters. The language can dynamically address different modules, which can be provided by plug-ins. There is no obvious discrimination between commands, subcommands and arguments in version 1 of the macro language. 

Special characters:

character

description

#

Indicates comments. must be the first character of a line

!

Commands for the Macro-interpreter and macro-primitives. These commands are used during runtime.

{variable}

The {} indicate the name of a variable in the stack. In openBEB 3, a variable is an array of elements. Individual elements can be accessed by {variable[index]).

[index]openBEB3 and higher. gives the index number of a array in a variable. Index starts with 0.

.

Indentation of blocks. E.g. after a !if statement

@Commands starting with an “@“ suppress log file entries.

Macro commands are send to the core state machine. If the core state machine does not understand a macro, it looks for the corresponding plugin-in to pass it to. If it does not find a plg-in, error 5018 is triggered.

Parameters and variables

You can pass parametres when starting a macro:

macro:Macroname::paramer1=value1:: parametrs2=value2

In the macro, use {parameter} to indicate the paramter you passed during macro start. The parameters are stored in the macro stack.

During run-time, you can define variables with the parser commands !store, !default or !push. In maros, variables are indicated with {variable} statements. Variables are stored in the stack. The highest level macro has its own stack and cannot be accessed by other macros. However, this stack is passed to the included submacros using the !include command.

openBEB 3 arrays

Icon

In openBEB 3 and higher, variables are arrays of element. A specific element i can be accessed by {variable[i]}. Furthermore, variables can be nested.

 

Macro blocks

Blocks are subunits of a macro. In the macro, they are indiacated by a point “.* at the begin of the line. Blocks can be nested.

A block starts with a flow statement:

  • !if
  • !do
  • !tellmodule

Also including a submacro using the !include statement starts a new block.

You can stop the execution of a block using the !breakif command (not recommended)

Icon

A submacro calling itself will result in a endless loop!

Macro pragmas

Pragmas are pre-excecution instructions and control the way macros are executed. Currently, two pragmas are implemented (not the different notation style of pragmas):

Version 2.8.1

Icon

The debug anbd waittime pragma were introduced in CORE version 2.8.1

PragamaParamatersDescription
pragma.version()Macro parser version numberSets the macro-parser version number to interpret the macro. If pragma.version is not given, the latest macro-interreter is used. Note, currently only macro interpreter version 1 is available.
pragma.debug(#)

2: Debug mode with stepwise execution
1: Debug mode
0: Standard mode

Sets a flag, if a small parser window is displayed, which allows the Termination of the macro. Mode 1 displays a window and automatically sends the macro commands to the corresponding modules. Use pragma.waittime to set a wait-time between each line during execution. Mode 2 allows step by step execution of a macro.
pragma.waittime()Wait time in msSets a minimal wait time between sending of commands to the modules. Note, this setting does not replace coordination operations (rendez-vous, semaphores) in macros!
pragma.ManualErrorHandle()2: Manual error handling.
1: No manual error handling.
0: Take over CORE setting.
Mode 2 starts a graphical error handler. Mode 1 suppresses manual handling.
pragma.sendErrorMail()2: Send mail.
1: Do not send.
0: CORE settings.
 
pragma.resetCommandQueues()2: reset.
1: No reset.
0: CORE settings.
 
pragma.errormacro()macronameAfter error processing, the rescue macro named "errormacro" is started. You can pass parameters using erromacroname::val=xxx to the macro. Note: The error code is automatically passed to the errormacro and stored in a variable called errorcode.

 

Modules

Modules are standard “queued state-machines” used in openBEB combined with semaphores. The CORE “queue” is one module, an other example is the current viewport. Plug-ins can provide additionally and arbitrary number of modules. To be classified as module, the state-machine must understand a minimal set of commands. See here.

In  macros, you must specify the target module. If the target module is not known, an 5022 error is triggered. The name of the queue of the state-machine is the module address. If yopu do not specify a target module, the commands are senfd to the core program. Important: Internally, module names are always small letters.

Be aware of race situation if you depend on the outcome of one of the module queues. In a module itself, the commands are executed one after the other. Between modules, theere is no direct synchronization! Use !waitmodule and !semaphore commands, or notifiers respectively, for the synchronization between different modules.

 

  • No labels
Write a comment…