dpGet()

Reads values of datapoint attributes in variables.

Synopsis

int dpGet(string dp1 | dyn_string dp1, <type1> &var1 [, string dp2, <type2> &var2,...]);

Parameter

Parameter Meaning
dp1, dp2, ...

datapoint attributes to be read.

Note:

Do not use datapoints of different systems! The function dpGet only works for one system. If the dpGet is used for at least two systems, it does not work and the following error message is shown:

WCCOAui (1), 2006.09.26 14:11:19.266, PARAM,SEVERE, 175, this request cannot address more than one system, DP: dist_789:ExampleDP_Arg1.:_original.._value WCCOAui (1), 2006.09.26 14:11:19.266, CTRL, WARNING, 76, Invalid argument in function,
var1, var2, ... variables to be written.
Note:
dp1 is a list of datapoint elements, the variable type1 type has to be dyn_anytype!

Return Value

If the function was successfully executed, it returns 0 and in the event of a failure -1. The return value 0 only indicates that the message was correctly sent to Event Manager.

Error

Independently of the return value, errors can be retrieved with getLastError() (nonexistent data points, missing arguments or no read permission).

Description

The function dpGet() writes the values of the datapoint attributes dp1, dp2, ... to the variables var1, var2, ... of the appropriate type.

Querying attributes of the datapoint config:

With the help of the function dpGet() attributes of the config can be queried for an existing datapoint element (cf. dpSet()). The tables with the various Control constants can be found in the appendix.

  • dpGet checks whether a DPE exists but not if a config exists.

  • Please consider that, with increased number of value pairs, a quadratic decrease of the functions performance will occur.

If no definition for a config or attribute exists, the following defaults are used and added internal:

Function Default
dpSet*() _original.._value
dpGet() _online.._value
dpGetAsynch() _offline.._value
dpGetPeriod() _offline.._value
dpConnect() _online.._value
dpDisconnect() _online.._value

If you use a dpGet() on another system (not the local) and the dist connection does not exist, the dpGet returns 0 (OK). This also applies when you execute a dpGet without read permission for the queried datapoint. Query the error by using getLastError(). GetLastError() returns the following error message: "Message could not be sent, DP: System1:ap.:_original.._value, MAN: (SYS: 1 Dist -num 1 CONN: 1), Could not send message DP_MSG_SIMPLE_REQUEST #326"

_alert_hdl attributes which can be queried via dpGet()

attributes that can be queried via dpGet() type Bits description
_abbr string short sign of the priority (for example,: A for alarm)
_abbr_pattern string short sign pattern for group alert
_ack_deletes bool global alert for "acknowledge deletes"?
_ack_has_prio bool sequence of acknowledgement statuses for group alerts
_ack_oblig bool 6/22 alert needs to be acknowledged?
_ack_possible bool something to acknowledge
_ack_state int acknowledgement status for an alert
_ack_time time acknowledgement time for an alert
_ack_type int type of acknowledgement
_act_prior char priority of the current range
_act_range int current range
_alert_hdl.<i>._act_state int

Acknowledgement status of an alert. You can query the acknowledgement state of an alert.

1 = CAME unacknowledged

2 = CAME acknowledged

3 = WENT unacknowledged

0 = No alert
_act_state_color string color string of the current alert status range
_act_state_prior char priority of the current alert status range
_act_state_range int range of the current alert status
_act_state_text langString text of the current alert status range
_act_text langString text of the current range
_active bool alert handling activated ?
_alert_color string color string of the alert
_archive bool 10/26 Should alert be saved?
_both_ack bool group alert for "both must be acknowledged"?
_came_ack bool group alert for "CAME can be acknowledged"?
_class dpid reference to alert class of the range
_comment string user comment to an alert
_del_date time when is alert deleted or moved?
_delete bool 15/31 delete or move alerts
_dest int target range of the alert
_dest_text langString text of the target range of the alert
_direction bool 0/16 Direction of the alert
_dp_list dyn_dpid DP list for group alert
_dp_pattern string DP pattern for group alert
_help langString help (help text or path to help file)
_hyst_type int type of hysterisis used
_inact_ack bool alerts that are no longer current must be acknowledged
_inactive bool 11/27 marks with deactivated "WENT" alerts
_l_hyst_limit var lower insensitivity barrier (hysterisis)
_l_incl bool lower limit of the range included
_l_limit var lower limit of the range
_last bool 2/18 last alert of alert range?
_last_of_all bool 3/19 last alert of alert handling?
_min_prio char minimum priority (to suppress alerts)
_non_ack bool group alert for "cannot be acknowledged"?
_num_ranges unsigned number of ranges
_obsolete bool 1/17 alert no longer current?
_ok_range bool valid range for bit-alert handling
_oldest_ack bool 9/25 oldest alert to be acknowledged in an alert handling
_order int sequence of alerts for group alerts
_orig_hdl bool original- or online- value treatment for alert handling
_pair_ack bool global alert for "pair must be acknowledged"?
_panel string panel for cross-selection
_panel_param dyn_string parameter for cross-selection panel
_param bool can alert handling be configured?
_partn_idx int alert index for the alert partner
_partner time alert time for the alert partner
_prio_pattern string priority pattern for group alert
_prior char priority of the alert range
_single_ack bool need to be acknowledged individually
_sum bool 12/28 is alert group alert?
_text langString status text for the range
_text0 langString text for digital 0 (bit-alert handling)
_text1 langString text for digital 1 (bit-alert handling)
_type int type of alert handling (0 = no alert handling, 4 = MinMax alert range, 59 = sum alert).
_u_hyst_limit bool upper insensitivity barrier (hysteresis)
_u_incl bool upper limit of the range included
_u_limit var upper limit of the range
_value var value leading to the alert
_visible bool 4/20 alert is visible in alert panel (if true, Mode: current)

You can use dpGet to see if a config exists by querying the _type attribute which contains all configs of the DP. A return value of 0 indicates that the config does not exist. Any other value than 0 indicates that the config exists (see example below).

Following example checks whether the DP ExampleDP_Arg1.:_default.._type config exists or not.

 main()
{
  int rc, x;
  rc=dpGet("ExampleDP_Arg1.:_default.._type", x);
  DebugN(rc, x); /*The return value of x is either 0 if the config does not exist or another value if it exists */
}
main()
{
  dpGet("Valve17.opening:_online.._value", x);
}

Assignment

Datapoint functions, waiting Control functions

Availability

UI, CTRL