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);
Parameter
Description
workFunc
Name of the work function
dp
Name of the data point
before
Time of previous call
now
Time of current call
call
Is set to TRUE when the work function is called the last time.
Wichtig: 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
Anmerkung: Note that the syntax highlighting in the script editor does not work for timedFunc(). This is because this function is only defined for the CTRL manager and not in the user interface. This means that the timedFunc() has to be started from a separate CTRL manager or has to be added to pvss_scripts.lst located in wincc_oa_path/scripts.

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:

Tabelle 1. Data point type "_TimedFunc"
_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
Tabelle 2. Elements of "_TimedFunc"
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):

  • A current interval that ends between 2 and 2:59:59 is completed ahead of time.

  • An interval that starts between 2:00 and 2:59:59 will be started at 3:00.00.

  • An interval from 2:01 and 2:59 will not be executed.

When switching to wintertime (Autumn - 1 hour more)

  • A current interval that should end at 2:30, will be completed at 2:30 summertime, will be applied again at 2:00 wintertime and will be completed at 2:30 wintertime again.

  • An interval between 2:01 and 3:00 will be executed twice meaning at summertime and at wintertime.

  • An interval that starts at 02:30 and should last after 3:00, will be started at 2:30 summertime and will be completed at 2:00 wintertime. It will be restarted at 2:30 wintertime and lasts after 3:00.

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:

Abbildung 1. Decision tree

  1. 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.

Abbildung 2. A. - Entries in the field "time" exist.

  1. 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".

Abbildung 3. B. - No entries in the field "time"and syncTime <> -1.

  1. 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.

Abbildung 4. C. - Neither entries in the field "time"nor syncTime.

    1. 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.

Anmerkung: A detailed description of possible configuration errors can be displayed using the dbg flag "TIMED_FUNC".
Anmerkung: If the DP element "mode" is used, the element "interval" specifies in which intervals the workFunction is called. (see also example at the end of this page).
  • 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.

Anmerkung: Do not use timedFunc() for short intervals as the overhead is too large.

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