diff --git a/Times-scripts/FC_GetSetLocalTime_readme.md b/Times-scripts/FC_GetSetLocalTime_readme.md new file mode 100644 index 0000000..486c9d0 --- /dev/null +++ b/Times-scripts/FC_GetSetLocalTime_readme.md @@ -0,0 +1,132 @@ +# 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. \ No newline at end of file