Introduction to the Entuity StormWorks statement language

Where is the statement language used?

What kind of language is the statement language?

Data Dictionary

Entuity's StormWorks statement language is used throughout Entuity as a means of accessing and manipulating the data held in the database and managed by the StormWorks kernel.

Where is the statement language used?

 Statement language is used in the following instances:

• in config files that define the data structures and collection methods used by the DsKernelStatic process, when discovering and polling network objects (the sw_*.cfg files in the etc directory).
• by the Report Builder and User Defined Polling to specify queries for accessing data.
• in code for accessing data.
• in Data Access Templates to define how each item of data return is derived.
• at the command line within the Debug Agent.

What kind of language is the statement language?

The language uses a mostly C-like syntax, but has been restricted to expressions so that every piece of statement langauge will have a return value.

The language also avoids side effects (e.g. similar to functional languages such as Lisp or Haskell), but is not truly a functional language itself. This is because a large part of the functions that can be used from the statement language are defined externally in C++, and these functions can have side effects.

Features of the Entuity statement language:

• every statement is an expression that returns a value.
• variables can be defined, but cannot be modified.
• you cannot define functions, and therefore you cannot define recursive solutions.
• you can achieve iteration by using a foreach operator to perform operations on a list of items.
• expressions are compiled, so errors can be either:
  • compile time (e.g. the current context type does not have that attribute); or
  • run time (e.g. the stream does not have the number of samples you requested).
• the language is designed specifically with the Entuity StormWorks data model in mind, and therefore has direct support for accessing attributes, associations and streams on StormWorks objects, and knowledge of StormWorks object types.

Examples of statement language expressions:

Getting the value of the 'name' attribute on the current object:

simple; this.name

Getting the 'id' attribute for the current object (i.e. the 'this' is unnecessary in the above example):

simple; id

Getting the list of port objects associated with the current object (which should be a device):

simple; ref.ports

Getting the entire contents of the chassisInventory stream on the current object:

simple; stream.chassisInventory

Getting all the values of the devSerialNumber attribute on the chassisInventory stream for the current object:

simple; stream.chassisInventory.devSerialNumber

Getting the most recent value of a specific stream attribute:

simple; stream.chassisInventory.samples(1).devSerialNumber

Getting all the values of a stream attribute in the last 6000 seconds:

simple; stream.chassisInventory.timespan(-6000).devSerialNumber

Getting a list of all the names of the devices that are of type 'DeviceEx' and whose average CPU utilization percentage is great than 1%:

simple; foreach(ref.devices, name, this.isa(DeviceEx) && try(mean(DeviceEx(this).stream.v_unifiedDeviceCPU.v_cpuUtilPercent), null) > 1)

Declaring a variable to store a literal list of values and then indexing into that list:

simple; variable items = [ 1, 2, 4, 8, 16 ]; items[2]

All the expressions start with the string "simple;", because the StormWorks kernel supports multiple languages and the string before the first semi-colon ; tells it what language is being used. If no string is specified, then the default is a basic URL-style "native" language. A detailed description of the "native" language is beyond the scope of this article, but this is an example of how it looks:

eq(obj://devType, 1001)

There is little reason to use statements in this language because they are more limited in what they can do. The one beneficial case is for simple literals returning e.g. true/false, or a constant integer, in which case the "native" language is several times faster. Therefore, you will often see it used for filters that are always passed, etc.

You may occasionally see statement language expressions used without the simple; prefix, such as embedded in Flex reports. In these cases, the language used is being assumed to be the simple statement language in order to keep the expression strings more compact, and it is not possible to specify use of the "native" language instead.

Data Dictionary:

The Data Dictionary lists all the object types with the following:

• their inheritance hierarchy and attributes.
• streams and their attributes.
• associations between object types.

Please see this article for further help and information on the Data Dictionary.