CSV Datei

Mit diesem Funktionsbaustein werden Messwerte in eine CSV Datei aufgezeichnet. Die Datei liegt im Projektverzeichnis der Steuerung und kann automatisch per Email versendet werden.

Der Baustein zeichnet nicht von sich aus auf. Eine Zeile wird nur geschrieben, wenn der Eingang TR von 0 auf einen Wert ungleich 0 wechselt. Den Zeitpunkt bestimmt also das Programm, zum Beispiel ein Taktgeber oder eine Uhr. In die Zeile kommen die Werte, die in diesem Moment an den Eingängen anliegen; es wird nicht gemittelt und es wird auch nichts nachgeholt, wenn ein Trigger ausbleibt. Damit alle Werte einer Zeile zusammenpassen, wird die Zeile erst rund eine halbe Sekunde nach der Flanke geschrieben. In dieser Zeit dürfen sich die Eingänge noch ändern, sie werden dann mit ihrem letzten Wert aufgezeichnet. Zwei Trigger sollten deshalb mindestens eine Sekunde auseinanderliegen.

Die Datei wird für jede Zeile geöffnet, ergänzt und wieder geschlossen. Es wird nichts zwischengespeichert, eine Zeile steht also unmittelbar nach dem Trigger auf dem Datenträger. Ein Stromausfall kostet dadurch höchstens die Zeile, die gerade geschrieben wird. Der Preis dafür ist, dass jede Zeile ein eigener Schreibvorgang auf der Speicherkarte ist. Wie oft aufgezeichnet wird, entscheidet daher über die Lebensdauer der Karte, siehe Speicherbedarf und Schreibzugriffe.

Die Datei wächst unbegrenzt weiter, sie wird weder automatisch begrenzt noch gelöscht. Um das zu steuern, gibt es zwei Wege: die Rotation über den Eingang RO oder einen Dateinamen mit Platzhaltern für das Datum, der zum Beispiel für jeden Monat eine neue Datei anlegt. Ohne eine dieser Massnahmen läuft der Datenträger irgendwann voll - danach schlägt nicht nur die Aufzeichnung fehl, sondern auch das Einspielen von Projekten und das Anlegen der Sicherungen.

Der Baustein ist für Zählerstände, Verbrauchswerte und ähnliche Aufzeichnungen im Minuten- bis Stundenraster gedacht, deren Ergebnis als fertige Datei gebraucht wird. Sollen Werte in kurzem Abstand über lange Zeiträume mitgeschrieben und in der Visualisierung als Diagramm dargestellt werden, ist die Statistik besser geeignet.

Wichtig: Siehe Hinweise bei Verwendung der Zählerbausteine.

Eingänge
TR	Trigger	Mit positiver Flanke am Eingang wird eine neue Zeile in die CSV Datei geschrieben.
RO	Rotation	Mit positiver Flanke am Eingang wird mit einer neuen Datei begonnen. Die aktuelle Datei wird in "dateiname.csv.0", ".1" usw. umbenannt.
01, 02 ...	Eingang 1, 2 ...	Die aufzuzeichnenden Werte. Jeder Eingang ergibt eine Spalte, die Reihenfolge der Spalten ist die Reihenfolge der Eingänge. Die Anzahl wird mit dem Parameter "Anzahl Eingänge" eingestellt.
Parameter
	Anzahl Eingänge	Anzahl der Eingänge und damit der Wertespalten, 1 bis 126.
	Dateiname	Dateiname unter dem die Daten gespeichert werden. Beim Anlegen des Bausteins wird ein eindeutiger Name vorgegeben, dieser sollte durch einen sprechenden Namen ersetzt werden. Der Dateiname kann Platzhalter für das Datum enthalten, siehe unten. Damit legt zum Beispiel "verbrauch_%Y_%m.csv" für jeden Monat eine eigene Datei an. Die Datei wird immer im Projektverzeichnis abgelegt, eine Pfadangabe ist nicht möglich. Die Zeichen / \ : * ? " < > \| sind in einem Dateinamen nicht zulässig und werden durch einen Unterstrich ersetzt. Hinweis: Enthält der Dateiname Platzhalter, wird beim Emailversand die Datei angehängt, auf die das Muster zum Zeitpunkt des Versands zutrifft. Wechselt die Datei genau dann, wenn auch versendet wird - zum Beispiel eine Monatsdatei bei monatlichem Versand -, ist bei "Anhang umbenennen Offset Zeit" ein negativer Offset einzustellen, damit noch die Datei des abgelaufenen Zeitraums versendet wird.
	Rotation	Anzahl der Rotationen. Mit positiver Flanke am Eingang RO wird die Datei in "dateiname.csv.0", ".1" usw. umbenannt, ist die maximale Anzahl erreicht, wird die älteste gelöscht. Mit der nächsten Zeile beginnt eine neue Datei, die wieder mit den Spaltenüberschriften anfängt. Auf dem Datenträger liegt damit eine Datei mehr als hier eingestellt ist, das ist beim Speicherbedarf zu berücksichtigen.
Spalten: Die Spalten stehen immer in dieser Reihenfolge: Kommentar, Datum, Zeit, danach die Werte der Eingänge. Jede Spalte wird mit einem Semikolon abgeschlossen, eine Zeile endet daher ebenfalls mit einem Semikolon.
	Kommentar	Mit dieser Option wird als erste Spalte der Text aus der allgemeinen Option Kommentar eingefügt. Dies kann beispielsweise verwendet werden um eine Zählernummer als Spalte einzufügen.
	Spalte Datum	Spalte mit aktuellem Datum einfügen, im Format TT.MM.JJJJ.
	Spalte Zeit	Spalte mit aktueller Zeit einfügen, im Format HH:MM:SS.
	Spaltenüberschriften	Hier können Spaltenüberschriften definiert werden. Trennzeichen ist Semikolon ";". Die Überschriften werden nur in eine neue, noch leere Datei geschrieben. Wird die Anzahl der Eingänge später geändert, passen die Überschriften einer bereits vorhandenen Datei nicht mehr - in diesem Fall die Datei löschen oder über den Eingang RO eine neue beginnen.
	Formatierung	Zahlenformat der Wertespalten, siehe auch Zahlenformatierungen. Mit "%d" wird ohne Nachkommastellen aufgezeichnet, der Wert wird dabei abgeschnitten und nicht gerundet. Die Vorgabe "%f" schreibt immer sechs Nachkommastellen und braucht dadurch unnötig viel Platz, für Zählerstände sind meist "%.2f" oder "%.3f" die bessere Wahl.
	Kommazeichen	Dezimaltrennzeichen der Wertespalten, Komma oder Punkt. Für die Weiterverarbeitung in einer deutschsprachigen Tabellenkalkulation ist das Komma richtig.
Emailversand: Die CSV Datei kann via Email versendet werden, hierzu können einige häufig verwendete Zeitpunkte ausgewählt werden. Soll die Datei zu einem speziellen Zeitpunkt versendet werden, kann dies auch mit dem Funktionsbaustein Mailversand realisiert werden. Die weiteren Felder werden erst angezeigt, wenn ein Zeitpunkt ausgewählt ist. Versendet wird immer die gesamte Datei. Der Versand löscht die Datei nicht und beginnt auch keine neue - ohne Rotation enthält jede Email also auch alle früheren Zeilen. Soll eine Email nur den neuen Zeitraum enthalten, ist kurz nach dem Versand eine Flanke am Eingang RO zu geben.
	Zeitpunkt	Zeitpunkt des Versands: Keine Email, Minute, Stündlich (zu jeder vollen Stunde), Täglich (um 0:00h), Wöchentlich (Montag um 0:00h) oder Monatlich (am Monatsersten um 0:00h).
	Adresse	Email Adresse
	Betreff	Betreff
	Text	Email Text
	Wartezeit	Wartezeit für den Emailversand in Sekunden. Wird beispielsweise als Zeitpunkt Tag gewählt, erfolgt der Versand um 0:00h plus dieser Zeit. Dies ist beispielsweise dann sinnvoll, wenn um 0:00h noch eine Zeile aufgezeichnet werden soll.
	Anhang umbenennen	Mit dieser Option kann die Datei umbenannt werden. Beispielsweise um ein Datum anzuhängen. Beispiel: log_%d_%m_%Y.csv wird in log_10_11_2023.csv umbenannt. Zum Umbenennen wird eine Kopie der Datei erzeugt, die nach dem Senden wieder gelöscht wird. Die CSV Datei selbst bleibt erhalten. Ergibt das Muster den originalen Dateinamen, wird die CSV Datei direkt angehängt.
	Anhang umbenennen Offset Zeit	Zeit Offset in Sekunden für das Umbenennen der Datei. Beispielsweise -3600 bedeutet minus 1 Stunde. Damit trägt eine Datei, die um 0:00h versendet wird, das Datum des abgelaufenen Tages. Der Offset gilt auch für Platzhalter im Dateinamen selbst: enthält dieser ein Datum, wird die Datei des um den Offset zurückliegenden Zeitpunkts versendet.

Folgende Platzhalter sind für den Dateinamen und für das Umbenennen des Anhangs verfügbar:

%a	Abgekürzter Name des Wochentags	Sun
%A	Vollständiger Name des Wochentags	Sunday
%b	Abgekürzter Monatsname	Mar
%B	Vollständiger Monatsname	March
%c	Zeit+Datum	Sun Aug 19 02:56:02 2012
%d	Tag des Monats (01-31)	19
%H	Stunde im 24-Stunden-Format (00-23)	14
%I	Stunde im 12h-Format (01-12)	05
%j	Tag des Jahres (001-366)	231
%m	Monat als Dezimalzahl (01-12)	08
%M	Minute (00-59)	55
%p	Bezeichnung AM (0-12) oder PM (12-0)	PM
%S	Sekunde (00-61)	02
%U	Wochennummer mit dem ersten Sonntag als erstem Tag der ersten Woche (00-53)	33
%w	Wochentag als Dezimalzahl mit Sonntag als 0 (0-6)	4
%W	Wochennummer mit dem ersten Montag als erstem Tag der ersten Woche (00-53)	34
%x	Datum	08/19/12
%X	Zeit	02:50:06
%y	Jahr, letzte zwei Ziffern (00-99)	01
%Y	Jahr	2012
%Z	Name oder Abkürzung der Zeitzone	CDT
%%	Prozent Zeichen	%

Speicherbedarf und Schreibzugriffe

Die CSV Datei liegt auf demselben Datenträger wie das Projekt, bei den meisten Steuerungen ist das eine Speicherkarte. Sie unterliegt damit zwei Einschränkungen: dem freien Platz und der begrenzten Anzahl an Schreibvorgängen, die eine Speicherkarte verträgt. Beides sollte vor der Inbetriebnahme überschlagen werden, weil eine Aufzeichnung meist über Jahre läuft.

Platzbedarf: Eine Zeile besteht aus reinem Text. Datum und Zeit brauchen zusammen rund 20 Zeichen, jeder Wert je nach Formatierung etwa 6 bis 12 Zeichen. Als grober Anhaltspunkt können 30 Byte für eine Zeile mit einem Wert und rund 110 Byte für eine Zeile mit zehn Werten angenommen werden. Daraus ergibt sich:

Aufzeichnung	Zeilen pro Tag	pro Tag	pro Jahr
stündlich, 1 Wert	24	unter 1 KB	rund 0,3 MB
jede Minute, 1 Wert	1.440	rund 42 KB	rund 16 MB
jede Minute, 10 Werte	1.440	rund 155 KB	rund 55 MB
alle 10 Sekunden, 10 Werte	8.640	rund 0,9 MB	rund 330 MB
jede Sekunde, 10 Werte	86.400	rund 9 MB	rund 3,4 GB

Wird die Rotation verwendet, vervielfacht sich der Bedarf entsprechend der eingestellten Anzahl. Mehrere Bausteine addieren sich, ebenso die Aufzeichnungen der Statistik.

Schreibzugriffe: Für jede Zeile wird die Datei geöffnet, der Text angehängt, die Datei geschlossen und der Schreibvorgang sofort auf den Datenträger gezwungen. Eine Speicherkarte schreibt dabei nie nur die wenigen Byte der Zeile, sondern immer einen ganzen Block, und sie muss zusätzlich die Verwaltungsdaten der Datei aktualisieren. Eine Zeile von 30 Byte kostet also ein Vielfaches davon an tatsächlicher Schreiblast. Für die Lebensdauer der Karte ist deshalb nicht die Grösse der Datei entscheidend, sondern die Anzahl der Trigger.

Praktische Empfehlungen:

Nicht schneller aufzeichnen als nötig. Für Zählerstände und Verbräuche reicht meist ein Wert je Viertelstunde oder je Stunde. Ein Trigger im Sekundentakt ist für diesen Baustein nicht vorgesehen.
Lieber wenige Bausteine mit vielen Eingängen als viele Bausteine mit je einem Eingang: jeder Baustein schreibt in seine eigene Datei und verursacht eigene Schreibzugriffe.
Die Formatierung so knapp wählen wie möglich. "%.2f" statt der Vorgabe "%f" spart bei zehn Werten je Zeile rund die Hälfte des Platzes.
Über die Rotation oder einen Dateinamen mit Datum dafür sorgen, dass die Dateien nicht unbegrenzt wachsen. Sehr grosse Dateien lassen sich weder bequem versenden noch in einer Tabellenkalkulation öffnen, die gängigen Programme zeigen rund eine Million Zeilen an.
Auf dem Datenträger immer ausreichend freien Platz lassen. Ist er voll, schlägt nicht nur die Aufzeichnung fehl - auch das Einspielen eines Projekts und das automatische Anlegen der Sicherungen ist dann nicht mehr möglich.
Für viele Werte in kurzem Abstand die Statistik verwenden. Sie sammelt die Werte in einer Datenbank, schreibt deutlich seltener auf den Datenträger und kann die Daten direkt in der Visualisierung als Diagramm darstellen.
Werden dauerhaft viele Daten aufgezeichnet, ist eine Speicherkarte für den Dauereinsatz zu verwenden und in die regelmässige Datensicherung einzubeziehen.

Tritt beim Schreiben ein Fehler auf, zum Beispiel weil der Datenträger voll oder schreibgeschützt ist, wird dies im Protokoll der Steuerung vermerkt. Der Baustein selbst hat keinen Ausgang, der einen solchen Fehler meldet.

Wichtig: Siehe Hinweise bei Verwendung der Zählerbausteine.

Siehe auch allgemeine Parameter aller Funktionsbausteine.