timedFunc()
Starts timed CTRL functions.
Synopsis
int timedFunc( string workFunc, string data point);
Parameters
Parameter | Meaning |
---|---|
workFunc |
Name of the work function. The DP name is also passed to the workFunc() function. Also the times of the previous and current call. When called for the first time, the time of the previous call is zero. These times are the computed times not the actual call times effected by the delay. When called from Control, the parameters of data point are passed and the function workFunc() is launched at the computed times. The function is defined as follows: void workFunc (string dp, time before, time now, bool call);
Important: Currently it is not supported to directly use
CTRL++ functions as
workFunc .
CTRL++ functions can still be called, by passing a function_ptr, pointing to a static CTRL++ member function,
instead. |
data point | Name of the data point |
Return value
In the event of an error -1, otherwise 0.
Errors
Missing or incorrect arguments
Description
The timedFunc() command allows you to launch user-defined, timed CTRL functions with parameters via a data point. The start time, interval and other parameters are set via data points of the internal data point type "_TimedFunc" with the following structure:
_TimedFunc. | |
validUntil time | |
time dyn_int | |
weekDay dyn_int | |
monthDay dyn_int | |
month dyn_int | |
result.inPeriod bool | |
syncTime int | |
syncWeekDay int | |
syncDay int | |
syncMonth int | |
interval unsigned | |
delay int | |
mode unsigned |
Element | Description |
---|---|
validFrom | The time from which the settings in the data point take effect. If "validFrom" is zero, the settings take effect immediately. |
validUntil |
The time until when the settings in the data point are effective. If "validUntil" is zero, the settings are effective without limitation. If the settings should not be effective without limitation, validUntil must be set to a later time than validFrom. |
time | The times at which set work functions are called (seconds since 00:00, range [0...86399]). If the "time" field is empty, the functions are launched at intervals. |
weekDay | The weekdays (1-7, 1...Monday) on which the set functions are launched at the set times "time" and months "month". If the "monthDay" field is not empty, the work functions are only launched if the desired days of the month coincide with the set weekdays. |
monthDay | The days of the month (1-31, 31....last day of month) on which the set work functions are launched at the times set in "time" and on the weekdays set in "weekDay" and in the months set in "month". If the "monthDay" field is empty, the work functions are launched daily at the set times according to the settings in "weekDay" and "month". |
month | The months (1-12) in which set work functions are launched at the times set in "time" and on the weekdays set in "weekDay" and "monthDay". If the "month" field is empty, the work functions are launched at the set times according to the settings in "weekDay" and "monthDay". |
result.inPeriod | "result.inPeriod" contains the state referring to the intervals (when mode = 1): if the function is within the interval the element is set to TRUE. See element "mode" further below. |
syncTime | The time in seconds since 00:00 (range [0...86399]) at which set work functions are launched. |
syncDay | The day of the month (1-31) of a new start time. If "syncDay" is set to -1, set work functions are launched taking into account the settings in "syncTime" and "syncMonth", on the first day of the set month after the set interval. |
syncWeekDay | The day of the week (1-7) of a new start time. If "syncWeekDay" is set to -1, set work functions are launched taking into account the settings in "syncTime" and "syncDay" with the first week after the set interval. |
syncMonth | The month (1-12) of a new start time. If "syncMonth" is set to -1, set work functions are launched taking into account the settings in "syncTime" and "syncDay" in the first month after the set interval. |
interval | The period during which set work functions are launched. Caution: So that the "interval" and the associated settings take effect, set the element "time" to zero! |
delay | Delays the call of the work function. If the previously launched function is still running at the next start time, the function is launched again regardless. Also negative values can be specified. If a negative value is given, the callback function is started earlier (i.e. by this value earlier) than calculated. |
mode |
The DPE element mode indicates the following operating states: 0 - default (the behavior as so far) 1 - time periods Function timedFunc and Winter and Summer time change When the mode =1 is used for the timedFunc, note the following special cases: When switching to summertime (Spring - 1 hour is missing):
When switching to wintertime (Autumn - 1 hour more)
|
If, for instance, the 15th and 31st were indicated as days of the month, but Monday and Thursday as days of the week, the work functions are only launched if the 15th and the 31st are a Monday or a Thursday! If the "weekDay" field is empty, the work functions are launched daily at the set times according to the settings in "monthDay" and "month".
'0' is not a valid value for the fields syncWeekDay, syncDay and syncMonth and leads to an error message!
As of the start time the timed function is always ready. Any parameter change takes immediate effect!
The times for launching functions are based on the following criteria:
-
If the fields ("time", "weekDay", "monthDay", "month") are empty or fields are set to -1, all possible settings apply.
-
All parameters are joined by logical AND.
-
The work function is only triggered within and inclusive "validFrom" and "validUntil".
-
The work function is always launched at the earliest valid time after the call or last parameter change.
The following cases are possible:
-
If "time" is given, the entry "interval" is ignored. As a result, only the settings in "time", "weekDay", "monthDay", and "month" are effective - see Figure a below.
An entry in the switch hour normal time to summer time (DaylightSavingTime, DST between 02:00:00 and 02:59:59) willnot be executed at the day of the switch in spring.
Instead it will be executed in autumn (at the day of the switch) twice.
When the systems are separated stationed, then the switching time can be also different, e.g. USA: 01:00:00 - 01:59:59.
-
The sync time determines when an action is triggered and, from this time on, the interval is restarted - see Figure b below. The function is first launched when: last sync time + x interval >= "validFrom".
-
Furthermore, the following differentiations can be made:
-
The work function starts at "validFrom" for the first time and then runs at "interval" until "validUntil".
-
If "validFrom" = "validUntil", the work function executes once regardless.
-
If "validFrom" is in the past, then the work function starts at "validFrom" + x "interval" >= start time, for the first time and then runs at "interval" until "validUntil".
-
If "validFrom" = 0, then the work function runs for the first time at the start time or on data point update and then runs at "interval" until "validUntil" - see Figure c.
-
If "interval" is zero, the default "interval" = 3600 is used.
-
-
-
If the element "mode" is set to 1. Time periods can be specified for specific days. The function is called periodically within the time periods. Two arrays "weekDay" and "time" present a table, which allows to enter start and end times. Another DP element "result.inPeriod" contains the state referring to the intervals: if the function is within the interval the element is set to TRUE.
The element is set when the function is initialized, for example,
-
- Monday 17:00 - Start
- Monday 18:00 - End
- Interval: 15 minutes
The function is called each monday at 17:00 (result: on ), at 17:15 (on), at 17:30 (on), 17:45 (on) and at 18:00 (off).
An arbitrary number of intervals can be specified.
- The values 1-7 stand for Monday - Sunday
- -2 stands for week days (Monday - Friday)
- -3 stands for weekend (Saturday -Sunday).
If the interval borders are not specified within the period, check the behavior of the function at the beginning and at the end according to the requirements.
When the function is started, the call back function is not called (no matter if within or outside of a period) but the flag result.inPeriod is set correctly. The callback function is called at next interval limit.
The intervals are synchronized at validFrom time. At the end of the validity period (when the end function is called) also the result.inPeriod flag is set to FALSE.
- Period 1: Wednesday 17:00, Wednesday 17:25,
- Period 2: Wednesday 17:37 - Wednesday 17:50, Interval 10 minutes:
- Callbacks: 17:00(on), 17:10(on), 17:20(on), 17:25(off), 17:37(on), 17:47(on), 17:50(off) )
Examples
Make a circular area blink red/green every five minutes. Make it blink by using the timedFunc() function.
The first step is to create a data point "Blinker" of the data point type "_timedFunc". According to Figure b the entry for "syncTime" must be -1 in order to run the function at intervals. The "interval" entry of Blinker is set to 300. The next step is to create a control function and store it in the file "Timed" in the directory /scripts. It contains the following commands:
main() { timedFunc("blink","Blinker"); } blink(string Blinker,time t1, time t2) { bool x; dpGet("ExampleDP_Blinker.:_original.._value",x); dpSet("ExampleDP_Blinker.:_original.._value",!x); }
The changes in the data point Example_DP_Blinker are used to display the blinking. A dpConnect() is used. It is configured for a property of the circular area, e.g: background.
main() { Connect("blink","ExampleDP_Blinker.:_original.._value"); } blink(string dp, bool x) { if (x) setValue("Circle","backCol","green"); else setValue("Circle","backCol","red"); }
The option of the example above when the _stopped function is used.
Data can be synchronized outside of the TimedFunc data point with the current state of the timedFunc(). The function void work_stopped(string dp) is used at the end of the valid time of timedFunction. The _stopped function gets one parameter - the data point name of the timedFunction. In the following example a circle blinks until the timedFunc has elapsed. "blink_stopped" is executed at the end.
main() { timedFunc("blink","test"); //timedFunc } blink(string test,time t1, time t2) { bool x; DebugN("before: ",t1); DebugN("now: ",t2); dpGet("ExampleDP_AlertHdl1.:_original.._value",x); dpSet("ExampleDP_AlertHdl1.:_original.._value",!x); } /* The same DP that is used for timedFunc. nothing is executed in case of: blink_stoppedx(string test) */ blink_stopped(string test) { bool x; DebugN("The end of time controlled function"); dpGet("System1:ExampleDP_AlertHdl2.:_original.._value",x); dpSet("System1:ExampleDP_AlertHdl2.:_original.._value",!x); }
Use the dpConnect() function also for this example and set the background color using a setValue() (like it was set in the example above).
main() { dpConnect("blink","ExampleDP_AlertHdl1.:_original.._value"); } blink(string dp, bool x) { if (x) setValue("Circle","backCol","green"); else setValue("Circle","backCol","white"); }
Set the data point "_startit" of the type "_TimedFunc" to calls beginning from 5 March 1996, as of 00:00 h for an unlimited time:
time t; dpSet("_startit.validFrom:_original.._value ", makeTime(1996,3,5), "_startit.validUntil:_original.._value", setPeriod(t, 0), "_startit.time:_original.._value ", makeDynInt(43200));
Example
Set data point "_startit" to four-hourly calls as of now up to 5 March 2007, 00:00 h. A new starting point is set on the 15th of each month at 12:30 h:
dpSet( "_startit.validFrom:_original.._value ", setPeriod(t, 0), "_startit.validUntil:_original.._value ", makeTime(2007,3,5), "_startit.time:_original.._value ", makeDynInt(), "_startit.interval:_original.._value", 14400, "_startit.syncDay:_original.._value ", 15, "_startit.syncTime:_original.._value", 45000, //12:30 "_startit.syncMonth:_original.._value ", -1);
Example
In this example the following days and times are set:
Monday 17:00 - 18:00
Wednesday 17:00 - 18:00
Saturday 16:00 - 17:00
The Workfunc is called every 10 seconds during these time periods.
main() { int rc; dyn_int weekDayList = makeDynInt( 1, 1, 3, 3, 6, 6 ); dyn_int timeList = makeDynInt( 61200, 64800, 61200, 64800, 57600, 61200 ); dpCreate( "testTimedFunc", "_TimedFunc" ); dpSet("testTimedFunc.weekDay", weekDayList,"testTimedFunc.time", timeList, "testTimedFunc.mode", 1,"testTimedFunc.interval", 10 ); rc = timedFunc( "workFunc", "testTimedFunc" ); } void workFunc( string dp, time before, time now ) { DebugN( dp, before, now ); }
When the sync time is set to a winter-time day and intervals are used, then a one-hour time shift is executed at the day of the summer time (the behavior is similar during a shift to normal time).
The set times are interpreted in local time calculation. Precaution is recommended during configuration at the shift days. Note that in case of using these shift times (in Europe: between 2:00 a.m. and 3:00 a.m.) this time is missing in spring (then either nothing is executed or subsequently to 3:00 a.m.), but is present in autumn twice (thus the function is executed twice).
Assignment
Miscellaneous functions
Availability
CTRL