# LGF_FileReadWriteDelete (FB / 1.0.0)

Übersicht

Autor: Simatic Systems Support

## Kurzbeschreibung

Mit der Funktion `LGF_FileReadWriteDelete` kann eine Datei auf/von der SIMATIC Memory Card (SMC) gelesen, geschrieben oder gelöscht werden.

Zum Lesen oder Schreiben der Daten ist es notwendig, diese zu deserialisieren/serialisieren, was die Funktion bereits für den Anwender übernimmt, dafür muss ein externer Puffer in Form eines Byte-Arrays verschaltet werden, der die Datenmenge aufnehmen kann, ist der Puffer zu klein, wird ein Fehler ausgegeben.

Der Dateiname muss immer vollständig zusammen mit dem Ordnernamen und der Dateierweiterung im folgenden Format angegeben werden: `UserFiles/Test.dat`.

### Baustein Schnittstelle

| LGF_FileReadWriteDelete (FB) |
--- | --- | ---
Bool |  |  | executeRead |  | done |  |  | Bool
Bool |  |  | executeWrite |  | busy |  |  | Bool
Bool |  |  | executeDelete |  | error |  |  | Bool
String |  |  | fileName |  | status |  |  | Word
LGF_typeFileReadWriteDeleteParameter |  |  | parameter |  | dataLength |  |  | DInt
|  |  |  |  | fileDoesNotExist |  |  | Bool
|  |  |  |  | timestamps |  |  | LGF_typeFileReadWriteDeleteTimestamps
|  |  |  |  | diagnostics |  |  | LGF_typeDiagnostics
Array[*] of Byte |  |  | bufferByteArray |  |  | Array[*] of Byte
Variant |  |  | data |  |  | Variant

### Input Parameter

Bezeichner | Datentyp | Default Wert | Beschreibung
--- | --- | --- | ---
executeRead | Bool | FALSE | Steigende Flanke startet einmaliges Lesen der Datei
executeWrite | Bool | FALSE | Steigende Flanke startet einmaliges Schreiben der Datei
executeDelete | Bool | FALSE | Steigende Flanke startet einmaliges Löschen der Datei
fileName | String | '' | Name der Datei inklusiv Pfad: `UserFiles/test.dat`
parameter | LGF_typeFileReadWriteDeleteParameter | --- | Dieser UDT gehört zu dem Modul `LGF_FileReadWriteDelete` und listet alle möglichen Parameter zur Konfiguration des Verhaltens auf.

### Output Parameter

Bezeichner | Datentyp | Beschreibung
--- | --- | ---
done | Bool | TRUE: FB-Abarbeitung erfolgreich fertiggestellt
busy | Bool | TRUE: FB ist aktiv; neue Ausgabewerte können erwartet werden.
error | Bool | TRUE: Bei der Ausführung der Funktionalität ist ein Fehler aufgetreten
status | Word | 16#0000-16#7FFF: Status des FB / 16#8000-16#FFFF: Fehleridentifikation (siehe folgende Tabelle)
dataLength | DInt | Datenlänge die aus der Datei gelesen wurde (Serialisierte Länge von `data`)
fileDoesNotExist | Bool | True: Die Datei oder der Pfad unter `Dateiname` existiert nicht
timestamps | LGF_typeFileReadWriteDeleteTimestamps | Zeitstempel für Kommandos und Datei
diagnostics | LGF_typeDiagnostics | Diagnosestruktur zur Speicherung und Übertragung von Diagnoseinformationen von Blöcken über die Schnittstelle.

### In/Out Parameter

Bezeichner | Datentyp | Beschreibung
--- | --- | ---
bufferByteArray | Array[*] of Byte | Byte-Array-Puffer für Lesen / Schreiben aus / in Datei
data | Variant | Datensatz der aus Datei gelesen / in Datei geschrieben wird

### Status & Error Meldungen

Code / Wert | Bezeichner / Beschreibung
--- | ---
16#0000 | STATUS_EXECUTION_FINISHED Ausführung ohne Fehler beendet
16#7000 | STATUS_NO_CALL Kein Job wird gerade verarbeitet
16#7001 | STATUS_FIRST_CALL Erster Aufruf nach Eingang eines neuen Auftrags (steigende Flanke 'execute')
16#7002 | STATUS_SUBSEQUENT_CALL Nachfolgender Aufruf bei aktiver Verarbeitung ohne weitere Angaben
16#8201 | ERR_BUFFER_LOWERBOUND Fehler: Untere Grenze des Pufferarrays Untere Grenze muss 0 sein
16#8202 | ERR_BUFFER_ARRAY_TO_SMALL_TO_COPY Fehler: Puffergröße kleiner als benötigte Größe für Daten
16#8400 | ERR_MULTIPLE_COMMANDS Fehler: Mehrere Befehle zur gleichen Zeit sind nicht erlaubt.
16#8401 | ERR_FILE_PATH Fehler: Dateipfad Fehler: der Dateipfad muss mit 'UserFiles/' beginnen.
16#8402 | ERR_READ_TIME_LOCAL Fehler: Lesen der Lokal Zeit `RD_LOC_T` - siehe `diagnostics.subFunctionStatus`
16#8403 | ERR_READ_TIME_SYSTEM Fehler: Lesen der System Zeit (UTC) `RD_SYS_T` - siehe `diagnostics.subFunctionStatus`
16#8411 | ERR_FILE_SIZE_GRATER_THEN_DATA_SIZE Fehler: Dateilänge und Datenlänge stimmen nicht überein!
16#8412 | ERR_FILE_SIZE_LESS_THEN_DATA_SIZE Fehler: Dateilänge und Datenlänge stimmen nicht überein!
16#8600 | ERR_UNDEFINED_STATE Fehler aufgrund eines undefinierten Zustands im Zustandsautomaten
16#8601 | ERR_MOVE_BLK_VARIANT Fehler: Blockvariante verschieben (Puffer nach Daten) - siehe `diagnostics.subFunctionStatus`
16#8602 | ERR_SERIALIZE_DATA Fehler: Daten serialisieren - siehe `diagnostics.subFunctionStatus`
16#8603 | ERR_DESERIALIZE_DATA Fehler: Daten deserialisieren - siehe `diagnostics.subFunctionStatus`
16#8604 | ERR_SERIALIZE_DATE_TIMESTAMP Fehler: Datums und Zeitstempel serialisieren - siehe `diagnostics.subFunctionStatus`
16#8605 | ERR_DESERIALIZE_DATE_TIMESTAMP Fehler: Datums und Zeitstempel deserialisieren - siehe `diagnostics.subFunctionStatus`
16#8610 | ERR_FILE_READ_INIT Fehler: Datei von der SMC lesen Initialisierung - siehe `diagnostics.subFunctionStatus`
16#8611 | ERR_FILE_READ Fehler: Datei von SMC lesen - siehe `diagnostics.subFunctionStatus`
16#8620 | ERR_FILE_WRITE_INIT Fehler: Datei auf die SMC schreiben Initialisierung - siehe `diagnostics.subFunctionStatus`
16#8621 | ERR_FILE_WRITE Fehler: Datei auf SMC schreiben - siehe `diagnostics.subFunctionStatus`
16#8630 | ERR_FILE_DELETE_INIT Fehler: Datei von der SMC löschen Initialisierung - siehe `diagnostics.subFunctionStatus`
16#8631 | ERR_FILE_DELETE Fehler: Datei von SMC löschen - siehe `diagnostics.subFunctionStatus`

## Benutzer definierte Datentypen

### LGF_typeFileReadWriteDeleteParameter (UDT / V0.0.1)

Dieser UDT gehört zu dem Modul `LGF_FileReadWriteDelete` und listet alle möglichen Parameter zur Konfiguration des Verhaltens auf.

Bezeichner | Datentyp | Default Wert | Beschreibung
--- | --- | --- | ---
dataLengthMustMatch | Bool | TRUE | TRUE: Die Länge der Daten aus der Datei und der PLC muss übereinstimmen (Datei lesen)
clearBufferBefore | Bool | TRUE | TRUE: Der Puffer wird vor dem Schreiben der Daten mit 16#00 Byte gelöscht (Datei schreiben)
includeTimestamp | Bool | FALSE | TRUE: Ein Zeitstempel (DTL) wird den Daten vorangestellt. `executeWrite` fügt die aktuelle Zeit (System- oder Ortszeit) hinzu `executeRead` liest den Zeitstempel zurück
timeStampIsLocal | Bool | FALSE | TRUE: Der Zeitstempel wird in Ortszeit verwendet. FALSE: Der Zeitstempel wird in Systemzeit / UTC verwendet. Nur genutzt, wenn `includeTimestamp` gesetzt ist.

### LGF_typeFileReadWriteDeleteTimestamps (UDT / V0.0.1)

Dieser UDT gehört zu dem Modul `LGF_FileReadWriteDelete` und listet alle Zeit Stempel der Befehle und der Datei auf, falls bekannt.
Wenn der Zeit Stempel unbekannt ist, wird er Default Zeit Stempel angezeigt: `DTL#1970-01-01-00:00:00`.

Bezeichner | Datentyp | Default Wert | Beschreibung
--- | --- | --- | ---
file | LGF_typeFileReadWriteDeleteTimestamp | --- | Zeitstempel der Datei
lastCommand | LGF_typeFileReadWriteDeleteTimestamp | --- | Zeitstempel letztes Kommando
executeRead | LGF_typeFileReadWriteDeleteTimestamp | --- | Zeitstempel Kommando `executeRead`
executeWrite | LGF_typeFileReadWriteDeleteTimestamp | --- | Zeitstempel Kommando `executeWrite`
executeDelete | LGF_typeFileReadWriteDeleteTimestamp | --- | Zeitstempel Kommando `executeDelete`
lastError | LGF_typeFileReadWriteDeleteTimestamp | --- | Zeitstempel des letzten aufgetretenen Fehlers

### LGF_typeFileReadWriteDeleteTimestamp (UDT / V0.0.1)

Dieser UDT gehört zu dem Modul `LGF_FileReadWriteDelete` und enthält einen Zeit Stempel eines Befehls oder der Datei. Wenn der Zeit Stempel unbekannt ist, wird er Default Zeit Stempel angezeigt: `DTL#1970-01-01-00:00:00`.

Bezeichner | Datentyp | Default Wert | Beschreibung
--- | --- | --- | ---
dateAndTime | DTL | --- | Zeitstempel
timestampIsLocal | Bool | FALSE | TRUE: Der Zeitstempel wird in Ortszeit verwendet. FALSE: Der Zeitstempel wird in Systemzeit / UTC verwendet. Nur genutzt wenn `includeTimestamp` gesetzt ist.

### LGF_typeDiagnostics (UDT / V1.0.1)

Diagnosestruktur zur Speicherung und Übertragung von Diagnoseinformationen von Blöcken über die Schnittstelle.

Bezeichner | Datentyp | Default Wert | Beschreibung
--- | --- | --- | ---
status | Word | 16#0000 | Status des Bausteins oder Fehleridentifikation beim Auftreten des Fehlers
subfunctionStatus | Word | 16#0000 | Status oder Rückgabewert von aufgerufenen FB's, FC's und Systembausteinen
stateNumber | DInt | 0 | Zustand in der Zustandsmaschine des Blocks, in dem der Fehler aufgetreten ist

## Funktionsbeschreibung

### Alle Befehle:

Der Dateiname muss immer vollumfänglich zusammen mit dem Ordner Namen und der Datei Erweiterung in folgendem Format angegeben werden: `UserFiles/test.dat`

### Zeit Stempel

Zeitstempel werden für Befehle, einen Fehler und die Datei geschrieben, sie werden in der Variablen `Timestamps` gespeichert. Im Falle eines Fehlers werden die Zeitstempel der einzelnen Befehle nicht geschrieben, der Zeitstempel der Datei wird auf den Standardwert `DTL#1970-01-01-00:00:00` zurückgesetzt.

### Datei Lesen - Befehl `executeRead`

Mit dem Befehl `executeRead` kann eine Datei in den Datenhaushalt einer Variable an `data` eingelesen werden. Zum Lesen der Daten ist es notwendig diese zu deserialisieren, was die Funktion dem Anwender bereits abnimmt.
Zum Deserialisieren muss dafür ein externer Puffer in Form eines Byte Arrays verschaltet werden, der die Datenmenge aufnehmen kann, ist der Puffer zu klein wird ein Fehler ausgegeben.

### Datei Löschen - Befehl `executeDelete`

Mit dem Befehl `executeDelete` kann eine Datei von der SIMATIC Memory Card (SMC) gelöscht werden.

### Datei Schreiben - Befehl `executeWrite`

Mit dem Befehl `executeWrite` kann der Datenhaushalt einer Variable an `data` in eine Datei geschrieben werden. Zum Schreiben der Daten ist es notwendig diese zu serialisieren, was die Funktion dem Anwender bereits abnimmt.
Zum Serialisieren muss dafür ein externer Puffer in Form eines Byte Arrays verschaltet werden, der die Datenmenge aufnehmen kann, ist der Puffer zu klein wird ein Fehler ausgegeben.

Hinweis
  Die Datei Erweiterung (hier z.B. `dat`) kann frei gewählt werden oder auch entfallen, sie ist für eine externe Weiterverarbeitung von Nutzen, um dem Anwender das Format der Datei anzuzeigen.
  Eine Dateiendung im Dateinamen hat keinerlei Einfluss auf den Inhalt der Datei sowie dessen Formatierung, die Daten in einem entsprechenden Dateiformat bereitzustellen obliegt dem Anwender.

Warnung
  Die SMC (SIMATIC Memory Card) ist ein Flash Speicher mit endlichen Schreibzyklen.
  Ein hochfrequenter Schreibzugriff wirkt sich deshalb auch auf die Lebensdauer der SMC aus!

## Änderungshistorie

Version & Datum | Änderungsbeschreibung
--- | ---
| 1.0.0 | Simatic Systems Support
| 10.07.2025 | First released version