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