Control Unit Scripting Engine

The Control Unit Scripting Engine bundle executes a script from a given file or text command line, that holds the description of control units actions and state variables. The script performs a check if the described actions are properly executed, and monitors the state variables values. If an error occurs, the script stops and notifies about the error that is came out.

Contents:

Bundle Information
- Bundle JAR
- Import
Pluggable Commands
Console Commands
Script Commands Syntax Description

Bundle Information

Bundle JAR

The JAR file of the Control Unit Scripting Engine bundle is cu-script.jar, and is located in the bundles folder.

Import

Package	Exporter	Description
`org.osgi.util.tracker`	OSGi Library Bundle	The OSGi Service Tracker utility.
`org.osgi.service.metatype`	OSGi Library Bundle	The OSGi Metatype for definition of metadata.
`org.mbs.services.metatype`	ProSyst Metatype Bundle	The Metadata Manager service for management of metadata.
`org.mbs.services.cu`	Control Unit Admin Bundle	The Control Unit Admin service for management of control units.
`com.prosyst.util.pcommands`	ProSyst Util Bundle/ ProSyst Util Full Bundle	Contains the API for plugging text commands.
`com.prosyst.util.hash`	System Bundle	Delivers hashtable utilities.
`com.prosyst.util.beans`	ProSyst Util Bundle/ ProSyst Util Full Bundle	Holds the ProSyst API for JavaBeans management.

Pluggable Commands

The Control Unit Scripting Engine bundle registers pluggable commands under a com.prosyst.util.pcommands.PluggableCommands service for executing a script from a file or from a console command line. For more information, about the mechanism of processing console commands, refer to the "Parser Service" document.

These commands are registered under a command group. The command group of the Control Unit Scripting Engine bundle is scripting. The paragraph below provides a detailed description of the commands.

Console Commands

Command	Description
`run {<file_name>\| log <log_file_name>}`	Executes a script from a file. Optionally, error logs can be written in a specified file.
`script <lines>`	Executes a script given as parameters to the command.
`ls`	List all the scripts that is currently executed.
`stop <script_id>`	Stops the script execution by the given execution ID.

Tip: To get the parameters and descriptions of scripting commands, type help. The help command is standard and is added for all pluggable commands groups. To get the options supported by these commands, use help -scripting. To view detailed help for a single command, for example the custom command, type custom?.

Script Commands Syntax Description

The described commands can be used to to invoke some control unit actions by means of a script. The script itself has a basic support for loops and a wait command to halt the execution of the script for a while. Here is the list of available commands:

Command	Description
`ALIAS`	An alias is a pseudonym under which the corresponding control unit can be found
`ASSERT (value:type) -> SV(cuType,cuID,stateVariable)`	Verifies the value of a specified state variable. If the value is different the script execution is interrupted and the failed assertion is logged. You can also use replace '->' with the following comparison operators: >, <, >=, <=, =, ==. Actually, '->' is the same as '=' and '=='. The other, relative comparison operators should be used with caution. They work only with `Number` objects - like, `integer`, `character`, `float` .. etc.
`DESTROYCU (cuType, cuID)`	Destroys a Control Unit by specified type and ID.
`ECHO <message>`	Prints the given message into the log stream.
`EVAL state_variable= expression`	Checks if a state variable's value matches the specified expression. The expression has the syntax `expression =: String \| Number \| $other_variable$ [('+' \| '-' \| '' \| '/') String \| Number \| $other_variable$]`
`EXEC UNIT(type:id) -> arg(a:int, b:float, c:dictionary)`	Executes the action of a specified unit. The arguments are in using the following form - value:type. And the valid types are: `int`, `byte`, `boolean`, `string`, `long`, `short`, `char`, `double`, `float`, `biginteger`, `bigdecimal`, `dictionary`. The types are also valid for the `ASSERT` command. In certain situation it might be useful to continue execution of the script even when the `EXEC` command failed. In this case, you can use `!EXEC` that acts in a similar way with the only difference, that if the executed action fails, the execution of the script is not interrupted.
`MEMINFO`	Prints information about the free and total memory. Also runs the GC.
`LOOP <count>/END LOOP`	Repeats the execution of the script inside the loop body for the times given in the 'count' parameter.
`WAIT <time_period>`	Pauses the execution of the script for the specified time period, given in milliseconds.
`WATCH SV (cuType,cuID,stateVariable)`	Defines a state variable to be watched for changes and the changes are written in the log. Use this command again to add a new state variables to the watch list. If no `WATCH` command is executed, then ALL state variable changes are logged.

Note: If the type or the ID of the Control Unit contains spaces you should replace the space with the percent character - %.

The code below represents a simple demo usage of script commands. It is used the example ManagedControlUnit implementation, provided in "Examples of Provided Control Units" section of "Control Unit Admin Bundle" description.

ECHO Starting the script
WATCH SV(tuner, test.cu ,tuner_state)
#EXEC UNIT(CU_TYPE, CU_ID)
WAIT 10
#ASSERT (1:int) -> SV(tuner, test.cu ,tuner_state)
MEMINFO
#Script will stop in 3 seconds
WAIT 3000
ECHO Script Ends

Control Bundles