Constructor - creates new instance of an API object.
import { WinccoaManager } from 'winccoa-manager';
const winccoa = new WinccoaManager();
Private apiPrivate winccoaAllows to set data point alert attributes.
Alert(s) of type WinccoaAlertTime to be set.
Attribute value(s) to be set. Must have the same size as alerts. If alerts is a single string and not an array, this parameter must also be a single value and not an array.
Boolean true in case of a success, otherwise WinccoaError wil be thrown instead.
The attributes and their constants which can be set with this method are described in the chapter _alert_hdl
WinccoaError when DPE does not exist, mismatch number of DPs and values, invalid argument type, etc.
import { WinccoaManager, WinccoaAlertTime } from 'winccoa-manager';
const winccoa = new WinccoaManager();
async function alertSetTest() {
const dpeWithAlert = 'ExampleDP_AlertHdl1.'; // assuming alert is triggered
const result = await winccoa.dpQuery(
"SELECT ALERT '_alert_hdl.._act_state', '_alert_hdl.._value' FROM '" +
dpeWithAlert +
"'",
);
const ts = result[result.length - 1][1] as WinccoaAlertTime;
const alertTime = new WinccoaAlertTime(ts.date, ts.count, ts.dpe + '._comment');
let isSuccess = false;
try {
isSuccess = winccoa.alertSet(alertTime, 'Alert comment text from winccoa node manager.');
} catch (exc) {
console.error(exc);
}
console.info("AlertSet is called successfully - " + isSuccess);
}
Allows to set data point alert attributes with a given timestamp.
Source time for the attribute change.
Alert(s) of type WinccoaAlertTime to be set.
Attribute value to be set. Must have the same size as alerts. If alerts is a single string and not an array, this parameter must also be a single value and not an array.
Boolean true in case of a success, otherwise WinccoaError wil be thrown instead.
The attributes and their constants which can be set with this method are described in the chapter _alert_hdl
WinccoaError when DPE does not exist, mismatch number of DPs and values, invalid argument type, etc.
import { WinccoaManager, WinccoaAlertTime } from 'winccoa-manager';
const winccoa = new WinccoaManager();
async function alertSetTimedTest() {
const dpeWithAlert = 'ExampleDP_AlertHdl1.'; // assuming alert is triggered
const result = await winccoa.dpQuery(
"SELECT ALERT '_alert_hdl.._act_state', '_alert_hdl.._value' FROM '" +
dpeWithAlert +
"'",
);
const timeStamp = new Date('2024-03-19T04:05:06.789Z');
const ts = result[result.length - 1][1] as WinccoaAlertTime;
const alertTime = new WinccoaAlertTime(ts.date, ts.count, ts.dpe + '._ack_state');
let isSuccess = false;
try {
isSuccess = winccoa.alertSetTimed(timeStamp, alertTime, 1);
} catch (exc) {
console.error(exc);
}
console.info("AlertSet is called successfully - " + isSuccess);
}
Allows to set data point alert attributes with a given timestamp.
Source time for the attribute change.
Alert(s) of type WinccoaAlertTime to be set.
Attribute value to be set. Must have the same size as alerts. If alerts is a single string and not an array, this parameter must also be a single value and not an array.
Promise that resolves to true if successful. If not successful,
a WinccoaError wil be thrown instead.
WinccoaError when DPE does not exist, mismatch number of DPs and values, invalid argument type, etc.
import { WinccoaManager, WinccoaAlertTime } from 'winccoa-manager';
const winccoa = new WinccoaManager();
async function alertSetTimedWaitTest() {
const dpeWithAlert = 'ExampleDP_AlertHdl1.'; // assuming alert is triggered
const result = await winccoa.dpQuery(
`SELECT ALERT '_alert_hdl.._act_state', '_alert_hdl.._value' FROM '${dpeWithAlert}'`,
);
const timeStamp = new Date('2024-03-19T04:05:06.789Z');
const ts = result[result.length - 1][1] as WinccoaAlertTime;
const alertTime = new WinccoaAlertTime(
ts.date,
ts.count,
ts.dpe + '._ack_state',
);
try {
await winccoa.alertSetTimedWait(timeStamp, alertTime, 1);
console.info(`Alert is acknowledged at ${timeStamp}`);
} catch (exc) {
console.error(exc);
}
}
Allows to set data point alert attributes.
Alert(s) of type WinccoaAlertTime to be set.
Attribute value(s) to be set. Must have the same size as alerts. If alerts is a single string and not an array, this parameter must also be a single value and not an array.
Promise that resolves to true if successful. If not successful,
a WinccoaError wil be thrown instead.
WinccoaError when DPE does not exist, mismatch number of DPs and values, invalid argument type, etc.
import { WinccoaManager, WinccoaAlertTime } from 'winccoa-manager';
const winccoa = new WinccoaManager();
async function alertSetWaitTest() {
const dpeWithAlert = 'ExampleDP_AlertHdl1.'; // assuming alert is triggered
const result = await winccoa.dpQuery(
`SELECT ALERT '_alert_hdl.._act_state', '_alert_hdl.._value' FROM '${dpeWithAlert}'`,
);
const ts = result[result.length - 1][1] as WinccoaAlertTime;
const alertTime = new WinccoaAlertTime(
ts.date,
ts.count,
ts.dpe + '._comment',
);
try {
await winccoa.alertSetWait(
alertTime,
'Alert comment text from winccoa node manager.',
);
console.info(`Comment for alert of '${dpeWithAlert}' is successfully set`);
} catch (exc) {
console.error(exc);
}
}
Creates a connection for being notified of datapoint element updates.
Function that is called whenever a connected value changes.
DPE name(s) to connect to.
- Each update will contain updates for all elements in dpeNames, not only the changed values.
if true, callback is called with the initial values right away, if false,
callback is only called after an actual value change.
ID of the new connection (>= 0). This can be used to disconnect from updates if required with dpDisconnect. Otherwise the connection will be closed when the manager exits.
WinccoaError when invalid parameter types, unknown datapoint element names etc.
For an example describing how to pass user data to a callback, see the second example for WinccoaDpQueryConnectCallback.
import {
WinccoaManager,
WinccoaConnectUpdateType,
WinccoaError
} from 'winccoa-manager';
const winccoa = new WinccoaManager();
function connectCB(
names: string[],
values: unknown[],
type: WinccoaConnectUpdateType,
error?: WinccoaError
) {
if (error) {
console.log(error);
return;
}
if (type == WinccoaConnectUpdateType.Answer)
console.warn('--- Initial update ---');
for (let i = 0; i < names.length; i++)
console.info(`[${i}] '${names[i]}' : ${values[i]}`);
}
function connect() {
let id = -1;
try {
id = winccoa.dpConnect(
connectCB,
['ExampleDP_Arg1.', 'ExampleDP_Arg2.'],
true
);
} catch (exc) {
console.error(exc);
}
}
Copies a data point including its configuration.
Name of the datapoint to copy.
Name of the new copied datapoint. Must not exist yet.
Optional driver: numberOptional driver number (default 1).
Promise - will be resolved to true if successful or rejected with an error.
In case of an error, error.details will contain the same error code
that CTRL function dpCopy() would return (see there).
WinccoaError when given source datapoint does not exist, when datapoint is copied into itself, invalid argument given, etc.
async function dpCopyTest() {
let isSuccess = false;
try {
isSuccess = await winccoa.dpCopy('ExampleDP_Arg1', 'ExampleDP_Arg3');
} catch (exc) {
console.error(exc);
}
console.info("DP ExampleDP_Arg1 is copied to ExampleDP_Arg3 successfully - " + isSuccess);
}
Creates a data point.
Name of the data point to be created.
Type of data point to be created.
Optional systemId: numberTo create a data point on a remote system in a distributed system, this parameter must contain the system number.
Optional dpId: numberThe ID of the data point. If a data point with the given ID already exists, a random ID is chosen.
Promise - will be resolved to true if successful or rejected with an error.
WinccoaError in case of:
let dpCreated = false;
try {
dpCreated = await winccoa.dpCreate('newFloatDpe', 'ExampleDP_Float');
} catch (exc) {
console.error(exc);
}
console.info("DP newFloatDpe is created - " + dpCreated);
Deletes a data point.
Name of the data point to be deleted. In case of a distributed system the name of the data point to be deleted must contain the system name.
Promise - will be resolved to true if successful or rejected with an error.
WinccoaError when datapoint with the given name does not exist or current user has no privileges to delete a DP.
let isSuccess = false;
try {
isSuccess = await winccoa.dpCreate('newDpe', 'ExampleDP_Float');
} catch (exc) {
console.error(exc);
}
if (isSuccess)
{
try {
isSuccess = await winccoa.dpDelete('newDpe');
} catch (exc) {
console.error(exc);
}
}
console.info("DP newDpe was deleted successfully - " + isSuccess);
Disconnect from datapoint element update connections established with dpConnect.
ID of the connection to close as returned by dpConnect.
ID of the connection that has been closed (>= 0).
WinccoaError when id is not found or invalid.
function connect() {
let id = -1;
try {
id = winccoa.dpConnect(
connectCB,
['ExampleDP_Arg1.', 'ExampleDP_Arg2.'],
true
);
} catch (exc) {
console.error(exc);
}
}
function disconnect() {
try {
winccoa.dpDisconnect(id);
} catch (exc) {
console.error(exc);
}
}
Returns the data typeof a data point element.
Name of the data point element
Type of a data point element
WinccoaError when data point with the given dpeName is not found or invalid argument type.
import { WinccoaManager, WinccoaElementType } from 'winccoa-manager';
const winccoa = new WinccoaManager();
async function dpElementTypeTest()
try {
let dpType = await winccoa.dpElementType('ExampleDP_Arg1.');
console.info('The type of ExampleDP_Arg1 is float - ' + (dpType == WinccoaElementType.Float));
} catch (exc) {
console.error(exc);
}
}
Checks the existence of a valid data point identifier.
A data point identifier: a sys, a DPT, a DP, a DPE, a config, a detail or an attr.
true if at least one part of a data point identifier can be resolved correctly, otherwise false.
WinccoaError when invalid argument type is given.
let isDpExists = false;
try {
isDpExists = winccoa.dpExists('ExampleDP_Arg1.');
} catch (exc) {
console.error(exc);
}
console.info("Is ExampleDP_Arg1 exists - " + isDpExists);
Get the current values of one or more datapoint elements.
Datapoint element name(s) of the values to get.
Promise that resolves to the current value(s) of the DPE(s). The received values must be cast to their expected types before they can be used.
WinccoaError when DPE does not exist or current user has no read access to it.
const dpes = ['ExampleDP_Arg1.', 'ExampleDP_DDE.b1'];
try {
const values = (await winccoa.dpGet(dpes)) as [number, boolean];
for (let i = 0; i < dpes.length; i++) {
console.info(`${dpes[i]}: ${values[i]}`);
}
} catch (exc) {
console.error(exc);
}
Returns the alias for the specified data point.
Data point element
the appropriate alias in the language. Note that the alias can be only unilingual.
WinccoaError when data point with the given dpeName is not found or invalid argument type.
try {
let alias = winccoa.dpGetAlias('ExampleDP_Rpt1.');
console.info('DP alias: ' + alias);
} catch (exc) {
console.error(exc);
}
Returns the comment (description) for the data point.
Data point element or data point
Optional mode: numberMode of functionality.
For more details on all modes description see
CTRL function dpGetDescription().
Description in all available languages as langText or empty strings in all languages.
The returned data type can be defined with setOptions.
WinccoaError when data point with the given dpeName is not found or invalid argument type.
let description;
try {
description = winccoa.dpGetDescription('ExampleDP_Rpt1.');
} catch (exc) {
console.error(exc);
description = null;
}
if (description)
console.info('DP description: ' + description);
This function returns the numerical format(s) of a data point.
Data point element
Returns a string that contains the format (for example, '%6.2f') in one or several languages or an empty string if an error occured.
The returned data type can be defined with setOptions.
WinccoaError when data point with the given dpeName is not found or invalid argument type.
let formats;
try {
formats = winccoa.dpGetFormat('ExampleDP_Rpt1.');
} catch (exc) {
console.error(exc);
formats = null;
}
if (formats)
console.info('DP formats: ' + formats);
This function returns the unit(s) of a data point.
Data point element
Returns the unit as langText in one or several languages. In the event of an error, an empty string is returned.
The returned data type can be defined with setOptions.
WinccoaError when data point with the given dpeName is not found or invalid argument type.
try {
let units = winccoa.dpGetUnit('ExampleDP_Rpt1.');
console.info('DP units: ' + units);
} catch (exc) {
console.error(exc);
}
Returns all the data point names or the data point element names that match a pattern in alphabetical order.
Serach pattern. When an empty pattern is given (=default), then returns all datapoints.
Wildcards are used to filter data point name.
The charcters * and ? are used for the purpose,
where the asterisk (*) replaces any number of characters and the question mark ? stands for just one character.
Only data points that have the same number of levels as specified are found.
Levels are separated by a period. dpNames(**) is equivalent to dpNames(*.*).
Furthermore:
:* returns all configs, :config.* returns all details, :config.detail.* returns all attributesdp.el:* returns only the configs according to the DPE. , for example, no _original for a node.
Wildcards can be used in arrays (square brackets , e.g.: [0,3,5-7] - numbers 0,3,5,6,7) or outside arrays in option lists (in curly brackets {}).
Example of wildcards in lists of options:
winccoa.dpNames('{*.Ala.*,*.Ala*}', dpType);
winccoa.dpNames('*{.Ala.,.Ala}*', dpType);
winccoa.dpNames('*.A{la.,la}*', dpType);
winccoa.dpNames('*.Al{a.,a}*', dpType);
winccoa.dpNames('*.Ala{.,}*', dpType);
winccoa.dpNames('*.Ala{.}*', dpType);
winccoa.dpNames('*.Ala.*', dpType);
winccoa.dpNames('*.Ala*', dpType);
Data point type. Allows to restrict the returned data points to a specific data point type. When using the parameter only data points that match the pattern and the selected data point type will be returned.
Defines if the search should ignore the casing of the search pattern (=true) or not (=false, default)
List with data points or data point element names.
WinccoaError when invalid argument type is given.
let foundDpNames: string[] = [];
try {
foundDpNames = winccoa.dpNames('ExampleDP*', 'ExampleDP_Float');
} catch (exc) {
console.error(exc);
}
for (let i = 0; i < foundDpNames.length; i++) {
console.info("DPE name: " + foundDpNames.at(i));
}
Retrieves attribute values with the help of SQL statements.
SQL statement.
Promise - will be resolved to true if successful or rejected with an error.
The query result has a table-like structure:
| [0][0] (empty) | [0][1] column header | ... |
|---|---|---|
| [1][0] line name | [1][0] content of line | ... |
| [2][0] line name | [2][1] content of line | ... |
| ... | ... | ... |
e.g. this is the output for the query "SELECT '_original.._value' FROM 'ExampleDP_Arg*'" converted
to JSON:
[
["",":_original.._value"],
["System1:ExampleDP_Arg1.",2.43],
["System1:ExampleDP_Arg2.",5.76]
]
WinccoaError when invalid parameter or query string is given.
let result;
try {
result = await winccoa.dpQuery(
`SELECT '_original.._stime', '_original.._value' FROM 'ExampleDP_Arg*'`,
);
} catch (exc) {
console.error(exc);
result = null;
}
if (result) {
const queryTable: string[][] = result as string[][];
for (let i = 0; i < queryTable.length; i++) {
console.info(
`query line - name: '%s' - timestamp = %s - value = %s`,
...queryTable[i],
);
}
}
Calls callback whenever one or more DPEs which meet the query condition change.
It is recommended to use dpQueryConnectSingle if possible from the performance point of view.
Function that is called whenever a subscribed DPE value changes. The update message will contain all subscribed DPEs.
if true, callback is called with the initial DPE values right away, if false, callback is only called for an actual value change.
query as an SQL statement.
ID of the new connection (>= 0). This can be used to disconnect from updates if required with dpQueryDisconnect. Otherwise the connection will be closed when the manager exits.
WinccoaError when invalid parameter types, empty or invalid query, etc.
When the query passed to this method is invalid, no exception is thrown, but the first (and only) callback will contain a WinccoaError instead.
For an example describing how to pass user data to a callback, see the second example for WinccoaDpQueryConnectCallback.
dpQueryConnectAll()import {
WinccoaManager,
WinccoaConnectUpdateType,
WinccoaError
} from 'winccoa-manager';
const winccoa = new WinccoaManager();
function queryConnectCB (
values: unknown[][],
type: WinccoaConnectUpdateType,
error?: WinccoaError
) {
if (error) {
console.log(error);
return;
}
if (type == WinccoaConnectUpdateType.Answer)
console.warn('--- Initial update ---');
for (let i = 0; i < values.length; i++) {
console.info(`DPE = '%s', value = %s`, ...values[i]);
}
}
function connect() {
let id = -1;
try {
id = winccoa.dpQueryConnectAll(
queryConnectCB,
true,
`SELECT '_online.._value' FROM '*' WHERE _DPT="ExampleDP_Float"`
);
} catch (exc) {
console.error(exc);
}
}
Calls callback whenever one or more DPEs which meet the query condition are changed.
Function that is called whenever a subscribed DPE value changes. The update message will contain only changed DPEs.
if true, callback is called with the initial DPE values right away, if false, callback is only called for an actual value change.
query as an SQL statement.
ID of the new connection (>= 0). This can be used to disconnect from updates if required with dpQueryDisconnect. Otherwise the connection will be closed when the manager exits.
WinccoaError when invalid parameter types, empty query, etc.
When the query passed to this method is invalid, no exception is thrown, but the first (and only) callback will contain a WinccoaError instead.
For an example describing how to pass user data to a callback, see the second example for WinccoaDpQueryConnectCallback.
dpQueryConnectSingle()import {
WinccoaManager,
WinccoaConnectUpdateType,
WinccoaError
} from 'winccoa-manager';
const winccoa = new WinccoaManager();
function queryConnectCB (
values: unknown[][],
type: WinccoaConnectUpdateType,
error?: WinccoaError
) {
if (error) {
console.log(error);
return;
}
if (type == WinccoaConnectUpdateType.Answer)
console.warn('--- Initial update ---');
for (let i = 0; i < values.length; i++) {
console.info(`DPE = '%s', value = %s`, ...values[i]);
}
}
function connect() {
let id = -1;
try {
id = winccoa.dpQueryConnectSingle(
queryConnectCB,
true,
`SELECT '_online.._value' FROM '*' WHERE _DPT="ExampleDP_Float"`
);
} catch (exc) {
console.error(exc);
}
}
Disconnect from dpQueryConnectSingle (or dpQueryConnectAll) .
ID of the connection to close as returned by dpQueryConnectAll or dpQueryConnectSingle.
ID of the closed connection (>= 0).
WinccoaError when id is not found or invalid.
import {
WinccoaManager,
WinccoaConnectUpdateType,
WinccoaError
} from 'winccoa-manager';
const winccoa = new WinccoaManager();
function connect() {
let id = -1;
try {
id = winccoa.dpQueryConnectSingle(
function (
values: unknown[][],
type: WinccoaConnectUpdateType,
error?: WinccoaError
) {
if (error) {
console.log(error);
return;
}
console.info(values)
},
true,
"SELECT '_online.._value' FROM '*' WHERE _DPT= \"ExampleDP_Float\""
);
} catch (exc) {
console.error(exc);
}
}
function disconnect() {
try {
winccoa.dpQueryDisconnect(id);
} catch (exc) {
console.error(exc);
}
}
Set the value of one or more datapoint element(s).
Datapoint element name(s) of the values to set.
Values to set. Must have the same size as dpeNames. If dpeNames is a single string and not an array, this parameter must also be a single value and not an array.
true if successful, otherwise WinccoaError wil be thrown instead.
Since this method does not wait for the actual value update in the database, the update can still fail after this method returned
true. Use dpSetWait to also get informed about these errors.
WinccoaError when DPE names do not exist, values cannot be converted, array sizes mismatch etc.
const dpes = ['ExampleDP_Arg1.', 'ExampleDP_DDE.b1'];
const values = [123.456, false];
try {
winccoa.dpSet(dpes, values); // Two arrays of size 2
winccoa.dpSet('ExampleDP_Arg2.', 2); // single value
} catch (exc) {
console.error(exc);
}
Sets the alias for the specified data point element.
Data point element
Alias to be set. Note that the alias can be set only unilingual.
Promise - will be resolved to true if successful or rejected with an error.
WinccoaError when data point with the given dpeName is not found or invalid argument type, etc.
let isSuccess = false;
try {
isSuccess = await winccoa.dpSetAlias('ExampleDP_Rpt1.', 'rpt1Alias');
} catch (exc) {
console.error(exc);
}
console.info('DP alias is set successfully - ' + isSuccess);
Sets a comment (description) for the data point.
Data point element to be commented on
Comment as langText
Promise - will be resolved to true if successful or rejected with an error.
WinccoaError when data point with the given dpeName is not found or invalid argument type, etc.
let isSuccess = false;
try {
isSuccess = await winccoa.dpSetDescription('ExampleDP_Rpt1.', {
'de_AT.utf8': 'German description',
'en_US.utf8': 'English description',
'ru_RU.utf8': 'Russian description',
});
} catch (exc) {
console.error(exc);
}
console.info('DP description is set successfully - ' + isSuccess);
Sets the numerical format(s) of a data point.
Data point element
A string that contains the format (for example, '%6.2f') in one or several languages.
Promise - will be resolved to true if successful or rejected with an error.
WinccoaError when data point with the given dpeName is not found or invalid argument type, etc.
let isSuccess = false;
try {
isSuccess = await winccoa.dpSetFormat('ExampleDP_Rpt1.', {
'de_AT.utf8': '%.4f',
'en_US.utf8': '%.4f',
'ru_RU.utf8': '%.2f',
});
} catch (exc) {
console.error(exc);
}
console.info('DP formats are set successfully - ' + isSuccess);
Set values of one or more datapoint element(s) with a given source time.
Source time for the value change.
Datapoint element name(s) of the values to set.
Values to set. Must have the same size as dpeNames. If dpeNames is a single string and not an array, this parameter must also be a single value and not an array.
Boolean true in case of a success, otherwise false.
Since this method does not wait for the actual value update in the database, the update can still fail after this method returned
true. Use dpSetTimedWait to also get informed about these errors.
WinccoaError when DPE names do not exist, values cannot be converted, array sizes mismatch etc.
const timeStamp = new Date('2023-01-03T04:05:06.789Z');
let isSuccess = false;
try {
isSuccess = winccoa.dpSetTimed(timeStamp, 'ExampleDP_Arg1.', 2);
} catch (exc) {
console.error(exc);
}
console.info("dpSetTimed call is successed - " + isSuccess);
Set values of one or more datapoint element(s) with a given source time.
Source time for the value change.
Datapoint element name(s) of the values to set.
Values to set. Must have the same size as dpeNames. If dpeNames is a single string and not an array, this parameter must also be a single value and not an array.
Promise that resolves to true if succesful. If not successful,
a WinccoaError wil be thrown instead.
WinccoaError when DPE names do not exist, values cannot be converted, array sizes mismatch, no write access etc.
const timeStamp = new Date('2023-01-03T04:05:06.789Z');
let isSuccess = false;
try {
isSuccess = await winccoa.dpSetTimedWait(timeStamp, 'ExampleDP_Arg1.', 2);
} catch (exc) {
console.error(exc);
}
console.info("Time and value are set for ExampleDP_Arg1 - " + isSuccess);
Sets the unit(s) for a data point.
Data point
Unit (for example, kg) in one or several languages as langText.
Promise - will be resolved to true if successful or rejected with an error.
WinccoaError when data point with the given dpeName is not found or invalid argument type, etc.
let isSuccess = false;
try {
isSuccess = await winccoa.dpSetUnit('ExampleDP_Rpt1.', {
'de_AT.utf8': 's',
'en_US.utf8': 's',
'ru_RU.utf8': 'c',
});
} catch (exc) {
console.error(exc);
}
console.info('DP units are set successfully - ' + isSuccess);
Set the value of one or more datapoint element(s).
Datapoint element name(s) of the values to set.
Values to set. Must have the same size as dpeNames. If dpeNames is a single string and not an array, this parameter must also be a single value and not an array.
Promise that resolves to true if succesful. If not successful,
a WinccoaError wil be thrown instead.
WinccoaError when DPE names do not exist, values cannot be converted, array sizes mismatch, no write access etc.
const dpes = ['ExampleDP_Arg1.', 'ExampleDP_DDE.b1'];
const values = [123.456, false];
try {
await winccoa.dpSetWait(dpes, values); // Two arrays of size 2
await winccoa.dpSetWait('ExampleDP_Arg2.', 2); // single value
} catch (exc) {
console.error(exc);
}
Returns all or selected data point types from the current project.
Pattern for the returned DPTs. When an empty pattern is given (=default), then returns all DP types.
Wildcards are used to filter data point type name.
The charcters * and ? are used for the purpose,
where the asterisk (*) replaces any number of characters and the question mark ? stands for just one character.
Wildcards can be used in arrays (square brackets , e.g.: [0,3,5-7] - numbers 0,3,5,6,7) or outside arrays in option lists (in curly brackets {}).
Example of wildcards in lists of options:
winccoa.dpTypes('{*.Ala.*,*.Ala*}');
winccoa.dpTypes('*{.Ala.,.Ala}*');
winccoa.dpTypes('*.A{la.,la}*');
winccoa.dpTypes('*.Al{a.,a}*');
winccoa.dpTypes('*.Ala{.,}*');
winccoa.dpTypes('*.Ala{.}*');
winccoa.dpTypes('*.Ala.*');
winccoa.dpTypes('*.Ala*');
The desired system if querying from other systems. Optional parameter. If this parameter is not defined, the own system is queried.
When this is set to false, data point types without existing data points will be ignored.
String array with all DP type names.
WinccoaError when invalid argument type or non-existing systemId is given.
try {
const foundDpTypes = winccoa.dpTypes('ExampleDP*', 1, true);
for (let i = 0; i < foundDpTypes.length; i++) {
console.info("DP type: " + foundDpTypes.at(i));
}
} catch (exc) {
console.error(exc);
}
Search for file or directory in WinCC OA project and installation paths.
the file or directory to search for
full path of the file or directory or an empty string if not found
WinccoaError when invalid argument type is given.
let configPath;
try {
configPath = winccoa.findFile('config/config');
} catch (exc) {
console.error(exc);
}
console.info("Config file full path: " + configPath);
Returns all available options and their values. The options can be set with setOptions.
Object containing all current option values.
let options = winccoa.getOptions();
for (const [key, value] of Object.entries(options)) {
console.info(`Name: ${key} - Value: ${value}`);
}
Returns list of project, sub-project and product installation paths.
List of project, sub-project and product installation paths. The project path is always a first entry and the installation path is always the last.
let paths = winccoa.getPaths();
for (let i = 0; i < paths.length; i++) {
console.info(paths.at(i));
}
Returns the system ID.
Optional systemName: stringThe name of the system (optional). If it is not given, then the system ID of its own system will be returned.
The system ID.
WinccoaError when invalid system name is given.
let ownId;
let system1Id;
try {
ownId = winccoa.getSystemId();
system1Id = winccoa.getSystemId('System1:');
} catch (exc) {
console.error(exc);
}
console.info("Own system id = " + ownId);
console.info("System1 id = " + system1Id);
Returns the system name.
Optional systemId: numberSystem ID (optional). If it is not given, then the system name of its own system will be returned.
The system name.
WinccoaError when invalid system ID is given.
try {
const ownName = winccoa.getSystemName();
const id1Name = winccoa.getSystemName(1);
console.info(
`Own system name = '${ownName}, system with id 1 name = '${id1Name}'`
);
} catch (exc) {
console.error(exc);
}
Returns information about current API and WinCC OA versions.
Checks if the event manager to which this manager is connected is currently the active REDU partner.
true if the event manager to which this manager is connected is
currently the active REDU partner.
const isEventReduActive = winccoa.isReduActive();
console.info('Event currently is active - ' + isEventReduActive);
Returns the host name of the Event Manager this manager is connected to. Use this method only on redundant computers.
Host name of the Event Manager this manager is connected to.
const reduHostName = winccoa.myReduHost();
console.info('My redu host name - ' + reduHostName);
Returns host number in a redundant system depending on the connection to the Event Manager - manager 1 or 2 (for example, eventHost = "host1$host2"). In a non-redundant configuration this always returns 1.
Host number.
const reduHostNumber = winccoa.myReduHostNum();
console.info('My redu host number - ' + reduHostNumber);
Reports a security event, this must be called whenever a security-relevant action is made in JavaScript (like opening a server port).
ID of the security event.
Rest ...args: unknown[]Arguments for the security event, depending on the value of id. See WinccoaSecurityEventId for details.
WinccoaError when id is not known, required arguments are missing in args.
import { WinccoaManager, WinccoaSecurityEventId } from 'winccoa-manager';
const winccoa = new WinccoaManager();
winccoa.securityEvent(WinccoaSecurityEventId.PortOpened, 8443, 'https://');
Set one or more options. The options and their values can be retrieved with getOptions.
The options to be set (see WinccoaOptions for possible options).
Boolean true on success, otherwise WinccoaError wil be thrown instead.
The userId option cannot be set with this method.
The user can be set with setUserId for the instance of WinccoaManager.
The user can be set with -user manager option for the node manager,
see Administration of managers.
WinccoaError if option has wrong type or option value is out of range.
import { WinccoaManager, WinccoaLangTextFormat } from 'winccoa-manager';
const winccoa = new WinccoaManager();
function setOptionsTest() {
try {
winccoa.setOptions({
langTextFormat: WinccoaLangTextFormat.StringFixed,
langIdx: 1,
});
} catch (exc) {
console.error(exc);
}
}
Sets the current user ID to the specified value for the current instance of WinccoaManager.
User ID to set.
Optional password: stringPassword to use to set user (not needed if manager started as root).
Boolean true in case of a success, otherwise WinccoaError wil be thrown instead.
WinccoaError when id is not found or invalid.
let isSuccess = false;
try {
isSuccess = winccoa.setUserId(2048); // operatorAll user id
} catch (exc) {
console.error(exc);
}
console.info('User id is set to operatorAll user id successfully - ' + isSuccess);
Main class of the TypeScript/JavaScript API to the WinCC OA JavaScript Manager for Node.js®.
To use the API, an instance of this class needs to be created, e. g.:
Example