Preprocessor Directives

Preprocessor directives

Preprocessor directives can be used to influence the functions of the Math Module Compiler, the processing of variables, and the execution of the code. Preprocessor directives must be at the beginning of a line in the formula text and end with the first line break that is not hidden in a bracket level. Comments can be inserted according to known rules.

The directives are identified by a # character followed by an identifier. Which parameters follow the directive and how they are formatted depends on the function. Possible formats are, for example:

#directiveA <parameter>
#directiveB <name>[<parameter>](<parameter>){<code>}
#directiveC <key>, <key>=<value>, …

Insert formula text "#include"

This directive can be used to insert formula text from a resource or an external file. The syntax used determines which source is addressed.

#include "aResource"
#include 'aResource'
#include <aFile>

The resource specified as a string is transferred to the source code, taking into account the decoder specified there, or as text.

The file specified in <...> is included in the source code. Absolute and relative paths are permitted, whereby relative paths are searched for starting from fixed directories (search paths). Elements in %...% are replaced by the corresponding value of the environment variable.

Search paths under WINDOWS:

%USERPROFILE%/mm_lib/
%LOCALAPPDATA%/optimeas.osg.com/mm_lib/
%APPDATA%/optimeas.osg.com/mm_lib/

Search paths under LINUX/YOCTO:

/sdi/config/mm_lib/
/sdi/apps/smartcore/mm_lib/
/var/lib/mm_lib/
/usr/local/lib/mm_lib/
/usr/lib/mm_lib/

Remove time reference "#timeless"

To remove the time reference from certain input channels for the Math module, the #timeless directive can be used. The channel names can be passed to the directive in a list separated by commas. If the names contain characters other than those permitted for an identifier, they must be enclosed in '...' or "...". The use of the $'...' syntax is not permitted, as only one attribute of the channel is set here.

#timeless <varName>, <varName2>, ...

note

The same function is activated or deactivated via the #property macro with the property timeout=<bool>.

note

A similar functionality is provided by the value() function for specific, local use in formula text.

Basis: Real-time data processing and timeout

As described in the introduction, the Math module always processes data from the various smartCORE sources in a timely manner. This ensures that, for example, a current and voltage signal are correlated with each other for the calculation of power.

However, there are also data sources that only provide new values extremely rarely. These can be, for example, measurement data from a weather station, which may only be queried every 10 minutes and written to the smartCORE channels, or data from a timetable that is only queried and updated once a day by a server.

Data transferred from smartCORE to the Math module times out after an adjustable time interval and is then reused with this time offset and the last pending value, even though its validity has not been confirmed by more recent measurements or queries. As a result, all dependent calculations are still executed in a timely manner, but with this time delay.

The timeout interval is defined by the global parameter inputTimeoutS and can be overwritten individually for a channel using the #property macro and the property timeout.

This delay can have adverse effects on the display of MQTT data in the cloud or on control tasks.

With the functions

can be used to query the various states of an input variable. If no smartCORE channel could be connected or if this channel does not yet provide any data, a default value is assigned, which can be set using the macro #property <channel>, default=<var>.

What does the `timeless` attribute do?

Input channels marked as timeless are always valid from the beginning to the end of the respective calculation interval evaluationTimeMs relative to the respective system time.

Timeless Schema

In the example shown, the formula set is calculated at times $t_0,$ $t_1$ and $t_2$ . Up to time $t_0$ , only the value $y_0$ was set on the channel. Up to time $t_1$ , the signal source provides the data points $y_1,$ $y_2$ and $y_3$ . The data points $y_4$ and $y_5$ are not produced until time $t_2$ , even though their timestamp is before $t_1$ .

The data set immediately preceding the channel is always used for the beginning of the interval, regardless of how old it is. For the interval $]t_0,t_1]$ , this is the data point $y_1$ , and for the interval $]t_1,t_2]$ , it is the data point $y_5$ .

If new data values happen to fall within the current calculation interval and have already been entered there in time, they are taken into account with their timestamps. For the interval $]t_0,t_1]$ , these are the data points $y_2$ and $y_3$ .

The validity of the most recent data set available (here $y_3$ ) is automatically extended until the end of the interval (here $t_1$ ), so that this channel ultimately cannot delay any calculations that depend on it.

warning

The price for this is that short signal changes that lie within this extended validity range may no longer be included in the calculations. In the example, the data point $y_4$ is "overlooked" because it lies in a time interval that has already been supplemented by the automatic mechanism. However, assuming and requiring that these channels rarely provide data, this should not be a problem.

Setting properties of a variable "#property" ¹

This preprocessor directive can be used to set properties and meta-information for an input or output variable.

#property <channel>, <key>=<value>, ...

Argument	Type	Description
channel	`<str>`	The channel name must be specified as the first argument. If it contains special characters such as spaces or commas, it must be enclosed in quotation marks. The use of the `$'...'` syntax is not permitted, as only channel properties are set here.
key	`<str>`	The name of the property, see table below
value	`<var>`	The new value of the property (variant)

The following table lists the possible and permitted properties and their values:

Property	Type	Description
`default`	`<var>`	The `default` value assigned to a variable until the first data values arrive from the smartCORE channel. This makes it possible to respond to delayed data streams in the Math module.
`timeout`	`<dbl>`	Individual timeout value for this channel, overrides inputTimeoutS
`timeless`	`<bool>`	This enables or disables the timeless feature for this channel. This corresponds to the macro `#timeless`

Definition of functions "#define"

Under Construction This function is in preparation.

#define <newFunction>(<argsList>)[<options>]{<code>}

Debug information "#dump"

warning

For Debugging Only This preprocessor directive is intended solely for diagnostic and development purposes. It produces a large amount of informal output in the smartCORE log file and should therefore only be used for short periods of time.

The parameter of the #dump directive is a comma-separated list of keys or key-value pairs and affects the subsequent formula text:

#dump <key>, <key>=<value>, ...

Key	Value	Description
tree		Outputs the translated object tree. See below for interpretation.
node	`<uint>`	Adds a specific object node for continuous monitoring (², ³).
var	`<str>`	Adds a regex expression to select channel names whose accesses are to be logged (²)
trace	`<enum>`	Enables data flow output for - in inputs, - out outputs, or - io both data directions.
clear		Clears all dump settings for the following code section.

Examples:

#dump tree
#dump node=5, node=9
#dump var='Temp.*', trace=out

Output of the object tree

The output of the object tree using #dump tree provides detailed information about the functional relationships of the defined formula set. The evaluation is reserved for expert optiMEAS employees.

        +---o   [0]: sequencer, bareImpl, op: ';' listOfArgs
            >   out: nullptr
            +---o   [1]: operatorNode, followInputs, op: '=' orderR2L
            |   >   out: { n:'duration', s:[upLnk, wrVar], *rd[0], *wr[1], h:'=', empty}
            |   +---o   [2]: operatorNode, followInputs, op: '*' orderL2R
            |   |   >   out: { n:'', s:[upLnk], *rd[1], *wr[2], h:'*', empty}
            |   |   +---o   [3]: varPoolSource, followInputs
            |   |   |   >   var: { n:'wv2', s:[rdVar], *rd[3], empty}
            |   |   |   >   out: { n:'', s:[upLnk], *rd[2], *wr[3], empty}
            |   |   +---o   [4]: constValueNode, constValue
            |   |   |   >   out: { n:'', s:[upLnk, const], *rd[2], *wr[4], [1]={t: INF, d: TrustedTimestamp }, [0]={t: 0, d: (cScalar, cInt) 59}}}

Trace outputs for a data flow connection element (out: or var:, channel or TS_Stream) have the following compact structure:

{ n:'duration', s:[upLnk, wrVar], *rd[0], *wr[1], h:'=', [9]={t: 48, d: (cScalar, cDbl) 54.978065}, ... [0]={t: 20, d: (cScalar, cDbl) 0.000000}}}

In this context:

Abbreviation	Flags	Description
`n:'...'`		The name of the channel, if it is a variable
`s:[]`		Status flags of the channel
	`upLnk`	Up link, connection from a subnode to the parent node
	`rdVar`	Read variable, input variable, provided by smartCORE and read only
	`wrVar`	Write variable, output variable, can be fed back into smartCORE
	`inz`	Initializer, has an initializing node
	`const`	Constant value, the value does not change during runtime.
	`discr`	Discrete evaluation, this channel is calculated in discrete sampling steps
	`ev@0`	Evaluate at Start, the discrete channel has been initialized
	`evDT`	Evaluate Delta-T, a sampling step has been calculated for the discrete channel.
	`expl`	Explicit name, variable has been defined using the $'…' syntax and must exist in smartCORE.
	`fldE`	Field element, channel feeds a specific data field in a multidimensional structure (vector, matrix, etc.)
	`priv`	Private, a variable that was created by a function block and is used exclusively by that function block
	`prop`	Additional properties were set on the variable with `#property`.
	`noT`	noTime, this channel has been marked as #timeless and is always valid until the end of the calculation interval.
	`+=dT`	Channel has constant time offset from `shiftT()`
	`nRec`	NoRecursion, this variable must not be used in a recursion loop.
	`toVal`	Property `timeout` assigned
	`fdVal`	Property `default` assigned
	`noCh`	This channel could not be connected to a smartCORE channel as input. => Default assigned as constant value. See also `isConnected()`
	`TOut`	Timeout for input data if the channel is still empty (`noD`) or has not been marked as `#timeless`. See also `isTimeout()`
	`H1`	Explicit linear interpolation allowed (1st-order hold)
	`:=fd`	The `default` value was written to the channel, see also `#property <channel>, default=<var>`
`*rd[]`		The indices of the object nodes that access the channel in read mode
`*wr[]`		The index of the object node that accesses the channel in write mode
`*@0[]`		The index of the object node that performs the initialization of the discrete channel.
`h:'...'`		Reference to the function of the writing node, e.g., '*' or 'sin(…)'
`[n]={}`		The stored sample at the most recent position n (corresponds to the number of entries - 1) with...
	`t:`	Timestamp in ns since 01/01/1070, INF (infinite) or NAV (not available)
	`d:`	Data value with (structure, type) value or TrustedTimestamp, i.e., the preceding value remains valid until this point in time. The point in time can grow monotonically in each calculation interval.
`[0]={}`		The stored sample at the oldest position (optional)

Track calculation process "#monitor"

Monitoring the internal buffers "#warn"

For Debugging Only WARNING! This preprocessor directive is intended for diagnostic and development purposes only. It produces a large amount of informal output in the smartCORE log file and should therefore only be used for short periods of time. In addition, this option generates additional CPU load and may only be used temporarily under observation !!!

The parameter of the #warn directive is a comma-separated list of keys or key-value pairs and affects the following formula text:

Key	Value	Description
maxbuflen	`<uint>`	Monitors the maximum number of data records in a data queue. A warning is issued if the limit is exceeded. The limit is raised by 25% of maxbuflen for the following message.
timeout	`<dbl>`	Monitors the time interval between the first data sample and the execution time. A warning is issued if this time is greater than the value set in s.
clear		Deletes all warning settings for the following code section.

Examples:

#warn maxBufLen=10, timeout=1000
// Formula text for monitoring
#warn clea

Available from catalog version 10. ↩
Option can be specified multiple times. ↩ ↩²
Node numbers from the object tree ↩