FC_GetSetLocalTime

Version: 1.1
Language: SCL (Structured Control Language) — Siemens TIA Portal
Return Type: Int

Overview

FC_GetSetLocalTime is a reusable function block for Siemens PLCs that provides a unified interface to read the current local time or write (set) a new local date and time. It wraps the TIA Portal system instructions RD_LOC_T and WR_LOC_T into a single, easy-to-call function.

Parameters

Inputs

Parameter	Type	Description
`xWrite`	`BOOL`	`FALSE` = Read current local time. `TRUE` = Write a new local time.
`dtLocal`	`DTL`	When writing: pass the desired new date/time here. When reading: this parameter receives the current date/time as output.

Note: dtLocal acts as both an input and output depending on the mode selected by xWrite.

Outputs

Parameter	Type	Description
`xDone`	`BOOL`	Set to `TRUE` when the operation completes without error.
`xError`	`BOOL`	Set to `TRUE` when the operation fails.
`wStatus`	`WORD`	Detailed status or error code returned by the system instruction (e.g., `16#0000` = no error).

Return Value

Value	Meaning
`0`	Operation successful (OK)
`> 0`	Warning
`< 0`	Error

How It Works

The function uses a simple IF/ELSE branch controlled by the xWrite flag:

xWrite = FALSE  →  Calls RD_LOC_T  →  Reads current local time into dtLocal
xWrite = TRUE   →  Calls WR_LOC_T  →  Writes dtLocal value as new local time

In both cases:

If the system instruction returns ret = 0, xDone is set to TRUE.
If ret ≠ 0, xError is set to TRUE and wStatus holds the error code for diagnostics.
The function itself returns ret as its integer return value.

Usage Examples

Read Current Local Time

RET_VAL := FC_GetSetLocalTime(
    xWrite := FALSE,
    dtLocal => CurrentTime   // CurrentTime will be filled with the current date/time
);

Write / Set a New Local Time

RET_VAL := FC_GetSetLocalTime(
    xWrite := TRUE,
    dtLocal := NewTime       // NewTime contains the desired date/time to set
);

Error Handling

After calling the function, always check the outputs before proceeding:

IF xDone THEN
    // Operation was successful
ELSIF xError THEN
    // Handle error — inspect wStatus for the specific error code
END_IF;

The wStatus word follows standard Siemens status code conventions. A value of 16#0000 indicates no error.

Dependencies

This function relies on the following Siemens TIA Portal system instructions:

Instruction	Purpose
`RD_LOC_T`	Reads the current local date and time into a `DTL` variable
`WR_LOC_T`	Writes a new local date and time from a `DTL` variable

Both instructions are available on S7-1200 and S7-1500 series PLCs.

Data Type Reference — DTL

DTL (Date and Time Long) is a Siemens-specific data type that stores date and time with nanosecond precision.

Field	Type	Description
`YEAR`	`UINT`	Year (e.g., 2024)
`MONTH`	`USINT`	Month (1–12)
`DAY`	`USINT`	Day (1–31)
`WEEKDAY`	`USINT`	Day of week (1=Sunday … 7=Saturday)
`HOUR`	`USINT`	Hour (0–23)
`MINUTE`	`USINT`	Minute (0–59)
`SECOND`	`USINT`	Second (0–59)
`NANOSECOND`	`UDINT`	Nanoseconds (0–999,999,999)

Notes

The function resets xDone, xError, and wStatus at the start of every call, so outputs always reflect the most recent execution.
Only one operation (read or write) is performed per function call.
This function does not handle time zone conversion — it works with the local time as configured on the PLC.

3.8 KiB Raw Blame History Unescape Escape