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.
|