Variables

Variables are context entities that can be read to know something about the context and written to modify its behavior.

A value of every variable is always a Data Table:

• When you read a context variable, you always get a Data Table. The value can be retrieved from a storage facility, received from a device, or created on-the-fly by a server module - but it’s still a table.

• When plan to you write a context variable, you need a Data Table that represents its new value. You can modify a previously read value or construct new one from scratch - but don’t forget that you’re dealing with tables.

Context variables are also known as properties, parameters, or settings. These words are interchangeable in Iotellect jargon. Getting/setting context properties via API, retrieving context parameters via network, or modifying context settings via the UI essentially means reading and writing context variables different way.

Don’t forget that even simple values (e.g. numbers and strings) are represented by one-cell Data Tables. If you’re reading a Temperature variable, you will get a single-cell table with a single integer or floating point field.

All variables can be processed using unified routines for handling tables (such as smart data table copy).

The simplest example of a variable would be a pressure reading variable defined in a device context. That is a read-only variable whose format has just one floating-point field and strictly one record.

A bit more tricky sample is the "User Information" variable defined in the user context. Its value a single-record structure with several fields that store user's first name, last name, e-mail, phone number, etc.

Finally, "Filter Rules" variable in the event filter context is a multi-record table according to its format. Each record in its value table describes a separate event filtering rule.

Every variable is defined using a Variable Definition which contains several options:

• Variable Name. The name is a unique ID of the variable within a context where it is defined. This is a string that may contain only English characters, numbers, and underscore characters ("_").

• Variable Format. Table Format of the Data Table for the variable. This defines what the variable can look like - minimum and maximum rows, field types, possible field values, validation rules, etc. Some variables have a dynamic format - which means that any Data Table may represent their value.

• Writable. Flag indicating that it is possible to change the value of the variable to a new one.

• Description. Human-friendly description of the variable.

• Help. An optional detailed description of the variable.

• Group. Shows that the variable belongs to a variable group. The group may be not defined, i.e, there can be variables that do not belong to any group. Groups help to select several variables for processing. For example, a Device context may have a Configure action for configuring the Device Account, and another action for configuring the hardware DS. Each action will operate with all variables of a separate group. The group name may be pre-defined on the Iotellect Server or come from some hardware device, but it cannot be changed by the user.

• Read Permissions. Permission level required to get the value of this variable.

• Write Permissions. Permission level required to change the value of this variable.

A successful variable read operation returns the current value of the variable in form of a Data Table. This table always matches the variable format if it's not dynamic.

A variable write operation accepts a new variable's value in form of a Data Table that must match its format, or any Data Table if the format is dynamic. If the provided Data Table doesn't fully match the variable's format, the system does its best to convert provided Data Table to the proper format preserving as much data as possible.

Iotellect Server processes variables in various ways. If you pass a Data Table as the value of a variable, you won't necessarily get the same table back when you try and retrieve the value of the variable.

Internally, variables are divided into several types:

• In-memory structures that are not saved when Iotellect Server is stopped.

• Persistent settings that are stored in the database.

• Settings of Devices that are read/written from a remote device and cached by the server.

• "Virtual" variables. The value of virtual variables is generated on-the-fly, and they're not permanently stored.

If there are problems in setting or getting variable values, an exception may be thrown. In the case of the "get variable" operation, no value is returned. "Set variable" might throw an exception even though the variable value was indeed set, due to some other reason. The exception contains a textual description of the problem.

In most cases, variable values are browsed and edited using the Properties Editor UI component. The Properties Editor uses the Data Table Editor component for rendering and editing the value of each variable.

Every time a variable is updated a special Updated event is generated. The event's data contain the new value of the variable and update time. In Iotellect Server, a Change event is also generated in some cases.

Subscribing to an Updated event helps react to variable changes.

However, there are certain variables those value is generated on-demand during a variable read operation. Such variables do not actually have “current value” and “value changes”, and therefore Updated events are never generated for them.

Variables of Iotellect contexts may also have custom status. Variable status is a combination of a status code and a human-readable status description.

Variables statuses are displayed in the leftmost column of Properties Editor. However, there are some other ways to see variable statuses. For example, the statuses of device setting variables are shown in the Device Status dialog.

Was this page helpful?

Tell us more

Send

Thank you!