132 lines
3.8 KiB
Markdown
132 lines
3.8 KiB
Markdown
# 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
|
||
|
||
```scl
|
||
RET_VAL := FC_GetSetLocalTime(
|
||
xWrite := FALSE,
|
||
dtLocal => CurrentTime // CurrentTime will be filled with the current date/time
|
||
);
|
||
```
|
||
|
||
### Write / Set a New Local Time
|
||
|
||
```scl
|
||
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:
|
||
|
||
```scl
|
||
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. |