Library Description:

CoDeSys V 3.x
SysTime.library

Document Version 3.0

libdoc_e.dot / V1.0

3S - Smart Software Solutions GmbH Page 1 of 10

SysTime_V3x_E.doc
 Library SysTime.library

CONTENT

1 OVERVIEW 3

2 LIBRARY MODULES 4
2.1 General time functions 4
2.1.1 SysTimeGetMs 4
2.1.2 SysTimeGetNs 4
2.1.3 SysTimeGetUs 4
2.2 RTC - High Resolution functions 4
2.2.1 SysTimeRtcConvertDateToHighRes 5
2.2.2 SysTimeRtcConvertHighResToDate 5
2.2.3 SysTimeRtcHighResGet 5
2.2.4 SysTimeRtcHighResSet 5
2.3 RTC - Standard Functions 6
2.3.1 SysTimeRtcControl 6
2.3.2 SysTimeRtcConvertDateToUtc 6
2.3.3 SysTimeRtcConvertLocalToUtc 6
2.3.4 SysTimeRtcConvertUtcToDate 7
2.3.5 SysTimeRtcConvertUtcToLocal 7
2.3.6 SysTimeRtcGet 7
2.3.7 SysTimeRtcGetTimezone 7
2.3.8 SysTimeRtcSet 8
2.3.9 SysTimeRtcSetTimezone 8
2.3.10 SysTimeGetDate 8
2.3.11 SysTimeGetTimestamp 8
2.4 Data types, Structures 9
2.4.1 Data type SysTime 9
2.4.2 Structure SysTimeDate 9
2.4.3 Structure TimezoneInformation 9

CHANGE HISTORY 10
libdoc_e.dot / V1.0

3S - Smart Software Solutions GmbH Page 2 of 10

SysTime_V3x_E.doc
 Library SysTime.library

1 Overview

Note: It depends on the target system, which system libraries can be used in the application program..

If the target system supports the functionality, the functions of this library allow to read resp.
set the realtime clock of the local system as well as various conversions of the clock time
data. The time data are handled IEC-conforming and in data type UDINT.

The processing is synchronous.

Terms:

RTC: Real Time Clock

UTC time: Coordinated Universal Time

System time: Time which is provided in a device by an internal clock.

The functions:

SysTimeGetMs
SysTimeGetNs
SysTimeGetUs
RTC
SysTimeRtcConvertDataToHighRes
SysTimeRtcConvertHighResToDate
SysTimeRtcHighResGet
SysTimeRtcHighResSet
Standard
SysTimeRtcControl
SysTimeRtcConvertDateToUtc
SysTimeRtcConvertLocalToUtc
SysTimeRtcConvertUtcToDate
SysTimeRtcConvertUtcToLocal
SysTimeRtcGet
SysTimeRtcGetTimezone
SysTimeRtcSet
SysTimeRtcSetTimezone

The following structures are used by the library functions:

SysTime
libdoc_e.dot / V1.0

SysTimeDate
TimezoneInformation

3S - Smart Software Solutions GmbH Page 3 of 10

SysTime_V3x_E.doc
 Library SysTime.library

2 Library Modules

2.1 General time functions

2.1.1 SysTimeGetMs
This function reads the current system time.

The return value of type UDINT gives the current time in milliseconds [ms].

2.1.2 SysTimeGetNs
This function reads the current system time.

The return value of type RTS_IEC_RESULT gives an error code, which informs about the
success of the operation. See document Runtime Error Codes.
InputOutput Data type Description
Variable

NsTime SysTime After function call this parameter will show the system
time in nanoseconds.

2.1.3 SysTimeGetUs
Diese function reads the current system time.

The return value of type RTS_IEC_RESULT gives an error code, which informs about the
success of the operation. See document Runtime Error Codes.
InputOutput Data type Description
Variable

UsTime SysTime After function call this parameter will show the system
time in microseconds.

2.2 RTC - High Resolution functions

The functions for the realtime clock handle two different time types:

UTC time: current coordinated universal time; has replaced the Greenwich Mean Time.
The time zones are given as positive or negative deviation from UTC.:
e.g. UTC+1 corresponds to the Central European Time (CET) and
UTC+2 corresponds to the Central European Summer Time (CEST)
Local time: Local time including daylight time (summer time) and time zone shift

Due to the fact that only the UTC time is globally unique, on most systems only the UTC time
libdoc_e.dot / V1.0

is stored and processed. By using the additional information time zone and summer time
the local time can be computed from the UTC.

3S - Smart Software Solutions GmbH Page 4 of 10

SysTime_V3x_E.doc
 Library SysTime.library

2.2.1 SysTimeRtcConvertDateToHighRes
This function converts the time given by variable pDate (format SysTimeDate) into a High
Resolution Time of format SysTime.

The return value of type RTS_IEC_RESULT gives an error code, which informs about the
success of the operation. See document Runtime Error Codes.
InputOutput- Data type Description
Variable

pDate SysTimeDate The time to be converted (SysTimeDate format); see

structure SysTimeDate (Chap. 2.4.2)
pTimestamp SysTime The converted time (SysTime format).

2.2.2 SysTimeRtcConvertHighResToDate
This function converts the time given by variable pTimestamp (format SysTime) into format
SysTimeDate.

The return value of type RTS_IEC_RESULT gives an error code, which informs about the
success of the operation. See document Runtime Error Codes.
InputOutput- Data type Description
Variable

pTimestamp SysTime The time to be converted (SysTime format)

pDate SysTimeDate The converted time (SysTimeDate format); see

structure SysTimeDate (Chap. 2.4.2)

2.2.3 SysTimeRtcHighResGet
This function provides the time (milliseconds) which has passed since 01.01.1970 00:00:00
(RTC).

The return value of type RTS_IEC_RESULT gives an error code, which informs about the
success of the operation. See document Runtime Error Codes.
InputOutput- Data type Description
Variable

pTimestamp SysTime Time in milliseconds since 01.01.1970 00:00:00

2.2.4 SysTimeRtcHighResSet
This function sets the Real Time Clock.

The return value of type RTS_IEC_RESULT gives an error code, which informs about the
success of the operation. See document Runtime Error Codes.
InputOutput- Data type Description
Variable
libdoc_e.dot / V1.0

pTimestamp SysTime Time in milliseconds since 01.01.1970 00:00:00,

which should be set

3S - Smart Software Solutions GmbH Page 5 of 10

SysTime_V3x_E.doc
 Library SysTime.library

2.3 RTC - Standard Functions

2.3.1 SysTimeRtcControl
This function can be used to manage the Real Time Clock and to read the hardware status
information.

The return value of type RTS_IEC_RESULT gives an error code, which informs about the
success of the operation. See document Runtime Error Codes.
Input-Variable Data type Description

iControlTag DINT RTC_CTRL_CHECKBATTERY (0): RTC battery

check
RTC_CTRL_HOURMODE (1): hour mode of the RTC

InputOutput-Variable Data type Description

pdiControlResult DINT Result of control request:

HourMode:
RTC_12HOURS(0) or RTC_24HOURS (1)
CheckBattery:
RTC_BATTERY_FAILED (0) or
RTC_BATTERY_OK (1)

2.3.2 SysTimeRtcConvertDateToUtc
This function converts the system time (format SysTimeDate) into the UTC time format.

The return value of type RTS_IEC_RESULT gives an error code, which informs about the
success of the operation. See document Runtime Error Codes.
InputOutput-Variable Data type Description

pDate SysTimeDate Local time in SysTimeDate format, see structure

SysTimeDate (Chap 2.4.2)
pdwTimestampUtc DWORD UTC time

2.3.3 SysTimeRtcConvertLocalToUtc
This function converts the local time into the UTC time format.

The return value of type RTS_IEC_RESULT gives an error code, which informs about the
success of the operation. See document Runtime Error Codes.
Input-Variable Data type Description

dwTimestampLocal DWORD Local time, to be converted into UTC time format

libdoc_e.dot / V1.0

InputOutput-Variable Data type Description

pdwTimestampUTC DWORD Converted time (UTC format)

3S - Smart Software Solutions GmbH Page 6 of 10

SysTime_V3x_E.doc
 Library SysTime.library

2.3.4 SysTimeRtcConvertUtcToDate
This function converts the UTC time into the local time (format SysTimeDate).

The return value of type RTS_IEC_RESULT gives an error code, which informs about the
success of the operation. See document Runtime Error Codes.
Input-Variable Data type Description

dwTimestampUtc DWORD UTC time, to be converted into local time format

InputOutput-Variable Data type Description

pDate SysTimeDate Local time after conversion; see structure

SysTimeDate (Chap 2.4.2)

2.3.5 SysTimeRtcConvertUtcToLocal
This function converts the UTC time into the local time.

The return value of type RTS_IEC_RESULT gives an error code, which informs about the
success of the operation. See document Runtime Error Codes.
Input-Variable Data type Description

dwTimestampUtc DWORD UTC time to be converted

InputOutput-Variable Data type Description

pdwTimestampLocal DWORD Local time after conversion

2.3.6 SysTimeRtcGet
This function reads the current RTC system time.

The return value of type DWORD contains the RTC time since 01.01.1970 00:00:00 in
seconds.
Input-Variable Data type Description

pResult UDINT Error code, see document Runtime Error Codes

2.3.7 SysTimeRtcGetTimezone
This function detects the effective RTC time zone.

The return value of type RTS_IEC_RESULT gives an error code, which informs about the
success of the operation. See document Runtime Error Codes.
libdoc_e.dot / V1.0

InputOutput-Variable Data type Description

pTimezone TimezoneInformation Detailed information on the time zone, see

structure TimezoneInformation

3S - Smart Software Solutions GmbH Page 7 of 10

SysTime_V3x_E.doc
 Library SysTime.library

2.3.8 SysTimeRtcSet
This function sets the current RTC system time.

The return value of type RTS_IEC_RESULT gives an error code, which informs about the
success of the operation. See document Runtime Error Codes.
Input-Variable Data type Description

ulTimestamp DWORD RTC time since 01.01.1970 00:00:00 in

milliseconds to be set

2.3.9 SysTimeRtcSetTimezone
This function sets the current RTC time zone.

The return value of type RTS_IEC_RESULT gives an error code, which informs about the
success of the operation. See document Runtime Error Codes.
Input-Variable Data type Description

pTimezone TimezoneInformation Detailed information on the time zone, see

structure TimezoneInformation (Chap. 2.4.3)

2.3.10 SysTimeGetDate
This function detects the current time in SysTimeDate format.

The return value of type RTS_IEC_RESULT gives an error code, which informs about the
success of the operation. See document Runtime Error Codes.
InputOutput-Variable Data type Description

TimeDate SysTimeDate Current time

2.3.11 SysTimeGetTimestamp
This function detects the current timestamp (=SysTimeRtcGet).
The return value of type UDINT contains the RTC time since 01.01.1970 00:00:00 in
milliseconds.
libdoc_e.dot / V1.0

3S - Smart Software Solutions GmbH Page 8 of 10

SysTime_V3x_E.doc
 Library SysTime.library

2.4 Data types, Structures

2.4.1 Data type SysTime

Real time of the local system (64 Bit,ULINT).

2.4.2 Structure SysTimeDate

This structure contains detailed information on the system time, split up into a readable format
(in contrast to the timestamp).
Structure component Data type Meaning

wYear UINT Year, e.g. "2006"

wMonth UINT Month, values 1-12, Jan=1, Dec=12; e.g. "11"

wDay UINT Day in month, values 1-31; e.g. "3"

wHour UINT Hours of current day, values 0-23; e.g. "13"

wMinute UINT Minutes of current hour, values 0-59: e.g. "43"

wSecond UINT Seconds of current minute, values 0-59: e.g. "15"

wMilliseconds UINT Optional!: Milliseconds of current second, values 0-999:

e.g. "649"
wDayOfWeek UINT Day of the week, values 1-7, (Sunday=0, Monday = 1...);
e.g. "2"
wYday UINT Day of the year, values 1-365 (01.Jan=1, 31.Dec=364
resp. 365); e.g. 144

2.4.3 Structure TimezoneInformation

This structure contains detailed information on the time zone. It is used by the functions
SysTimeRtcGetTimezone and SysTimeRtcSetTimezone for reading resp. setting the time
zone.
Structure component Data type Meaning

ulStandardDate UDINT Date for switching from daylight time to normal time

ulDaylightDate UDINT Date for switching from normal time to daylight time

szStandardName STRING(32) Name of the standard time zone

e.g. Amsterdam, Berlin, Rom

szDaylightName STRING(32) Name of the daylight time

iBias INT UTC = Local time + iBias

libdoc_e.dot / V1.0

iStandardBias INT Additional shift versus standard time in minutes

iDaylightBias INT Additional shift versus daylight time in minutes

3S - Smart Software Solutions GmbH Page 9 of 10

SysTime_V3x_E.doc
 SysTime.library

Change History
Version Description Date

0.1 Issued 15.06.2007

0.2 Rework 27.06.2007
0.3 Translated corresponding to reviewed German version 0.4 15.07.2007
1.0 Rework corr. to German version 1.0, Release 09.08.2007
1.1 Corrections according to #35232 08.09.2008
2.0 Release 10.09.2008
2.1 Chap. 2.4.1 corrected (#35908) 22.10.2008
2.2 Review, ok 08.01.2009
3.0 Release 13.01.2009
libdoc_e.dot / V1.0

3S - Smart Software Solutions GmbH Page 10 of 10

SysTime_V3x_E.doc