oaJsApi

oaJsApi

new oaJsApi()

Source:

Methods

(static) alertGetPeriod(startTime, endTime, dpName, options)

Returns: → {boolean} Defines whether the server has accepted the message or not. In order to know if the command was successful or to retrieve the data, use the success/error callback.

Gets alarms inside a time interval
Parameters:
Name Type Description
startTime Date Start time of the interval from which alarms are returned
endTime Date End time of the interval from which alarms are returned
dpName String | Array Name(s) of the alert config(s) to return
options Object
Properties
Name Type Attributes Description
success oaJsApi~alertGetPeriodCallback Success Callback
error errorCallback <optional>
 Error Callback
Source:
Example
oaJsApi.alertGetPeriod(
  new Date(2019,2,5),
  new Date(2019,2,8),
  'System1:ExampleDP_AlertHdl1.:_alert_hdl.._text',
  {
    success: function(data) {
      console.log(data);
    },
    error: function() {
      console.error(arguments);
    }
  }
);

//query multiple dpe
oaJsApi.alertGetPeriod(
  new Date(2019,2,5),
  new Date(2019,2,8),
  ['System1:ExampleDP_AlertHdl1.:_alert_hdl.._text', 'System1:ExampleDP_AlertHdl1.:_alert_hdl.._prior'],
  {
    success: function(data) {
      console.log(data);
    },
    error: function() {
      console.error(arguments);
    }
  }
);

(static) cnsGetCompletions(pattern, includeDps, options)

Returns: → {boolean} undefined

Looks up pattern in CNS identifiers and IDs
Parameters:
Name Type Description
pattern string | Array Pattern to look up in CNS identifiers and IDs
includeDps boolean If true, result will also include the Dps matching the returned CNS paths
options Object
Properties
Name Type Attributes Description
success oaJsApi~cnsGetCompletionsCallback Success Callback
error errorCallback <optional>
 Error Callback
Source:
Example
oaJsApi.cnsGetCompletions('*Trend1', true, {
  success: function(data) {
     console.log(data);
  },
  error: function(data) {
     console.error(data);
  }
});

(static) customFunction(functionName, params, options)

Returns: → {boolean} Defines whether the server has accepted the message or not. In order to know if the command was successful or to retrieve the data use the success/error callback.

Allows to call a self implemented Method in /scripts/libs/classes/WssServer/WssUserRequestHandler.ctl
Parameters:
Name Type Description
functionName String Name of the Method which should be called
params Object Params which should be passed to RequestHandler
options Object
Properties
Name Type Attributes Description
success Success Callback
error errorCallback <optional>
 Error Callback
Source:
Example
oaJsApi.customFunction('dpTypeGet', {typeName: 'ExampleDP_Int', includeSubTypes: false}, {
  success: function(data) {
     console.log(data);
  },
  error: function() {
     console.error(arguments);
  }
});

(static) customSender(customSender)

Inject a custom sender method. This method will be called with a payload object instead
Parameters:
Name Type Description
customSender Function
Source:

(static) dpConnect(dpName, answer, options)

Returns: → {boolean} Defines whether the server has accepted the message or not. In order to know if the command was successful or to retrieve the data use the success/error callback.

Calls a callback function whenever the passed data point values/attributes change.
Parameters:
Name Type Description
dpName String | Array Name of the Data Point Element
answer bool Specifies if the callback function should be executed the first time already when the dpConnect() is called or first every time a value changes
options Object
Properties
Name Type Attributes Description
success oaJsApi~dpConnectCallback Success Callback
error errorCallback <optional>
 Error Callback
Source:
Example
oaJsApi.dpConnect('System1:_MemoryCheck.AvailKB:_original.._value', true, {
  success: function(data) {
     console.log(data);
  },
  error: function() {
     console.error(arguments);
  }
});

(static) dpDisconnect(dpName, callback, optionsopt)

Returns: → {boolean} Defines whether the server has accepted the message or not. In order to know if the command was successful or to retrieve the data use the success/error callback.

Disconnects the hotlink The list of the first argument of multiple datapoints (dpName) has to be the in the same order as in dpConnect.
Parameters:
Name Type Attributes Description
dpName String | Array Name of the Data Point Element
callback function The callback which should be disconnected
options Object <optional>
Properties
Name Type Attributes Description
success callback <optional>
 Success Callback
error errorCallback <optional>
 Error Callback
Source:

(static) dpGet(dpName, options)

Returns: → {boolean} Defines whether the server has accepted the message or not. In order to know if the command was successful or to retrieve the data use the success/error callback.

Reads values of data point attributes
Parameters:
Name Type Description
dpName String | Array Name of the Data Point Element
options Object
Properties
Name Type Attributes Description
success oaJsApi~dpGetCallback Success Callback
error errorCallback <optional>
 Error Callback
Source:
Example
oaJsApi.dpGet('System1:_MemoryCheck.AvailKB:_original.._value', {
  success: function(data) {
     console.log(data);
  },
  error: function() {
     console.error(arguments);
  }
});

(static) dpGetAlias(dpName, options)

Returns: → {boolean} Defines whether the server has accepted the message or not. In order to know if the command was successful or to retrieve the data use the success/error callback.

Get aliases of data point elements
Parameters:
Name Type Description
dpName String | Array Name of the Data Point Element(s)
options Object
Properties
Name Type Attributes Description
success oaJsApi~dpGetAliasCallback Success Callback
error errorCallback <optional>
 Error Callback
Source:
Example
oaJsApi.dpGetAlias('Pump12.value.RotationSpeed', {
  success: function(data) {
     console.log(data);
  },
  error: function() {
     console.error(arguments);
  }
});

(static) dpGetAsynch(time, dpName, options)

Returns: → {boolean} Defines whether the server has accepted the message or not. In order to know if the command was successful or to retrieve the data use the success/error callback.

Returns the historic values that were valid at that time
Parameters:
Name Type Description
time Date
dpName String | Array
options Object
Properties
Name Type Attributes Description
success oaJsApi~dpGetAsynchCallback Success Callback
error errorCallback <optional>
 Error Callback
Source:
Example
oaJsApi.dpGetAsynch(new Date(), 'System1:ExampleDP_Trend1.:_original.._value', {
  success: function(data) {
     console.log(data);
  },
  error: function() {
     console.error(arguments);
  }
});

//query multiple dpe
oaJsApi.dpGetAsynch(new Date(), ['System1:ExampleDP_Trend1.:_original.._value','System1:ExampleDP_Rpt2.:_original.._value'], {
   success: function(data) {
    console.log(data);
 },
 error: function() {
    console.error(arguments);
 }
});

(static) dpGetDescription(dpName, mode, options)

Returns: → {boolean} Defines whether the server has accepted the message or not. In order to know if the command was successful or to retrieve the data use the success/error callback.

Get descriptions of data point elements
Parameters:
Name Type Description
dpName String | Array Name of the Data Point Element(s)
mode Number Description mode (see WinCC OA Help for dpGetDescription()). Pass null to get default mode as specified by server
options Object
Properties
Name Type Attributes Description
success oaJsApi~dpGetDescriptionCallback Success Callback
error errorCallback <optional>
 Error Callback
Source:
Example
oaJsApi.dpGetDescription('Pump12.value.RotationSpeed', null, {
  success: function(data) {
     console.log(data);
  },
  error: function() {
     console.error(arguments);
  }
});

(static) dpGetFormat(dpName, options)

Returns: → {boolean} Defines whether the server has accepted the message or not. In order to know if the command was successful or to retrieve the data use the success/error callback.

Get output format of data point elements
Parameters:
Name Type Description
dpName String | Array Name of the Data Point Element(s)
options Object
Properties
Name Type Attributes Description
success oaJsApi~dpGetFormatCallback Success Callback
error errorCallback <optional>
 Error Callback
Source:
Example
oaJsApi.dpGetFormat('Pump12.value.RotationSpeed', {
  success: function(data) {
     console.log(data);
  },
  error: function() {
     console.error(arguments);
  }
});

(static) dpGetPeriod(startTime, endTime, count, dpName, options)

Returns: → {boolean} Defines whether the server has accepted the message or not. In order to know if the command was successful or to retrieve the data use the success/error callback.

Querying DP attributes over a particular time period
Parameters:
Name Type Description
startTime Date
endTime Date
count Number
dpName String | Array
options Object
Properties
Name Type Attributes Description
success oaJsApi~dpGetPeriodCallback Success Callback
error errorCallback <optional>
 Error Callback
Source:
Example
oaJsApi.dpGetPeriod(new Date(2017,5,5), new Date(2017,5,6), 5, 'System1:_MemoryCheck.AvailKB:_original.._value', {
  success: function(data) {
     console.log(data);
  },
  error: function() {
     console.error(arguments);
  }
});

//query multiple dpe

oaJsApi.dpGetPeriod(new Date(2019,2,5), new Date(2019,2,8), 5, ['System1:_MemoryCheck.AvailKB:_original.._value','System1:_MemoryCheck.UsedKB:_original.._value'], {
 success: function(data) {
    console.log(data);
 },
 error: function() {
    console.error(arguments);
 }
});

(static) dpGetUnit(dpName, options)

Returns: → {boolean} Defines whether the server has accepted the message or not. In order to know if the command was successful or to retrieve the data use the success/error callback.

Get units of data point elements
Parameters:
Name Type Description
dpName String | Array Name of the Data Point Element(s)
options Object
Properties
Name Type Attributes Description
success oaJsApi~dpGetUnitCallback Success Callback
error errorCallback <optional>
 Error Callback
Source:
Example
oaJsApi.dpGetUnit('Pump12.value.RotationSpeed', {
  success: function(data) {
     console.log(data);
  },
  error: function() {
     console.error(arguments);
  }
});

(static) dpNames(dpPattern, dpTypeopt, options)

Returns: → {boolean} Defines whether the server has accepted the message or not. In order to know if the command was successful or to retrieve the data use the success/error callback.

Returns all the data point names or data point element names that match a pattern. The data point structures are written to the array in alphabetical order
Parameters:
Name Type Attributes Description
dpPattern String Pattern
dpType String <optional>
 Data point type. Allows to restrict the returned data points to a specific data point type. When using the parameter only data points that are matching the pattern and the selected data point type will be returned.
options Object
Properties
Name Type Attributes Description
success oaJsApi~dpNamesCallback Success Callback
error errorCallback <optional>
 Error Callback
Source:
Example
oaJsApi.dpNames('System1:_MemoryCheck.*', null, {
  success: function(data) {
     console.log(data);
  },
  error: function() {
     console.error(arguments);
  }
});

(static) dpQuery(data, query, options)

Returns: → {boolean} Defines whether the server has accepted the message or not. In order to know if the command was successful or to retrieve the data use the success/error callback.

Parameters:
Name Type Description
data Array returned Data by Server for dpQuery
query String
options Object
Properties
Name Type Attributes Description
success oaJsApi~dpQueryCallback Success Callback
error errorCallback <optional>
 Error Callback
Source:
Examples
[
[
  "",
  ":_original.._value"
],
[
  "System1:ExampleDP_Arg1.",
  1234
],
[
  "System1:ExampleDP_Arg2.",
  50
]
]
Retrieves attribute values with the help of SQL statements
var params={
  query: "SELECT '_original.._value' FROM 'ExampleDP_Arg*' WHERE _DPT= \"ExampleDP_Float\"",
};

oaJsApi.dpQuery("SELECT '_original.._value' FROM 'ExampleDP_Arg*' WHERE _DPT= \"ExampleDP_Float\"", {
  success: function(data) {
     console.log(data);
  },
  error: function() {
     console.error(arguments);
  }
});

(static) dpSet(dpName, value, optionsopt)

Returns: → {boolean} Defines whether the server has accepted the message or not. In order to know if the command was successful or to retrieve the data use the success/error callback.

Assigns values to data point attributes
Parameters:
Name Type Attributes Description
dpName String | Array Name of the Data Point Element
value String | Array New Value for the Data Point
options Object <optional>
Properties
Name Type Attributes Description
success callback <optional>
 Success Callback
error errorCallback <optional>
 Error Callback
Source:
Example
oaJsApi.dpSet('System1:_MemoryCheck.AvailKB:_original.._value', '1234', {
  success: function() {
     console.log("dpSet succeeded");
  },
  error: function() {
     console.error(arguments);
  }
});

(static) getValue(shapeName, property, options)

Returns: → {boolean} Defines whether the server has accepted the message or not. In order to know if the command was successful or to retrieve the data use the success/error callback.

Reads graphics attribute values for a graphics object in variables
Parameters:
Name Type Description
shapeName string Name of the graphics object
property string Names of the attributes
options Object
Properties
Name Type Attributes Description
success oaJsApi~getValueCallback Success Callback
error errorCallback <optional>
 Error Callback
Source:
Example
oaJsApi.getValue("PUSH_BUTTON1", "foreCol", {
success: function() {
   console.log(arguments);
},
//optional
error: function() {
   console.log(arguments);
}
});


//query multiple properties
  oaJsApi.getValue("PUSH_BUTTON1", ["foreCol", "text"], {
   success: function(data) {
     console.log(data);
  },
//optional
   error: function() {
     console.log(arguments);
   }
});

(static) msgToWebViewEwo(shapeName, functionName, params, optionsopt)

Forwards the given params on another Webview Ewo
Parameters:
Name Type Attributes Description
shapeName String Name of the WebViewEwo
functionName String Name of the Function which should be executed on the shapeName
params Array An Array of arguments which will be forwarded
options Object <optional>
Properties
Name Type Attributes Description
success callback <optional>
 Success Callback
error errorCallback <optional>
 Error Callback
Source:
Example
oaJsApi.msgToWebViewEwo("WebView_Ewo2", "myFunction", [{key: "a value"},"a string", 3], {
  success: function() {
     console.log("msgToWebViewEwo succeeded");
  },
  error: function() {
     console.error(arguments);
  }
});

//in document of WebView_Ewo2
function myFunction(aObjectArgument, aStringArgument, aNumberArgument) {
  console.log(aObjectArgument);
  console.log(aStringArgument);
  console.log(aNumberArgument);
}

(static) registerListeners(listenerObject)

Register a listener
Parameters:
Name Type Description
listenerObject Object The key is the name of the listener, the Value is the callback Function
Source:
Example
oaJsApi.registerListeners({
error: function() {
   console.error(arguments)
 });

(static) setLocale(localeName, options)

Returns: → {boolean} Defines whether the server has accepted the message or not. In order to know if the command was successful use the success/error callback.

Set locale to be used for returning langStrings. This can only be used when connected to a WSS server (will raise an error when used inside a WebView EWO)
Parameters:
Name Type Description
localeName String Name of the locale to use
options Object
Properties
Name Type Attributes Description
success callback <optional>
 Success Callback
error errorCallback <optional>
 Error Callback
Source:
Example
oaJsApi.setLocale('en_US.utf8', {
  success: function() {
     console.log('locale set successfully');
  },
  error: function() {
     console.error(arguments);
  }
});

(static) setValue(shapeName, property, value, optionsopt)

Returns: → {boolean} Defines whether the server has accepted the message or not. In order to know if the command was successful or to retrieve the data use the success/error callback.

The function setValue() sets any number of graphics attributes of a graphics object
Parameters:
Name Type Attributes Description
shapeName string Name of the graphics object as it can be specified in the attribute editor. " " (empty string) addresses its own object
property string Name of the basic attribute
value Parameters that describe the graphics attribute. The number of parameters depends on the graphics attribute
options Object <optional>
Properties
Name Type Attributes Description
success callback <optional>
 Success Callback
error errorCallback <optional>
 Error Callback
Source:
Example
oaJsApi.setValue("Vision_1.yourpanelname.pnl:PUSH_BUTTON1", "foreCol", "red", {
success: function() {
   console.log("Setvalue succeeded");
},
//optional
error: function() {
   console.log(data);
}
});

//query multiple properties
oaJsApi.setValue("PUSH_BUTTON1", ["foreCol", "text"], ["green", "red"], {
success: function() {
   console.log("Setvalue succeeded");
},
//optional
error: function() {
   console.log(arguments);
}
});

(static) toCtrl(params, optionsopt)

Returns: → {boolean} Defines whether the server has accepted the message or not. In order to know if the command was successful or to retrieve the data use the success/error callback.

Triggers the messageReceived Event on the WebView Ewo
Parameters:
Name Type Attributes Description
params Object Object which will be forwarded to the messageReceived event of the WebView EWO
options Object <optional>
Properties
Name Type Attributes Description
success requestCallback <optional>
 Success Callback; Only triggered if msgToJs() is called within the messageReceived Event. If a success callback is given but msgToJs() is not called, some memory allocated for handling the callback will not be freed.
error errorCallback Error Callback
Source:
Example
var params={
  exampleKey : "exampleValue"
};
oaJsApi.toCtrl(params,{
  success: function(data) {
     console.log(data);
  },
  error: function() {
     console.error(arguments);
  }
});

Type Definitions

alertGetPeriodCallback(data)

Parameters:
Name Type Description
data Object returned Data by Server for alertGetPeriod
Source:
Example
{
  data: ["Value to 1"],
  dataCount: [0],
  dataDpa: ["System1:ExampleDP_AlertHdl1.:_alert_hdl.._text"],
  dataTime: [1551951458868]
  }

//result for multiple attributes
  {
  data: [
       ["Value to 1"], [60]
    ],
    dataCount: [0],
    dataDpa: [
      ["System1:ExampleDP_AlertHdl1.:_alert_hdl.._text"],
      ["System1:ExampleDP_AlertHdl1.:_alert_hdl.._prior"]
  ],
    dataTime: [1551951458868]
}

cnsGetCompletionsCallback(data)

Parameters:
Name Type Description
data Object returned data by server for cnsGetCompletionsCallback
Source:
Example
{
  data: [
    'DasSystem.Erster View:Beispiele.Float.Sub Float.Trend1',
    'TheSystem.First View:Examples.Float.Sub Float.Trend1',
    'System1.View1:Examples.Float.SubFloat.Trend1'
  ],
  dps: [
   'System1:ExampleDP_Trend1.',
   'System1:ExampleDP_Trend1.',
   'System1:ExampleDP_Trend1.',
  ]
}

dpConnectCallback(data)

Parameters:
Name Type Description
data Array returned Data by Server for dpConnect
Source:
Example
{
 "dp": ["System1:_MemoryCheck.AvailKB:_original.._value"],
"value": [22408656]
}
//in case of multiple values:
{
 "dp": ["System1:_MemoryCheck.AvailKB:_original.._value", "System1:_MemoryCheck.FreeKB:_original.._value"],
"value": [1, 2]
}

dpGetAliasCallback(data)

Parameters:
Name Type Description
data String | Array returned aliases by Server for dpGetAlias
Source:
Example
// in case of String
'P12Val_Rot'
// in case of multiple Arguments:
[
'P12Com_ON',
'P12Com_OFF'
]

dpGetAsynchCallback(data)

Parameters:
Name Type Description
data String | Number | Array returned Data by Server for dpGet
Source:
Example
// in case of Number
4
// in case of multple Arguments: oaJsApi.dpGet(['System1:_MemoryCheck.AvailKB:_original.._value','System1:_MemoryCheck.UsedKB:_original.._value','System1:_MemoryCheck.AvailKB:_original.._value', ...]
[
22783640,
10559852,
22783640
]

dpGetCallback(data)

Parameters:
Name Type Description
data String | Number | Array returned Data by Server for dpGet
Source:
Example
// in case of Number
4
// in case of multple Arguments: oaJsApi.dpGet(['System1:_MemoryCheck.AvailKB:_original.._value','System1:_MemoryCheck.UsedKB:_original.._value','System1:_MemoryCheck.AvailKB:_original.._value',...]
[
22783640,
10559852,
22783640
   ]

dpGetDescriptionCallback(data)

Parameters:
Name Type Description
data String | Array returned descriptions by Server for dpGetDescription.
Source:
Example
// in case of String
'Description for DPE'
// in case of multiple Arguments:
[
  'Description for first DPE',
  'Description for second DPE'
]

dpGetFormatCallback(data)

Parameters:
Name Type Description
data String | Array Output formats returned by Server for dpGetFormat().
Source:
Example
// in case of String
'%10.3f'
// in case of multiple Arguments:
[
  '%10.3f',
  '%14.3e'
]

dpGetPeriodCallback(data)

Parameters:
Name Type Description
data Object returned Data by Server for dpGetPeriod
Source:
Example
{
  "data": [
    54321
  ],
  "dataTime": [
    "2018-01-09T11:32:14"
  ]
}

//in case of multiple dpes
{"data":[
     [0,23642068,23566520,23543584],
     [33343448]
   ],
   "dataTime":[
      [1551780370405,1551949331446,1551949336690,1551949341993],
      [1551948923632]
   ]
}

dpGetUnitCallback(data)

Parameters:
Name Type Description
data String | Array unit names returned by Server for dpGetUnit().
Source:
Example
// in case of String
'm/s'
// in case of multiple Arguments:
[
  'm/s',
  'mm'
]

dpNamesCallback(data)

Parameters:
Name Type Description
data Array returned Data by Server for dpNames
Source:
Example
//for "System1:_MemoryCheck.*"
[
"System1:_MemoryCheck.AvailKB",
"System1:_MemoryCheck.AvailPerc",
"System1:_MemoryCheck.EmergencyKBLimit",
"System1:_MemoryCheck.FreeKB",
"System1:_MemoryCheck.FreePerc",
"System1:_MemoryCheck.Status",
"System1:_MemoryCheck.TotalKB",
"System1:_MemoryCheck.UsedKB"
]

getValueCallback(data)

Parameters:
Name Type Description
data * returned Data by Server for getValue
Source:
Example
{ "0" : "_ButtonText"}

//in case of multiple attributes of same shape
[ "_ButtonText" , "PUSH_BUTTON1" ]