Date and Time Library Manual
About this documentation
This documentation provides essential information for working with components of the DDAS software ecosystem. It is intended for software developers and machine manufacturers who integrate, validate, and operate DDAS function blocks within CODESYS‑based applications.
Note!
Before installing or configuring any software, ensure that you have read and understood the operating instructions of all relevant hardware devices!
Tip!
Further information can be found at: https://www.ddas.digital
This manual is part of the DDAS library collection, which includes documentation for license management, date and time handling, scheduling, equipment performance, and other functional modules:
| Documentation | Subject |
|---|---|
| DDAS License Manager Manual | Licensing with DDAS activation keys (Machine Insight Suite) |
| DDAS Machine Insight Suite SL – Installation and Licensing | Licensing with a CODESYS device license (Machine Insight Suite SL) |
| DDAS Date Time Library Manual | Description and usage of the Date Time function blocks |
| DDAS Scheduler Library Manual | Description and usage of the Scheduler function blocks |
| DDAS Equipment Performance Library Manual | Description and usage of the Equipment Performance function blocks |
| DDAS Application Template Manual | Structure and usage of the Application Template |
Document history
| Version | Description | ||
|---|---|---|---|
| 1.0 | 14.04.2026 | DDAS | Initial version |
| 1.1 | 07.10.2026 | DDAS | Time zone difference: tTimeZoneDiff is the absolute value, new iTimeZoneOffsetMin with sign. Output xLicensed clarified. |
General
Library
This library provides function blocks for retrieving local and UTC date and time information. It is intended for applications that require reliable and consistent time data, such as data logging, event time stamping, and system-wide time synchronization.
The library supplies local time, UTC time, and a UTC-based timestamp with millisecond resolution in predefined, standardized formats.
The library includes the following user function block:
GetDateTimeInfo
Detailed descriptions of the function blocks and their relevant dependencies are provided in the following chapters.
Licensing
All DDAS libraries require a valid license. The license check is performed by the DDAS License Manager library (DDAS_LicenseManager_Lib), which is added to the project automatically as a dependency of this library. The function blocks of this library need no licensing code.
How the license is activated depends on your product:
DDAS Machine Insight Suite (DDAS activation keys): DDAS License Manager Manual, https://ddas.cloudet.digital/html/DDAS-LicenseManager-LibraryManual-en.html
DDAS Machine Insight Suite SL (CODESYS device license): DDAS Machine Insight Suite SL – Installation and Licensing, https://ddas.cloudet.digital/html/DDAS-MachineInsightSuiteSL-Manual-en.html
Without a valid license, the library runs in a time-limited demo mode, as described in the licensing documentation of your product. After the demo has expired, all function blocks of this library stop and report error 10 (no_ValidLicense). The function DDAS_LM.GetLicenseInfo returns the license status and the cause.
Note: The function Get_sError is available in every library and returns the error text and the enumeration value for an error code of this library.
FB GetDateTimeInfo
General Information
This chapter describes the function block GetDateTimeInfo.
Function Block Name: GetDateTimeInfo
Library: DDAS_DateTime_Lib
Dependent Codesys libraries: SysTime | SysTimeRtc | Util
CODESYS Version Compatibility: CODESYS V3.5 and higher
License / Usage Restrictions: Requires valid full or demo library license
Purpose & Scope
The GetDateTimeInfo function block provides
consistent access to local time, UTC time,
and a UTC-based timestamp in milliseconds or seconds.
It is designed for applications where synchronized and comparable time
information
is required across different systems or devices.
Typical Use Cases
Event and alarm time stamping
Production data logging
Time synchronization reference for distributed control systems
HMI display of local and UTC time
Functional Overview
When enabled, the function block GetDateTimeInfo periodically retrieves the current system’s time.
It outputs:
- Local date and time
- Day of week
- Structured date and time details
- Optional millisecond-accurate UTC timestamp
The update interval is configurable within a range of 0 to 1 second.
The update interval shall be selected according to application needs. Short intervals increase accuracy but may increase system load
The function block uses CODESYS system time and real-time clock
services to
retrieve both local and UTC date/time information.
Error states are monitored continuously and reported via diagnostic
outputs.
Interface Description
Function block Inputs and Outputs
| Scope | Name | Type | Initial | Comment |
|---|---|---|---|---|
| Input | xEnabled | BOOL | Enables execution of the function block when TRUE. | |
| tUpdateInterval | TIME | TIME#250ms | Time base that defines how often date and time information is updated (e.g. T#250ms updates the date and time every 250 ms). The time base is limited to T#1s. |
|
| xGetMilliseconds | BOOL | FALSE | When set to TRUE, time is provided in milliseconds; otherwise, time is provided in seconds. | |
| Output | dtLocalDateTime | DT | Local Date and Time. | |
| uiDayofWeek | UINT | Local day of the week, where 1 = Monday and 7 = Sunday. A value of 0 indicates an unknown weekday. | ||
| scDateTimeInfo | scDateTimeInfo | Detail information about Date and Time. | ||
| xLicensed | BOOL | TRUE when a valid full or demo library license is active. FALSE while the function block is disabled (xEnabled = FALSE). | ||
| xError | BOOL | TRUE if an error or warning is detected. Detailed error information is provided in iErrorID. | ||
| iErrorID | INT | Error and status identifier for diagnostics. |
Structures
scDateTimeInfo
This structure provides UTC and local date and time in various formats, as well as the current day of the week and calendar week.
| Name | Type | Comment |
|---|---|---|
| sLocalDateTime | STRING | Local Date and Time string. |
| dLocalDate | DATE | Local Date. |
| todLocalTIME | TOD | Local Time in time of day format. |
| uli_UTC_Timestamp | ULINT | Unix UTC Timestamp. |
| dtUTC_DateTime | DT | UTC Date and Time. |
| sUTCDateTime | STRING | UTC Date and Time string. |
| dUTC_Date | DATE | Date of UTC Time. |
| todUTC_Time | TOD | UTC Time in time of day format. |
| eDayofWeek | eWeekday | Local Day of the week. |
| tTimeZoneDiff | TIME | Time difference between Local and UTC Time (absolute value). |
| iTimeZoneOffsetMin | INT | Difference between Local and UTC Time in minutes, negative west of UTC. |
| ui_cw | UINT | Local Calendar week. |
Note: The data type TIME has no sign. tTimeZoneDiff therefore provides only the amount of the difference. Use iTimeZoneOffsetMin when the direction is required, for example +120 for UTC+2 and -300 for UTC-5.
Enumerations
eWeekday
Day of the week enumeration.
| Name | Initial | Comment |
|---|---|---|
| Unknown | 0 | Unknown day of the week. |
| Monday | 1 | Week day Monday. |
| Tuesday | 2 | Week day Tuesday. |
| Wednesday | 3 | Week day Wednesday. |
| Thursday | 4 | Week day Thursday. |
| Friday | 5 | Week day Friday. |
| Saturday | 6 | Week day Saturday. |
| Sunday | 7 | Week day Sunday. |
eError
Library Possible Error Codes and Descriptions.
| Name | Initial | Comment |
|---|---|---|
| no_error | 0 | No error detected. |
| no_ValidLicense | 10 | No valid license was found. Check the license status with DDAS_LM.GetLicenseInfo. |
| invalid_GetTimeBase | 20 | The input parameter tGetDateTimeDuration is greater than T#1s, the time base is limited to T#1s (maximum update interval). |
| invalid_LocalDateTime | 21 | Invalid dtLocalDateTime = DT#1970-01-01-00:00:00 |
| invalid_UTC_DateTime | 22 | Invalid dtUTC_DateTime = DT#1970-01-01-00:00:00 |
| invalid_eDayofWeek | 23 | Invalid week day eDayofWeek = 0 or eDayofWeek > 7 |
| invalid_ui_cw | 24 | Invalid calendar week ui_cw = 0 or ui_cw > 53 |
| unknowing_error | 99 | Unknown error. |
Note: The library function Get_eError can be used to determine the corresponding eError enumeration based on a given integer iErrorID.
Global Variable
GVL_LibGuide
This Global Variable List provides the library GUID. It is used for activation keys (DDAS_LM.GVL_License) and for the license status (DDAS_LM.GetLicenseInfo); see the licensing documentation of your product.
| Scope | Name | Type | Initial | Comment |
|---|---|---|---|---|
| Constant | cLibraryGuid | STRING | ‘{LIB-DDAS-D5BA612E}’ | Unique Library license GUID for use in the user program to activate the library license. |
Execution & Timing Behaviour
The function block is intended to be executed cyclically in a task context.
Timing precision depends on the configured task cycle time and target platform
Error Handling & Diagnostics
If an internal error, a library issue, or a licensing problem occurs, xError is set to TRUE and iErrorID provides the corresponding error code. Detailed descriptions of the error codes are defined in the enumeration eError.
Assumptions & Limitations
Accuracy depends on the system clock and the RTC configuration. Hardware‑dependent behavior may vary across different CODESYS platforms.
Before ordering this library, please verify the correct functionality of the library function block in your target system.
Example Implementation
Declaration and Call of the Function Block GetDateTimeInfo:
VAR
fb_GetDateTime : DDAS_DT.GetDateTimeInfo;
END_VAR
FB call in structure text:
fb_GetDateTime(
xEnabled := TRUE,
tUpdateInterval := T#250MS,
xGetMilliseconds := TRUE
);
FB call in continuous function chart diagram:
Function block sample input and output parameter:
Screenshot example in Online / Monitor mode
Demo Visualisation
Your Feedback Matters
These instructions have been prepared to the best of our knowledge and belief to provide you with the highest possible level of support when working with our product.
Despite our best efforts, we may not always fully achieve this objective. If you identify any issues or have suggestions for improvement, we would greatly appreciate your feedback.
Please send your comments or criticism in a short e‑mail to:
Thank you for your support.
Your DDAS Application Software Team