Class WinccoaManager

Main class of the TypeScript/JavaScript API to the WinCC OA JavaScript Manager for Node.js®.

IMPORTANT

All methods described in this documentation must be called from code inside a method or function to prevent unexpected or undefined behavior.

To use the API, an instance of this class needs to be created, e. g.:

Example

import { WinccoaManager } from 'winccoa-manager';
const winccoa = new WinccoaManager();

Index

Alert

alertGet

alertGet(alertsTime, dpeNames, alertCount?): Promise<unknown>

The function does the query only of the last alert attributes of a data point.

Parameters

alertsTime: WinccoaAlertTime | WinccoaAlertTime[]
Alert(s) time of type WinccoaAlertTime.
dpeNames: string | string[]
Data point element name(s) with the alert config.
OptionalalertCount: number | number[]
Serial number of alert (optional).

Returns Promise<unknown>

Promise that resolves to the requested value(s) of the DPE(s). The received values must be cast to their expected types before they can be used.

NOTE

The function can accept a list of data points for a single alert time. In this case, the data point should be the same, but the alert configs are different:

winccoa.alertGet(alertTime, [dpe + ':_alert_hdl.._value', dpe + ':_alert_hdl.._text']);.

The function can accept a list of alert times and a list of data points. In this case all lists must have the same length:

winccoa.alertGet([alertTime1, alertTime2], ['dpe1', 'dpe2']);

Throws

WinccoaError when DPE does not exist or current user has no read access to it.

See

Example: Calling alertGet with a single alert time and several alert configs

import { WinccoaManager, WinccoaAlertTime } from 'winccoa-manager';
const winccoa = new WinccoaManager();

async function alertGetTest() {
  const dpe = 'ExampleDP_AlertHdl1.';
  try {
    await winccoa.dpSet(dpe, true);  // trigger alert on the dpe
    const result = await winccoa.dpQuery(
      "SELECT ALERT '_alert_hdl.._value' FROM '" +
      dpe +
      "'",
    );

    for (let i = 1; i < result.length; i++) {
      const alertTime = result[i][1];
      const values = (await winccoa.alertGet(alertTime,
                     [dpe + ':_alert_hdl.._value', dpe + ':_alert_hdl.._text'])) as [boolean, WinccoaLangString];
      console.info(dpe, values);
    }
  } catch (exc) {
    console.error(exc);
  }
}

Example: Calling alertGet with a list of alert times and a list of data points

import { WinccoaManager, WinccoaAlertTime } from 'winccoa-manager';
const winccoa = new WinccoaManager();

async function alertGetTest() {
  const dpes = ['ExampleDP_AlertHdl1.', 'ExampleDP_AlertHdl2.'];
 try {
   await winccoa.dpSet(dpes, [true, true]);  // trigger alert on the dpes
   let alertTimes: WinccoaAlertTime[] = [];
   for (let d = 0; d < dpes.length; d++)
   {
     const result = await winccoa.dpQuery(
       "SELECT ALERT '_alert_hdl.._value' FROM '" +
       dpes[d] +
       "'",
     );

     if (result.length > 1)
       alertTimes.push(result[1][1]);
   }

   if (dpes.length == alertTimes.length)
   {
     const values = await winccoa.alertGet(alertTimes, [dpes[0] + ':_alert_hdl.._value', dpes[1] + ':_alert_hdl.._value']);
     console.info(dpes, values);
   }
  } catch (exc) {
    console.error(exc);
  }
}

alertGetPeriod

alertGetPeriod(startTime, endTime, names): Promise<{
alertTimes: WinccoaAlertTime[];
values: unknown[];
}>
The function returns the values of the specified alert attributes of the data point elements for which alerts were triggered.
Parameters
- startTime: Date
  The start time for reading alerts.
- endTime: Date
  The end time for reading alerts.
- names: string | string[]
  Alert handling attribute names.
Returns Promise<{
alertTimes: WinccoaAlertTime[];
values: unknown[];
}>
Promise that resolves to an object containing two arrays, one containing WinccoaAlertTimes with the alert details and the other the corresponding values.
Throws
WinccoaError when alert attribute name does not exist or in case of an invalid argument type.
See
Example
```
const startTime = new Date('2024-10-25T12:00:00.789Z');
const currentTime = new Date();
const dpes = [':_alert_hdl.._value', ':_alert_hdl.._text']

const { alertTimes, values } = await winccoa.alertGetPeriod(
  startTime,
  currentTime,
  dpes,
);

for (let i = 0; i < alertTimes.length; i++) {
  const alertTime: WinccoaAlertTime = alertTimes[i];
  console.info(
    '#' + i,
    'alertTime: ' + alertTime.date,
    alertTime.count,
    alertTime.dpe,
  );
  console.info('#' + i, 'value: ' + values[i]);
}
```
- Defined in binding.ts:4852

alertSet

alertSet(alerts, values): boolean

Allows to set data point alert attributes.

Parameters

alerts: WinccoaAlertTime | WinccoaAlertTime[]
Alert(s) of type WinccoaAlertTime to be set.
values: unknown
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.

Returns boolean

Boolean true in case of a success, otherwise WinccoaError wil be thrown instead.

Remarks

The attributes and their constants which can be set with this method are described in the chapter _alert_hdl

Throws

WinccoaError when DPE does not exist, mismatch number of DPs and values, invalid argument type, etc.

See

Example

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);
}

alertSetTimed

alertSetTimed(time, alerts, values): boolean

Allows to set data point alert attributes with a given timestamp.

Parameters

time: Date
Source time for the attribute change.
alerts: WinccoaAlertTime | WinccoaAlertTime[]
Alert(s) of type WinccoaAlertTime to be set.
values: unknown
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.

Returns boolean

Boolean true in case of a success, otherwise WinccoaError wil be thrown instead.

Remarks

The attributes and their constants which can be set with this method are described in the chapter _alert_hdl

Throws

WinccoaError when DPE does not exist, mismatch number of DPs and values, invalid argument type, etc.

See

Example

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);
}

alertSetTimedWait

alertSetTimedWait(time, alerts, values): Promise<unknown>

Allows to set data point alert attributes with a given timestamp.

Parameters

time: Date
Source time for the attribute change.
alerts: WinccoaAlertTime | WinccoaAlertTime[]
Alert(s) of type WinccoaAlertTime to be set.
values: unknown
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.

Returns Promise<unknown>

Promise that resolves to true if successful. If not successful, a WinccoaError wil be thrown instead.

Remarks

The attributes and their constants which can be set with this method are described in the chapter _alert_hdl

Throws

WinccoaError when DPE does not exist, mismatch number of DPs and values, invalid argument type, etc.

See

Example

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);
  }
}

alertSetWait

alertSetWait(alerts, values): Promise<unknown>

Allows to set data point alert attributes.

Parameters

alerts: WinccoaAlertTime | WinccoaAlertTime[]
Alert(s) of type WinccoaAlertTime to be set.
values: unknown
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.

Returns Promise<unknown>

Promise that resolves to true if successful. If not successful, a WinccoaError wil be thrown instead.

Remarks

The attributes and their constants which can be set with this method are described in the chapter _alert_hdl

Throws

WinccoaError when DPE does not exist, mismatch number of DPs and values, invalid argument type, etc.

See

Example

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);
  }
}

CNS

cns_checkId

cns_checkId(id): Promise<boolean>
Checks whether id is a vaild CNS ID.
Parameters
- id: string
  ID to check
Returns Promise<boolean>
Promise - will be resolved to true if id is a valid ID or to false if not.
See
CTRL function cns_checkId()
Example
```
const isValid = await winccoa.cns_checkId('someId');
```
- Defined in binding.ts:3840

cns_checkName

cns_checkName(name): Promise<number>

Checks whether name is a valid display name for CNS.

Parameters

name: WinccoaLangString
Display name to check.

Returns Promise<number>

Promise - will be resolved to:

0 - valid name
-1 - incomplete langString
-2 - contains invalid characters

See

CTRL function cns_checkName()

Example

import { WinccoaLangString, WinccoaManager } from 'winccoa-manager';
const winccoa = new WinccoaManager();

async function test(name: WinccoaLangString) {
  switch (await winccoa.cns_checkName(name)) {
    case 0:
      console.info('valid CNS display name');
      break;
    case -1:
      console.error('incomplete langString');
      break;
    case -2:
      console.error('contains invalid characters');
      break;
  }
}

cns_checkSeparator

cns_checkSeparator(separator): Promise<boolean>
Checks whether separator is a vaild CNS separator.
Parameters
- separator: string
  Separator to check
Returns Promise<boolean>
Promise - will be resolved to true if separator is a valid separator or to false if not.
See
CTRL function cns_checkSeparator()
Example
```
const isValid = await winccoa.cns_checkSeparator('.');
```
- Defined in binding.ts:3907

cns_getNodeIcon

cns_getNodeIcon(id): Promise<string>
Returns the path of the icon defined for given id.
Parameters
- id: string
  CNS ID.
Returns Promise<string>
Promise - will be resolved to the path of the icon or empty string if no icon is defined for id.
See
CTRL function cns_getNodeIcon()
Example
```
const iconPath = await winccoa.cns_getNodeIcon('System1.View1:Node1.Rpt2');
```
- Defined in binding.ts:3932

cns_getNodeTypeDisplayName

cns_getNodeTypeDisplayName(typeName): Promise<WinccoaLangString>
Returns the display name of the given CNS node type.
Parameters
- typeName: string
  Name of the CNS node type.
Returns Promise<WinccoaLangString>
Promise - will be resolved to the display name of the node type in the current multi-language string format or empty string if node type does not exist.
See
CTRL function cns_getNodeTypeDisplayName()
Example
```
const displayName = await winccoa.cns_getNodeTypeDisplayName('struct');
```
- Defined in binding.ts:3958

cns_getNodeTypes

cns_getNodeTypes(): Promise<{
    icons: string[];
    typeIds: string[];
    typeNames: string[];
    values: number[];
}>
Gets all CNS node type details.

Returns Promise<{
    icons: string[];
    typeIds: string[];
    typeNames: string[];
    values: number[];
}>
Promise for an object containing arrays with details for all defined CNS node types. All arrays have the same size.
See
CTRL function cns_getNodeTypes()
Example
```
const { typeIds, typeNames, values, icons } = await winccoa.cns_getNodeTypes();
for (let i = 0; i < typeIds.length; ++i)
  console.info(typeIds[i], typeNames[i], values[i], icons[i]);
```
- Defined in binding.ts:3984

cns_getNodeTypeValue

cns_getNodeTypeValue(typeName): Promise<number>
Returns the numerical value for the given CNS node type.
Parameters
- typeName: string
  Name of the CNS node type.
Returns Promise<number>
Promise - will be resolved to the numerical value for the node type or -1 if type does not exist.
See
CTRL function cns_getNodeTypeValue()
Example
```
const typeNum = await winccoa.cns_getNodeTypeValue('struct');
```
- Defined in binding.ts:4027

cns_getReadableViews

cns_getReadableViews(systemName): Promise<string[]>
Returns a list with all views (for which the current permission is sufficient) of the given system.
Parameters
- systemName: string
  System name
Returns Promise<string[]>
Promise - will be resolved to an array containing the names of all readable views.
See
CTRL function cns_getReadableViews()
Example
```
const views = await winccoa.cns_getReadableViews('System1');
```
- Defined in binding.ts:4051

cns_getViewPermission

cns_getViewPermission(viewName): Promise<number>
Returns the permission bits for the given view.
Parameters
- viewName: string
  View name.
Returns Promise<number>
Promise - will be resolved to a number containing the permission bits.
See
CTRL function cns_getViewPermission
Example
```
const views = await winccoa.cns_getViewPermission('System1.View1:');
```
- Defined in binding.ts:4075

cns_isNode

cns_isNode(path): Promise<boolean>
Checks whether the given CNS ID path is a node.
Parameters
- path: string
  CNS ID path.
Returns Promise<boolean>
Promise - will be resolved to true if path is a node.
See
CTRL function cns_isNode
Example
```
const isNode = await winccoa.cns_isNode('System1.View1::Node1');
```
- Defined in binding.ts:4099

cns_isTree

cns_isTree(path): Promise<boolean>
Checks whether the given CNS ID path is a tree.
Parameters
- path: string
  CNS ID path.
Returns Promise<boolean>
Promise - will be resolved to true if path is a tree.
See
CTRL function cns_isTree
Example
```
const isTree = await winccoa.cns_isTree('System1.View1:Node1');
```
- Defined in binding.ts:4123

cns_isView

cns_isView(path): Promise<boolean>
Checks whether the given CNS ID path is a view.
Parameters
- path: string
  CNS ID path.
Returns Promise<boolean>
Promise - will be resolved to true if path is a view.
See
CTRL function cns_isView
Example
```
const isView = await winccoa.cns_isView('System1.View1:');
```
- Defined in binding.ts:4147

cns_nodeExists

cns_nodeExists(path): Promise<boolean>
Checks whether the node with the given CNS ID path exists.
Parameters
- path: string
  CNS ID path.
Returns Promise<boolean>
Promise - will be resolved to true if node with path exists.
See
CTRL function cns_nodeExists
Example
```
const exists = await winccoa.cns_nodeExists('System1.View1::Node1');
```
- Defined in binding.ts:4171

cns_treeExists

cns_treeExists(path): Promise<boolean>
Checks whether the tree with the given CNS ID path exists.
Parameters
- path: string
  CNS ID path.
Returns Promise<boolean>
Promise - will be resolved to true if tree with path exists.
See
CTRL function cns_treeExists
Example
```
const exists = await winccoa.cns_treeExists('System1.View1::Node1');
```
- Defined in binding.ts:4195

cns_viewDpToName

cns_viewDpToName(dpName): Promise<string>
Returns the name of the CNS view linked to given dpName, if any.
Parameters
- dpName: string
  Data point name.
Returns Promise<string>
Name of the view linked to dpName or empty string if not found.
See
- CTRL function cns_viewDpToName
- cns_viewNameToDpName
Example
```
const viewName = winccoa.cns_viewDpToName('System1:_CNS_View_00002');
```
- Defined in binding.ts:4245

cns_viewExists

cns_viewExists(path): Promise<boolean>
Checks whether the view with the given CNS ID path exists.
Parameters
- path: string
  CNS ID path.
Returns Promise<boolean>
Promise - will be resolved to true if view with path exists.
See
CTRL function cns_viewExists
Example
```
const exists = await winccoa.cns_viewExists('System1.View1::Node1');
```
- Defined in binding.ts:4219

cns_viewNameToDpName

cns_viewNameToDpName(viewName, createNonExistingViewDp?): Promise<string>
Returns the name of the data point linked to given CNS viewName.
Parameters
- viewName: string
  CNS view name.
- createNonExistingViewDp: boolean = true
  If true (default), a linked data point is created if it does not already exist. If false, an empty string is returned if no linked data point exists.
Returns Promise<string>
Name of the data point linked to dpName or empty string if not found.
See
- CTRL function cns_viewNameToDpName
- cns_viewDpToName
Example
```
const viewName = winccoa.cns_viewNameToDpName('System1.View1:');
```
- Defined in binding.ts:4274

cnsAddNode

cnsAddNode(cnsParentPath, name, displayName, dp?): Promise<boolean>
Adds a new node to a tree or sub-tree.
Parameters
- cnsParentPath: string
  The ID path of the parent node of the new node.
  
  Note: You must specify a node and not a view.
- name: string
  ID of the new node
- displayName: unknown
  Display name of the new node as multi-language string
- dp: string = ''
  The optional data point (element) which is linked to the node. If no data point shall be linked an empty string can be defined (= default).
Returns Promise<boolean>
Promise - will be resolved to true if successful or rejected with WinccoaError in case of:
- Wrong or missing parameters
- The defined node cnsParentPath could not be found
- Illegal characters in name
See
- CTRL function cnsAddNode()
Example
```
try {
  await winccoa.cnsAddNode('System1.View1:Node1', 'A', 'A', 'System1:ExampleDP_Trend1.');
} catch(exc) {
  console.error(exc);
}
```
- WinccoaLangStringFormat
- Defined in binding.ts:4445

cnsAddObserver

cnsAddObserver(callback): number

Registers a callback for notification of CNS changes.

Parameters

callback: WinccoaCnsObserverCallback
Callback function that will be registered.

Returns number

ID of the callback.

See

Example

import {
  WinccoaManager,
  WinccoaCnsAction,
  WinccoaCnsChangeType,
} from 'winccoa-manager';
const winccoa = new WinccoaManager();

function cnsCB(
  path: string,
  changeType: WinccoaCnsChangeType,
  action: WinccoaCnsAction,
) {
  console.log(path, changeType, action);
}

const cbId = winccoa.cnsAddObserver(cnsCb);

cnsAddTree

cnsAddTree(cnsParentPath, tree): Promise<boolean>
Create a tree or sub-tree.
Parameters
- cnsParentPath: string
  The path of the parent element (view, tree or node)
- tree: WinccoaCnsTreeNode
  Details of the tree to create
Returns Promise<boolean>
Promise - will be resolved to true if successful or rejected with WinccoaError in case of:
- Wrong or missing parameters
- The defined view, tree or node cnsParentPath could not be found
- Illegal characters in WinccoaCnsTreeNode.name
- Data point in WinccoaCnsTreeNode.dp not found
See
- CTRL function cnsAddTree()
Example
```
try {
  let tree = new WinccoaCnsTreeNode('MyTree', 'MyTree', '', [
    new WinccoaCnsTreeNode('B', 'B', '', [
      new WinccoaCnsTreeNode('dp', 'ExampleDP_Rpt1', 'System1:ExampleDP_Rpt1.')
    ]),
    new WinccoaCnsTreeNode('C', {'de_AT.utf8': 'deC', 'en_US.utf8': 'enC'})
  ]);

  await winccoa.cnsAddTree('System1.View1', tree);
} catch(exc) {
  console.error(exc);
}
```
- Defined in binding.ts:4484

cnsChangeTree

cnsChangeTree(cnsPath, tree): Promise<boolean>
Replaces a tree or sub-tree with a new tree.
Parameters
- cnsPath: string
  The ID path of the tree (or node) that shall be replaced.
- tree: WinccoaCnsTreeNode
  Details of the tree to create
Returns Promise<boolean>
Promise - will be resolved to true if successful or rejected with WinccoaError in case of:
- Wrong or missing parameters
- The defined node or tree cnsPath could not be found
- Illegal characters in WinccoaCnsTreeNode.name
- Data point in WinccoaCnsTreeNode.dp not found
See
- CTRL function cnsChangeTree()
Example
```
try {
  let tree = new WinccoaCnsTreeNode('MyTree2', 'MyTree2', '', [
    new WinccoaCnsTreeNode('B', 'B', '', [
      new WinccoaCnsTreeNode('dp', 'ExampleDP_Rpt1', 'System1:ExampleDP_Rpt1.')
    ]),
    new WinccoaCnsTreeNode('C', {'de_AT.utf8': 'deC', 'en_US.utf8': 'enC'})
  ]);

  await winccoa.cnsChangeTree('System1.View1:MyTree', tree);
} catch(exc) {
  console.error(exc);
}
```
- Defined in binding.ts:4521

cnsCreateView

cnsCreateView(view, displayName, separator?): Promise<boolean>
Creates a new view with the given display name.
Parameters
- view: string
  The ID path of the new view
- displayName: unknown
  The display name of the new view as multi-language string
- separator: unknown = '.'
  The optional separator for the new view as multi-language string
  
  Note: The following characters are not allowed for separators: ' (single quotation mark), " (quotation marks), * (asterisk), ? (question mark). Moreover, numbers and letters which are already used in the view or node name must not be used.
Returns Promise<boolean>
Promise - will be resolved to true if successful or rejected with WinccoaError in case of:
- invalid argument type is given
- invalid view, or separator is given
- view with the given view already exists
See
- CTRL function cnsCreateView()
Example
```
try {
  await winccoa.cnsCreateView('System1.View123:', 'View123', '/');
} catch(exc) {
  console.error(exc);
}
```
- WinccoaLangStringFormat
- Defined in binding.ts:4317

cnsDeleteTree

cnsDeleteTree(cnsPath): Promise<boolean>
Delete a tree, sub-tree or node.
Parameters
- cnsPath: string
  The ID path of the element that shall be deleted.
Returns Promise<boolean>
Promise - will be resolved to true if successful or rejected with WinccoaError in case of:
- Wrong or missing parameters
- The defined tree cnsPath could not be found
See
- CTRL function cnsDeleteTree()
Example
```
try {
  await winccoa.cnsDeleteTree('System1.View1:MyTree');
} catch(exc) {
  console.error(exc);
}
```
- Defined in binding.ts:4545

cnsDeleteView

cnsDeleteView(view): Promise<boolean>
Delete a view with all its trees.
Parameters
- view: string
  ID path of the view
Returns Promise<boolean>
Promise - will be resolved to true if successful or rejected with WinccoaError in case of:
- invalid argument type is given
- invalid view
See
- CTRL function cnsDeleteView()
Example
```
try {
  await winccoa.cnsDeleteView('System1.View123:');
} catch(exc) {
  console.error(exc);
}
```
- Defined in binding.ts:4345

cnsGetAccessRight

cnsGetAccessRight(cnsPath, propertyKey): WinccoaCnsAccessRight
Returns the AccessRight for the given node. Note: the CNS property must be an uint.
Parameters
- cnsPath: string
  ID path of the node
- propertyKey: string
  The cns property key which is used for getting the AccessRight
Returns WinccoaCnsAccessRight
accessRight of type WinccoaCnsAccessRight
Throws
WinccoaError for invalid parameters (cnsPath does not exist).
See
- CTRL function cnsGetAccessRight()
Example
```
console.log(winccoa.cnsGetAccessRight('System1.View1:Node1', 'OA:OPC'));
```
- Defined in binding.ts:3656

cnsGetChildren

cnsGetChildren(cnsPath): string[]
Returns the paths of all children nodes for the given cnsPath.
Parameters
- cnsPath: string
  ID path of the node.
Returns string[]
Array of paths for all children nodes for cnsPath.
Throws
WinccoaError for invalid parameters (cnsPath or child for the given cnsPath does not exist).
See
- CTRL function cnsGetChildren()
- cnsGetParent
Example
```
const children = winccoa.cnsGetChildren('System1.View1:Node1');
console.log(children);
```
- Defined in binding.ts:3783

cnsGetDisplayNames

cnsGetDisplayNames(cnsPath): WinccoaLangString
Returns the display names for node with given cnsPath.
Parameters
- cnsPath: string
  CNS path for the node.
Returns WinccoaLangString
Display names in the current multi-language string format.
Throws
WinccoaError for invalid parameters (cnsPath does not exist).
See
- CTRL function cnsGetDisplayNames()
- WinccoaLangStringFormat
Example
```
console.log(winccoa.cnsGetDisplayNames('System1.View1:Node1.Rpt1'));
```
- Defined in binding.ts:3563

cnsGetDisplayPath

cnsGetDisplayPath(cnsPath): WinccoaLangString
Returns the display path for node with given cnsPath.
Parameters
- cnsPath: string
  CNS path for the node.
Returns WinccoaLangString
Display path in the current multi-language string format.
Throws
WinccoaError for invalid parameters (cnsPath does not exist).
See
- CTRL function cnsGetDisplayPath()
- WinccoaLangStringFormat
Example
```
console.log(winccoa.cnsGetDisplayPath('System1.View1:Node1.Rpt1'));
```
- Defined in binding.ts:3543

cnsGetId

cnsGetId(cnsPath, typeOutput?): string
Returns the data point element name (and optionally type) linked with given cnsPath.
Parameters
- cnsPath: string
  CNS path of the data point element.
- OptionaltypeOutput: {
  type: number;
  }
  If given, the property type will be set to the (customizable) ID of the CNS node.
  - type: number
Returns string
Data point element name or empty string.
Throws
WinccoaError when cnsPath does not exist.
See
- CTRL function cnsGetId()
Example
```
const details = { type: 0 };
const dpeName = winccoa.cnsGetId('System1.vvv:n1.nn1', details);
console.log(`DPE name: ${dpeName}, type: ${details.type}`);
```
- Defined in binding.ts:3346

cnsGetIdSet

cnsGetIdSet(pattern, viewPath?, searchMode?, langIdx?, type?): string[]
Returns a list of data point element names linked to nodes matching given pattern and additional criteria.
Parameters
- pattern: string
  Search pattern for the paths, can use wildcards **, * and ?. See cnsGetIdSet() for details.
- viewPath: string = ''
  Path to the view to be searched (optional, default: search all views).
- searchMode: WinccoaCnsSearchMode = ...
  Search mode (optional, default: search all names, case insensitive).
- langIdx: number = WinccoaCnsConstants.AllLanguages
  Index of the language to search when searchMode includes display names (optional, default: search all languages).
- type: number = WinccoaCnsNodeType.All
  Type of the nodes to search (optional, default: search all types).
Returns string[]
Array of data point element names linked to the matching nodes.
Throws
WinccoaError for invalid parameters.
See
- CTRL function cnsGetIdSet()
Example
```
import { WinccoaManager, WinccoaCnsSearchMode } from 'winccoa-manager';
const winccoa = new WinccoaManager();

// using default parameters
let dpeNames = winccoa.cnsGetIdSet('**1');
console.log(dpeNames);

// using explicit parameters
dpeNames = winccoa.cnsGetIdSet(
  '**Report*',
  'System1.View1:',
  WinccoaCnsSearchMode.DisplayName | WinccoaCnsSearchMode.CaseInsensitive,
  0,  // first project language
  55, // custom node type
);
console.log(dpeNames);
```
- Defined in binding.ts:3390

cnsGetNodesByData

cnsGetNodesByData(dpName, type?, viewPath?): string[]
Returns all CNS paths for nodes that are linked to a given data point (element).
Parameters
- dpName: string
  Name of the data point (element).
- type: number = WinccoaCnsNodeType.All
  Type of the nodes to search (optional, default: search all types).
- viewPath: string = ''
  Path to the view to be searched (optional, default: search all views).
Returns string[]
Array of matching CNS paths.
Throws
WinccoaError for invalid parameters.
See
- CTRL function cnsGetNodesByData()
Example
```
// default parameters
let result = winccoa.cnsGetNodesByData('ExampleDP_Rpt1.');
console.log(result);

// custom type, single view
result = winccoa.cnsGetNodesByData('ExampleDP_Rpt1.', 55, 'System1.View1:');
console.log(result);
```
- Defined in binding.ts:3478

cnsGetNodesByName

cnsGetNodesByName(pattern, viewPath?, searchMode?, langIdx?, type?): string[]
Returns a CNS paths matching given pattern and additional criteria.
Parameters
- pattern: string
  Search pattern for the paths, can use wildcards **, * and ?. See cnsGetNodesByName() for details.
- viewPath: string = ''
  Path to the view to be searched (optional, default: search all views).
- searchMode: WinccoaCnsSearchMode = ...
  Search mode (optional, default: search all names, case insensitive).
- langIdx: number = WinccoaCnsConstants.AllLanguages
  Index of the language to search when searchMode includes display names (optional, default: search all languages).
- type: number = WinccoaCnsNodeType.All
  Type of the nodes to search (optional, default: search all types).
Returns string[]
Array of matching CNS paths.
Throws
WinccoaError for invalid parameters.
See
- CTRL function cnsGetNodesByName()
Example
```
import { WinccoaManager, WinccoaCnsSearchMode } from 'winccoa-manager';
const winccoa = new WinccoaManager();

// using default parameters
let paths = winccoa.cnsGetNodesByName('**1');
console.log(paths);

// using explicit parameters
paths = winccoa.cnsGetNodesByName(
  '**Report*',
  'System1.View1:',
  WinccoaCnsSearchMode.DisplayName | WinccoaCnsSearchMode.CaseInsensitive,
  0,  // first project language
  55, // custom node type
);
console.log(paths);
```
- Defined in binding.ts:3438

cnsGetOPCAccessRight

cnsGetOPCAccessRight(cnsPath): WinccoaCnsAccessRight
Returns the OPC AccessLevel for the given node.
Parameters
- cnsPath: string
  ID path of the node
Returns WinccoaCnsAccessRight
accessRight of type WinccoaCnsAccessRight
Throws
WinccoaError for invalid parameters (cnsPath does not exist).
See
- CTRL function cnsGetOPCAccessRight()
Example
```
console.log(winccoa.cnsGetOPCAccessRight('System1.View1:Node1'));
```
- Defined in binding.ts:3681

cnsGetParent

cnsGetParent(cnsPath): string
Returns the path of the parent node for the given cnsPath.
Parameters
- cnsPath: string
  ID path of the node
Returns string
The ID path of the parent node for the given cnsPath.
Throws
WinccoaError for invalid parameters (cnsPath or parent for the given cnsPath does not exist).
See
- CTRL function cnsGetParent()
- cnsGetChildren
Example
```
const parent = winccoa.cnsGetParent('System1.View1:Node1.Node1');
console.log(parent);
```
- Defined in binding.ts:3762

cnsGetProperty

cnsGetProperty(cnsPath, key): unknown
Returns the value of the property with given key from node with given cnsPath.
Parameters
- cnsPath: string
  CNS path of the node for which the property value should be returned.
- key: string
  Key of the property
Returns unknown
Value of the property
Throws
WinccoaError for invalid parameters (cnsPath or key does not exist).
See
- CTRL function cnsGetProperty()
Example
```
const key = 'stringProperty';
const value = winccoa.cnsGetProperty('System1.View1:Node1.Rpt1', key);
console.log(`value of property '${key}' is '${value}'`);
```
- Defined in binding.ts:3504

cnsGetPropertyKeys

cnsGetPropertyKeys(cnsPath): string[]
Returns a list of the property keys existing for node with given cnsPath.
Parameters
- cnsPath: string
  CNS path of the node for which the property keys should be returned.
Returns string[]
List of property keys (possibly empty).
Throws
WinccoaError for invalid parameters (cnsPath does not exist).
See
- CTRL function cnsGetPropertyKeys()
Example
```
console.log(winccoa.cnsGetPropertyKeys('System1.View1:Node1.Rpt1'));
```
- Defined in binding.ts:3523

cnsGetRoot

cnsGetRoot(cnsNodePath): string
Returns the ID path of the root node of the tree which contains the given node.
Parameters
- cnsNodePath: string
  The ID path of the node
Returns string
ID path of the root node
Throws
WinccoaError for invalid parameters (cnsNodePath does not exist).
See
- CTRL function cnsGetRoot()
Example
```
console.log(winccoa.cnsGetRoot('System1.View1:Node1.Rpt1'));
```
- Defined in binding.ts:3581

cnsGetSystemNames

cnsGetSystemNames(systemName): WinccoaLangString
Returns the display names of the given system.
Parameters
- systemName: string
  System name in the current multi-language string format.
Returns WinccoaLangString
display names of the system
Throws
WinccoaError for invalid parameters (systemName does not exist).
See
- CTRL function cnsGetSystemNames()
- WinccoaLangStringFormat
Example
```
console.log(winccoa.cnsGetSystemNames('System1'));
```
- Defined in binding.ts:3600

cnsGetTrees

cnsGetTrees(view): string[]
Returns the ID paths of all trees of the given view.
Parameters
- view: string
  Name of the view
Returns string[]
The ID paths of all trees of the given view
Throws
WinccoaError for invalid parameters (view does not exist).
See
- CTRL function cnsGetTrees()
Example
```
console.log(winccoa.cnsGetTrees('System1.View1:'));
```
- Defined in binding.ts:3618

cnsGetUserData

cnsGetUserData(cnsPath): Buffer
Returns the user data stored in a node.
Parameters
- cnsPath: string
  ID path of the node
Returns Buffer
the user data stored in the node
Throws
WinccoaError for invalid parameters (cnsPath does not exist).
See
- CTRL function cnsGetUserData()
Example
```
console.log(winccoa.cnsGetUserData('System1.View1:Node1'));
```
- Defined in binding.ts:3636

cnsGetViewDisplayNames

cnsGetViewDisplayNames(viewPath): WinccoaLangString
Returns the display names for given viewPath.
Parameters
- viewPath: string
  ID path of the view.
Returns WinccoaLangString
Display names in the current multi-language string format.
Throws
WinccoaError for invalid parameters (viewPath does not exist).
See
- CTRL function cnsGetViewDisplayNames()
- WinccoaLangStringFormat
Example
```
console.log(winccoa.cnsGetViewDisplayNames('System1.View1:'));
```
- Defined in binding.ts:3701

cnsGetViews

cnsGetViews(systemName): string[]
Returns the paths of all views for the given systemName.
Parameters
- systemName: string
  System name.
Returns string[]
Array of paths for all found views for systemName.
Throws
WinccoaError for invalid parameters (systemName does not exist).
See
- CTRL function cnsGetViews()
Example
```
const result = winccoa.cnsGetViews('System1');
console.log(result);
```
- Defined in binding.ts:3741

cnsGetViewSeparators

cnsGetViewSeparators(viewPath): WinccoaLangString
Returns the separators for given viewPath.
Parameters
- viewPath: string
  ID path of the view.
Returns WinccoaLangString
Separators in the current multi-language string format.
Throws
WinccoaError for invalid parameters (viewPath does not exist).
See
- CTRL function cnsGetViewSeparators()
- WinccoaLangStringFormat
Example
```
console.log(winccoa.cnsGetViewSeparators('System1.View1:'));
```
- Defined in binding.ts:3721

cnsRemoveObserver

cnsRemoveObserver(id): number
Unregisters a callback for notification of CNS changes.
Parameters
- id: number
  ID of the callback to unregister as returned by cnsAddObserver.
Returns number
Callback ID.
Throws
WinccoaError when id is not registered.
See
- CTRL function cnsRemoveObserver()
- cnsAddObserver
Example
```
const id = winccoa.cnsAddObserver(cnsCb);
...

try {
  winccoa.cnsRemoveObserver(id);
} catch (exc) {
  console.error(exc);
}
```
- Defined in binding.ts:3324

cnsSetProperty

cnsSetProperty(cnsPath, key, value, valueType): Promise<boolean>
Sets or add the property for the given node as key/value pair. The following keys are already used by WinCC OA internally:
- OA:ICON Name of the icon (including the path relative to the pictures folder) that shall be set for the node.
- OA:OPC Appropriate bit pattern to define the AccessLevel. E.g. 3 to set the bits for read & write.
- OA:MOD Number of used registers (see Modbus/TCP server details or Plantmodel Editor - Modbus)
- OA:DMOD Number of dyn elements (see Modbus/TCP server details or Plantmodel Editor - Modbus)
Note: A maximum of 256 byte (sum of length of key, value and internal control characters) can be stored per node.
Parameters
- cnsPath: string
  ID path of the node
- key: string
  name
- value: unknown
  value
- valueType: WinccoaCtrlType
  Type of value (see WinccoaCtrlType).
Returns Promise<boolean>
Promise - will be resolved to true if successful or rejected with WinccoaError in case of:
- Wrong or missing parameters
- The defined node cnsPath could not be found
- The key/value pair exceeds the maximum length for node properties (256 bytes). Therefore, the pair cannot be added.
See
- CTRL function cnsSetProperty()
Example
```
try {
  await winccoa.cnsSetProperty('System1.View1:Node1', 'OA:OPC', 5, WinccoaCtrlType.int);
} catch(exc) {
  console.error(exc);
}
```
- Defined in binding.ts:4409

cnsSetUserData

cnsSetUserData(cnsPath, userData): Promise<boolean>
Stores user data in a node.
Parameters
- cnsPath: string
  ID path of the node
- userData: Buffer
  User data which shall be stored in the node. The blob is truncated to 255 bytes if it is too long.
Returns Promise<boolean>
Promise - will be resolved to true if successful or rejected with WinccoaError in case of:
- invalid argument type is given
- invalid cnsPath
See
- CTRL function cnsSetUserData()
Example
```
try {
  // v- Sample data in hex: 00 01 02 03  41 42 43 44  61 62 63 64  FC FB FE FF
  const userData = Buffer.alloc(16, 'AAECA0FCQ0RhYmNk/Pv+/w==', 'base64');

  await winccoa.cnsSetUserData('System1.View1:Node1', userData);
} catch(exc) {
  console.error(exc);
}
```
- Defined in binding.ts:4374

cnsSubStr

cnsSubStr(cnsPath, flags, resolvePath?): string
Returns a sub-string of cnsPath.
Parameters
- cnsPath: string
  ID path.
- flags: WinccoaCnsSubStrFlags
  Flag(s) that determine which part(s) of cnsPath should be included in the sub-string. Can be combined with a binary OR (|).
- resolvePath: boolean = true
  If true, cnsPath is resolved and existing elements will be used to determine the system name and separate the path from the tail. If false or no elements of cnsPath can be found, the specified parts will be extracted by parsing the path string. Disabling path resolution is mainly useful when you already know whether the path exists, so that you can avoid the overhead of accessing CNS.
Returns string
Sub-string of cnsPath.
See
- CTRL function cnsSubStr()
Example
```
const path = 'System1.View1:Node1.Rpt99';
console.log(winccoa.cnsSubStr(path, WinccoaCnsSubStrFlags.View));
console.log(
  winccoa.cnsSubStr(
    path,
    WinccoaCnsSubStrFlags.System | WinccoaCnsSubStrFlags.View,
    false,
  ),
);
```
- Defined in binding.ts:3817

Data Point

dpAliasToName

dpAliasToName(alias): string
Returns the data point name for the specified alias.
Parameters
- alias: string
  Data point alias to look up
Returns string
Data point name for given alias.
Throws
WinccoaError when alias is not found or invalid argument type.
See
Example
```
const alias = 'aliasReport1';
const dpName = winccoa.dpAliasToName(alias);
console.info(`DP for alias ${alias}: ${dpName}`);
```
- Defined in binding.ts:3098

dpAttributeType

dpAttributeType(dpAttributeName): WinccoaCtrlType
Returns the data type of a given data point attribute.
Parameters
- dpAttributeName: string
  The data point attribute name.
Returns WinccoaCtrlType
Returns the data type as a WinccoaCtrlType.
Throws
WinccoaError when the data point attribute does not exist or in case of an invalid argument type.
See
- WinccoaCtrlType
- CTRL function dpAttributeType()
Example
```
import { WinccoaManager, WinccoaCtrlType } from 'winccoa-manager';
const winccoa = new WinccoaManager();

async function dpAttributeType() {
  console.info(winccoa.dpAttributeType('ExampleDP_AlertHdl1.:_original.._value') == WinccoaCtrlType.bool);
}
```
- Defined in binding.ts:4674

dpCancelSplitRequest

dpCancelSplitRequest(id): boolean
Cancel dpQuerySplit request.
Parameters
- id: number
  from dpQuerySplit request.
Returns boolean
boolean true
Throws
Various argument errors.
See
- dpQuerySplit
- CTRL function dpCancelSplitRequest()
- Defined in binding.ts:2442

dpConnect

dpConnect(callback, dpeNames, answer?): number
Creates a connection for being notified of data point element updates.
Parameters
- callback: WinccoaDpConnectCallback
  Function that is called whenever a connected value changes.
- dpeNames: string | string[]
  DPE name(s) to connect to.
  Each update will contain updates for all elements in dpeNames, not only the changed values.
  - Each update will contain an array of values, also if only a single data point element name is given.
- answer: boolean = true
  if true, callback is called with the initial values right away, if false, callback is only called after an actual value change.
Returns number
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.
Throws
WinccoaError when invalid parameter types, unknown data point element names etc.

Remarks
For an example describing how to pass user data to a callback, see the second example for WinccoaDpQueryConnectCallback.
See
Example
```
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);
  }
}
```
- Defined in binding.ts:2112

dpCopy

dpCopy(source, destination, driver?): Promise<boolean>
Copies a data point including its configuration.
Parameters
- source: string
  Name of the data point to copy.
- destination: string
  Name of the new copied data point. Must not exist yet.
- Optionaldriver: number
  Optional driver number (default 1).
Returns Promise<boolean>
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).
Throws
WinccoaError when given source data point does not exist, when data point is copied into itself, invalid argument given, etc.
See
- CTRL function dpCopy()
Example
```
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);
}
```
- Defined in binding.ts:2288

dpCreate

dpCreate(dpeName, dpType, systemId?, dpId?): Promise<boolean>
Creates a data point.
Parameters
- dpeName: string
  Name of the data point to be created.
- dpType: string
  Type of data point to be created.
- OptionalsystemId: number
  To create a data point on a remote system in a distributed system, this parameter must contain the system number.
- OptionaldpId: number
  The ID of the data point. If a data point with the given ID already exists, a random ID is chosen.
Returns Promise<boolean>
Promise - will be resolved to true if successful or rejected with an error.
Throws
WinccoaError in case of:
- invalid argument type is given,
- invalid dpeName, dpType or non-existing systemId is given,
- data point with the given dpeName is already exist.
See
- dpDelete
- CTRL function dpCreate()
Example
```
let dpCreated = false;
try {
  dpCreated = await winccoa.dpCreate('newFloatDpe', 'ExampleDP_Float');
} catch (exc) {
  console.error(exc);
}

console.info("DP newFloatDpe is created - " + dpCreated);
```
- Defined in binding.ts:1096

dpDelete

dpDelete(dpName): Promise<boolean>
Deletes a data point.
Parameters
- dpName: string
  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.
Returns Promise<boolean>
Promise - will be resolved to true if successful or rejected with an error.
Throws
WinccoaError when data point with the given name does not exist or current user has no privileges to delete a DP.
See
- dpCreate
- CTRL function dpDelete()
Example
```
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);
```
- Defined in binding.ts:2256

dpDisconnect

dpDisconnect(id): number

Disconnect from data point element update connections established with dpConnect.

Parameters

id: number
ID of the connection to close as returned by dpConnect.

Returns number

ID of the connection that has been closed (>= 0).

Throws

WinccoaError when id is not found or invalid.

See

dpConnect

Example

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);
  }
}

dpElementType

dpElementType(dpeName): WinccoaElementType

Returns the data typeof a data point element.

Parameters

dpeName: string
Name of the data point element

Returns WinccoaElementType

Type of a data point element

Throws

WinccoaError when data point with the given dpeName is not found or invalid argument type.

See

Example

import { WinccoaManager, WinccoaElementType } from 'winccoa-manager';
const winccoa = new WinccoaManager();

function dpElementTypeTest() {
  try {
    let dpType = winccoa.dpElementType('ExampleDP_Arg1.');
    console.info('The type of ExampleDP_Arg1 is float - ' + (dpType == WinccoaElementType.Float));
  } catch (exc) {
    console.error(exc);
  }
}

dpExists

dpExists(dpeName): boolean
Checks the existence of a valid data point identifier.
Parameters
- dpeName: string
  A data point identifier: a sys, a DPT, a DP, a DPE, a config, a detail or an attr.
Returns boolean
true if at least one part of a data point identifier can be resolved correctly, otherwise false.
Throws
WinccoaError when invalid argument type is given.
See
- CTRL function dpExists()
Example
```
let isDpExists = false;
try {
  isDpExists = winccoa.dpExists('ExampleDP_Arg1.');
} catch (exc) {
  console.error(exc);
}
console.info("Is ExampleDP_Arg1 exists - " + isDpExists);
```
- Defined in binding.ts:937

dpGet

dpGet(dpeNames): Promise<unknown>
Get the current values of one or more data point elements.
Parameters
- dpeNames: string | string[]
  Data point element name(s) of the values to get.
Returns Promise<unknown>
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.
Throws
WinccoaError when DPE does not exist or current user has no read access to it.

See
CTRL function dpGet()
Example
```
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);
}
```
- Defined in binding.ts:1430

dpGetAlias

dpGetAlias(dpeName): string
Returns the alias for the specified data point.
Parameters
- dpeName: string
  Data point element
Returns string
the appropriate alias in the language. Note that the alias can be only unilingual.
Throws
WinccoaError when data point with the given dpeName is not found or invalid argument type.
See
Example
```
try {
  const alias = winccoa.dpGetAlias('ExampleDP_Rpt1.');
  console.info('DP alias: ' + alias);
} catch (exc) {
  console.error(exc);
}
```
- Defined in binding.ts:3075

dpGetAllAliases

dpGetAllAliases(aliasFilter?, dpeFilter?): {
aliases: string[];
dpNames: string[];
}
Returns data points and their aliases with the possibility to filter by data point element and/or alias.
Parameters
- aliasFilter: string = ''
  Pattern string for filtering the aliases (for example,'Engine*', '*').
- dpeFilter: string = ''
  Pattern string for filtering data point elements (for example '*.para'). An empty dpe pattern ('') and a '*' are treated like ALL DPEs. Also queries on remote systems can be executed. The system is part of the dpeFilter (for example, 'Sys23:*.**' - returns all aliases of a specific system; '*:*.**' would return the aliases of all systems. you can use it e.g. in a distributed system). Several systems can be defined with a list (for example, 'Sys{1,2,3,45}:Ex*').
Returns {
aliases: string[];
dpNames: string[];
}
Object containing two arrays with DPE names and their aliases that matching filter criteria. Both arrays have the same size.
- aliases: string[]
  Aliases corresponding to the DPEs in dpNames.
- dpNames: string[]
  Data point elements.
See
- dpGetAlias
- CTRL function dpGetAllAliases()
```
const { aliases, dpNames } = winccoa.dpGetAllAliases('*Pub*', '*Group*.');
for (let i = 0; i < aliases.length; i++)
  console.info(`${aliases[i]} --> ${dpNames[i]}`);
```
- Defined in binding.ts:3125

dpGetAllAttributes

dpGetAllAttributes(configName): string[]
Returns all attributes for the given config name.
Parameters
- configName: string
  Name of the config.
Returns string[]
Array of attributes of a config.
Throws
WinccoaError in case of an invalid argument type.
See
- dpGetAllConfigs
- CTRL function dpGetAllAttributes()
Example
```
function getAllDetails() {
  try {
    const atts = winccoa.dpGetAllAttributes('_original');
    console.info(atts, 'number of attributes = ' + atts.length);
  } catch (exc) {
    console.error(exc);
  }
}
```
- Defined in binding.ts:4701

dpGetAllConfigs

dpGetAllConfigs(dpNameOrType): string[]
Returns all possible configs, which are allowed to configure for the given data point element or data point type.
Parameters
- dpNameOrType: string | WinccoaElementType
  Name of the data point element or data point type. See WinccoaElementType.
Returns string[]
Array of configs for dpNameOrType.
Throws
WinccoaError when data point or type with the given dpNameOrType is not found or invalid argument type.
See
- WinccoaElementType
- CTRL function dpGetAllConfigs()
Example
```
import { WinccoaManager, WinccoaElementType } from 'winccoa-manager';
const winccoa = new WinccoaManager();

function getAllConfigs() {
  try {
    const configs = winccoa.dpGetAllConfigs(WinccoaElementType.String);
    console.info(configs);
  } catch (exc) {
    console.error(exc);
  }
}
```
- Defined in binding.ts:4589

dpGetAllDescriptions

dpGetAllDescriptions(descriptionFilter?, dpeFilter?, mode?): {
descriptions: WinccoaLangString[];
dpNames: string[];
}
Returns all data points and all descriptions that correspond to the given filters.
Parameters
- OptionaldescriptionFilter: string
  Pattern string for filtering the descriptions (optional, default: *).
- OptionaldpeFilter: string
  Pattern string for filtering data point elements (optional, default: *.**). An empty pattern ("") and a * are treated like *.**.
- Optionalmode: number
  Mode of functionality. For more details on all modes description see CTRL function dpGetAllDescriptions().
Returns {
descriptions: WinccoaLangString[];
dpNames: string[];
}
Object containing two arrays with data point names and their corresponding description.
- descriptions: WinccoaLangString[]
  Descriptions corresponding to the DPEs in dpNames
- dpNames: string[]
  Data point names.
See
- dpGetDescription
- CTRL function dpGetAllDescriptions()
Example
```
const { dpNames, descriptions } = winccoa.dpGetAllDescriptions('*', 'Example*');
for (let i = 0; i < dpNames.length; i++)
  console.info(`Description for ${dpNames[i]}: ${descriptions[i]}`);
```
- Defined in binding.ts:4640

dpGetAllDetails

dpGetAllDetails(configName): string[]
Returns all details of a given config name.
Parameters
- configName: string
  Name of the config.
Returns string[]
Array of details of a config.
Throws
WinccoaError in case of an invalid argument type.
See
- dpGetAllConfigs
- CTRL function dpGetAllDetails()
Example
```
try {
  const details = winccoa.dpGetAllDetails('_auth');
  console.info(details);
} catch (exc) {
  console.error(exc);
}
```
- Defined in binding.ts:4614

dpGetDescription

dpGetDescription(dpeName, mode?): WinccoaLangString
Returns the comment (description) for the data point.
Parameters
- dpeName: string
  Data point element or data point
- Optionalmode: number
  Mode of functionality. For more details on all modes description see CTRL function dpGetDescription().
Returns WinccoaLangString
Description in all available languages as or empty strings in all languages.

The returned data type can be defined with setOptions.
Throws
WinccoaError when data point with the given dpeName is not found or invalid argument type.
See
- dpSetDescription
- CTRL function dpGetDescription()
Example
```
let description;
try {
  description = winccoa.dpGetDescription('ExampleDP_Rpt1.');
} catch (exc) {
  console.error(exc);
  description = null;
}

if (description)
  console.info('DP description: ' + description);
```
- Defined in binding.ts:3014

dpGetFormat

dpGetFormat(dpeName): WinccoaLangString
This function returns the numerical format(s) of a data point.
Parameters
- dpeName: string
  Data point element
Returns WinccoaLangString
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.
Throws
WinccoaError when data point with the given dpeName is not found or invalid argument type.
See
- dpSetFormat
- CTRL function dpGetFormat()
Example
```
let formats;
try {
  formats = winccoa.dpGetFormat('ExampleDP_Rpt1.');
} catch (exc) {
  console.error(exc);
  formats = null;
}

if (formats)
  console.info('DP formats: ' + formats);
```
- Defined in binding.ts:2948

dpGetId

dpGetId(dpName): number[]
Returns the data point ID and the element ID of the given data point.
Parameters
- dpName: string
  Name of the data point.
Returns number[]
Array of size 2 with the first value - data point ID and the second value - element ID.
Throws
WinccoaError in case of an invalid argument type or data point does not exist.
See
- dpGetName
- CTRL function dpGetId()
Example
```
const dpe = 'ExampleDP_DDE.f1';
try {
  const dpEl_id = winccoa.dpGetId(dpe);
  console.info('data point ID = ' + dpEl_id[0], 'element id = ' + dpEl_id[1]);
} catch (exc) {
  console.error(exc);
}
```
- Defined in binding.ts:4727

dpGetMaxAge

dpGetMaxAge(age, dpeNames): Promise<unknown>
The function returns the value(s) of one or more data point elements from the driver. This function is available for the OPC UA Client, Modbus, S7Plus, SNMP, OPC drivers and S-Bus driver. The use of this function is only useful if an input or input/output peripheral address exists for a data point element. If a peripheral address exists, the function triggers a singleQuery for a driver if the value of the data point element dpName is older than the parameter age. The function returns the value from the driver. If a peripheral address does not exist, the function works as the function dpGet meaning that the function returns a value immediately irrespective of how old the value is.
Parameters
- age: number
  The maximum age of the value in milliseconds. When value is older than age, then value from the driver is returned.
- dpeNames: string | string[]
  Data point element name(s) whose value is queried.
Returns Promise<unknown>
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.
Throws
WinccoaError when DPE does not exist or current user has no read access to it.
See
- CTRL function dpGetMaxAge()
- dpGet
Example
```
const dpes = ['EIPtestCompactIN.BOOL', 'EIPtestCompactIN.INT', 'EIPtestCompactIN.STRING'];
try {
  // get value with the max age less than 5 seconds
  const values = (await winccoa.dpGetMaxAge(5000, dpes)) as [boolean, number, string];
  for (let i = 0; i < dpes.length; i++) {
    console.info(`${dpes[i]}: ${values[i]}`);
  }
} catch (exc) {
  console.error(exc);
}
```
- Defined in binding.ts:1472

dpGetName

dpGetName(dpId, elemId, systemId?): string
Returns the data point name for the given data point ID and element ID.
Parameters
- dpId: number
  Data point ID.
- elemId: number
  Element ID.
- OptionalsystemId: number
  System ID (optional). When not specified - own system.
Returns string
The data point name.
Throws
WinccoaError in case of an invalid argument type or data point does not exist with the given ID.
See
Example
```
try {
  const dpName = winccoa.dpGetName(1, 1);
  console.info('data point with id 1 and element id 1 =' + dpName);
} catch (exc) {
  console.error(exc);
}
```
- Defined in binding.ts:4755

dpGetPeriod

dpGetPeriod(startTime, endTime, dpeList, count?): Promise<{
times: Date[];
values: unknown[];
}[]>
Queries DP attributes over a specified period of time.
Parameters
- startTime: Date
  The start time of the interval from which values should be returned.
- endTime: Date
  The end time of the interval from which values should be returned.
- dpeList: string[]
  Single or multiple Data Points in an array.
- count: number = 0
  Optional number of values before startTime and after endTime that will also be returned.
Returns Promise<{
times: Date[];
values: unknown[];
}[]>
Promise will be resolved to data for the given DPEs if successful. It consists of an array of results (one for each DPE, in the order they are given in dpeList), each result contains two arrays, one for the values and one for the corresponding value change timestamps).
Throws
Promise will be rejected with WinccoaError in case of:
- empty data point list dpList
- data point not found
- invalid requestId
See
- CTRL function dpGetPeriod()
- dpGetPeriodSplit
Example
```
const dpe = 'System1:ExampleDP_Trend1.';
  const startTime = new Date(2023);
  const endTime = new Date(2025);
  console.log(await winccoa.dpGetPeriod(startTime, endTime, [dpe]));
```
- Defined in binding.ts:2475

dpGetPeriodSplit

dpGetPeriodSplit(startTime, endTime, dpeList, count?): Promise<{
    answerId: number;
    data: {
        times: Date[];
        values: unknown[];
    }[];
    id: number;
    progress: number;
}>
Queries DP attributes over a specified period of time. There are two calls, the first call described below and subsequent calls with requestId.
Parameters
- startTime: Date
  The start time of the interval from which values should be returned.
- endTime: Date
  The end time of the interval from which values should be returned.
- dpeList: string[]
  Single or multiple Data Points in an array.
- Optionalcount: number
  Optional number of values before startTime and after endTime that also have to be read out.
Returns Promise<{
    answerId: number;
    data: {
        times: Date[];
        values: unknown[];
    }[];
    id: number;
    progress: number;
}>
Promise will be resolved to an object containing:
- id Unique ID which must be used in subsequent calls (this is invalid when progress is 100)
- answerId Request or answer ID from data manager.
- progress Shows how much of the function was executed. 100 means that the function was executed completely.
- data Data identically to the result of dpGetPeriod,
Remarks
Use this function signature for the first call.
Throws
Promise will be rejected with WinccoaError in case of:
- empty data point list dpList
- data point not found
- invalid requestId
See
Example
```
async function test() {
 const dpe = 'System1:ExampleDP_Trend1.';
 const startTime = new Date(2023);
 const endTime = new Date(2025);

 const showResult = function (data: { times: Date[]; values: unknown[] }[]) {
   if (data.length > 0) {
     const { times, values } = data[0];
     for (let i = 0; i < data[0].times.length; i++) {
       console.info(
         `query line - timestamp = '${times[i]}' - value = ${values[i]}`,
       );
     }
   }
 };

let result = await winccoa.dpGetPeriodSplit(startTime, endTime, [dpe]);
 showResult(result.data);
 while (result.progress != 100) {
   result = await winccoa.dpGetPeriodSplit(result.id);
   showResult(result.data);
 }
}

await test();
```
- Defined in binding.ts:2541
dpGetPeriodSplit(requestId): Promise<{
    answerId: number;
    data: {
        times: Date[];
        values: unknown[];
    }[];
    id: number;
    progress: number;
}>
Queries DP attributes over a specified period of time.
Parameters
- requestId: number
  ID, only, subsequent calls.
Returns Promise<{
    answerId: number;
    data: {
        times: Date[];
        values: unknown[];
    }[];
    id: number;
    progress: number;
}>
Promise as described in dpGetPeriodSplit above.
Remarks
Use this function signature for subsequent call.
See
- CTRL function dpGetPeriodSplit()
- dpQuerySplit
- Defined in binding.ts:2563

dpGetUnit

dpGetUnit(dpeName): WinccoaLangString
This function returns the unit(s) of a data point.
Parameters
- dpeName: string
  Data point element
Returns WinccoaLangString
Returns the unit 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.
Throws
WinccoaError when data point with the given dpeName is not found or invalid argument type.
See
Example
```
try {
  let units = winccoa.dpGetUnit('ExampleDP_Rpt1.');
  console.info('DP units: ' + units);
} catch (exc) {
  console.error(exc);
}
```
- Defined in binding.ts:2885

dpNames

dpNames(dpPattern?, dpType?, ignoreCase?): string[]
Returns all the data point names or the data point element names that match a pattern in alphabetical order.
Parameters
- dpPattern: string = ''
  Serach pattern. When an empty pattern is given (=default), then returns all data points.
  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 attributes
  - dp.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);
```
- dpType: string = ''
  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.
- ignoreCase: boolean = false
  Defines if the search should ignore the casing of the search pattern (=true) or not (=false, default)
Returns string[]
List with data points or data point element names.
Throws
WinccoaError when invalid argument type is given.
See
- CTRL function dpNames()
Example
```
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));
}
```
- Defined in binding.ts:987

dpQuery

dpQuery(query): Promise<unknown[][]>
Retrieves attribute values with the help of SQL statements.
Parameters
- query: string
  SQL statement.
Returns Promise<unknown[][]>
Promise - will be resolved to true if successful or rejected with an error.
Remarks
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]
]
```
Throws
WinccoaError when invalid parameter or query string is given.
See
Example
```
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],
    );
  }
}
```
- Defined in binding.ts:2367

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

dpQueryConnectAll

dpQueryConnectAll(callback, answer, query, blockingTime?): number
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.
Parameters
- callback: WinccoaDpQueryConnectCallback
  Function that is called whenever a subscribed DPE value changes. The update message will contain all subscribed DPEs.
- answer: boolean
  if true, callback is called with the initial DPE values right away, if false, callback is only called for an actual value change.
- query: string
  query as an SQL statement.
- blockingTime: number = -1
  Time in milli-seconds when the call of the callback function is blocked by an open query. In this time, query results are collected and then returned after blockingTime in a single callback. If blockingTime is set to 0, the callback function is called immediately when a value is updated. If not given, the blocking time is read from the config entry queryHLBlockedTime.
Returns number
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.
Throws
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.

Remarks
For an example describing how to pass user data to a callback, see the second example for WinccoaDpQueryConnectCallback.
See
Example
```
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);
  }
}
```
- Defined in binding.ts:2738

dpQueryConnectSingle

dpQueryConnectSingle(callback, answer, query, blockingTime?): number
Calls callback whenever one or more DPEs which meet the query condition are changed.
Parameters
- callback: WinccoaDpQueryConnectCallback
  Function that is called whenever a subscribed DPE value changes. The update message will contain only changed DPEs.
- answer: boolean
  if true, callback is called with the initial DPE values right away, if false, callback is only called for an actual value change.
- query: string
  query as an SQL statement.
- blockingTime: number = -1
  Time in milli-seconds when the call of the callback function is blocked by an open query. In this time, query results are collected and then returned after blockingTime in a single callback. If blockingTime is set to 0, the callback function is called immediately when a value is updated. If not given, the blocking time is read from the config entry queryHLBlockedTime.
Returns number
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.
Throws
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.

Remarks
For an example describing how to pass user data to a callback, see the second example for WinccoaDpQueryConnectCallback.
See
Example
```
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);
  }
}
```
- Defined in binding.ts:2657

dpQueryDisconnect

dpQueryDisconnect(id): number

Disconnect from dpQueryConnectSingle (or dpQueryConnectAll) .

Parameters

id: number
ID of the connection to close as returned by dpQueryConnectAll or dpQueryConnectSingle.

Returns number

ID of the closed connection (>= 0).

Throws

WinccoaError when id is not found or invalid.

See

Example

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);
  }
}

dpQuerySplit

dpQuerySplit(queryOrId): Promise<{
    answerId: number;
    data?: unknown[][];
    id: number;
    progress: number;
}>
Query attributes of a set of data points as an SQL-like query string. Use the function when you query a large amount of data. The function reduces the system load and offers a considerable advantage when dealing with a large amount of data. To cancel a dpQuerySplit use dpCancelSplitRequest. After WinccoaOptions.splitTimeout milliseconds, the id is invalid.
Parameters
- queryOrId: string | number
  First call: SQL statement, subsequent calls: ID.
Returns Promise<{
    answerId: number;
    data?: unknown[][];
    id: number;
    progress: number;
}>
Promise will be resolved to an object containing:
- id Unique ID which must be used in subsequent calls (this is invalid when progress is 100)
- answerId Request or answer ID from data manager.
- progress Shows how much of the function was executed. 100 means that the function was executed completely.
- data Data identically to the result of dpQuery.
Throws
Promise will be rejected with WinccoaError in case of:
- query is invalid
- id is invalid
- dpQuerySplit is called again without waiting for previous dpQuerySplit promise to be resolved or rejected.
Throws
Various argument errors.
See
Example
```
async function test() {
  // TIMERANGE: use historic data, otherwise no split occur
   const query = `SELECT '_original.._stime', '_original.._value' FROM '_*' TIMERANGE("1970-01-01T00:00:00.000Z", "2060-01-01T00:00:00.000Z", 0, 0)`;
 let result;

  const showResult = function (queryTable: string[][]) {
    for (let i = 0; i < queryTable.length; i++) {
      console.info(
        `query line - name: '%s' - timestamp = %s - value = %s`,
        ...queryTable[i],
      );
    }
  };

  result = await winccoa.dpQuerySplit(query);
  showResult(result.data as string[][]);
  while (result.progress != 100) {
    result = await winccoa.dpQuerySplit(result.id);
    showResult(result.data as string[][]);
  }
}
await test();
```
- Defined in binding.ts:2421

dpSet

dpSet(dpeNames, values): boolean
Set the value of one or more data point element(s).
Parameters
- dpeNames: string | string[]
  Data point element name(s) of the values to set.
- values: unknown
  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.
Returns boolean
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.
Throws
WinccoaError when DPE names do not exist, values cannot be converted, array sizes mismatch etc.
See
Example
```
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);
}
```
- Defined in binding.ts:1139

dpSetAlias

dpSetAlias(dpeName, alias): Promise<boolean>
Sets the alias for the specified data point element.
Parameters
- dpeName: string
  Data point element
- alias: string
  Alias to be set. Note that the alias can be set only unilingual.
Returns Promise<boolean>
Promise - will be resolved to true if successful or rejected with an error.
Throws
WinccoaError when data point with the given dpeName is not found or invalid argument type, etc.
See
- dpGetAlias
- CTRL function dpSetAlias()
Example
```
let isSuccess = false;
try {
  isSuccess = await winccoa.dpSetAlias('ExampleDP_Rpt1.', 'rpt1Alias');
} catch (exc) {
  console.error(exc);
}

console.info('DP alias is set successfully - ' + isSuccess);
```
- Defined in binding.ts:3191

dpSetAndWaitForValue

dpSetAndWaitForValue(dpNamesSet, dpValuesSet, dpNamesWait, conditions, dpNamesReturn, timeoutMs?): Promise<unknown>
This function sets the data points listed in dpNamesSet to the values given in dpValuesSet and waits for another set of data points to change their values until all specified conditions are met (that is, all values of the data points listed in dpNamesWait are equal to the values given in conditions). Once conditions are fulfilled, it returns the values of another set of data points (given in dpNamesReturn). If the conditions are not met within the specified timeoutMs period, the promise is rejected.

NOTE

The values in conditions are compared directly in TypeScript, not by WinCC OA. Therefore the comparision is not as strict as it would be when using the CTRL function dpSetAndWaitForValue(), which also checks the type of the values. For example, in CTRL an integer value will never match a float value, also if both have the same numeric value, while in JavaScript the comparision will only based on the numeric value.
Parameters
- dpNamesSet: string[]
  Names of the data points to set.
- dpValuesSet: unknown[]
  Values to set, must have the same size as dpNamesSet.
- dpNamesWait: string[]
  Names of the data points to wait for a value change.
- conditions: unknown[]
  Expected values for the data points in dpNamesWait to wait for. Must have the same size as dpNamesWait.
- dpNamesReturn: string[]
  Names of the data points whose values will be returned in the Promise.
- timeoutMs: number = 0
  Optional timeout for waiting on conditions.
Returns Promise<unknown>
Promise containing the values for dpNamesReturn .
Throws
WinccoaError when timeout expired, DPE names do not exist, values cannot be converted, array sizes mismatch, no write access etc.
See
Example
```
const argNames = ['ExampleDP_Arg1.', 'ExampleDP_Arg2.'];
const resultName = ['ExampleDP_Result.'];

console.log(
  await winccoa.dpSetAndWaitForValue(
    argNames,
    [3, 7],
    resultName,
    [10],
    argNames.concat(resultName),
    1000,
  ),
);
```
- Defined in binding.ts:1386

dpSetDescription

dpSetDescription(dpeName, comment): Promise<boolean>
Sets a comment (description) for the data point.
Parameters
- dpeName: string
  Data point element to be commented on.
- comment: WinccoaLangString
  Comment in one or all languages.
Returns Promise<boolean>
Promise - will be resolved to true if successful or rejected with an error.
Throws
WinccoaError when data point with the given dpeName is not found or invalid argument type, etc.
See
- dpGetDescription
- CTRL function dpSetDescription()
Example
```
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);
```
- Defined in binding.ts:3046

dpSetFormat

dpSetFormat(dpeName, format): Promise<boolean>
Sets the numerical format(s) of a data point.
Parameters
- dpeName: string
  Data point element
- format: WinccoaLangString
  A string that contains the format (for example, '%6.2f') in one or several languages.
Returns Promise<boolean>
Promise - will be resolved to true if successful or rejected with an error.
Throws
WinccoaError when data point with the given dpeName is not found or invalid argument type, etc.
See
- dpGetFormat
- CTRL function dpSetFormat()
Example
```
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);
```
- Defined in binding.ts:2981

dpSetTimed

dpSetTimed(time, dpeNames, values): boolean
Set values of one or more data point element(s) with a given source time.
Parameters
- time: Date
  Source time for the value change.
- dpeNames: string | string[]
  Data point element name(s) of the values to set.
- values: unknown
  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.
Returns boolean
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.
Throws
WinccoaError when DPE names do not exist, values cannot be converted, array sizes mismatch etc.
See
Example
```
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);
```
- Defined in binding.ts:1218

dpSetTimedWait

dpSetTimedWait(time, dpeNames, values): Promise<boolean>
Set values of one or more data point element(s) with a given source time.
Parameters
- time: Date
  Source time for the value change.
- dpeNames: string | string[]
  Data point element name(s) of the values to set.
- values: unknown
  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.
Returns Promise<boolean>
Promise that resolves to true if succesful. If not successful, a WinccoaError wil be thrown instead.
Throws
WinccoaError when DPE names do not exist, values cannot be converted, array sizes mismatch, no write access etc.
See
Example
```
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);
```
- Defined in binding.ts:1259

dpSetUnit

dpSetUnit(dpeName, unit): Promise<boolean>
Sets the unit(s) for a data point.
Parameters
- dpeName: string
  Data point
- unit: WinccoaLangString
  Unit (for example, kg) in one or several languages.
Returns Promise<boolean>
Promise - will be resolved to true if successful or rejected with an error.
Throws
WinccoaError when data point with the given dpeName is not found or invalid argument type, etc.
See
- dpGetUnit
- CTRL function dpSetUnit()
Example
```
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);
```
- Defined in binding.ts:2917

dpSetWait

dpSetWait(dpeNames, values): Promise<boolean>
Set the value of one or more data point element(s).
Parameters
- dpeNames: string | string[]
  Data point element name(s) of the values to set.
- values: unknown
  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.
Returns Promise<boolean>
Promise that resolves to true if succesful. If not successful, a WinccoaError wil be thrown instead.
Throws
WinccoaError when DPE names do not exist, values cannot be converted, array sizes mismatch, no write access etc.
See
Example
```
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);
}
```
- Defined in binding.ts:1173

dpTypes

dpTypes(pattern?, systemId?, includeEmpty?): string[]
Returns all or selected data point types from the current project.
Parameters
- pattern: string = ''
  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*');
```
- systemId: number = -1
  The desired system if querying from other systems. Optional parameter. If this parameter is not defined, the own system is queried.
- includeEmpty: boolean = true
  When this is set to false, data point types without existing data points will be ignored.
Returns string[]
String array with all DP type names.
Throws
WinccoaError when invalid argument type or non-existing systemId is given.
See
- CTRL function dpTypes()
Example
```
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);
}
```
- Defined in binding.ts:1034

dpWaitForValue

dpWaitForValue(dpNamesWait, conditions, dpNamesReturn, timeoutMs?): Promise<unknown>
This function waits for a set of data points to change their values until all specified conditions are met (that is, all values of the data points listed in dpNamesWait are equal to the values given in conditions). Once conditions are fulfilled, it returns the values of another set of data points (given in dpNamesReturn). If the conditions are not met within the specified timeoutMs period, the promise is rejected.

NOTE

The values in conditions are compared directly in TypeScript, not by WinCC OA. Therefore the comparision is not as strict as it would be when using the CTRL function dpWaitForValue(), which also checks the type of the values. For example, in CTRL an integer value will not match a float value, also if both have the same numeric value, while in JavaScript the comparision will only based on the numeric value.
Parameters
- dpNamesWait: string[]
  Names of the data points to wait for a value change.
- conditions: unknown[]
  Expected values for the data points in dpNamesWait to wait for. Must have the same size as dpNamesWait.
- dpNamesReturn: string[]
  Names of the data points whose values will be returned in the Promise.
- timeoutMs: number = 0
  Optional timeout for waiting on conditions.
Returns Promise<unknown>
Promise containing the values for dpNamesReturn .
Throws
WinccoaError when timeout expired, DPE names do not exist, values cannot be converted, array sizes mismatch etc.
See
Example
```
const argNames = ['ExampleDP_Arg1.', 'ExampleDP_Arg2.'];
const resultName = ['ExampleDP_Result.'];

setTimeout(() => winccoa.dpSet(argNames, [6, 4]), 100);

console.log(
  await winccoa.dpWaitForValue(resultName, [10], argNames.concat(resultName)),
);
```
- Defined in binding.ts:1316

nameCheck

nameCheck(name, nameType): Promise<{
name: string;
valid: boolean;
}>
Checks if a given name contains invalid characters for a specific use (e. g. as data point or project name) and also provides a version of that name with invalid characters removed.
Parameters
- name: string
  The name to check
- nameType: WinccoaNameCheckType
  The type of check to perform, there is a different set of invalid characters for each type.
Returns Promise<{
name: string;
valid: boolean;
}>
Promise for an object containing a valid flag and a version of name without invalid characters.
Throws
WinccoaError in case of an invalid arguments.
See
- WinccoaNameCheckType
- CTRL function nameCheck()
Example
```
import { WinccoaManager, WinccoaNameCheckType } from 'winccoa-manager';
const winccoa = new WinccoaManager();

...

// checking if a name is valid
if (
  !(await winccoa.nameCheck(nameToCheck, WinccoaNameCheckType.Project)).valid
)
  console.error(`Invalid project name: ${nameToCheck}`);

// automatically correct name if necessary
const name = (await winccoa.nameCheck(nameToCheck, WinccoaNameCheckType.Dp)).name;
```
- Defined in binding.ts:4792

Data Point Type

dpGetDpTypeRefs

dpGetDpTypeRefs(dpt): {
dpePaths: string[];
refNames: string[];
}
Returns all references to other DPTs in a DPT.
Parameters
- dpt: string
  Name of the data point type to be checked for references (for example, "PUMP1")
Returns {
dpePaths: string[];
refNames: string[];
}
Object containing two array with references and their corresponding data point element path.
- dpePaths: string[]
  Data point element paths corresponding to the references in refNames.
- refNames: string[]
  Reference names.
Throws
WinccoaError in case of:
- an invalid argument type or
- dpt does not exist
See
- CTRL function dpGetDpTypeRefs()
Example
```
console.log(winccoa.dpGetDpTypeRefs('PUMP1'));
```
- Defined in binding.ts:2011

dpGetRefsToDpType

dpGetRefsToDpType(reference): {
dpePaths: string[];
dptNames: string[];
}
Returns all DPTs and DPs that contain the specified DPT as a reference.
Parameters
- reference: string
  Name of the DPT reference to check data point types and data points for (for example, "_MyReference" or "_ValueArchive").
Returns {
dpePaths: string[];
dptNames: string[];
}
Object containing two arrays with DPT names and the corresponding data point element path.
- dpePaths: string[]
  Data point element names corresponding to the the DPTs in dptNames.
- dptNames: string[]
  DPT names.
Throws
WinccoaError in case of:
- an invalid argument type
Remarks
reference is only a filter and its content causes never an error.
See
- CTRL function dpGetRefsToDpType()
Example
```
console.log(winccoa.dpGetRefsToDpType('MODE_STATE'));
```
- Defined in binding.ts:2039

dpTypeChange

dpTypeChange(startNode): Promise<boolean>
Change an existing data point type tree. The startNode.name must be an existing Data point type name. The complete type structure under startNode will be replaced. Use WinccoaDpTypeNode.newName to rename an existing name.
Parameters
- startNode: WinccoaDpTypeNode
  the top data point type node of the tree.
Returns Promise<boolean>
Promise - will be resolved to true if successful or rejected with WinccoaError in case of:
- invalid argument type is given
- WinccoaDpTypeNode.name contains invalid characters or is empty
- WinccoaDpTypeNode.newName contains invalid characters or
- WinccoaDpTypeNode.refName is neither empty nor a valid data point
See
Example
```
import { WinccoaDpTypeNode,  WinccoaElementType, WinccoaManager } from 'winccoa-manager';
const winccoa = new WinccoaManager();

async function test1() {
  const tree =
    new WinccoaDpTypeNode('MyType1', WinccoaElementType.Struct, '', [
      new WinccoaDpTypeNode('text', WinccoaElementType.String, '', [], 'string'),
      new WinccoaDpTypeNode('typeRef', WinccoaElementType.Typeref, 'ExampleDP_Int'),
      new WinccoaDpTypeNode('struct', WinccoaElementType.Struct, '', [
        new WinccoaDpTypeNode('id2', WinccoaElementType.Float)
      ])
    ]);
  console.log(await winccoa.dpTypeChange(tree));
}
test1();
```
- Defined in binding.ts:1924

dpTypeCreate

dpTypeCreate(startNode): Promise<boolean>

Creates a new data point type tree.

Parameters

startNode: WinccoaDpTypeNode
the first data point type node of the tree.

Returns Promise<boolean>

Promise - will be resolved to true if successful or rejected with WinccoaError in case of:

invalid argument type is given or
WinccoaDpTypeNode.name contains invalid characters or is empty
WinccoaDpTypeNode.refName is neither empty nor a valid data point

See

Example

import { WinccoaDpTypeNode,  WinccoaElementType, WinccoaManager } from 'winccoa-manager';
const winccoa = new WinccoaManager();

async function test1() {
  const tree =
    new WinccoaDpTypeNode('MyType1', WinccoaElementType.Struct, '', [
      new WinccoaDpTypeNode('id', WinccoaElementType.Int),
      new WinccoaDpTypeNode('text', WinccoaElementType.String),
      new WinccoaDpTypeNode('typeRef', WinccoaElementType.Typeref, 'ExampleDP_Float'),
      new WinccoaDpTypeNode('struct', WinccoaElementType.Struct, '', [
        new WinccoaDpTypeNode('id2', WinccoaElementType.Int),
        new WinccoaDpTypeNode('text2', WinccoaElementType.String)
      ])
    ]);
  console.log(await winccoa.dpTypeCreate(tree));
}
test1();

dpTypeDelete

dpTypeDelete(dpt): Promise<boolean>
Deletes an existing data point type.
Parameters
- dpt: string
  Name of the data point type to delete.
Returns Promise<boolean>
Promise - will be resolved to true if successful or rejected with WinccoaError in case of:
- invalid argument type is given
- dpt does not exist
See
Example
```
console.log(await winccoa.dpTypeDelete('MyType1'));
```
- Defined in binding.ts:1947

dpTypeGet

dpTypeGet(dpt, includeSubTypes?): WinccoaDpTypeNode
Returns the structure of a data point type.
Parameters
- dpt: string
  Data point type.
- includeSubTypes: boolean = false
  true: subtypes will be passed
Returns WinccoaDpTypeNode
Data point type structure as a tree of WinccoaDpTypeNode
Throws
WinccoaError in case of:
- an invalid argument type or
- dpt does not exist
See
Example
```
import { WinccoaDpTypeNode,  WinccoaElementType, WinccoaManager } from 'winccoa-manager';
const winccoa = new WinccoaManager();

console.log(winccoa.dpTypeGet('ExampleDP_Float'));
```
- Defined in binding.ts:1838

dpTypeName

dpTypeName(dp): string
Returns the data point type for the data point name.
Parameters
- dp: string
  Name of the data point (for example, "ExampleDP_Trend1")
Returns string
Data Point Type name
Throws
WinccoaError in case of:
- an invalid argument type or
- dp does not exist
See
- CTRL function dpTypeName()
Example
```
console.log(winccoa.dpTypeName('ExampleDP_Trend1'));
```
- Defined in binding.ts:1968

dpTypeRefName

dpTypeRefName(dpe): string
Returns the type reference of the selected DPE.
Parameters
- dpe: string
  Name of the data point element (for example, "_mp_PUMP1.state.mode")
Returns string
Empty string or type reference as string.
Throws
WinccoaError in case of:
- an invalid argument type or
- dpe does not exist
See
- CTRL function dpTypeRefName()
Example
```
console.log(winccoa.dpTypeRefName('_mp_PUMP1.state.mode')); // output MODE_STATE
```
- Defined in binding.ts:1989

Logging

logFatal

logFatal(...args): void
Writes a fatal error log entry. This also exits the WinCC OA manager.
Parameters
- Rest...args: unknown[]
  Fatal error information to be written to log.
Returns void
Example
```
let note = "Additional note.";
winccoa.logFatal("Fatal message", note);
```
- Defined in binding.ts:802

logInfo

logInfo(...args): void
Writes an information log entry. console.log() and console.info() are mapped to this method.
Parameters
- Rest...args: unknown[]
  Information to be written to log.
Returns void
Example
```
let note = "Additional note.";
winccoa.logInfo("Info message", note);
```
- Defined in binding.ts:757

logSevere

logSevere(...args): void
Writes a severe error log entry. console.error() is mapped to this method.
Parameters
- Rest...args: unknown[]
  Severe error information to be written to log.
Returns void
Example
```
let note = "Additional note.";
winccoa.logSevere("Severe message", note);
```
- Defined in binding.ts:787

logWarning

logWarning(...args): void
Writes a warning log entry. console.warn() is mapped to this method.
Parameters
- Rest...args: unknown[]
  Warning information to be written to log.
Returns void
Example
```
let note = "Additional note.";
winccoa.logWarning("Warning message", note);
```
- Defined in binding.ts:772

securityEvent

securityEvent(id, ...args): void
Reports a security event, this must be called whenever a security-relevant action is made in JavaScript (like opening a server port).
Parameters
- id: WinccoaSecurityEventId
  ID of the security event.
- Rest...args: unknown[]
  Arguments for the security event, depending on the value of id. See WinccoaSecurityEventId for details.
Returns void
Throws
WinccoaError when id is not known, required arguments are missing in args.

See
WinccoaSecurityEventId
Example
```
import { WinccoaManager, WinccoaSecurityEventId } from 'winccoa-manager';
const winccoa = new WinccoaManager();

winccoa.securityEvent(WinccoaSecurityEventId.PortOpened, 8443, 'https://');
```
- Defined in binding.ts:2857

Manager

constructor

new WinccoaManager(): WinccoaManager
Constructor - creates new instance of an API object.

Returns WinccoaManager
Example
```
import { WinccoaManager } from 'winccoa-manager';
const winccoa = new WinccoaManager();
```
- Defined in binding.ts:739

sysConnect

get sysConnect(): WinccoaSysConnect
Gets access sysConnect updates, which uses the Node.js event emitter mechanism to inform clients of various events. For details and examples see WinccoaSysConnect.

Returns WinccoaSysConnect
See
WinccoaSysConnect
- Defined in binding.ts:4559

exit

exit(exitCode?): void
Exits the WinCC OA manager.

NOTE

For details about using an exit listener with WinCC OA, see the note in the documentation for WinccoaSysConEvent.
Parameters
- exitCode: number = 0
  Exit code to return to the operating system.
Returns void
Example
```
winccoa.exit();
```
- Defined in binding.ts:839

findFile

findFile(fileDirName): string
Search for file or directory in WinCC OA project and installation paths.
Parameters
- fileDirName: string
  the file or directory to search for
Returns string
full path of the file or directory or an empty string if not found
Throws
WinccoaError when invalid argument type is given.
Example
```
let configPath;
try {
  configPath = winccoa.findFile('config/config');
} catch (exc) {
  console.error(exc);
}

console.info("Config file full path: " + configPath);
```
- Defined in binding.ts:1061

getOptions

getOptions(): WinccoaOptions
Returns all available options and their values. The options can be set with setOptions.

Returns WinccoaOptions
Object containing all current option values.
See
- setOptions
- WinccoaOptions
Example
```
let options = winccoa.getOptions();
for (const [key, value] of Object.entries(options)) {
  console.info(`Name: ${key} - Value: ${value}`);
}
```
- Defined in binding.ts:859

getPaths

getPaths(): string[]
Returns list of project, sub-project and product installation paths.

Returns string[]
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.
Example
```
let paths = winccoa.getPaths();
for (let i = 0; i < paths.length; i++) {
  console.info(paths.at(i));
}
```
- Defined in binding.ts:820

getSystemId

getSystemId(systemName?): number
Returns the system ID.
Parameters
- OptionalsystemName: string
  The name of the system (optional). If it is not given, then the system ID of its own system will be returned.
Returns number
The system ID.
Throws
WinccoaError when invalid system name is given.
See
- getSystemName
- CTRL function getSystemId()
Example
```
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);
```
- Defined in binding.ts:2189

getSystemName

getSystemName(systemId?): string
Returns the system name.
Parameters
- OptionalsystemId: number
  System ID (optional). If it is not given, then the system name of its own system will be returned.
Returns string
The system name.
Throws
WinccoaError when invalid system ID is given.
See
- getSystemId
- CTRL function getSystemName()
Example
```
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);
}
```
- Defined in binding.ts:2218

getVersionInfo

getVersionInfo(): WinccoaVersionDetails
Returns information about current API and WinCC OA versions.

Returns WinccoaVersionDetails
API and WinCC OA versions.
- Defined in binding.ts:914

setOptions

setOptions(options): boolean
Set one or more options. The options and their values can be retrieved with getOptions.
Parameters
- options: Partial<Omit<WinccoaOptions, "userId">>
  The options to be set (see WinccoaOptions for possible options).
Returns boolean
Boolean true on success, otherwise WinccoaError wil be thrown instead.
Remarks
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.

Throws
WinccoaError if option has wrong type or option value is out of range.
See
Example
```
import { WinccoaManager, WinccoaLangStringFormat } from 'winccoa-manager';
const winccoa = new WinccoaManager();

function setOptionsTest() {
  try {
    winccoa.setOptions({
      langStringFormat: WinccoaLangStringFormat.StringFixed,
      langIdx: 1,
    });
  } catch (exc) {
    console.error(exc);
  }
}
```
- Defined in binding.ts:896

setUserId

setUserId(id, password?): boolean
Sets the current user ID to the specified value for the current instance of WinccoaManager.

Note that when Server-side Authentication for Managers is activated and the JavaScript manager is not started as root, trying to change the user ID will lead to a fatal error and the JavaScript manager will be terminated immediately.
Parameters
- id: number
  User ID to set.
- Optionalpassword: string
  Password to use to set user (not needed if manager started as root).
Returns boolean
Boolean true in case of a success, otherwise WinccoaError wil be thrown instead.
Throws
WinccoaError when id is not found or invalid.
See
- CTRL function setUserId()
Example
```
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);
```
- Defined in binding.ts:2832

Redundancy

isReduActive

isReduActive(): boolean
Checks if the event manager to which this manager is connected is currently the active REDU partner.

Returns boolean
true if the event manager to which this manager is connected is currently the active REDU partner.
See
- CTRL function isReduActive()
Example
```
const isEventReduActive = winccoa.isReduActive();
console.info('Event currently is active - ' + isEventReduActive);
```
- Defined in binding.ts:3262

isRedundant

isRedundant(): boolean
Checks whether the project has been configured as redundant.

Returns boolean
true if project has been configured as redundant.
See
- CTRL function isRedundant()
Example
```
const isProjectRedundant = winccoa.isRedundant();
console.info('My project is redundant - ' + isProjectRedundant);
```
- Defined in binding.ts:3243

myReduHost

myReduHost(): string
Returns the host name of the Event Manager this manager is connected to. Use this method only on redundant computers.

Returns string
Host name of the Event Manager this manager is connected to.
See
- CTRL function myReduHost()
Example
```
const reduHostName = winccoa.myReduHost();
console.info('My redu host name - ' + reduHostName);
```
- Defined in binding.ts:3208

myReduHostNum

myReduHostNum(): number
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.

Returns number
Host number.
See
- CTRL function myReduHostNum()
Example
```
const reduHostNumber = winccoa.myReduHostNum();
console.info('My redu host number - ' + reduHostNumber);
```
- Defined in binding.ts:3226

Class WinccoaManager

Example

Index

Alert

CNS

Data Point

Data Point Type

Logging

Manager

Redundancy

Alert

alertGet

Parameters

Returns Promise<unknown>

Throws

See

Example: Calling alertGet with a single alert time and several alert configs

Example: Calling alertGet with a list of alert times and a list of data points

alertGetPeriod

Parameters

Returns Promise<{ alertTimes: WinccoaAlertTime[]; values: unknown[]; }>

Throws

See

Example

alertSet

Parameters

Returns boolean

Remarks

Throws

See

Example

alertSetTimed

Parameters

Returns boolean

Remarks

Throws

See

Example

alertSetTimedWait

Parameters

Returns Promise<unknown>

Remarks

Throws

See

Example

alertSetWait

Parameters

Returns Promise<unknown>

Remarks

Throws

See

Example

CNS

cns_checkId

Parameters

Returns Promise<boolean>

See

Example

cns_checkName

Parameters

Returns Promise<number>

See

Example

cns_checkSeparator

Parameters

Returns Promise<boolean>

See

Example

cns_getNodeIcon

Parameters

Returns Promise<string>

See

Example

cns_getNodeTypeDisplayName

Parameters

Returns Promise<WinccoaLangString>

See

Example

cns_getNodeTypes

Returns Promise<{ icons: string[]; typeIds: string[]; typeNames: string[]; values: number[]; }>

Returns Promise<{
alertTimes: WinccoaAlertTime[];
values: unknown[];
}>

Returns Promise<{
icons: string[];
typeIds: string[];
typeNames: string[];
values: number[];
}>