System

Overview

System is a global table providing information about the system, versions, debugging information and debugging controls.

System.

System.BuildVersion

String representing the Composer version number in “X.X.X.X” format. This is a read only variable so any changes made to it will not have an effect.

print(System.BuildVersion)                >> 8.0.1.7

System.MajorVersion

Integer representing the Composer Major version number. This is the first digit in the four-digit version, “X.x.x.x”. This is a read only variable so any changes made to it will not have an effect.

print(System.MajorVersion)                >> 8

System.MinorVersion

Integer representing the Composer Minor version number. This is the second digit in the four-digit version, “x.X.x.x”. This is a read only variable so any changes made to it will not have an effect.

print(System.MinorVersion)                >> 0

System.PatchVersion

Integer representing the Composer Patch version number. This is the third digit in the four-digit version, “x.x.X.x”. This is a read only variable so any changes made to it will not have an effect.

print(System.PatchVersion)                >> 1

System.Build

Integer representing the Composer Patch version number. This is the fourth digit in the four-digit version, “x.x.x.X”. This is a read only variable so any changes made to it will not have an effect.

print(System.Build)                       >> 7

System.IsEmulating

Bool representing the state of Offline operation. It will be “true” if the script is running while Composer is Offline and “false” if the script is running while Composer is Online. This is a read only variable so any changes made to it will not have an effect.

print(System.IsEmulating)                 >> false

System.IsDebugging

Bool representing the state of debugging. It is always “true” during offline execution but may be “true” or “false” when online depending on the setting of the Intelligent Module right click menu command ”Enable Online Script Debugging”. This is a read only variable so any changes made to it will not have an effect.

print(System.IsDebugging)                 >> true

System.ClearDebugging()

Function to clear to the Debug Output File.

System.ClearDebugging()             -- Debug Output File will be cleared

System.GetTime()

Returns the time in milliseconds since 1/1/1970., or since the PC has been booted if offline.

print(System.GetTime())             >> -903260332

lowPortion, highPortion = System.GetTime()
print(lowPortion)                   >>  371
print(highPortion)                  >> 903095174 --

The high portion is Negative because we are beyond halfway through the epoch so it wraps around. This doesn’t matter because the value returned is generally not especially useful in and of itself. But when compared with previous values, it can be used to determine how much time has passed between the two times. See the example below.

System.GetTime() is calculated the same whether Offline or Online although you may see a shift due to differences in time zone implementations between a Windows computer and the Symetrix hardware.

If you want to get the actual date and time for display, os.date() is better for this purpose because of its flexibility.

System.GetExecutionTime()

This API can tell you more about how much CPU processing time your script is consuming. This may be needed for optimizing complex and intensive scripts and should only be necessary if errors indicate your scripts are consuming too much CPU time.

It returns the number of ms which have passed since processing started on the current 4 Hz pass. This includes all timers, and other callbacks that happened on the current pass. This is the key thing that must be controlled to ensure processing doesn’t exceed 1/8 second (125 ms) on each pass to prevent starving other routines.

printSystem.GetExecutionTime())           >> 1

If you are seeing Skipped script passes or Load Factor over 100%, you may want to use this to profile your script. You can insert this into various sections of your code, usually in your Timer callback, to determine which parts are taking excessively long to execute. Then hopefully you can use this information to optimize.

Usage Examples

The following examples illustrate how these can be used:

Example 1 – Check Version Number

There may be some functionality that is only available in a certain version of Composer or newer. The following code shows how this can be checked before doing some operation.

if (System.MajorVersion >= 8) then
      -- Do Something
else
      -- Do Something Else
end

Example 2 – Check Offline Status

There may be some behavior you need to do differently offline vs online. This allows the creation of separate code paths to use whether the script is being run Offline or Online.

if (System.IsEmulating) then
      --do something when emulating
else
      --do something else when running on hardware
end

Example 3 – Emulate Control Pins Offline

When emulating offline, inputs from control pins are not available. Thus, the System.IsEmulating can also be used to simulate data from control pins.

offline = System.IsEmulating
data = 0

if (offline) then
      data = 0.5
else
      data = Controls.Inputs[1].Value
end

--Use the "data"

Note if this code block is called repeatedly, it is good practice to set System.IsEmulating to a variable since its status won’t be changing during the script execution.

Example 4 - Comparing Elapsed time

Using a timer, System.GetTime() can be used to determine the elapsed time since starting a process.

startTime = System.GetTime()

function TimerClick ()
      elapsedTime = System.GetTime() - startTime)
      --Do something with elapsed time
end

MyTimer = Timer.New()
MyTimer.EventHandler = TimerClick
MyTimer:Start(1)