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. Any object associated with the instance will change its status to OpcUa_BadOutOfService and its value will be set to Terminated. 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:

The possible values for the write_group parameter are:

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

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

table

Searches a value in the entire tree structure and returns a table with all the objects that contain this value in their paths.

All Components

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).

Master Core only

Below is a list of supported options.

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 connector to which the given object belongs or nil if no connector 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 core to which the given object belongs 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

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.

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](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

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. When there is only one historized value, it returns one, and when no data has ever been historized, it returns none.

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 the its ID or path.

The number of data points return depends on the values of time_start, time_end and max_limit. Bounds is a boolean value that specify whether additional Bounding Values should also be returned. Bounding Values are data points that 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 that 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 return The behavior of this function is generally that specified by OPC UA part 11 Section 6.4.3.2 (with the exception of continuation points). Section 4.4 of the same document provides more information on Start and End periods.

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.

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 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

userdata

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

The system database has 3 tables: 'properties', 'live_properties' and 'history' that can be used to query information. Their schemas are shown below:

However, he property codes can also be accessed by using the syslib.model.properties. notation.

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 to which the given object belongs 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.

All Components

In the following tree structure:

System

+

For the script to access holder2 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".

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, but concurrent execution of these functions will raise a Lua error.

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:

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

boolean

Specifies whether a string matches a regular expression.

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 JSON string or 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

boolean

Short name: syslib.sethist

Adds historical data to a given item and returns the result of executing this operation, where true means it was successful and false otherwise.

All Components

table

Update the historical data on external historians using OPC HDA Classic.

Connector only

Creates or modifies the references of an object. Receives a table as parameter (refs) where each entry is itself a table, corresponding to one reference. Each reference has three fields: name, path, and type. Only the path field is mandatory. The type, when not specified, defaults to "OBJECT_LINK" (triggering). The existing types are:

These are listed in the ReferenceType Coding Group.

All Components

To delete the references from an object use the following:

To set a security reference, the refs table should also contain the security flags (see the SecurityAttributes flag group for available flags). To set the security reference with flags, use the 64bit mask where the upper 32bit contains the ReferenceType and the lower 32bit contains the SecurityAttribute flags:

This sets a security reference to the "so" profile on the System object

None

Utility function to modify the scope-settings of the current Lua Instance.

All Components

The new scope-settings will be applied to all subsequent calls within the current Lua instance.

none

Short name: syslib.set

This function sets 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.

When using syslib.setvalue() to set the value property of an IO Item, the function converts this to an OPC Write to the associated Data Source, rather than setting the property directly. The value property will then be updated from the resultant value change as indicated by the Data Source, if any.

All Components

In the following tree structure : System

-localhost

-folder1

script

-folder2

holder2

For the script to access holder2 via a relative path:

Writing null values (or nil values in the Lua syntax) to objects or object properties in system syslib.

Startig with inmation v1.20 and later, nullable values can also be written as arrays or as null value elements in an array.

Using setvalue with tabledata properties

To successfully set tabledata properties the user must know whether the tabledata property is Schema-defined or Schema-less. Schema-defined tabledata properties have a set schema so this schema needs to be known and matched in order to successfully set the property. Schema-less tabledata properties (for example the Table Holder object’s Table Data property) can be set using the { "data": {}} JSON structure as the property value. It is recommend to define JSON strings using double square brackets.

For a table with 2 columns containing 2 rows of values on a Table Holder object:

This function causes its calling thread to sleep for the specified number of milliseconds. Note that function is not guaranteed to sleep exactly the specified duration, the actual duration is the best effort by the operating system.

All Components

string

Short name: syslib.splitp

This function splits a given object path and returns the path of the parent and the object’s name. If the path contains escape characters, the result of the function will follow the rules detailed in the Disambiguation of Item Paths section of this document.

All Components

variant

This function is related to buffering historical data (see buffer function). See the In-Memory Aggregation Jump Start for more information and working examples of the buffer function. It retrieves and clears, atomically, the buffer with the specified name at the specified object or path. The buffer must exist. It returns four values, the array of buffered data values, the array of buffered time stamps, the array of buffered qualities, and the buffer’s counter. The buffer’s counter increases monotonically each time a value is placed into the buffer, and is meant as an aid in detecting buffer overflows.

Assume there is an object obj that generates a numerical value every 10 seconds and historizes its data. We set a buffer on it that stores the values from the last minute:

Now assume syslib.tear is called after at least one minute:

Possible output can be:

table

Returns the References of the specified nodes. The function mimics Browse Service call from View Service Set as specified in Section 5.8.2 of OPC-UA Specification Release 1.04.

Connector only

Browse Properties (defaults)

UA Browse service call supports different browse properties which can be used to control the type and information of references being browsed for. The following key-value entries can be used to specify these browse properties:

Browse Descriptions (nodes_to_browse)

The browse description for the nodes can be specified in one of the three formats given below:

A table with mixed argument formats : (2) and (3) is also supported.

The function will always return a Lua table-of-tables, where every sub-table represents the references information of each UA-node specified in the input. Each sub-table contains the following fields:

A example browse call from UA AnsiC server is shown below:

The above code returns two "HasProperty" type references for the corresponding UA node, as shown below:

table

Returns the next set of browsed References from the specified continuation points. The function mimics BrowseNext Service call from View Service Set as specified in Section 5.8.3 of OPC-UA Specification Release 1.04.

Connector only

The return value format of uabrowsenext is identical to uabrowse, except that the returned references are per continuation-point basis instead of per UA node basis.

table

Returns the value of the specified attributes of UA nodes. The function mimics Read Service call from Attribute Service Set as specified in Section 5.10.2 of OPC-UA Specification Release 1.04.

Connector only

nodes_to_read

nodes_to_read is a Lua table-of-tables where every sub-table represents a node description containing the following entries:

The function always returns a Lua table-of-tables, where every sub-table represents the attribute value per entry in the nodes_to_read argument. Each attribute-value table contains the following entries: