dpGetMaxAge()

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 and returns the value from the driver.

Synopsis

int dpGetMaxAge(unsigned age, string dp1, <type1> &var1 [,string dp2, <type2> &var2,...]);

Parameters

Parameter Description
age If the value of the data point element dpName is older than the parameter age, the function returns the value from the driver. Specify the time in milliseconds. If the age is set to 0, the value is always requested from the driver even if the timestamp is equal to the current time.
dpName Datapoint element whose value is queried.
var A variable for the value that is returned. NOTE: if the dp1 is a list of data point elements, the variable type1 type must 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 the Event Manager.

Errors

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

Description

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 identically to dpGet(), meaning that it returns a value immediately, irrespective of how old the value is.

For more information on the dpGet() functions, see also dpGet().

Use this function carefully for the following reasons:

  • The time the function takes to execute can be quite long since the driver waits for the result of the query.
  • If the driver cannot return a value, the function does not return until the timeout has expired. This timeout is defined by the config entry [all drivers] IOTransitionTimeout which has a default value of 10 seconds.
Restriction: This function is only available for:

Example

The following example returns the value of the data point element System1:EIPtestCompactArrays.BOOL if the value is not older than 3600 seconds (=1h).

main()
{
   dyn_anytype var1;
   unsigned ag1 = 3600000;
   string dp1 = "System1:EIPtestCompactArrays.BOOL";
   int retV;

   retV=dpGetMaxAge(ag1,dp1, var1);
DebugN("The return value of System1:EIPtestCompactArrays.BOOL: ",retV, "Value:",var1);
}

Assignment

Data point functions

Availability

CTRL