12. Time & Date

12.1. Introduction

The time and date functions of the library OSCAT depend on the target
system implemented so that they take into account the diferences in the
implementation of date / time types of the individual systems. For exam-
ple, on the UNIX systems CoDeSys implements the UNIX TIME DATE, which
means that the data type TD is mapped in seconds as of 1.1.1970-00:00
as 32-bit value. In STEP7, however, the data type TD in seconds is shown
as 1.1.1990. The range of time / date functions in CoDeSys systems
01.01.1970 - 31.12.2099 and in STEP7 systems 01.01.1990 - 31.12.2099.
The limitation of the range on the year 2099 is mainly due to the fact that
in 2100 will be not a leap year.
Furthermore, the date and time functions are in accordance with the
ISO8601 (international standard for numeric date functions). Here, for ex-
ample, the implementation of the days with 1 = Monday and 7 = Sunday
is prescribed.

12.2. CALENDAR_CALC

Type Function module
Input SPE: BOOL (TRUE calculates the current sun position)
I / O XCAL: CALENDAR (external variables)
HOLIDAYS HOLIDAY_DATA (holiday list)

CALENDAR_CALC automatically calculates all the values in a CALENDAR
structure based on the value of the type UTC in the structure. XCAL is a
Pointer an external or global variable of type CALENDAR. CALENDAR_CALC
can thus deliver calendar values based on the structure XCAL throughout
the module. CALENDAR_CALC determines at each change of the value UTC
in XCAL automatically all other values in the structure. Alone the value of
UTC in a structure must be fed by the RTC module. The defnition of the

structured type CALENDAR you can fnd in section data structures. The
continuous calculation of the sun position can weigh heavily on a PLC wi-
thout FPU, which is why the current sun position is calculated only once
every 25 seconds if SPE = TRUE. This corresponds to an accuracy of 0.1
degrees which is quite sufcient for normal applications. If SPE is FALSE,
the position of the sun is not calculated. By an external array HOLIDAYS of
type HOLYDAY_DATA, the user can specify specifc holidays according to
his needs, for more information on the defnition of public holidays see the
module data structures.
If several structures of the type CALENDAR are required (for example, or
various local and UTC times) then more modules CALENDAR_CALC can be
used with diferent structures of TYPE CALENDAR in accordance.
The following example shows how the module SYSRTCGETTIME reads the
RTC of the CPU and writes the current time in SYSTEMCAL.UTC. CALEN-
DAR_CALC checks every cycle if the value in .UTC has changed and if so it
calculates the other values of the structure automatically. The output
WDAY shows how the structure reads data for further processing. CALEN-
DAR_CALC accounts of the setup data from the data structure (OFFSET
DST_EN, LONGITUDE, LATITUDE).

In the external array HOLIDAYS up to 30 holidays can be defned. For ex-
amples, see the description of the data type HOLIDAY_DATA. This array of
HOLIDAY_DATA must be defned outside of the module and be pre-assi-
gned as a variable with the holiday dates.

12.3. DATE_ADD

Type Function
Input IDATE: DATE (date)
D: INT (days to be added)
W: INT (weeks to be added)
M: INT (months to be added)
Y: INT (years to be added)

Output DATE (result date)

The function DATE_ADD add days, weeks, months, and add years to a
date. First the module adds the specifed days and weeks, then months
and fnally the years.
The input values can be both positive as well be negative. So it can also
be subtracted from a date.
Note that especially for negative input values the sum of negative values,
i.e. -3000 days does not run below 1.1.1970 because this would have an
overfow of data type DATE and undefned values are obtained.
Example: DATE_ADD(1.1.2007,3,1,-1,-2) = 11/12/2005
adds additional 3 days and 1 week and then draws 1 month
and 2 years from.

12.4. DAY_OF_DATE

Type Function: DINT
Input IDATE: DATE (date)
Output DINT (day in month of inout date)

The function calculates the DAY_OF_DATE day since 1.1.1970. The result of
the function is of type DINT because the entire DATE Range Includes
49,710 days.

12.5. DAY_OF_MONTH

Type Function: INT

Input IDATE: DATE (date)
Output INT (day in month of input date)

The DAY_OF_MONTH function calculates the day of the month from the in-
put date IDATE.

12.6. DAY_OF_WEEK

Type Function: INT
Input IDATE: DATE (date)
Output INT (month in the year of the input date)

The function calculates the DAY_OF_WEEK week from the date of receipt
IDATE.
Monday = 1  Sunday = 7 The calculation is done in accordance with
ISO8601.
Example: DAY_OF_WEEK(D#2007-1-8) = 1

12.7. DAY_OF_YEAR

Type Function: INT
Input IDATE: DATE (date)
Output INT (day of the year of input date)

The DAY_OF_YEAR function calculates the day of the year from the input
date IDATE. Leap years are taken into account according to the Gregorian
calendar. The function is defned for the years 1970 - 2099.

Example: DAY_OF_YEAR(31.12.2007) = 365
DAY_OF_YEAR(31.12.2008) = 366

12.8. DAY_TO_TIME

Type Function: TIME
Input IN : REAL (number of days with decimal places)
Output TIME ( TIME )

The function DAY_TO_TIME calculates a value (TIME) from the input value
in days as REAL.
Example: DAY_TO_TIME(1.1) = T#26h24m

12.9. DAYS_DELTA

Type Function: DINT
Input DATE_1: DATE (Date1)
DATE_2: DATE (date2)
Output DINT (diference of the two input dates in days)

The function DAYS_DELTA calculates the diference between two data in
days.
Example: DAYS_DELTA(10.1.2007, 1.1.2007) = -9
DAYS_DELTA(1.1.2007, 10.1.2007) = 9
The result of the function is of type DINT because the entire DATE Range
Includes 49,710 days.

12.10. DAYS_IN_MONTH

Type Function: INT
Input IDATE: DATE (current date)
Output INT (number of days of current month)

The days_in_month function calculates the number of days in the current
month.

12.11. DAYS_IN_YEAR

Type Function: INT
Input IDATE: DATE (current date)
Output INT (number of days in the current year)

The DAYS_IN_YEAR function calculates the number of days in the current
year.

12.12. DCF77

Type Function module
Input REC: BOOL (input for the DCF77 receiver)
SET: BOOL (Asynchronous SET input)
SDT: DT (initial value for RTC)
DSI: BOOL (DST in)
Output TP: BOOL ( pulse for setting downstream clock)
DS: BOOL (TRUE if daylight saving time is)
WDAY : INT (weekday)

ERROR: BOOL (TRUE, if REC supplies no signal)
RTC: DT (Synchronized Universal Time UTC)
RTC1: DT (Synchronized local time)
MSEC: INT (milliseconds from RTC and RTC1)
SYNC: BOOL (TRUE, when RTC is in sync with DCF)
Setup SYNC_TIMEOUT: TIME ( Default = T#2m)
Time_ofset: INT (time ofset for RTC1, Default = 1 hour)
DST_EN: BOOL (daylight saving time for RTC1, Default = TRUE)

The function DCF77 decodes the serial signal of DCF77 receiver and con-
trols 2 internal clock RTC and RTC1, or via output TP external (down-
stream) watches. An output DS is TRUE if daylight saving time is. The out-
put WDAY is the weekday (1 = Monday). The output ERROR is TRUE if no
valid signal is received. The internal clocks continue to run anyway, also if
they already synchronized. A Another output SYNC indicates that in inter-
nal clocks are synchronized with DCF77 and gets FALSE if they were syn-
chronized by not less than the setup variable SYNC_TIMEOUT specifed
time. The internal clocks runs always with the accuracy of the SPS Timers
further. By double-clicking the icon in the CFC editor other setup variables
are defned. Here SYNC_TIMEOUT sets, after which time the output signal
SYNC gets FALSE, if the internal clock RTC and RTC1 were not synchronized
by DCF77. The variable time_ofset determines the time diference bet-
ween local time (RTC1) from the UTC. Default is 1 hour for CET (Central Eu-
ropean Time). The variable TIME_OFFSET is of type INTEGER thus also time
zones with negative ofset (west of Greenwich) are possible.
By DST_EN is determined whether RTC1 should automatically switch to
summer time or not. The output MSEC extends the by RTC to RTC1 provi-
ded time to milliseconds. The SDT is used to put the internal clock RTC and
RTC1 to a defned initial value, so that immediately after the start a valid
time is available. During the frst cycle date and time is copied from SDT
to RTC and runs from the frst cycle. If necessary, the internal CLOCK can
be set always new with the asynchronous set input SET. However, it is
overwritten again by a valid DCF77 signal after a cycle, unless the SET in-
put remains TRUE. If a valid DCF77 signal was decoded, RTC and RTC1 is

synchronized to the corresponding precise DCF77 time. At the input of SDT
for example, the time from the information contained in the PLC Hardware
Clock can be used. It must be ensured, that the DCF77 is called only if a
valid time is already present in SDT, the DCF77 reads this value only once
in the frst cycle, or at any time when the SET input is set to TRUE.

12.13. DT2_TO_SDT

Type Function: BOOL
Input UTC: DATE_TIME (Universal Time)
Output BOOL (TRUE if daylight saving time)

The DST function checks whether daylight saving time is right now or not.
It can be used to an existing non-DST enabled clock to switch to summer
and winter in exact seconds.
The function of DST switches on the last Sunday of March at 01:00 UTC
(02:00 CET) to summer time (03:00 GMT) and on the last Sunday of Octo-
ber at 01:00 UTC (03:00 BST) to 02:00 CET back. The output of DST is
TRUE if daylight saving time is.
The summer time is calculated based on UTC (Universal Time). A calculati-
on of location-time for daylight saving time is generally not possible be-
cause in the last Sunday of October, the hour of 2:00 a.m. to 3:00 a.m.
PST or PDT there exists twice. The summer time will be changed in all
countries of the EU since 1992, at the same second to world time. In Cen-
tral Europe at 02:00, at 01:00 in England and Greece at 04:00. By using
the world time calculation of daylight saving time for all European time zo-
nes is calculated correctly.

12.14. DT2_TO_SDT

Type Function: SDT
Input DI: DATE (date)
TI: TOD (time of day)
Output SDT (Structured date time value of type SDT)

DT2_TO_SDT converts a date and time of day to day in a structured date
type SDT.

12.15. DT_TO_SDT

Type Function: SDT
Input DTI: DT (date time value)
Output SDT (Structured date time value of type SDT)

DT_TO_SDT converts a date value into a structured date day of type SDT.

12.16. EASTER

Type Function: DATE
Input YEAR : INT (year)
Output DATE (date of Easter Sunday for the specifed year)

The function EASTER calculates for a given year, the date of Easter Sun-
day. Most religious holidays have a fxed distance from Easter, so that in
the case that Easter is known for a year, these holidays can also be deter-
mined easily. EASTER is also used in the module HOLIDAY to calculate holi-
days.

12.17. EVENTS

Type Function module

Input Date_in: DATE (input date)
ENA: BOOL (Enable Input)
I / O ELIST: ARRAY [0.49] of HOLIDAY_DATA
Output Y: BOOL (TRUE if date_in is an event)
Name: STRING(30) (name of today's event)

The module EVENTS shows the output Y with TRUE special days and also
provides the names of the events at the output NAME. EVENTS can also
take into account events over several days. The array ELIST name, date
and duration of events are set.
In the external array ELIST can defne up to 50 such events in the followi-
ng format.
*.NAME : STRING(30) specifes the name of the event
*.DAY : SINT Events of the month
*.MONTH : SINT Month of Events
*.USE : SINT Duration of the event in days

Examples:
(NAME: = 'Foundation Day', DAY = 13 MONTH = 7, USE: = 1) solid event
"Foundation Day" on 13 July for one day.
(NAME: = 'Foundation Day', DAY = 13 MONTH = 7, USE: = 0) event at a f-
xed date USE = 0 means it is not active.
(NAME: = 'Operation Holiday' DAY: = 1, MONTH = 8, USE: = 31) defnes an
event with a duration of 31 days.

12.18. HOLIDAY

Type Function module

Input Date_in: DATE (input date)
Langue: INT (desired language)
FRIDAY: BOOL (Y is true on Friday when TRUE)
SATURDAY: BOOL (Y is true on Saturdays if TRUE)
SUNDAY: BOOL (Y is TRUE if TRUE on Sundays)
I / O HOLIDAYS: ARRAY [029] of HOLIDAY_DATA
Output Y: BOOL (TRUE if DATE_IN is a holiday)
Name: STRING(30) (name of present-day holiday)

The HOLIDAY function shows the output Y with TRUE holidays and also pro-
vides the name of the current holiday at the output NAME. HOLIDAY can,
in addition to celebration days during the weekdays Friday, Saturday or
Sunday be active and deliver at the output Y TRUE, depending on whether
the inputs are FRIDAY, SATURDAY or SUNDAY set to TRUE. In the array HO-
LIDAYS are name and date of holidays defned and also universally adapta-
ble to other countries. Holidays can be defned as a fxed date, with a di-
stance of Easter or the week before a fxed date. The input LANGU selects
the appropriate language from the setup data so that expenditure for Fri-
day, Saturday and Sunday can be customized language-specifc. [fzy] The
languages are global constants in the "LOCATION SETUP" defned and can
be expanded or adapted.
In the external array HOLIDAYS up to 30 holidays can be defned. Examp-
les are located in the description of the data type HOLYDAY_DATA.

12.19. HOUR

Type Function: INT
Input ITOD: TIMEOFDAY (day time)
Output INT (current hour)

The HOUR function extracts the current hour of the day.
Example: HOUR(22:55:13) = 22

12.20. HOUR_OF_DT

Type Function: INT
Input XDT: DATETIME (input)
Output INT (current hour)

HOUR_OF_DT extracts the hour from a current DT value.
HOUR_OF_DT(DT#2008-6-6-10:22:20) = 10

12.21. HOUR_TO_TIME

Type Function: TIME
Input IN: REAL (number of hours with decimals)
Output TIME (TIME)

The function HOUR_TO_TIME calculates a time value (TIME) from the input
value in hours as REAL.
Example: HOUR_TO_TIME(1.1) = T#1h6m

12.22. HOUR_TO_TOD

Type Function: TIME
Input IN: REAL (number of hours with decimals)

Output TIME (days)

The function HOUR_TO_TOD calculate a time of day (TIMEOFDAY) from the
input value in hours as REAL.
Example: HOUR_TO_TOD(12.1) = 12:06:00

12.23. JD2000

Type Function: REAL
Input DTI: DT (Gregorian date)
Output REAL (astronomical, Julian Day as of 1/1/2000 12:00)

JD2000 calculates the astronomical Julian day since January, 1st., 2000
12:00 (the Standardäquinoktium).
The Julian date is the time in days since January 1st. 4713 BC, as a foat at
12:00. The January 1st. 2000 00:00 corresponds to the Julian date
2451544.5. Since a date as the January 1st 2000 can would already ex-
ceed the resolution limit of a REAL with about 7 character, the Julian date
can not be represented correctly with the data type REAL. The function
counts the JD2000 Julian days since 1/1/2000 12:00 pm and can present a
current date in the data type REAL.

12.24. LEAP_DAY

Type Function: BOOL
Input IDATE: DATE (date)
Output BOOL (TRUE if the current day is 29 February)

The LEAP_DAY function checks if the input date is a leap or a 29th Februa-
ry. The test is valid for the time window from 1970 to 2099. In the year
2100 a leap year indicated although this is not one. However, since the
range of dates according to IEC61131-3 extends only to the year 2106 this
correction will be omitted.
Example: LEAP_DAY(D#2004-02-29) = TRUE

12.25. LEAP_OF_DATE

Type Function: BOOL
Input IDATE: DATE (date)
Output BOOL (TRUE if IDATE is a leap year)

The function LEAP_OF_DATE tests whether the input date is in a leap year.
The function calculates whether a date falls within a leap year and returns
TRUE if necessary. The test is valid for the time window from 1970 to

2099. In the year 2100 a leap year is indicated although this is not one. However, since the range of dates according to IEC61131-3 extends only to the year 2106 this correction will be omitted. Example: LEAP_OF_YEAR(D#2004-01-12) = TRUE

12.26. LEAP_YEAR

Type Function: BOOL
Input YR: INT (year)
Output BOOL (TRUE if the specifed year is a leap year)

The function LEAP_YEAR tests if the input year is a leap year and passs
TRUE if true. The test is valid for the time window from 1970 to 2099. In
the year 2100 a leap year is indicated although this is not one. However,
since the range of dates according to IEC61131-3 extends only to the year
2106 this correction will be omitted.

12.27. LTIME_TO_UTC

Type Function: DATE_TIME
Input LTIME: DATE_TIME (local time)
DST: BOOL (TRUE if daylight saving time is true)
TIME_ZONE_OFFSET: INT (time diference to UTC in minutes)
Output DATE_TIME (UTC, Universal Time)

LTIME_TO_UTC calculates UTC (Universal Time) from a given local time.
The world time is calculated by subtracting from the TIME_ZONE_OFFSET
LTIME local time. If the DST is active (DST = TRUE), an additional hour of
LTIME is deducted.
Note: The summer time is not regulated the same in all countries. The
function assumes that in addition to summer time a further hour is added
to ofset.

12.28. MINUTE

Type Function: INT
Input ITOD: TIMEOFDAY (day time)
Output INT (current minute)

The MINUTE function extracts the current minute of the day.
Example: MINUTE(22:55:13) = 55

12.29. MINUTE_OF_DT

Type Function: INT
Input XDT: DATETIME (input)

Output INT (current minute)

MINUTE_OF_DT extracts the current minute from a DT value.
MINUTE_OF_DT(DT#2008-6-6-10:22:20) = 22

12.30. MINUTE_TO_TIME

Type Function: TIME
Input IN: REAL (number of minutes with decimals)
Output TIME (TIME)

The function MINUTE_TO_TIME calculates a time value (TIME) from the in-
put in minutes as REAL.
Example: MINUTE_TO_TIME(122.5) = T#2h2m30s

12.31. MONTH_BEGIN

Type Function: DATE
Input IDATE: DATE (current date)
Output DATE (date of the 1st day of current month)

MONTH_BEGIN calculates the date of frst Day of the current month and
current year.
MONTH_BEGIN(D#2008-2-13) = D#2008-2-1

12.32. MONTH_END

Type Function: DATE
Input IDATE: DATE (current date)
Output DATE (date of the last day of the current month)

MONTH_END calculates the date of the last day of the current month and
current year.
MONTH_END(D#2008-2-13) = D#2008-2-29

12.33. MONTH_OF_DATE

Type Function: INT
Input IDATE: DATE (date)
Output INT (month in the year of the input date)

The MONTH function calculates the month of the year from the date of in-
put date IDATE.
Example: MONTH_OF_DATE(D#2007-12-31) = 12
MONTH_OF_DATE(D#2006-1-1) = 1

12.34. MULTIME

Type Function: TIME
Input T: TIME (input time)
M: REAL (multiplier)
Output TIME (result input time multiplied by M)

The MULTIME function multiplies a time value with a multiplier.
Example: MULTIME(T#1h10m, 2.5) = T#2h55m

12.35. PERIOD

Type Function: BOOL
Input D1: DATE (period begin)
DX: DATE (date to be tested)
D2: DATE (period end)
Output BOOL (TRUE if DX within the period D1  D2)

The function checks whether an input date DX is greater or equal than D1
and is less equal D2. If the date DX in the period between D1 and D2 (D1
and D2 included) is the output of the function TRUE. PERIOD ignores the
years in the dates D1, D2 and DX. The test is performed only for months
and days, so this function works for each year. The test period can also af-
ter 31 Extend beyond December, so for example from 9/1 - 3/15, a typical
application is to determine whether there is a heating period. That PERIOD
work properly the two dates D1 and D2 may not be in a leap year. It can,
for example, always be 2001, or even any other year that is not a leap
year.
PERIOD (10/1/2001, 11/11/2007, 31/03/2001) returns TRUE, because the
test date within the period from 10/1 - 3/31 content.

12.36. PERIOD2

Type Function: BOOL
Input DP: ARRAY [03,01] of DATE (periods)
DX: DATE (date to be tested)
Output BOOL (TRUE if DX is within one of the periods)

PERIOD2 check if the DX date within a specifed period of 4 periods. The
periods are in an array [03,01] of DATE specifed. In contrast to the
function PERIOD of PERIOD2 reviewes also the year. The periods are speci-
fed in ARRAY DP, where DP[N,0] is the beginning date of the period N,
DP[N,1] N is the end date of period.
The function test using the formula: DX >= DP [N,0] AND DX <= DP [N,1].
In each case it is considered N = 0 to 3. If DX is one of the 4 periods, the
output is set to TRUE.
The individual periods need not be present sorted. PERIOD2 can be used
to defne holiday or vacation time. PERIOD2 reviews not repeated periods,
but tests yearly repeated periods.

12.37. REFRACTION

Type Function: REAL
Input ELEV: REAL (elevation in degrees above the horizon)
Output REAL (refraction in degrees)

REFRACTION calculates the atmospheric refraction outside the atmosphe-
re and celestial bodies. A celestial body appears by the refraction of light
in the atmosphere by the refraction higher above the horizon than he ac-
tually is. The refraction is 0 at the zenith (at 12:00 noon) and increases
much close to the horizon. At 0° (the horizon), the refraction is -0.59° and
10° above the horizon, it is 0.09°. The refraction is needed to calculated
orbits of celestial bodies and to correct satellite so that they match with
observation. The module calculates an average value for the pressure of
1010mBar and 10° C. When the sun is actually at 0°, so exactly in the ho-
rizon, it appears above the horizon because of refraction at 0.59 degrees.
The visible sun position is the actual (astronomical) sun position H + the
refraction of the sun. The refraction angle is also calculated below the ho-
rizon ELEV < - 2°, so that below the horizon always the refraction is added
to the astronomical refraction angle, so as the distance to the sun can be
calculated correctly at any time. For astronomical angle < -1.9 ° is the re-
fraction remains constant at 0.744 degrees.

12.38. RTC_2

Type Function module
Input SET: BOOL (set input)
SDT: DT (set date and time)
SMS: INT (set Milliseconds)
DEN: BOOL (automatic daylight saving time ON)
SFO: INT (local time ofset from UTC in minutes)
Output UDT: DT (Date and time output for Universal Time)
LDT: DT (local time)
DSO: BOOL (summer active)
XMS: INT (milliseconds)

RTC_2 is a clock component of the UTC and local time at the outputs of
LDT and UDT provides. The time is automatically every time you SET =
TRUE to the value of SDT and SMS. If SET = FALSE the time runs on and on
and provides at the output UDT the current date and time for Universal
Time (UTC), and at the output LDT the current local time. The output LDT
corresponds UDT + OFS + summer time when it is current. Summer time
is, if DEN = TRUE, automatically switched back on the last Sunday of
March at 01:00 UTC (02:00 CET) to summer time (03:00 GMT) and on the
last Sunday of October at 01:00 UTC (03:00 BST) on 02:00 CET. The output
of DSO is TRUE if daylight saving time is. If DEN is FALSE, no summer time
change is made. The accuracy of the clock depends on the millisecond Ti-
mer of the PLC. The input SFO specifes the time ofset of LDT to UDT, for
MEZ this value is 1 hour. SFO is specifed as INT in minutes so that a nega-
tive ofset is available. For CET (Central European Time, an ofset is set to
60 minutes.) RTC_2 takes over the Power Up automatically applied to the
SDT start time and date. The output of XMS passes the milliseconds and
every second counts from 0 - 999
The following example when starting the system time is taken.

12.39. RTC_MS

Type Function module
Input SET: BOOL (set input)
SDT: DT (set date and time)
SMS: INT (set Milliseconds)
Output XDT: DT (Date and Time Out)
XMS: INT (milliseconds output)

RTC_MS is a clock component with a resolution of milliseconds and date.
The time is automatically every time you SET = TRUE to the value of SDT
and SMS. If SET = FALSE the time is running on their own and provides the
output XDT the current date and time, and at the output XMS milliseconds.
The output XMS counts every second 0-999 and begins with the next se-
cond again at 0. The accuracy of the clock depends on the millisecond Ti-
mer of the PLC.

12.40. SDT_TO_DATE

Type Function: DATE
Input DTI: SDT (structured input value as date / time value)
Output DATE (Date value)

SDT_TO_DATE produces a date value of a structured date-time value

12.41. SDT_TO_DT

Type Position: DT
Input DTI: SDT (structured input value as date / time value)
Output DT (date-time value)

SDT_TO_DT generates a date-time value of a structured date-time value

12.42. SDT_TO_TOD

Type Function: TOD
Input DTI: SDT (structured input value as date / time value)
Output TOD (time of day)

SDT_TO_TOD produces a time of day of a structured date-time value.

12.43. SECOND

Type Function: REAL
Input ITOD: TOD (time of day)
Output REAL (seconds and milliseconds of time of day)

The function SECOND extracts the seconds portion of the day
Example: SECOND(22:10:12.331) = 12.331

12.44. SECOND_OF_DT

Type Function: INT
Input XDT: DATETIME (input)
Output INT (current second)

SECOND_OF_DT extracts the second from a current DT value.
SECOND_OF_DT(DT#2008-6-6-10:22:20) = 20

12.45. SECOND_TO_TIME

Type Function: TIME
Input IN: REAL (number of seconds with decimals)
Output TIME (TIME)

The function SECOND_TO_TIME calculates a value (TIME) from the input
value in seconds as a REAL.
Example: SECOND_TO_TIME(63.123) = T#1m3s123ms

12.46. SET_DATE

Type Function: DATE
Input YEAR: INT (year)
MONTH: INT (month)
DAY: INT (day)
Output DATE (Composite date)

The function SET_DATE calculates a Date (DATE) from the input values,
day, month and year. SET_DATE does not test the validity of a date. For
example, also be February, 30th will be set, which, of course results the
1st March or in a leap year, the March, 2nd. SET_DATE can therefore also
be used to generate any day of the year. This can be a quite practicable
application. In this case, the monthly amount may also be 0. An invalid
month always gives a date in relation to January. An invalid month (month
< 1 or month > 12) is always interpreted as January.
Example: SET_DATE(2007,1,365) = 31.12.2007
Example: SET_DATE(2007, 1, 22) = 22.1.2007

12.47. SET_DT

Type Function: DATE_TIME
Input YEAR: INT (year)
MONTH: INT (month)
DAY: INT (day)
HOUR: INT (hour)
MINUTE: INT (min)
SECOND: INT (seconds)
Output DATE_TIME (Composite time date)

The function SET_DT calculates a time-date value (DATE_TIME) from the
input values, day, month, year, hour, minute and seconds.
Example: Set_DT(2007, 1, 22, 13, 10, 22) = DT#2007-1-22-13:10:22

12.48. SET_TOD

Type Function: TOD
Input HOUR: INT (hour)
MINUTE: INT (min)
SECOND: REAL (seconds and milliseconds)
Output TOD (output value day)

The function SET_TOD calculates a time of day (TOD) from the input va-
lues, hours, minutes and seconds.
Example: Set_TOD(13, 10, 22.33) = 13:10:22.330

12.49. SUN_MIDDAY

Type Function
Input LON : REAL (longitude of the reference location)
UTC: DATE (Universal Time)
Output TOD (time of day when Sun is exactly in the south)

The function SUN_MIDDAY calculates at what time the sun is exactly in the
south, depending on the date. The calculation is done in UTC (Universal
Time).

12.50. SUN_POS

Type Function module

Input LATITUDE: REAL (latitude of the reference location)
LONGITUDE : REAL (longitude of the reference location)
UTC: DATE_TIME (Universal Time)
Output B: REAL (azimuth in degrees from North)
H: REAL (Astronomical sun height)
HR: REAL (solar altitude in degrees above the horizon with re-
fraction)

SUN_POS calculated the position of the sun (B, H) at the current time. The
time is expressed as Universal Time (UTC). Any possible local time must
frst be converted to UTC. At the sun position HR, the atmospheric refracti-
on for 1010mbar and 10°C is already taken into account. The accuracy is
better than 0.1 degrees for the period from 2000 to 2050. Possible appli-
cations of SUN_POS are the tracking of solar panels or a sun dependent
tracking of the slats of blinds. SUN_POS is a complicated algorithm, but
delivers the exact values. To keep the load of a PLC as low as possible, the
calculation can be performed, for example, only every 10 seconds, which
corresponds to an uncertainty of 0.04 degrees. The output B passes the
solar angle in degrees from north (south = 180 °). H is the Astronomical
angle above the horizon (the horizon = 0 °). HR is the sun above the hori-
zon to the atmospheric corrected by the refraction (refraction). An obser-
ver on the Earth sees the sun in a, by the refraction raised position, of the
horizon, which will cause the sun is shining already, but it is still slightly
below the horizon.

12.51. SUN_TIME

Type Function module
Input LATITUDE: REAL (latitude of the reference location)
LONGITUDE : REAL (longitude of the reference location)
UTC: DATE (Universal Time)
H: Real (angle above the horizon in degrees)
Output MIDDAY : TOD (sun exactly south)
SUN_RISE : TOD (time of sunrise)

SUN_SET: TOD (time of sunset)
SUN_Declension : REAL (height in the sun South)

The function block SUN_TIME is a astro timer. It calculates sunrise and
sunset for any day, defned by the input UTC. In addition to sunrise and
sunset, the time of the solar azimuth (daily peak in the south) and the
solar angle above the horizon in the azimuth is calculated. This SUN_TIME
will work regardless of the site all the time is calculated in UTC (Universal
Time) and can again be converted to local time as needed. In addition, to
the times of sunrise and sunset, the module also calculates the angle of
the sun above the horizon SUN_DECLINATION. SUN_TIME uses a complex
algorithm to minimize the loading of a PLC as low as possible, the values
should be calculated with SUN_TIME only once per day. SUN_TIME is used
for the control of blinds, in order to pull up just before sunrise and enjoy in
the bedroom the twilight. Other applications are include controlling
irrigation in horticulture to using the sunrise and sunset or even for
tracking solar panels. Further calculations of Sun's position is provided by
the module SUN_POS. SUN_TIME is only in latitudes between 65°S and
65°North is available. The output MIDDAY passes, at what time the sun is
the south and SUN_DECLINATION stating the angle above the horizon in
degrees.
Example of 1.1.1970, 12° East and 47° North:

The times of sunrise and - Sunset in UTC (Universal Time), the highest
position of the sun will be at 11:16 UTC at 20 degrees above the horizon.
As at the input -6 ° is given, the module calculates the Civil twilight.
SUN_RISE is the time, when the upper edge of the sun is visible on the
horizon. SUN_SET is the time when the upper edge of the sun disappears
behind the horizon. The horizon is just above the open sea constantly at 0°
depending on the terrain and location of hills and mountains, this time
may difer materially for various locations. A corresponding correction can
only be place dependent, where is the basis for revisions is, thatthe sun
travels in one minute 4 degrees. For practical applications, except on the
open sea must both rise as well as set times be adjusted accordingly. With
the input of H can be defned, how many degrees before or after the
horizon SUN_RISE and SUN_SET is determined. If not specifed on input H,

the module works internally with the default of -0.83333 degrees which
will compensate the refraction at the horizon. For civil, nautical and
astronomical twilight at the entrance of H, the corresponding values (-6 °,
-12 °, -18 °) are given.
For sunrise and sunset, there are diferent defnitions and requirements:
The Civil twilight describes that time when the sun is 6 degrees below the
horizon, it is the time where daylight is already achieved.
As nautical twilight is the period when the sun is 12 ° below the horizon, it
is the time when the frst lightening on the horizon is determined.
The Astronomical twilight is the time when the sun is 18 degrees below the
horizon, it is the time at which no illumination of the sun longer
measurable.
Additional information on sunrise and sunset times are available on the
following websites:
http://www.calsky.com/cs.cgi
http://lexikon.astronomie.info/java/sunmoon/

12.52. TIME CHECK

Type Function: BOOL
Input TD: TOD(time of day)
TD: TOD(time of day)
STOP: TOD(stop time)
Output BOOL ( Return Value )

TIME CHECK checks whether the daily time TD is between the START and
STOP time. TIME CHECK returns TRUE if TD > = START and TD < STOP. IF
START and STOP are defned in a way that START > STOP, the output with
the start set to TRUE and remains by midnight TRUE until at the next day
STOP is reached.
The function has the following defnition:
START < STOP : TD >= START AND TD < STOP

START > STOP : TD >= START OR TD < STOP

12.53. UTC_TO_LTIME

Type Function module
Input UTC: DATE_TIME (Universal Time)
DST_ENABLE: BOOL(TRUE allows DST)
TIME_ZONE_OFFSET: INT(time diference to UTC in minutes)
Output DT: DATE_TIME (local time)

The function module UTC_TO_LTIME calculates from the universal time at
input UTC the local time (LOCAL_DT), with automatic daylight saving time
if DST_ENABLE is set to True. If DST_ENABLE is FALSE, the local time is cal-
culated without daylight saving.
This function module requires UTC at the input, which is normally provided
by the PLC and can be read by a routine of the manufacturer.
The following example an application for a WAGO 750-841 CPU is shown.
The reading of the internal clock is done by the manufacturer SYSRTCGET-
TIME routine. The PLC clock must be in this case set to UTC.

12.54. WORK_WEEK

Type Function: INT
Input IDATE: DATE (date)
Output INT (working week of the input date)

The function WORK_WEEK calculates the week from the date of input IDA-
TE. The week starts with 1 for the frst week of the year. The frst Thursday
of the year is always in the frst week. If a year starts with a Thursday or
end on a Thursday this year has 53 calendar weeks. If the frst day of the
year a Tuesday, Wednesday or Thursday so the week begins one early as
December of last year. If the frst day of the year is Friday, Saturday or
Sunday, the last week of the year extends into January. The calculation is
done in accordance with ISO8601.
As the work week (Work Week ) International is not always used consis-
tent, before the application of the function is to clarify, whether the work
week according to ISO8601 is desired in the desired application function.

12.55. YEAR_BEGIN

Type Function: DATE
Input Y: INT (year)
Output DATE (date of 1 January of the year)

YEAR_BEGIN calculate the date of the frst January for the year Y.

12.56. YEAR_END

Type Function: DATE
Input Y: INT (year)
Output DATE (date of December 31 for the year)

YEAR_END calculates '31 December in the year Y.

12.57. YEAR_OF_DATE

Type Function: INT
Input IDATE: DATE (date)
Output INT (year of the date)

The function YEAR_OF_DATE calculates the corresponding year from the
date of input IDATE.
Example: YEAR_OF_DATE(31.12.2007) = 2007