syslib Library Functions

Converts an ASCII string into an UTF8 string and returns it.

string

All Components

This method is related to buffering historical data (see buffer function) and, depending on the specified arguments, it has two variations.

The repeater shall be an object or a path to an object that has a dynamic property. The buffer with the specified name must exist. If a repeater at the specified buffer already exists, it is replaced. The dynamic property of the repeater object receives each value stored into the buffer.

First, assume there is an object obj which has a dynamic property that generates numerical values every second. Also, assume it historizes these values in raw format (without any aggregation). We set a buffer on this object, which will contain the generated values within the last minute:

Now, assume there is another object obj2 that has a dynamic property. This property can take the values received by the buffer buff in the following way:

This function is related to historization (see gethistory function) and its main purpose is buffering historical data. See the In-Memory Aggregation Jump Start for more information and working examples of the buffer function.

Assume obj is an object having a dynamic property which generates numerical values every second. Also, assume it historizes these values in raw format (without any aggregation). We could set a buffer which will contain the generated values within the last minute in the following way:

Depending on the provided arguments, it has several variations:

boolean

Checks if the profile of the user or the optional list of profiles have access to the models given. The function returns a boolean value indicating if all the profiles together have access to all the models given.

Core only

This example checks if the profile "visitor" has access to IO and Access models.

boolean

Checks the access permissions (security attributes) for a given object in the context of an optional list of profiles. The function returns a boolean value indicating if all attributes apply to the specified pathspec for the union of permissions granted to the given profiles.

Core only

This example checks if the object with the path "/System/Core/Item" can be read and written to using the read-only profile "/ro".

number

Returns the id of the Lua instance that called syslib.control.getself.

boolean

You need to be system administrator to run this function. Promotes a non-dedicated instance to a dedicated instance, if the instance is not yet dedicated. If the instance is already dedicated then this function will do nothing. Returns false followed by an error message if it failed to make the request to the Lua instance to be made dedicated. Returns true otherwise.

table

Lists all running Lua instances. Returns a table of tables, where each inner table represents a Lua instance. The Lua instance tables have the following properties:

You need to be system administrator to run this function. Terminates the Lua virtual machine running an instance. If the Lua virtual machine is executing native code then the instance will not terminate until it has finished running the native code.

For example, if a Lua instance is running socket.sleep(60) and a call to syslib.control.terminate() is made on this instance, it will not terminate until the socket.sleep(60) command has finished. An attempt to terminate an instance associated with an object, such as a Generic Item that is not running in a dedicated thread, from another object that is also not running in a dedicated thread, may not work as expected if the target instance is currently running and does not return control to the system (because it is running an infinite loop or experiences a similar condition). This is because the running instance will monopolize the thread used by all such objects.

Any object associated with the instance will change its status to OpcUa_BadOutOfService and its value will be set to Terminated. The bad status and the "Terminated" message will be set only when the instance is terminated when it was running, or at the next attempt to run the instance. If the instance is terminated while it is idle, and the next attempt to run the instance is not forthcoming (soon or ever), the previous status and value are preserved.

Returns false followed by an error message if it failed to make the request to the Lua instance to be terminated. Returns true otherwise.

table

Short name: syslib.new

Creates a new object and returns it. The possible values for the type parameter are:

All Components

The example above will create a Data Holder Item under /System/localhost. Now properties can be set on this object. The object is not physically created until the "commit" function is called on it. This solution was approached in order to commit all the changes in a single transaction.

The example above can be elaborated as follows:

When the third parameter is not specified, it is assumed that the object’s type is regular object ("OT_OBJECT"). Below, there is an example of creating another type of object – a rule:

number

Short name: syslib.now

Returns the number of milliseconds since Epoch in UTC time. If it is called with a parameter which is true, it will return the local time.

All Components

variant

This function returns 3 values regarding current time zone information. The first value is the offset from UTC time in milliseconds (including possible daylight bias); the second one is the name of the time zone; the third one is a boolean specifying whether daylight saving time is active or not.

All Components

string

Returns binary data, as Lua-string, converted from Base64-encoded ASCII input.

All components

table

Short name: syslib.def

When called without a table parameter, it resets the current defaults to the default defaults. When called with a table parameter, it copies valid defaults from the supplied table into the current defaults. The effects of this function apply only to the executing script and are preserved during the lifetime of a script environment.

All Components

All the currently defined defaults deal with OPC write behavior:

The possible values for the write_fetch parameter are in the coding group OpcWriteMode:

The possible values for the write_group parameter are:

table

Some object properties can be used to store files in the system. The files themselves are stored in a MongoDB GridFS bucket. The files can be deleted using this function with the file name as the key.

On success, this function returns the metadata table of the deleted file, which can be an empty table if the file didn’t exist. Otherwise, it raises a Lua error if argument validation failed or returns nil and an error message in case of a runtime error.

All Components

Delete a file which was stored as example.pdf in the Attachments property of an object.

Short name: syslib.del

Deletes an object.

Core only

Deletes a time span of raw history for an object.

All the parameters are mandatory. The time parameters are the numbers of milliseconds since the POSIX epoch. A time value that is not an integer number of hours is adjusted to a system-defined time boundary in an unspecified way. After the adjustment, if any, all the values stored for the specified object that are at or after the adjusted start time, and before the adjusted end time, are deleted.

Core only

string

Returns the SHA256 digest of the string passed as argument.

All Components

Returns the SHA256 digest of the library libname that is embedded in the executable. The main use of this function is to obtain the digest of a built-in library and compare it with the digest of the overloaded library (a Lua library stored in an AdvancedLuaScript property that has the same name as the one shipped with the executable). The latter can be obtained with syslib.digest(text).

All Components

Short name: syslib.dis

Disables an object.

All Components

string

Dumps the objects under the immation component to an image file. The function also creates a copy of the fingerprint file and a db file which contain some details necessary for the component to function. This function can be used to back up the current state of the objects under the component. The function deletes any existing image, fingerprint and db files with the same path as the argument before starting the dump.

All Components

The two examples above are equivalent and create three files called "core_snapshot.inimgdump", "core_snapshot.infpdump" and "core_snapshot.dbdump" at "D:/backup". These files contain the state of the component at the time the function was called and can be used to restore the component to that state at a later point in time.

Short name: syslib.ena

Enables an object.

All Components

string

Returns ASCII representation of binary data using Base64 binary-to-text encoding schema.

All components

number

Converts Excel time to POSIX time.

All components

nil

Executes a Lua chunk, potentially in a remote component.

The chunk executes in a dedicated thread, which terminates as soon as the chunk returns.

If the timeout is nil or a non-zero number, the chunk executes synchronously, i.e., the call to syslib.execute() blocks till the remote chunk terminates or times out. In this case, the return values of the remote chunk are returned by syslib.execute(). If the remote chunk raises a compilation or execution error, the error is returned.

If the timeout is zero, the chunk executes asynchronously, i.e., syslib.execute() returns as soon as the chunk is scheduled for the transmission to the remote component. Neither normal nor return values are transferred. This is a low level mode, and the user will typically want to use, for example, messaging API to communicate and synchronize execution.

The default timeout is 30000 milliseconds. A non-zero value is adjusted to at least 30000 milliseconds.

Core Components

table

Searches the entire tree structure and returns an array of inmation objects which contain the string str in their names or paths (see fullpath parameter below).

All Components

Search for "target" in the names of all objects of all models:

Search for "target" in the paths of dynamic objects of the I/O Model:

Given the following tree:

Object A^/B can be found by searhing for: * A or B in objects names or paths. * A^/B (not A/B due to path ambiguity with object B) in objects names or path.

Object G^/H can be found by searhing for: * G or H in objects names or paths. * G^/H (or G/H as there is no path ambiguity) in objects names or path.

string

Converts a string into lowercase and returns it. It also takes into account non-ASCII characters.

All Components

table

Returns attribute information of itmes from an OPC-compliant data source.

Connector only

attribute_ids

The attribute_ids argument is expected to be a table of valid attribute ids, corresponding to the type of the data source.

The function returns a Lua table-of-tables, where every subtable contains the information of the specified attributes per item-id. Every subtable contains the following entries per attribute, if available from the server:

table

This function retrieves Audit Trail entries from the repository.

To use this function, the profile of the user should have either System-wide Reviewer or Limited Reviewer Audit Trail Roles assigned (see Enabling Audit Trail Hands on for more details).

The schema of documents returned by this function is described here.

Master Core only

Below is a list of supported options.

table

Short name: syslib.brefs

The function returns an array, whose elements are a table with three fields: name (of the reference), path (to the referencing object), and type (of the reference). The type can be either a string or an integer, with the following possible string values:

These are listed in the ReferenceType coding group. The numeric type typically encodes a security reference with access right permissions.

The returned table meets the expectations of syslib.setreferences.

All Components

string

Short name: syslib.connp

Takes as parameter an object path or nil (in the latter case, the path defaults to the current object). It returns the path of the first connector object found when traversing the model hierarchy upwards, starting at the object specified with the objspec parameter, or nil if no connector object was found in the parent objects hierarchy.

Connector only

string

Short name: syslib.corep

Takes as parameter an object path or nil (in the latter case, the path defaults to the current object). It returns the path of the first core object found when traversing the model hierarchy upwards, starting at the object specified with the objspec parameter, or nil if no core object was found in the parent objects hierarchy.

All Components

table

Returns the current default values for read/write SCI. See defaults function for a list of all the possible default values.

All Components

string/table

This function returns historical events for the given objects within the interval provided. A set of options to filter and process the event data can also be passed to the function.

Core only

Below is a list of supported options.

Below is a representation of the schema of event documents.

The coding group syslib.model.codes.UaEventType can also be used to map the numeric codes from the returned documents to human readable strings.

string, table

Some object properties can be used to store files in the system. The files themselves are stored in a MongoDB GridFS bucket. The files can be retrieved using the file name as the key. The content of the file is returned as a string.

If pathspec specifies a File property, the name parameter can be omitted. Otherwise, it is mandatory.

On success, the function returns the file contents and its metadata table. Otherwise, it raises a Lua error if argument validation failed or returns nil and an error message in case of a runtime error.

Master Core only

Retrieve a file which was stored in the Attachments property of an object as example.pdf and write it to the disk.

table [, string]

Some object properties can be used to store files in the system. The files themselves are stored in a MongoDB GridFS bucket. The metadata of existing files can be retrieved using this function.

On success, the function returns the metadata table. Otherwise, it raises a Lua error if argument validation failed or returns nil and an error message in case of a runtime error.

All Components

The filter parameter consists of zero or more arguments used to match a particular file entry. It’s grammar is:

A filter can have an optional start value prev which is typically the metatable obtained from a previous call to continue iterating over all matching entries. It may also be an integral row index (negative values are relative to the last row, i.e. specifying -2 returns the last table row if it matches).

The next symbols define the filter criteria.

The simplest form is a single string value matching the name metadata field.

To match multiple fields simultaneously use pairs, which is a list of key - value pairs which all have to match a metadata entry.

condition is similar to pairs, but the key - value pairs are encoded as a regular Lua table.

To match custom metadata fields, the key needs to be prefixed with "custom." for the pairs filter, or nested inside a "custom" table in a condition filter. If a condition filter is used, an optional mode string can be specified to control how string values are matched. The mode can be "e" (case-sensitive equality, the default) or "p" (string values in the condition are used as a Lua pattern to match against the metadata field).

Finally, a filter can be a function which is called for each metadata entry until it returns true or all entries have been visited.

Examples:

Retrieve metadata of a file example.pdf in the Attachments property of an object.

Retrieve all PDF documents

table

Short name: syslib.hist

This function returns historical data according to the specified aggregate(s), which conform to the OPC UA standard.

Each given path is mapped to the aggregate which corresponds to its index, i.e. the item at paths[i] will be mapped to the aggregate at aggregates[i]. If there are more objects than aggregates, the extra objects will be mapped to the last aggregate in the aggregates table. If multiple aggregates are desired for the same object, then the object’s path has to be repeated in the paths table. The resulting table structure is:

A table is represented like: {key_1 = value_1, …​, key_n = value_n} The keys V, S, T represent value, status, timestamp respectively. If the requested aggregate is AGG_TYPE_RAW, then to each V, S, T corresponds a table containing all the raw values available in the given interval of time. Otherwise, the V, S, T keys map single values, which are the result of aggregating the existing raw values. The status is made of two parts: aggregation flag + quality code.

A code snippet as below can be used to mask out the aggregation flags and retrieve a 32-bit UA quality code:

Aggregation flags are as follows:

They are compliant to the OPC UA specification. For example 0x200000000 means AGG_STATUS_CALCULATED + GOOD QUALITY.

Core only

The following example shows how to collect the values from the resulting tables with respect to the requested aggregate.

When the time period of the historization is not precisely known, the syslib.gethistoryframe function can be used in order to get the time interval start and end point of the entire historized data for a specific item. The example below shows how historic raw data can be collected and written to another item using the syslib.sethistory function:

Observations

Because of their nondeterministic time of execution, scripts having history calls should be run on a separate thread. To do this, go to the Object Properties view of the item that contains the script and then, under Common menu, tick Dedicated Thread Execution. In order to obtain the duration of a history call, the syslib.currenttime function can be used as follows:

table

Returns historical data from an external HDA/UA server.

Connector only

Each history is a table with fields V, Q, T, which are arrays of values, qualities and timestamps, respectively. The order of values in the V, Q, T tables is exactly as produced by the underlying HDA server which, for conformant serves, is governed by the start and end time arguments. Of these three arrays, only Q and T are true arrays, in the sense that thay can have their length reliable taken with #. The V array may have gaps due to empty or null data at certain points.

For an OPC HDA datasource:

For an OPC UA datasource:

[number][,number]

Short name: syslib.histf

Returns the oldest and the newest timestamp in history for a given object or path. The function can return at most two elements. If there is only one historized value, it returns one, and if no data has ever been historized, it returns none. When being applied to properties with the Data Historization capability, this function takes into account the current Archive Mode configuration for this capability. E.g., if the Archive Mode is set to 'No Value', nothing will be returned, no matter if earlier changes of this property have been historized or not.

Core only

table

Returns the logs which were created between the start and end times for the objects specified. If no objects are specified, the logs for all objects in the system are returned. The function returns a table which contains the log messages and their details. The structure of the table data is the same as what you see on Log Display in DataStudio.

Master Core only

number

Returns a micro-second based time count using a steady clock.

All components

userdata

Takes the objspec or the numerical code for a MongoDB data store and returns a lua-mongo 'client' which represents a connection to the data store. If no argument is passed, the System Custom Data Store is assumed on the Master Core. On Local Cores, the store parameter is required and should represent a custom datastore object.

All 64-bit components

string

Takes the objspec or the numerical code for a MongoDB data store and returns a MongoDB connection string which can be used with lua-mongo library to create a connection to the data store. If no argument is passed, the System Custom Data Store is assumed on the Master Core. On Local Cores, the store parameter is required and should represent a custom datastore object.

All 64-bit components

table

Short name: syslib.obj

Returns an existing object. If the object doesn’t exist, it returns nil.

All Components

Now the object’s properties can be read or written to:

Like in the syslib.createobject function case, changed properties are committed into the system only after the commit function is called on the object:

Additionally, the current object can be obtained using a relative path to the current folder:

number

Takes an integer argument and interprets the low 16 bits as an OPC Classic quality code and returns a corresponding OPC UA quality code.

All Components

string

Short name: syslib.parent

Takes the path of an object as argument and returns the path of the parent.

All Components

number

Short name: syslib.propid

Takes as parameters an object or a path and, optionally, a property name. When the second parameter is omitted, it returns the id of the dynamic property which belongs to the given object. If a property name is passed and such property can be found in the object’s configuration, then its corresponding id is returned. If no property is found, the function returns nil.

All Components

string

Returns the name of a property given its id.

All Components

userdata

This function returns raw historic data, i.e. the actual stored data points, from the given property or object, either specified by its ID or path. The function may also return modified historical data (as defined in OPC UA) if they are supported by the underlying data store.

The number of data points returned depends on the values of time_start, time_end and max_limit.
Bounds is a boolean value that specifies whether additional Bounding Values should also be returned. This must be false when modified_data_mode is true. Bounding Values are data points which are not necessarily part of the original data set, but may be used to interpolate the actual data for calculations.
time_start and time_end specify the time window which should be retrieved. Both values should be specified in milliseconds from the current epoch (inmation’s POSIX time standard). Values are retrieved sequentially, from time_start to time_end, unless time_start is greater than time_end, in which case the values are retrieved on a backwards order. Either time_start or time_end may be nil (but not both). If time_end equals nil the values will be read towards the latest available time, or if time_start is nil the values will be read backwards to the earliest available time.
max_limit specifies the maximum number of values that may be retrieved. If fewer values are available, they are all returned. If more values are available for the specified period, only the first max_limit points are returned and the "more" flag is raised. If max_limit is set to 0 then all the available data points are returned.
The behavior of this function is generally that, which is specified by OPC UA part 11 Section 6.4.3.2 (with the exception of continuation points and possibly modified data; see below on the latter) or Section 6.4.3.3 (depending on the value of modified_data_mode). Section 4.4 of the same document provides more information on Start and End periods, and Section 3.1 on modified data.

By default, i.e., when modified_data_mode is nil or absent, the function returns only the most recent version of the raw data, completely ignoring any modified data that may be present in the queried time domain. Note that, when modified data are present, this behavior is not fully OPC UA compliant. It is retained for backward compatibility.

If the value of modified_data_mode is false, the function will use the status (quality) to indicate whether modified data are present for a given raw value. In this mode, the function still returns only the most recent version of raw data. The presence of the modified data is signaled by the bits 10 (InfoType) and 3 (Extra Data): see the definition of StatusCode in OPC UA Part 4 Section 7.34.1 and the behavior prescribed in Part 11 Section 6.4.3.2. If the underlying data store does not support modified data, the parameter has no effect (i.e., the behavior as if it were nil). In this mode, the function is fully compliant with respect to modified data. For convenience, syslib.uaextradata() can be used to check for the presence of modified data.

If the value of modified_data_mode is true, the functions returns only the modified data, mostly as described in OPC UA Part 11 Section 6.4.3.3. In this mode, the returned data are all the versions of the modified raw data present in the specified time domain. If a raw value has no previous version, nothing is returned for that raw value. The multiple versions of a raw value are returned with the same source timestamp, sequentially together in the reverse order with respect to the general order of retrieval: if 'time_start' is less than or equal to 'time_end', the most recent version is returned first; otherwise, the least recent version is returned first. If the underlying data store does not support modified data, the behavior is as if no modified data were present, i.e., an empty result set is returned. By derogation from OPC UA Part 11 Section 6.4.3.3, as already remarked, the latest version is also returned. Every version is returned with a server timestamp, which can be used to construct the "modification timestamp" (per Section 6.4.3.3) a.k.a. modificationTime (per Section 6.5.3) by taking the server timestamp of the next more recent value.

Return Values

Core only

The following code shows how to call the syslib.getrawhistory function and iterate through the results.

The following example creates an object, populates it with history data and then query its history, using the previous code.

Using the following value for t instead would force syslib.getrawhistory to return a "more" flag.

The following example retrieves raw data and looks for the "Extra Data" bit for modified values:

The following example retrieves modified data:

Objects located beneath the Connector are unable to access the time-series repository. Therefore, executing scripts that request historical data from any location other than below the Core object will return the error: "Attempt to access historical data from a component that does not have the time-series repository". This applies to all syslib functions that access historical data (excluding `syslib.gethistoryex`as this function does not request data from the time-series repository) Although this function adheres to the OPC UA part 11 Section 6.4.3.2 (or. 3) standard, it doesn’t implement Continuation Points, therefore all calls to this function return the max_limit number of data points or all (if max_limit equals 0). Please keep in mind that further calls to this function do not handle data that wasn’t returned on a previous call due to a max_limit specification. A subsequent call to treat those data points must specifically identify them. Lua Iterators are presented on the book "Programming in Lua", in chapter 7, as well as their usage with Generic fors.

table

Short name: syslib.refs

If objspec parameter is supplied, the function returns an array, whose elements are a table with three fields: name (of the reference), path (to the referenced object), and type (of the reference). The type can be either a string or an integer, with the following possible string values:

These are listed in the ReferenceType coding group. The numeric type typically encodes a security reference with access right permissions. The returned table meets the expectations of syslib.setreferences. If parameter objspec is not supplied, the function returns an array containing the names of the references belonging to the current (self) object. The array does not contain empty names.

All Components

variant

Returns the Store and Forward sequence number(s) for data forwarded to the target system which has been confirmed (stored successfully). If category is syslib.model.codes.SafDataCategory.NONE then a table with sequence numbers of all available categories, keyed by the numeric category code, is returned. Otherwise, a single integer number is returned.

Core and Connector

variant

Returns the Store and Forward sequence number(s) for which data has been forwarded to the target system. If category is syslib.model.codes.SafDataCategory.NONE then a table with sequence numbers of all available categories, keyed by the numeric category code, is returned. Otherwise, a single integer number is returned.

Core and Connector

variant

Returns the current Store and Forward sequence number(s). If category is syslib.model.codes.SafDataCategory.NONE then a table with sequence numbers of all available categories, keyed by the numeric category code, is returned. Otherwise, a single integer number is returned. Separate SaF sequence numbers for each data category are used to uniquely enumerate each stored datum. Sequence numbers are strictly monotonically increasing when new data is stored. The current sequence number is always greater or equal to the forwarded sequence number, which is always greater or equal to the confirmed sequence number. Calculating differences between those three numbers allows to deduce state changes of the SaF system from one point in time to another.

Core and Connector

table

Utility function to retrieve the scope-setttings of the current Lua Instance.

All Components

None

table

Short name: syslib.relayp

Takes as parameter an object path or nil (in the latter case, the path defaults to the current object). It returns a table containing the paths of the relays to which the given object belongs or nil if no relay was found in the parents hierarchy.

All Components

table

Returns the currently available entries for a selector property, given its pathspec or property code.

The returned table may be empty or contain a items field and optionally a tree field:

The items field is an array (table with consecutive numerical indices) of tables. Each array element has the following member fields, depending on the property type.

For InstanceSelector type properties:

The value field is nil for items which represent hierachical nodes for InstanceSelector properties. Such items are not selectable and only used for hierarchically representing the items.

If label and description are both nil, the label and description information should be retrieved using the localized text associated with the code in class_code.

For TableRowSelector type properties:

If a coding_group field is present, the label and description fields are nil. The label and description information should be retrieved using the localized text associated with the coding value from value for the codding group identified by the coding_group field.

In general, every item field can be nil if some internal data mismatch is encountered.

Additionally to the top-level items field, the tree field is returned for InstanceSelector type properties if options.tree is set to true. The field contains edge information for the returned items. Edges are encoded as an array of integral numbers in tree, where each pair of numbers (the first pair being the first and second number in the tree array) contains the index for the start and end node as they are stored in the items array. Note that every item whose index is not present in the tree array is a root node and there may be more than one root.

All Components

The pathspec_or_propcode parameter supports a pathspec (or property code) denoting a property of type InstanceSelector or TableRowSelector. In case of InstanceSelector properties, the parameter can be a property code like syslib.model.properties.DataStoreSelector.

table

Short name: syslib.slf

Returns the current object as an inmation object.

All Components

string

Short name: inmaton.selfp

Returns the path to the current object.

All Components

integer

This function returns a numerical id identifying a "store object". These objects are generic buffer objects like Generic Time Series Buffer and Generic Event Buffer objects, custom MongoDB data store objects, or one of the system stores. For system stores, the store parameter must be value from the RepoStoreName coding group. For all other store types, the store parameter is a regular objspec.

All components

userdata

Returns a read-only handle to the system database. This handle can be used to query information about the system data using SQL.

The values of all static properties in the system is stored in a table called properties. It can be used to find objects and properties matching various criterion using SQL.

The schema of the properties table is given below

Properties may be accessed using their code. 1 is the code for the property ObjectName.

Property codes may also be accessed by using the syslib.model.properties.property_name notation.

Properties may also be accessed using the path of the property.

Putting it all together we can search for propery codes for specific Object Types, in this case Connector.

We support JSON1 extension of SQLite3 using which we can query any JSON strings stored in our properties. The following code fetches all objects where the first row of the firstname column of the property CustomOptions.CustomTables.TableData is John.

JSON1 extension is documented here.

string

Short name: syslib.systemp

Takes as parameter an object path or nil (in the latter case, the path defaults to the current object). It returns the path of the system object found by traversing the model hierarchy upwards, starting at the object specified with the objspec parameter, or nil if no system object was found in the parent objects hierarchy.

All Components

number

Short name: syslib.time

This function returns the number of milliseconds since Epoch, corresponding to the parameter given as a timestamp. If the format is omitted,then the timestamp is considered to have the default format "%Y-%m-%d %H:%M:%S%f%ZP" (which is also compatible with the ISO 8601 format). If the format and / or the timestamp are wrong, it returns a negative number. For more about the possible formats, click here. Alternatively, it can also take the number of milliseconds since Epoch and return a timestamp having the ISO 8601 format.

All Components

number

Short name: syslib.tparts

Takes as parameter a string datetime (having ISO 8601 format) or a number representing the POSIX time as milliseconds. It returns the corresponding time parts as year, month, day, hour, minutes, seconds, milliseconds. If a string datetime is passed and it doesn’t have the ISO 8601 format, incorrect values may be returned.

All Components

table

Short name: syslib.tpartst

Takes as parameter a string datetime (having ISO 8601 format) or a number representing POSIX time as milliseconds. It returns a table containing the corresponding time parts as year, month, day, hour, minutes, seconds, milliseconds. If a string datetime is passed and it doesn’t have the ISO 8601 format, incorrect values may be returned.

All Components

multiple return values

Short name: syslib.get

This function gets the value, quality and timestamp of a property specified by the pathspec. If the pathspec includes a property specification, this property will be resolved, if present. If the pathspec has no property specification at all (i.e., it refers to an object), a default property will be selected, if availble at the specified object. Please refer to the documentation on paths for more information.

Please note that, depending on the property, any or all of the returned values may be nil. Please refer to the documentation on Property Values for more information. For more information on qulaity codes and expected return values for quality, please see the Quality Codes section of the documentation.

All Components

In the following tree structure:

For the script to access Dataholder2 via a relative path:

Observations

If the item contains binary data, i.e. an image, the syslib.getvalue() returns the data in Base64 encoding scheme.

table, integer

Returns the item attributes supported by the server. The function mimics the IOPCHDA_Server::GetItemAttributes interface as specified in OPC HDA 1.20 Specification.

Connector only

The function will always return two values: ATTRIBUTE_DESCRIPTION_TABLE, RETURN_CODE

The code above will return 4 Lua-tables containing tags, names, descriptions and data-type information of all available attributes as shown below:

table

Returns values of attributes for a specified item. The function mimics the IOPCHDA_SyncRead::ReadAttribute as specified in OPC HDA 1.20 Specification.

Connector only

The function always returns a lua table-of-tables, where each sub-table represents an attribute value. Each sub-table contains the following entries:

The returned attributes values are in the same order as the attribute-tags, specified in the function call.

The return value of the code-snippet above will be:

boolean

Checks if a quality code is bad.

All Components

boolean

Checks if a quality code is good. For more details, see the isbadstatus function.

All Components

boolean

Checks if a quality code is uncertain. For more details, see the isbadstatus function.

All Components

variant

This function is related to buffering historical data (see buffer function). It retrieves the last value in the buffer with the specified name (name) at the specified object or path (objspec).

First assume there is a numerical generator obj which historizes its data. We first set a buffer on it:

The last value that is stored in the buffer buff can be obtained as follows:

table

Lists the buffers set up for the object specified by objspec, if present, or all the buffers in the component service otherwise.

The returned table has the following keys:

The value for each key in the returned table is an array (i.e., a table with keys from 1 to N). All the arrays have the same length, and each buffer is described by elements with an identical index. See the Examples section.

All Components

Sample return value:

All the elements with index 1 correspond to buffer "buf2", and all those with index 2 to buffer "buf1".

table, size

A function providing a way to obtain detailed information about object properties, including their values.

The function returns a list of live object properties, which can differ depending on an object configuration; in comparison with getvalue it does not require knowing the property paths in advance; it has a performance advantage over multiple calls of getvalue; and it has limited convenience filtering.

Get properties for mass.

Short name: syslib.linkpv

Sets the ProcessValueLink property of a KPI or ISA-95 Equipment model object (for example: GenKPI or Analog Measurement object) to a data item in the I/O model (for example: an I/O item). The first parameter is the path of the object or the object itself which receives the reference (the KPI or ISA-95 model object) and the second one is the path to the object to be linked (the I/O model object).

All Components

Creates a log entry in the system log using the supplied arguments as content. The log_code argument determines the severity or type of the log message.

Log Severity Codes for the syslib.log() function:

The syslib.log() function will only create log messages for the object that is executing the Lua script. Log messages cannot be attched to other objects. To view the log messages generated by the object, open the Log Display or right click on the object and select Admin > Open Log.

All Components

variant

Returns the memory usage for one or more objects. It can be called either with a single argument (object id or path) and it returns the memory usage for this object, or with a limit as a second argument (the first being nil), which returns a table containing up to limit entries such as [ oid1 = size1, oid2 = size2, oid3 = size3, …​ ]. It can also be called with no arguments, in which case memory usage information is returned for all objects containing scripts.

All Components

table

Does the equivalent of a Mass Configuation operation in DataStudio. A mass entry in the entries parameter contains the modifications that are applied to one single object and it’s represented as key-value pairs. The keys can be settings or names of respective object’s properties. The entry’s settings are reserved case-sensitive words:

The type, flags and cfgversion in the entries parameter are advanced settings, which are already set by default, and should be only used by advanced users.

The property names for compound properties can be specified in two ways:

In the above two cases we did exactly the same operation, we have set the Latitude property to be equal to 10. The only difference is the syntax, in the second case a full property path has to be specified to the root property compound. See here in order to get all the available options for the batch_flags parameter.

All components

Returns

The function returns two values when the SUPPRESS_RESULTS flag is not set, otherwise it returns no values:

Simple example:

The above example will create 100 HolderItems under the ../data folder if they do not exist.

More advanced examples:

The above example will create three objects, namely, Generic Item, Action Item and Folder, with a few predefined properties.

The above example will update the current core object’s name if the object’s config version is 1. If it is not the case, the operation will not be executed.

Returns the numerical code for an object, all available objects are listed here.

number

All Components

Returns the available codings for a coding group or the numerical code for a specific coding, all available coding groups are listed here. See the examples below for more details.

variant

All Components

Code groups can also be referenced by their numerical code, see the example below.

Returns the numerical code for a performance counter. All available counters of an object can be seen on its dev page, e.g. here is the dev page of the Connector object.

number

All Components

Returns the available flags for a flag group or the numerical code for a specific flag, all available flag groups are listed here. See the examples below for more details.

variant

All Components

Code groups can also be referenced by their numerical code, see the example below.

Returns the numerical code for an object property, all available properties are listed here.

number

All Components

Moves and/or renames an object. The operation will succeed only when object and parent are within the same component service, and when object and parent are different and parent is not currently a direct or indirect child of object, and when object’s name (optionally renamed) is not currently used by other children of parent, and when parent’s type accepts children of object’s type.

All Components

Get the message queue associated with objspec and the numeric slot number slot. The returned message queue is an opaque object, to be passed as an argument to the other syslib.msg functions. Messages can be read from the queue either using syslib.msgnext(queue [, msgid]) or pairs(queue). Messages themselves are strings, which are opaque to the messaging system.

There is currently a hard limit of 63 message queues per object, with the slot number in the range of [1, 63].

Messages can be pushed to the same queue from different Lua scripts (which can run concurrently in dedicated threads). However, messages can only be read, popped and cleared sequentially. It is allowed to read, pop and clear messages from different Lua instances. However, popping and clearing messages concurrently is discouraged.

All Components.

Currently, a message queue cannot be shared between components and messages cannot be pushed to or read from different components.

userdata

Get the message queue of the Core object with slot number 1:

Iterating over all currently fetched (in memory) messages of a queue is done using pairs or the call operator on the queue:

The call operator allows to specify a maximum waiting time for messages to be available in the queue before the iteration starts:

Removing elements using syslib.msgpop while iterating over a queue is allowed. Another way of reading messages is analoguous to Lua’s next function for tables, see syslib.msgnext.

Push a new message to queue. The message is persistently stored and can be read (multiple times) until it is popped from the queue (or a later message is popped).

On success, the function returns true. Otherwise, it returns false and an error string.

All Components.

boolean, string

Push a single message:

Pop (delete) messages from queue. Messages are identified with a strict monotonically increasing msgid. All messages with id <= msgid are deleted from the queue.

This function returns nothing.

All Components.

Pop all messages with id <= 10:

Return the next message and its id pending in queue after msgid. If msgid is nil, the function returns the first message in the queue. If there is no message after msgid, nothing is returned (nil).

This function can be used to test if queue is empty.

All Components.

integer, string

Test if a message queue is empty:

Get the first and second message:

Remove all messages from queue. This completely removes all persisted messages.

This function returns nothing.

All Components.

This function returns statistics about the specified queue or about all queues currently being used.

If no queue is specified, a table of tables is returned. Otherwise, a single table is returned.

All Components.

table

Print the statistics of queue as a JSON document:

with output (similar to):

variant

See tear function, the behavior is identical except it does not clear the buffer.

number

Converts POSIX time to Excel time.

All components

string

Takes as parameter a string representing a key in the environment variables map and returns its value.

Below, there is a list of all the currently available variables:

All Components

table

Queries the server timestamp in the data archived for the given pathspec, where the server timestamp is either absent or less recent than the specified time.

The datastore parameter chooses the time series data store to query; if it is not specified, a data store default for the given pathspec is selected.

The function returns a table of source (key) - server (value) timestamp pairs that correspond to the archived data matching the arguments of the query. For some source timestamps, server timestamps may be absent, in which case the value is false. Otherwise, all the timestamps are integer Posix time values, in milliseconds.

Note that server timestamps are associated with blocks of source values, rather than individual source values.

Core Components

boolean

Specifies whether a string matches a regular expression. This function uses ECMAScript variant.

All Components

variant

Utility function to execute a Lua function with the specified scope-parameters. Please note that the scope-parameters outside the function call remains unchanged.

All Components

When we modify a function specific scope-setting, the previous scope settings are copied as it is and newly specified settings are reset. The new scope settings are applicable within the scope of the callback function. After this call is completed, previous scope settings will be applied as usual in the outer scope. For example:

table

Sets the default values for read/write SCI. When called without a table parameter, it resets the current defaults to the default defaults. When called with a table parameter, it copies valid defaults from the supplied table into the current defaults. The effects of this function apply only to the executing script and are preserved during the lifetime of a script environment. See defaults function for a list of all the possible default values.

All Components

boolean

Short name: syslib.setev

Sets a script event. Expects a table. Returns a boolean value stating the success of the operation. The table should contain key-value pairs, representing attributes of the event. Below, there is a list of built-in attributes that can be set (otherwise, they are automatically initialized with default values):

All Components