dpGet()
Reads values of data point attributes in variables.
Synopsis
int dpGet(string dp1 | dyn_string dp1, <type1> &var1 [, string dp2,
<type2> &var2,...]);
Parameter
Parameter | Meaning |
---|---|
dp1, dp2, ... |
data point attributes to be read. Anmerkung:
Do not use data points 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.
Anmerkung: dp1 is a list of data point 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 data point attributes dp1, dp2, ... to the variables var1, var2, ... of the appropriate type.
Querying attributes of the data point config:
With the help of the function dpGet() attributes of the config can be queried for an existing data point 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 data point. 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).
Example
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 */
}
Example
main()
{
dpGet("Valve17.opening:_online.._value", x);
}
Assignment
Data point functions, waiting Control functions
Availability
UI, CTRL