pdr Konfiguration | Index | pdr Interaktiver Betrieb

## pdr Referenz

Momentan stehen folgende Typen von Datenquellen zur Verfügung:

Kommandozeile e-mail-Postfächer Twitter Textdateien | diese vier Datenquellen arbeiten mit Ausdrücken
CSV-Dateien XML-Dateien | diese beiden Datenquellen arbeiten mit verschiedenen, spezifischen Datenformaten

### Eingabe per Kommandozeile

Die einfachste (und zugleich unkomfortabelste) Eingabemöglichkeit ist die Kommandozeile, d.h. der Aufruf von pdr selbst. Hierzu muß nichts speziell konfiguriert werden.
pdr besitzt den Kommandozeilenparameter -e bzw. --expression, der die Angabe genau eines Ausdrucks erlaubt. Dieser Parameter ist mehrfach verwendbar. Ferner werden alle hinter pdr eingegebenen Zeichen, die nicht Teil oder Argument eines Kommandozeilenparameters sind, zu einem Ausdruck zusammengefaßt und gemeinsam ausgewertet (siehe dort).
Besitzt der angegebene Ausdruck keinen Zeitstempel werden die aktuellen Werte für Datum und Uhrzeit benutzt.
Tritt bei der Verarbeitung ein Fehler auf, weil der Ausdruck nicht korrekt war, so gibt pdr eine Meldung aus. Eine Übernahme des Ausdrucks in die rejections erfolgt nicht.

### Eingabe per Mail (POP3 und IMAP)

Bei der Abfrage von e-mail-Postfächern wird davon ausgegangen, daß der Benutzer anfallende Daten mit einem anderen Programm oder einem Mobiltelefon an ein e-mail-Postfach sendet und diese dort liegenbleiben (d.h. nicht anderweitig abgeholt werden). Diese e-mails müssen folgende Eigenschaften aufweisen:

1. ein eindeutiges subject
2. einen verwertbaren Zeitstempel (dafür sorgt normalerweise der SMTP-Server beim Senden)
3. reines, zusammenhängendes Text-Format (kein HTML, RTF o.ä.)
4. Text ausschließlich in Ausdrücken

Ist für pdr eine e-mail-Datenquelle konfiguriert, so wird sie beim nächsten Aufruf automatisch abgefragt. pdr schaut dann nach, ob sich mails im Postfach befinden, prüft deren subject und wertet passende e-mails der Reihe nach aus, wobei jede Zeile als jeweils ein Ausdruck interpretiert wird. Besitzt eine Zeile einen eigenen Zeitstempel, so besitzt dieser Priorität, ansonsten gilt für alle Zeilen implizit der Zeitstempel der e-mail-Nachricht. Das ist insofern praktisch, weil man üblicherweise in einzeiligen e-mails nie einen Zeitstempel manuell eingeben muß.
Hier einmal ein vollständiger e-mail-Quelltext:
From: superhero <MyMail@gmx.net>
To: MyMail@gmx.net
Subject: Q
Date: Thu, 04 Feb 2010 17:56:11 +0100
Message-ID: <87pr4ley8k.fsf@castor.ch>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
5.3 8i
Die meisten Werte in den Headerzeilen kann man in der Regel aus default-Einstellungen entnehmen. Date und Message-ID setzt der Server hinzu, MIME-Version und Content-Type stammen vom verwendeten e-mail-Client. Die einzigen Texte, die man wirklich tippen muß, sind das subject (es empfiehlt sich darum, das subject so kurz wie möglich zu vereinbaren, hier der einzelne Buchstabe Q) sowie der Inhalt der Nachricht (letzte Zeile).
Auf POP3-Servern werden verarbeitete e-mails anschließend unabhängig vom Erfolg der Verarbeitung automatisch gelöscht, so daß sie später nicht ein zweites Mal verarbeitet werden. Dieses automatische Löschen kann bei der Konfiguration der Datenquelle unterbunden werden. Für IMAP-Server kann konfigurert werden, ob pdr die mails nach der Verarbeitung löschen oder als gelesen markieren soll. Letzteres ist praktisch, wenn man die verarbeiteten mails auf dem Server noch archivieren will.
Tritt bei der Verarbeitung ein Fehler auf, weil ein Ausdruck nicht korrekt war o.ä., so gelangen die betreffenden Ausdrücke in die rejections und müssen nachbearbeitet werden. pdr gibt in diesem Falle eine Meldung aus.

### Eingabe per Twitter

Es ist vielleicht der eleganteste Weg zur Dateneingabe, einen dafür eingerichteten Twitter-Account zu benutzen. Für Twitter existiert auf fast jeder Plattform ein geeignetes Frontend, insbesondere auf Mobiltelefonen, so daß die Dateneingabe sehr einfach wird. Twitter vergibt die notwendigen Zeitstempel automatisch, der Benutzer muß nichts weiter als seine expressions eingeben.
pdr holt jeweils diejenigen Daten aus dem feed, die jünger sind als der Zeitpunkt, als der feed das letzte Mal abgefragt wurde. Hat pdr den feed noch nie abgefragt, so werden alle Daten aus dem feed geholt, die jünger als der jüngste Datenwert in der Datenbank sind.
Tritt bei der Verarbeitung ein Fehler auf, weil ein Ausdruck nicht korrekt war o.ä., so gelangen die betreffenden Ausdrücke in die rejections und müssen nachbearbeitet werden. pdr gibt in diesem Falle eine Meldung aus.

#### Hinweise

- Es ist ratsam, den Twitter-Account zu schützen, einerseits um die Daten nicht öffentlich zu machen, andererseits um Störungen des feeds durch Kommentare zu vermeiden. Diese Option ist im Twitter-Benutzeraccount unter Einstellungen, Konto, unten "Tweetsicherheit [x] Schütze meine Tweets" zu machen.
- Ein geschützter Twitter-Account macht eine Authentifizierung nötig. Diese Authentifizierung erfolgt, wenn pdr zum ersten Mal auf einen Twitter-Account zugreift. Dabei werden zwei private Schlüssel beschafft und lokal abgelegt, so daß die Authentifizierung beim nächsten Mal nicht noch einmal ausgeführt werden muß.
- Leider erfordert Twitter die Authentifizierung mit einem interaktiven Schritt: der Benutzer bekommt in seinem Webbrowser eine Twitter-eigene Webseite präsentiert, auf der er mindestens einen Button drücken muß. Dann erscheint eine siebenstellige Nummer, eine PIN, die er in pdr eintippen muß. Aus diesem Grunde ist im Moment des ersten Zugriffs auf einen Twitter-Account die Angabe eines Browsers nötig (Kommandozeilenparameter --browser).
- Wenn die Authentifizierung erfolgreich abgeschlossen wurde, verhält sich eine Twitter-Datenquelle wie jede andere.

### Eingabe über Textdateien

Bei der Verwendung von Textdateien zur Eingabe wird jede Zeile als Ausdruck interpretiert. Dieses Verfahren ist nützlich, wenn man über einen gewissen Zeitraum Daten sammeln, aber nicht online übermitteln kann. Man schreibt die Ausdrücke einfach mit einem Editor Ausdruck für Ausdruck, d.h. Zeile für Zeile in eine Textdatei.
Zeilen, die innerhalb solcher Textdateien mit # beginnen, werden nicht ausgewertet.
Tritt bei der Verarbeitung ein Fehler auf, bleibt die gesamte Datei unverarbeitet. Eine Übernahme in die rejections erfolgt nicht.
Erfolgreich verarbeitete Textdateien werden, sofern sie in der Konfigurationsdatei als Datenquelle angegeben sind, automatisch gelöscht, damit sie nicht ein zweites Mal verarbeitet werden. Dieses Löschen kann bei der Konfiguration unterbunden werden.

### Eingabe über CSV-Dateien

Die Abkürzung CSV steht für "comma separated values", durch Komma getrennte Werte. Das Komma ist nicht ganz wörtlich zu nehmen, pdr akzeptiert das Komma, das Semikolon und den Tabulator als Separator zwischen den Werten.
Es gibt zwei Möglichkeiten, pdr mitzuteilen, welcher kommaseparierter Datenwert in welche collection gelangen soll:

1. über eine Steuerzeile in der CSV-Datei, die den Datenzeilen vorangeht
2. über eine Steuerzeile in der Konfigurationsdatei, die für die gesamte CSV-Datei gilt

Im ersten Fall besitzt eine von pdr verwendbare CSV-Datei folgende Struktur:
Steuerzeile
Datenzeile1
[...]
DatenzeileN
Steuerzeile
Datenzeile1
[...]
DatenzeileN
[...]
Diese Art der Verwendung von Steuerzeilen ist ungewöhnlich, liefert aber die gewünschte Flexibilität und Offenheit. In der Regel kann man sie sehr leicht einfügen, entweder von Hand oder über ein Programm wie sed. Im zweiten Fall enthielte die CSV-Datei wie erwartet nur Datenzeilen.
Eine Steuerzeile hat folgenden Aufbau:
[# pdr] datetime [Separator collection]+
z.B.
# pdr datetime, *, n, l; h; q»p, # (» soll ein Tabulator sein)
Dies ist eine Steuerzeile für nachfolgende Datenzeilen mit jeweils einem Zeitstempel und sieben weiteren Werten für die collections *, n, l, h, q, p und #.
Jede Steuerzeile wird innerhalb einer CSV-Datei an ihrer Einleitung # pdr erkannt, bei Angabe der Steuerzeile in der Konfigurationsdatei ist diese Kennung nicht erforderlich. Das folgende Schlüsselwort datetime kennzeichnet die Lage des Zeitstempels auf den Datenzeilen. Es muß nicht am Anfang stehen, jedoch auf jeder Zeile enthalten sein - Datenwerte ohne Zeitstempel sind nicht denkbar. Im Beispiel ist zu sehen, daß verschiedene Separatoren innerhalb einer Zeile benutzt werden können. Datenzeilen, die zu dieser Steuerzeile passen, hätten damit folgendes Aussehen:
2008-10-11 12:31:38, 5.2, 7, 8; 42.3; 12»96, erste Messung
2008-10-12 12:48:08, 6.1, , 8; 53.1; 16»93,
2008-10-13 12:43:57, 5.8, 7, 7; 34.2; 15»94, dritte Messung
In der zweiten Zeile fehlen Werte für die collections n und # - im Fall fehlender Werte erfolgen einfach keine Eingaben.
Besitzt man CSV-Dateien, die mehr Werte enthalten, als man in collections importieren will, so kann man auf der Steuerzeile Auslassungen vereinbaren:
# pdr datetime, a, b, , , , c, d, e
Hier werden hinter dem Zeitstempel zwei collections gelesen, dann jeweils drei Datenwerte auf den Datenzeilen ausgelassen, und dann die restlichen drei collections gelesen.
Zeilen, die innerhalb von CSV-Dateien mit dem Symbol # beginnen, werden als Kommentar betrachtet und nicht weiter ausgewertet.
Beim Einfügen von Werten in die Datenbank wird eine gesamte CSV-Datei in einer einzigen Transaktion behandelt. Wenn dabei ein Fehler auftritt, beispielsweise weil ein Datenwert nicht zum Typ der in der Steuerzeile vereinbarten collection paßt, so wird die gesamte Datei verworfen. Es kann nicht passieren, daß eine Datei zur Hälfte eingelesen wird und zur anderen Hälfte nicht und man hinterher gar keine rechte Kontrolle mehr darüber hat. Eine Übernahme in die rejections erfolgt nicht.
Erfolgreich verarbeitete CSV-Dateien werden, sofern sie in der Konfigurationsdatei als Datenquelle angegeben sind, automatisch gelöscht, damit sie nicht ein zweites Mal verarbeitet werden. Dieses Löschen kann bei der Konfiguration unterbunden werden.

### Eingabe über XML-Dateien

pdr bietet die Möglichkeit, XML-Dateien einzulesen. Diese Dateien sind wohlstrukturiert, les- und editierbar, und sind damit ideal zum Austausch von Daten zwischen verschiedenen Softwaresystemen geeignet. pdr definiert zunächst ein eigenes, absichtlich sehr einfaches Format. Der entsprechende Programmteil ist aber dafür ausgelegt, nach entsprechender Erweiterung auch andere XML-Formate zu lesen.

#### Das pdr-XML-Format

Das Format ist vollständig abgelegt in der Datei pdr.xsd:
`<?xml version="1.0" encoding="iso-8859-1" ?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" >
<xsd:annotation>
<xsd:documentation xml:lang="en">
pdr XML input file definition (C) T.M. Bremgarten 2010-01-31
</xsd:documentation>
</xsd:annotation>
<xsd:element name="pdr">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="collection" type="collection" minOccurs="0" maxOccurs="unbounded" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:complexType name="collection">
<xsd:sequence>
<xsd:element name="item" minOccurs="0" maxOccurs="unbounded">
<xsd:complexType>
<xsd:attribute name="datetime" type="xs:string" />
<xsd:attribute name="value" type="xs:string" />
</xsd:complexType>
</xsd:element>
</xsd:sequence>
<xsd:attribute name="name" type="xs:string" use="required" />
<xsd:attribute name="type" type="collection_type" use="required" />
<xsd:attribute name="purpose" type="xs:string" />
</xsd:complexType>
</xsd:schema>
`
Diese Definition erlaubt Dateien, die folgendes Aussehen haben:
`<?xml version="1.0" encoding="ISO-8859-1"?>
<pdr>
<collection name="#" type="text">
<item datetime="2001-07-09 18:27:11" value="erste Messung"/>
<item date` `time``="2001-``07``-10 07:52:01" value="zweite Messung"/>
<item date` `time``="2001-``07``-10 10:07:00" value="dritte Messung"/>
[...]
</collection>
<collection name="*" type="numeric">
<item date` `time``="2001-``07``-12 13:57:01" value="9.3"/>
<item date` `time``="2001-``07``-12 14:46:45" value="5.6"/>
<item date` `time``="2001-``07``-12 18:25:36" value="5.7"/>
[...]
</collection>
<collection name="l" type="numeric">
<item date` `time``="2001-``07``-03 21:41:58" value="7"/>
<item date` `time``="2001-``07``-04 21:48:43" value="8"/>
<item date` `time``="2001-``07``-05 21:50:49" value="7"/>
[...]
</collection>
</pdr>
`
Das Format ist beinahe selbsterklärend. Die Daten der collections werden direkt lesbar angegeben und genau so eingelesen.
Beim Einfügen von Werten in die Datenbank wird eine gesamte XML-Datei in einer einzigen Transaktion behandelt. Wenn dabei ein Fehler auftritt, beispielsweise weil ein Datenwert nicht zum Typ der angegebenen collection paßt, so wird die gesamte Datei verworfen. Es kann nicht passieren, daß eine Datei zur Hälfte eingelesen wird und zur anderen Hälfte nicht und man hinterher gar keine rechte Kontrolle mehr darüber hat. Eine Übernahme in die rejections erfolgt nicht.
Erfolgreich verarbeitete XML-Dateien werden, sofern sie in der Konfigurationsdatei als Datenquelle angegeben sind, automatisch gelöscht, damit sie nicht ein zweites Mal verarbeitet werden. Dieses Löschen kann bei der Konfiguration unterbunden werden.

#### (weitere XML-Formate)

...

pdr Konfiguration | Index | pdr Interaktiver Betrieb