# LGF_FileWrite (FB / 1.1.0)

Übersicht

Autor: Siemens SIMATIC Systems Support

## Kurzbeschreibung

Dieser Funktionsbaustein bietet die Möglichkeit, Daten als binären / serialisierten Datenstrom in eine Datei zu schreiben, die dann auf der Speicherkarte der SPS im Ordner `UserFiles` abgelegt wird.

### Baustein Schnittstelle

| LGF_FileWrite (FB) |
--- | --- | ---
Bool |  |  | execute |  | done |  |  | Bool
Bool |  |  | clearBufferBefore |  | busy |  |  | Bool
String |  |  | fileName |  | error |  |  | Bool
|  |  |  |  | status |  |  | Word
|  |  |  |  | dataLength |  |  | DInt
|  |  |  |  | diagnostics |  |  | LGF_typeDiagnostics
Array[*] of Byte |  |  | bufferByteArray |  |  | Array[*] of Byte
Variant |  |  | data |  |  | Variant

### Input Parameter

Bezeichner | Datentyp | Default Wert | Beschreibung
--- | --- | --- | ---
execute | Bool | FALSE | Steigende Flanke startet einmaliges Schreiben der Datei
clearBufferBefore | Bool | FALSE | TRUE: Der Puffer wird vor dem Schreiben der Daten mit 16#00 Byte gelöscht
fileName | String | '' | Name der Datei inklusiv Pfad: `UserFiles/test.dat`

### 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 in die Datei geschrieben wurde (Serialisierte Länge von `data`)
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 zum Schreiben in Datei

### 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 der Puffermatrix 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#8401 | ERR_FILE_PATH Fehler: Dateipfad Fehler: der Dateipfad muss mit 'UserFiles/' beginnen.
16#8600 | ERR_UNDEFINED_STATE Fehler aufgrund eines undefinierten Zustands im Zustandsautomaten
16#8601 | ERR_MOVE_BLK_VARIANT Fehler: Blockvariante verschieben (Daten in Puffer) - siehe `diagnostics.subFunctionStatus`
16#8603 | ERR_DATA_SERIALIZE Fehler: Daten Serialisieren - siehe `diagnostics.subFunctionStatus`
16#8604 | ERR_FILE_WRITE_INIT Fehler: Datei auf die SMC schreiben - siehe `diagnostics.subFunctionStatus`
16#8605 | ERR_FILE_WRITE Fehler: Datei auf SMC schreiben - siehe `diagnostics.subFunctionStatus`

## Benutzer definierte Datentypen

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

Mit der Funktion `LGF_FileWrite` 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.

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

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
| 19.02.2023 | First released version
| 1.1.0 | Simatic Systems Support
| 29.04.2025 | Insert parameter `clearBufferBefore` to clear buffer befor serializing the data