cpdx Konfiguration | Index | pdx Interaktiver Betrieb

## pdx Referenz

### Erzeugung von Berichten und Diagrammen

Berichte entstehen aus Textvorlagen. pdx sucht innerhalb einer solchen Vorlage nach einem gekennzeichneten Abschnitt mit Funktionsaufrufen, meist einer format-Funktion. Dieser Abschnitt wird dann aus der Vorlage herausgeschnitten, ausgewertet und durch das Ergebnis ersetzt. In einer Vorlage können beliebig viele Abschnitte mit Funktionsaufrufen angeordnet werden.
Textvorlagen sind entweder einfacher ASCII-Text oder Text in einer Formatierungssprache wie HTML oder XML bzw. einer Programmiersprache wie C oder SQL, im Sinne dieser Abhandlung eine Wirtssprache. Worum es sich dabei konkret handelt, soll absichtlich in keiner Weise eingeschränkt werden. pdx muß aber wissen, woran die Abschnitte mit den Funktionsaufrufen zu erkennen sind. Deshalb werden solche Abschnitte generell in Kommentaren der jeweiligen Wirtssprache angeordnet, in HTML oder XML also zwischen <!-- und -->, in C hingegen zwischen /* und */. Dabei bleibt die Vorlage eine unvollständige, aber korrekte Datei ihres Typs, was den Vorteil hat, daß man sie nach wie vor mit Werkzeugen (z.B. HTML-Editoren) bearbeiten kann. Es ist klug, diese pdx-Kommentarblöcke noch weiter zu kennzeichnen, um sie von bereits existierenden, echten Kommentaren zu unterscheiden. Man verwende also klugerweise z.B. <!--- und ---> oder /** und **/. Eine vollständige, kleine Vorlage für eine HTML-Datei mit pdx-Anweisungen würde also beispielsweise wie folgt aussehen:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html lang="de-ch">
<head>
<meta http-equiv="CONTENT-TYPE" content="text/html; charset=iso-8859-1">
<title>MyTitle</title>
</head>
<body style="direction: ltr;" lang="de-DE">
<!--- (now) --->, <b>pdx</b> <!--- (version) ---> (<!--- (build) --->) *
</body>
</html>
In der mit * markierten Zeile stehen drei pdx-Abschnitte, in denen je eine der Funktionen now, version und build aufgerufen wird. Die Ausgabe, die diese Zeile erzeugt, sieht ungefähr so aus:
2009-12-27 15:14:51, pdx 0.3.0 (2009-12-27 10:28:14 on castor, GNU/Linux 2.6.31-ARCH x86_64)
Man sieht, daß alle Bestandteile der Zeile, die nicht innerhalb pdx-Abschnitten stehen, (sowie auch der gesamte umgebende Text) unverändert in die Ausgabe übernommen werden. Diese Zeile hätte übrigens unter Benutzung der format-Funktion auch anders formuliert werden können:
<!--- (format (now) ", <b>pdx</b> " (version) " (" (build) ")") --->
Um nun in HTML eine komplette Tabelle anzuordnen, würde man beispielsweise wie folgt vorgehen:
[...]
<table style="page-break-before: always; page-break-inside: avoid;
width: 800px;" border="1" cellpadding="1" cellspacing="1">
<tbody>
<tr valign="top">
<td>Datum/Zeit</td>
<td>*</td>
<td>n</td>
<td>l</td>
<td>m</td>
<td>x</td>
<td>Kommentar</td>
</tr>
<!---
(format
(empty "<br>")
"<tr valign=top>"
"<td>" datetime "</td>"
"<td>" (select "*" (days 7)) <1.1> "</td>"
"<td>" (select "n" (days 7)) <1> "</td>"
"<td>" (select "l" (days 7)) <1> "</td>"
"<td>" (select "m" (days 7)) <1.0> "</td>"
"<td>" (select "x" (days 7)) <1.1> "</td>"
"<td>" (select "#" (days 7)) "</td>"
"</tr>" newline
)
--->
</tbody>
</table>
[...]
Die Tabelle beginnt außerhalb des pdx-Abschnitts und endet wiederum außerhalb. Die Zeilen der Tabelle mit Ausnahme der Kopfzeile werden aber vollständig von pdx generiert. Diese Zeilen besitzen alle das gleiche Aussehen.
Diagramme entstehen aus Diagrammdefinitionsdateien. Diese enthalten immer genau eine Diagrammdefinition, d.h. einen Aufruf der diagram-Funktion. In Diagrammdefinitionsdateien sind keine Kommentar-Abschnitte notwendig, da es keine Wirtssprache gibt. Eine vollständige Diagrammdefinition sieht beispielsweise so aus:
(diagram 400 300 #FFFDFD
(axes (month 1) 3.0 9.0 1.0 #0)
(hline 5.0 #C0C0C0)
(hline 6.0 #C0C0C0)
(hline 7.0 #C0C0C0)
(curve (sum (select "*" (month 1)) day 3:30 9:30) #FF0000)
(curve (sum (select "*" (month 1)) day 11:00 14:30) #00FF00)
(curve (sum (select "*" (month 1)) day 17:30 20:30) #0000FF)
(curve (sum (select "*" (month 1)) day 21:00 2:00) #FFFF00)
(curve (avg (select "*" (month 1)) day 2:00) #0 1.0)
)
Bei der Entwicklung neuer Berichtsvorlagen bzw. Diagrammdefinitionen ist es klug, sich existierende Daten herzunehmen und leicht zu modifizieren.

### Syntax

Es gelten folgende syntaktische Vereinbarungen:

- jede Funktionsdefinition wird mit einer öffnenden runden Klammer begonnen und mit einer schließenden runden Klammer beendet, dieser Abschnitt zwischen den runden Klammern ist das, was zum Aurfuf vollständig angegeben werden muß
- der Name der Funktion ist das erste, was hinter der öffnenden runden Klammer folgt
- alle weiteren Angaben bis zur schließenden Klammer sind Typen von möglichen Parametern, jeder Typ wird in geschweiften Klammern geschrieben
- die Menge möglicher Typen ist begrenzt, folgende Typen sind möglich:

{int}, {double} | vorzeichenbehaftete Zahlen | 5, 3.14
{string} | Zeichenketten beliebiger Länge | "Hugo"
{time} | meist eine Zeitdauer, selten tatsächlich eine Uhrzeit | 09:13
{timestamp} | ein konkreter Zeitpunkt mit Datum und Uhrzeit | 2009-12-31-7:30:01
{selection} | eine Menge von Zeitstempel-Wert-Paaren |
{color} | eine RGB-Farbe in hexadezimaler Schreibweise | #00FF00
{nothing} | nur für Funktionsrückgabetypen: das Ergebnis der Funktion ist leer und kann nicht weiter ausgewertet werden |

- hinter der schließenden runden Klammer folgt ein Pfeil und ein weiterer Typ, dies ist der Typ des Funktionsergebnisses

Hinweis: In einigen Fällen werden Zeitstempel als Parameter verwendet. Zeitstempel besitzen eigentlich die Syntax CCYY-MM-DD hh:mm[:ss], haben also eigentlich ein Leerzeichen in der Mitte. Damit hier beim Funktionsaufruf klar ist, daß es sich bei diesen Zeitstempeln um einen und nicht um zwei Parameter handelt, ist hier ein - (Minuszeichen) als Bindeglied zwischen Datum und Uhrzeit erforderlich.

### Funktionen

Zeitspannen
Die folgenden Funktionen berechnen jeweils eine konkrete Zeitspanne. Ein mögliches {int}-Argument ist schlicht ein Faktor. Ist kein {int}-Argument angegeben, so gilt implizit der Faktor 1. Die Pluralform hat keinerlei inhaltliche Bedeutung, es handelt sich lediglich um eine intuitivere Schreibweise.
(second) → {time} (second {int}) → {time} (seconds {int}) → {time} (minute) → {time} (minute {int}) → {time} (minutes {int}) → {time} (hour) → {time} (hour {int}) → {time} (hours {int}) → {time} (day) → {time} (day {int}) → {time} (days {int}) → {time} (week) → {time} (week {int}) → {time} (weeks {int}) → {time} | Die Namen dieser Funktionen sind selbsterklärend.
(month) → {time} (month {int}) → {time} (months {int}) → {time} | Achtung, ein Monat im hier relevanten Sinne entspricht genau 30 Tagen. Die Angaben (month) und (days 30) sind synonym.
(year) → {time} (year {int}) → {time} (years {int}) → {time} | Achtung, ein Jahr im hier relevanten Sinne entspricht genau 365 Tagen. Die Angaben (year) und (days 365) sind synonym.

now
(now) → {timestamp} | Die Funktion now berechnet den aktuellen Zeitstempel.
Hinweis 1: Der Wert entspricht bei Verwendung des Kommandozeilenparameters -f dem Zeitpunkt des Programmstarts, auch wenn seitdem aufgrund längerer Berechnungen bereits ein paar Sekunden vergangen sein mögen. D.h. alle now-Aufrufe liefern bei Verwendung von -f denselben Zeitstempel. Das ist notwendig, um Zwischenergebnisse aufheben zu können. Hinweis 2: Der von der Funktion now zurückgegebene Wert kann mit dem Kommandozeilenparameter -n explizit auf einen konkrete Zeitstempel gesetzt werden. Damit lassen sich bei geschickt gestalteten Berichtsvorlagen und Diagrammdefinitionen Berichte und Diagramme für beliebige Zeitpunkte in der Vergangenheit erstellen.

midnight
(midnight) → {timestamp} | Die Funktion midnight berechnet einen Zeitstempel nach der folgenden Formel: tmidnight = tnow + 1 Tag - Uhrzeit + m (m ist der Parameter midnight aus der Datei .pdrxrc) Die Funktion liefert damit den Zeitpunkt, der als erster nach dem aktuellen Tag folgt, d.h. der aktuelle Tag ist vollständig enthalten, auch wenn er noch nicht zu Ende ist. Dieser Zeitpunkt ist in der Regel günstiger als now für die Erstellung von Berichten oder Diagrammen: now liefert einen angebrochenen, laufenden Tag, midnight einen ganzen, abgelaufenen.
Hinweis: Der Wert hängt vom Kommandozeilenparameter -n ab. Beispiel: Angenommen, der aktuelle Zeitunkt sei 2011-07-08 17:07:38 und der Parameter midnight ist in .pdrxrc als 2:00 definiert, dann liefert (midnight) den Wert 2011-07-09 02:00:00.

Selektion
Die fünf Implementationen der select-Funktion holen Werte aus einer collection und legen diese in einer selection ab. Eine selection ist ein zeitlich begrenzter, nicht unbedingt lückenloser Ausschnitt aus einer collection. Der obligatorische {string}-Parameter benennt jeweils die collection. Ist die collection leer oder wird entsprechend der zeitlichen Einschränkungen kein einziger Wert in der collection gefunden, so ist das Ergebnis leer.
(select {string}) → {selection} | Die Funktion holt alle Datenwerte der collection.
(select {string} {timestamp}) → {selection} | Die Funktion holt den Datenwert aus der collection, der zu dem angegebenen {timestamp} paßt.
(select {string} {timestamp} {timestamp}) → {selection} | Die Funktion holt alle Datenwerte aus der collection, die in der Zeitspanne zwischen den beiden {timestamp}-Parametern liegen.
(select {string} {time}) → {selection} | Die Funktion holt alle Datenwerte aus der collection, die in der Zeitspanne (now)-{time} bis (now) liegen.
(select {string} {time} {timestamp}) → {selection} | Die Funktion holt alle Datenwerte aus der collection, die in der Zeitspanne {timestamp}-{time} bis {timestamp} liegen.
Beispiele: (select "*") alle Werte der default collection holen (select "*" 2009-12-01-12:34) Werte der default collection seit dem 01.12.2009 12:34 holen (select "n" 2009-01-01-0:00 2010-01-01-0:00) alle Werte der collection n des Jahres 2009 holen (select "l" (weeks 2)) alle Werte der collection l der letzten zwei Wochen holen (select "l" (months 3) 2009-06-01-0:00) alle Werte der collection l aus den drei Monaten vor dem 01.06.2009 holen

merge
Die Funktion merge erlaubt das Mischen von selections, d.h. von Werten, die nicht aus derselben collection stammen. Das ist nützlich, wenn man Werte kategorisiert in verschiedenen collections ablegt, die aber doch zusammengehören.
(merge keyword ...) → {selection} | keyword benennt die Funktion, die benutzt wird, wenn zwei Werte verschiedener collections den gleichen Zeitstempel aufweisen. Folgende Angaben sind für keyword erlaubt: avg (Durchschnitt bilden) min (den kleineren Wert nehmen) max (den größeren Wert nehmen) sum (beide Werte summieren) Die offene Parameterliste hinter keyword erlaubt ausschließlich selections, und zwar mindestens zwei.
Beispiel: (merge avg (select "*" (days 7)) (select "x" (days 5)))

fold
Die Funktion fold erlaubt das "Falten" der Zeitachse einer selection. Man stelle sich die collection auf einem Streifen Papier vor und falte diesen in Gedanken ein paar Mal, so daß Zeitabschnitte übereinanderliegen. Auf diese Weise wird es möglich, beispielsweise Tage oder Monate miteinander zu vergleichen. Der Sinn dieser Funktion liegt darin, beispielsweise den Verlauf einer durchschnittlichen Tageskurve zu ermitteln, jedoch auf Basis mehrerer Tage mit dann sehr vielen Meßwerten.
(fold keyword1 keyword2 {selection}) → {selection} | keyword1 steuert das Intervall, anhand dessen die Faltung erfolgen soll. Anstelle von keyword1 sind folgende Angaben denkbar: year, month, day, hour oder minute. Wird beispielsweise mit der Angabe day gefaltet, so werden aus den Zeitstempeln der selection alle Bestandteile bis hin zum Tag entfernt, d.h. es bleibt nur noch die Uhrzeit übrig. Alle Werte liegen dann auf einer Zeitachse, die nur noch 24 Stunden umfaßt. keyword2 hat dieselbe Funktion wie keyword in der merge-Funktion. Auch hier sind folgende Angaben denkbar: avg, min, max, sum, first, last.
Hinweis: auch die selection im Ergebnis einer fold-Operation muß Zeitstempel enthalten. Es kann jedoch bei der Faltung eines Zeitbereichs kein absoluter Zeitstempel mehr ausgemacht werden, mehrere liegen ja übereinander. Aus diesem Grund tragen die Zeitstempel das Jahr 9999. Entsprechend dem benutzten Intervall sind zudem auch weitere Bestandteile dieser Zeitstempel (Monat, Tag usw.) zwar syntaktisch gültig, aber inhaltlich nicht sinnvoll.
Beispiel: selection a (fold day avg (select "a")) (fold day first (select "a")) (fold day last (select "a")) -------------------- --------------------------- ----------------------------- ---------------------------- 2009-12-01 13:01 5.2 9999-01-01 13:01 5.45 <- avg! 9999-01-01 13:01 5.2 <- first! 9999-12-05 13:01 5.7 <- last! 2009-12-02 13:02 5.7 9999-01-01 13:02 5.7 9999-01-01 13:02 5.7 9999-01-01 13:02 5.7 2009-12-03 13:03 3.2 9999-01-01 13:03 3.2 9999-01-01 13:03 3.2 9999-01-01 13:03 3.2 2009-12-04 13:04 4.8 9999-01-01 13:04 4.8 9999-01-01 13:04 4.8 9999-01-01 13:04 4.8 2009-12-05 13:01 5.7 2009-12-06 13:06 5.3 9999-01-01 13:06 5.3 9999-01-01 13:06 5.3 9999-01-01 13:06 5.3

Statistik
Die Statistikfunktionen dienen zur Ausführung typischer, statistischer Berechnungen auf einer selection. Die Funktionen berechnen im Einzelnen: avg: den arithmetischen Durchschnitt count: die Anzahl der Werte first: den zeitlich ersten Wert last: den zeitlich letzten Wert max: den größten Wert min: den kleinsten Wert sdv: die Standardabweichung sum: die Summe aller Werte Diese Funktionen liegen zunächst in jeweils fünf Implementierungen vor (func ist ein Platzhalter für den Funktionsnamen).
(func {selection}) → {selection} | die Berechnung auf die gesamte selection anwenden, das Ergebnis enthält eine einzelne Zeile
(func {selection} {time} {time}) → {selection} | die Berechnung auf die gesamte selection anwenden, dabei aber nur die Werte zwischen den beiden angegebenen Tageszeiten berücksichtigen, das Ergebnis enthält eine einzelne Zeile
Die folgenden Implementierungen benutzen ein keyword, das das Aggregationsintervall benennt. Dieses keyword kann lauten: year, month, day, hour, minute, second. Das Ergebnis enthält dann eine Zeile pro Intervall. Benutzt man beispielsweise day als Aggregationsintervall, so liefert der Aufruf im Ergebnis eine Zeile pro in der ursprünglichen selection enthaltenem Tag.
(func {selection} keyword) → {selection} | die Berechnung auf die gesamte selection anwenden, dabei entsprechend keyword aggregieren
(func {selection} keyword {time} {time}) → {selection} | die Berechnung auf die gesamte selection anwenden, dabei entsprechend keyword aggregieren und nur Werte zwischen den beiden angegebenen Uhrzeiten benutzen
Die Funktionen avg und sdv haben noch eine sechste, gleitende Implementierung, die zur Berechnung jeweils vorhergehende bzw. nachfolgende Werte heranzieht und sehr schöne Kurven liefert.
(func {selection} {int} {int}) → {selection} | die Berechnung auf die gesamte selection anwenden, dabei pro Wert {int} zurückliegende und {int} nachfolgende Werte ermitteln und nur in diesem gleitenden Fenster rechnen, dies ergibt im Ergebnis so viele Werte, wie in der ursprünglichen selection enthalten sind
Beispiele: (avg (select "*")) den Durchschnitt über alle Werte der default collection bilden (sum (select "n" 3:30 9:00) day) die tägliche Summe über Werte der collection n bilden, aber nur Werte zwischen 3:30 und 9:00 berücksichtigen (avg (select "l" (month)) 5 5) den gleitenden Durchschnitt über je 11 Werte der collection l des letzten Monats bilden (first (select "*" (month)) day 4:00 9:00) die jeweils erste Zeile eines jeden Tages des letzten Monats aus der default collection holen, nur Werte zwischen 4 und 9 Uhr berücksichtigen (last (select "*" (day)) hour) die letzte Zeile einer Stunde des letzten Tages aus der default collection holen

Vergleich
(== {selection} {double}) → {selection} (!= {selection} {double}) → {selection} (< {selection} {double}) → {selection} (> {selection} {double}) → {selection} (<= {selection} {double}) → {selection} (>= {selection} {double}) → {selection} | All diese Funktionen vergleichen jeden Wert einer selection mit der angegebenen Konstante und übernehmen nur diejenigen Werte in das Ergebnis, die dem Vergleich genügen. Die selection im Funktionsergebis ist somit höchstens gleich groß wie die als Parameter übergebene selection.
Beispiele: (< (select "*") 5.0) liefert alle Werte aus der default collection, die kleiner als 5.0 sind (>= (select "*") 7.0) liefert alle Werte aus der default collection, die größer oder gleich 7.0 sind

Arithmetik
(+ {double} {double}) → {selection} (- {double} {double}) → {selection} (* {double} {double}) → {selection} (/ {double} {double}) → {selection} | Diese vier Funktionen verknüpfen jeweils zwei Zahlen miteinander. Achtung: das Ergebnis ist dennoch eine selection, um es einfacher weiterverarbeiten zu können. Diese selection hat nur eine Zeile und auf dieser keinen Zeitstempel.
(+ {selection} {double}) → {selection} (- {selection} {double}) → {selection} (* {selection} {double}) → {selection} (/ {selection} {double}) → {selection} | Diese Gruppe von Funktionen verknüpft jeweils jeden Wert der übergebenen selection mit einer Zahl. Das Ergebnis hat genauso viele Zeilen wie die übergebene selection.
(+ {selection} {selection}) → {selection} (- {selection} {selection}) → {selection} (* {selection} {selection}) → {selection} (/ {selection} {selection}) → {selection} | Diese vier Funktionen verknüpfen jeweils zwei selections. Dabei werden Zeile für Zeile ihre Zeitstempel verglichen und als Schlüssel benutzt. Die Anzahlen der Zeilen in beiden selections müssen allerdings nicht gleich sein. Wenn in der zweiten selection keine gleich alte Zeile wie in der ersten selection vorhanden ist, wird die nächst ältere genommen. Das Ergebnis hat so viele Zeilen wie die erste selection. Die Zeitstempel des Ergebnisses entsprechen ebenfalls der ersten selection. Wesentlich ist, daß auch für die erste Zeile in der ersten selection eine brauchbare, d.h. gleich alte oder ältere Zeile in der zweiten selection erforderlich ist. pdx gibt einen Fehler aus, wenn diese Bedingung nicht erfüllt ist. Nützlich sind diese vier Implementierungen insbesondere dann, wenn man zwei selections hat, die Zähler und Nenner eines Quotienten darstellen, wenn man also Werte hat, die auf irgendeine Basis bezogen sind, d.h. spezifische Werte, z.B. ein Benzinverbrauch pro 100km.
(+ {timestamp} {time}) → {timestamp} (- {timestamp} {time}) → {timestamp} | Diese beiden Funktionen rechnen zu einem Zeitstempel {timestamp} eine Zeitdauer {time} hinzu oder hinweg. Das Ergebnis is folgerichtig wieder ein Zeitstempel.
(+ {string} {string} ...) → {string} | Diese Funktion verkettet eine beliebige Anzahl (mindestens zwei) von {string}-Parametern. Das Ergebnis ist wieder eine Zeichenkette.
Beispiel 1: (+ 2010-17-12-00:00:00 (days 3)) ergibt den 20.12.2010, 0 Uhr Beispiel 2: selection a selection b (* (select "a") (select "b")) -------------------- -------------------- ----------------------------- 2009-11-17 12:38 9.3 2009-12-01 13:00 5.2 -> 5.2 * 9.3 = 2009-12-01 13:00 48.36 2009-12-02 13:00 5.7 -> 5.7 * 9.3 = 2009-12-02 13:00 53.01 2009-12-03 13:00 3.2 -> 3.2 * 9.3 = 2009-12-03 13:00 18.24 2009-12-03 19:17 8.4 2009-12-04 13:00 4.8 -> 4.8 * 8.4 = 2009-12-04 13:00 40.32 2009-12-05 13:00 5.7 2009-12-05 13:00 4.7 -> 5.7 * 4.7 = 2009-12-05 13:00 26.79 2009-12-06 13:00 5.3 -> 5.3 * 4.7 = 2009-12-06 13:00 30.21

Informationen über collections
(unit {string}) → {string} | Diese Funktion liefert die beim Anlegen der collection definierte Maßeinheit.
(purpose {string}) → {string} | Diese Funktion liefert die beim Anlegen den collection definierten Zweck.

HbA1c
Diese Funktionen sind spezifisch für Diabetiker. Sie berechnen den Wert HbA1c anhand der Blutzuckerwerte der letzten 90 Tage. Diese Datenmenge ist in der collection erforderlich. Die Funktion HbA1c gewichtet alle Werte in der collection gleich, während die Funktion HbA1c2 jüngeren Werten ein höheres Gewicht gibt. Sie schwankt deshalb etwas mehr als erstere. Der {string}-Parameter bei allen HbA1c-Funktionen benennt die collection, aus der die Werte entnommen werden.
(HbA1c {string}) → {selection} | berechnet HbA1c von heute, das Ergebnis enthält nur eine Zeile
(HbA1c {string} {timestamp}) → {selection} | berechnet HbA1c vom angegebenen {timestamp}, das Ergebnis enthält nur eine Zeile
(HbA1c {string} {timestamp} {timestamp}) → {selection} | berechnet HbA1c in der Zeitspanne vom ersten {timestamp} bis zum zweiten {timestamp}, das Ergebnis enthält so viele Zeilen, wie in dieser Zeitspanne Werte gefunden werden
(HbA1c {string} {time}) → {selection} | berechnet HbA1c in der Zeitspanne von (now)-{time} bis (now), das Ergebnis enthält so viele Zeilen, wie in dieser Zeitspanne Werte gefunden werden
(HbA1c {string} {time} {timestamp}) → {selection} | berechnet HbA1c in der Zeitspanne von {timestamp} - {time} bis {timestamp}, das Ergebnis enthält so viele Zeilen, wie in dieser Zeitspanne Werte gefunden werden
(HbA1c2 {string}) → {selection} | (diese fünf Implementationen verhalten sich hinsichtlich der Parameter genau wie die fünf vorhergehenden)
(HbA1c2 {string} {timestamp}) → {selection}
(HbA1c2 {string} {timestamp} {timestamp}) → {selection}
(HbA1c2 {string} {time}) → {selection}
(HbA1c2 {string} {time} {timestamp}) → {selection}

Berichte
Die Funktionen dieses Abschnitts sind notwendig für die Erstellung von Berichten. Sie geben jeweils eine Zeichenkette zurück, oft einen umfangreichen Block Text. pdx liest die Textvorlage des Berichts, trifft darin auf eine format-Anweisung, wertet diese augenblicklich aus und ersetzt sie an derselben Position im Text mit deren Ergebnis. Diese Funktionen können interaktiv getestet werden.
(format ...) → {string} | Sie erwartet eine beliebig lange Liste von Parametern, die aus Text, Funktionsergebnissen, Formatierungsanweisungen und Schlüsselworten bestehen können: (format "<tr>" "<td>" datetime "</td>" "<td>" (select "*" (days 7)) <1.1> "</td>" "<td>" (select "n" (days 7)) <1> "</td>" "</tr>" newline ) All diese Teilausdrücke ergeben lauter kurze Textstücke, die verkettet werden. Das Ergebnis ist ein ein- oder mehrzeiliges Stück Text beliebiger Länge. Die Anzahl der Zeilen darin richtet sich nach der Anzahl der Werte in den Funktionsergebnissen. Passen Werte entsprechend ihrer Zeitstempel zusammen, so erscheinen sie auf derselben Zeile. Das Schlüsselwort datetime ist ein Platzhalter für den Zeitstempel der Zeile. Das Schlüsselwort newline fügt einen physischen Zeilenwechsel ein. Die Formatieranweisungen erkennt man an ihrer Schreibweise in spitzen Klammern. Sie beziehen sich stets auf den Wert unmittelbar zuvor. Es gibt drei verschiedene Formate: <n>: eine ganze Zahl (ohne Komma) mit mindestens n Stellen ausgeben <n.0>: eine Zahl mit n Vorkommastellen und nur wenn nötig Nachkommastellen ausgeben <n.m>: immer n Vorkomma- und m Nachkommastellen ausgeben Das Ergebnis obigen Beispiels ist echtes HTML: [...] <tr><td>2009-01-17 21:42:49</td><td>5.6</td><td>6</td></tr> <tr><td>2009-01-18 05:54:41</td><td>6.8</td><td>7</td></tr> <tr><td>2009-01-18 12:17:22</td><td>5.4</td><td>6</td></tr> [...]
(empty {string}) → {string} | Innerhalb einer format-Funktion besteht also gelegentlich das Problem, daß man in der Ausgabe leere Werte kennzeichnen, d.h. sichtbar machen will oder muß. Leere Werte entstehen durch die Verknüpfung mehrerer Selektionen zu einer mehrspaltigen Tabelle (outer join). Mit Hilfe der empty-Funktion kann man der umgebenden format-Funktion mitteilen, welche Zeichenkette {string} anstelle eines leeren Werts in die Ausgabe eingefügt werden soll.

Diagramme
Die folgenden Funktionen zeichnen etwas Sichtbares in ein Diagramm. Sie können daher nicht in der interaktiven Betriebsart von pdx erprobt werden. Das Ergebnis all dieser Funktionen ist außerdem immer vom Typ {nothing}, man kann es nicht für weitere Berechnungen nutzen.
(diagram {int} {int} {color} ...) → {nothing} | Die diagram-Funktion ist ein wrapper. Sie umschließt die gesamte Definition eines konkreten Diagramms. Der erste {int}-Parameter benennt die Größe de Diagramms in x-Richtung, der zweite {int}-Parameter die Größe in y-Richtung. Der {color}-Parameter gibt die Hintergrundfarbe in RGB-Notation an. Die dann folgende offene Parameterliste enthält Aufrufe anderer Diagrammfunktionen, insbesondere mindestens eine axes- und eine curve-Funktion.
(sundays {color}) → {nothing} | Die Funktion legt fest, dass Sonntage auf der Zeitachse eine bestimmte Farbe bekommen sollen. Dies ist nur sinnvoll, wenn auf der Zeitachse auch tatsächlich Tage dargestellt werden. Die sundays-Funktion muss, damit sie wirkt, vor der axes-Funktion aufgerufen werden.
Die zehn verschiedenen Implementierungen der axes-Funktion zeichnen jeweils ein komplettes und beschriftetes Koordinatensystem, um dessen Einzelheiten sich der Benutzer nicht mehr kümmern muß. Grundsätzlich gilt: je weniger Parameter die Implementierung hat, umso mehr läuft automatisch ab, je mehr, umso präziser kann der Benutzer festlegen, wie die Achsen aussehen sollen.
(axes {timestamp} {timestamp} {double} {double} {double} {color} {string}) → {nothing} a (axes {time} {timestamp} {double} {double} {double} {color} {string}) → {nothing} b (axes {time} {double} {double} {double} {color} {string}) → {nothing} c (axes keyword {double} {double} {double} {color} {string}) → {nothing} d (axes {timestamp} {timestamp} {double} {color} {string}) → {nothing} e (axes {time} {timestamp} {double} {color} {string}) → {nothing} f (axes {time} {double} {color} {string}) → {nothing} g (axes keyword {double} {color} {string}) → {nothing} h (axes {double} {double} {double} {color} {string}) → {nothing} i (axes {double} {color} {string}) → {nothing} j
Grün dargestellte Parameter beziehen sich auf die x-Achse: Die Implementierungen a und e benutzen zwei {timestamp}-Parameter, um Anfang bzw. Ende der x-Achse ganz konkret festzulegen. Bei den Implementierungen b und f legt jeweils der {timestamp}-Parameter das Ende der x-Achse fest, während der Anfang durch {timestamp}-{time} bestimmt wird. Die Implementierungen c und g funktionieren wie b bzw. f, wobei statt einem festen {timestamp} der Ausdruck (now) benutzt wird, d.h. das Ende der x-Achse wird durch (now) festgelegt, der Anfang durch (now)-{time}. Die Implementierungen d und h verwenden eins der folgenden Schlüsselworte, um eine gefaltete x-Achse zu erzeugen: year, month, day, hour oder minute. Die x-Achse bildet dann diese Länge ab. Die Implementierungen i und j verzichten auf konkrete Angaben zur x-Achse. Dies bedeutet, die x-Achse wird vollständig automatisch anhand der Werte bestimmt, die in den darzustellenden Kurven auftauchen. Dies führt einerseits zu sehr präzisen, dynamischen x-Achsen, hat andererseits aber nur einen Sinn, wenn tatsächlich Kurven und Werte vorhanden sind. Blau dargestellte Parameter beziehen sich auf die y-Achse. Der erste {double}-Parameter kennzeichnet stets das untere Ende der y-Achse, der zweite {double}-Parameter das obere. Der erste {double}-Wert muß arithmetisch kleiner als der zweite sein, auch im Negativen. Die Implementationen e, f, g, h und j machen keine Angaben über Anfang und Ende der y-Achse. Diese Implementationen bestimmen die Länge der y-Achse automatisch anhand der abzubildenden Werte. Dies führt einerseits zu sehr präzisen, dynamischen y-Achsen, hat andererseits aber nur einen Sinn, wenn tatsächlich Kurven und Werte vorhanden sind. Die Implementation j berechnet somit beide Achsen vollautomatisch, so daß prinzipiell jeder Wert sauber gezeichnet werden kann, ohne daß er aufgrund einer Unvorhersehbarkeit das Diagramm verließe. Der stets vorhandene rote {double}-Parameter kennzeichnet die Schrittweite der Beschriftung auf der y-Achse. Der {color}-Parameter benennt die Farbe beider Achsen und ihrer Beschriftung. Der {string}-Parameter am Ende kann einen kurzen Text enthalten, der am oberen Ende der y-Achse dargestellt wird. Dieser sollte üblicherweise eine Maßeinheit enthalten.
Die folgenden Funktionen zeichnen "Kurven", mit denen Werteverläufe dargestellt werden können.
(curve {selection} {color}) a → {nothing} | Die Funktion zeichnet eine Zickzack-Linie in der angegebenen Farbe und in vorgegebener Strichdicke.
(curve {selection} {color} {double}) b → {nothing} | Wie die vorhergehende Implementation. Der {double}-Parameter kennzeichnet die gewünschte Strichdicke: Werte >1 führen zu starken Strichdicken, Werte <1 zu dünneren.
(curve {selection} {color} {string}) c → {nothing} | Die Funktion zeichnet eine Kurve bestehend aus einzelnen, nicht verbundenen Punkten in der angegeben Farbe und in vorgegebener Strichdicke. Der {string}-Parameter kennzeichnet die Symbole, mit denen die Punkte dargestellt werden sollen. Es können folgende Angaben verwendet werden: ".", "+", "|", "-", "x", "X", "°" oder "#".
(curve {selection} {color} {string} {double}) d → {nothing} | Wie die vorhergehende Implementation. Der {double}-Parameter kennzeichnet die gewünschte Strichdicke: Werte >1 führen zu starken Strichdicken, Werte <1 zu dünneren.
(spline {selection} {color} {int}) a → {nothing} | Die beiden Implementierungen a und b der spline-Funktion entsprechen inhaltlich exakt den Implementierungen a und b der curve-Funktion (siehe oben). Der Unterschied liegt darin, dass der hier verwendete spline-Algorithmus versucht, zusätzliche Zwischenwerte zu errechnen, so dass die Kurve aus viel mehr Punkten besteht, als tatsächlich verfügbar sind, was anstelle der Geraden zu schöneren, runderen Kurven führt. Der zusätzliche {int}-Parameter gibt an, wieviele Zwischenwerte jeweils zwischen zwei gegebenen Punkten errechnet werden sollen, beispielsweise 5 oder 10. Achtung! Eine erfolgreiche Anwendung der spline-Funktion setzt geeignete Ausgangsdaten voraus. Man erreicht üblicherweise gute Ergebnisse, wenn in x-Richtung äquidistante Ausgangswerte vorliegen. Hat man hingegen Werte, die sich an bestimmten Zeitpunkten häufen, wie es oft bei gefalteten Zeitachsen der Fall ist, errechnet die spline-Funktion fantastische und unerwartete Minima und Maxima, die nie und nimmer realistisch sein können.
(spline {selection} {color} {double} {int}) b → {nothing}
(bars {selection} {color}) → {nothing} | Die Funktion zeichnet senkrechte Balken, und zwar pro in der selection enthaltenem Wert einen. Das kann bedeuten, daß in konkreten, gleich langen Zeitintervallen verschieden viele, verschieden dicke Balken auftauchen, je nachdem, was die selection liefert. Es hat sich als sehr zweckmäßig erwiesen, die Zeitintervalle deshalb farblich leicht gegeneinander abzusetzen (dies geschieht automatisch).
(bars {selection} {color} {int} {int}) → {nothing} | Die Funktion zeichnet senkrechte Balken mit gleicher Breite. Der erste {int}-Parameter gibt bei 1 beginnend die Nummer des Balkens im Intervall an, der zweite {int}-Parameter enthält die Gesamtanzahl an Balken im Intervall. Mit Hilfe dieser {int}-Parameter und entsprechend mehrfachem Aufruf der bars-Funktion können so mehrere selections sauber nebeneinander als verschiedenfarbige Balken dargestellt werden.
(stairs {selection} {color}) → {nothing} | Die Funktion zeichnet eine Linie in Treppenstufen, d.h. alle gezeichneten Teilstücke sind entweder waagerecht oder senkrecht.
(stairs {selection} {color} {double}) → {nothing} | Wie die vorhergehende Implementation. Der {double}-Parameter gibt die Strichdicke an.
Die folgenden Funktionen zeichnen horizontale Linien in der angegeben Farbe.
(hline {double} {color}) → {nothing} | Die beiden Funktionen zeichnen genau eine horizontale Linie. Der erste {double}-Parameter bezeichnet die Schrittweite zwischen den Linien, der zweite gibt die Strichdicke der Linie an
(hline {double} {double} {color}) → {nothing}
(hlines {double} {color}) → {nothing} | Die beiden Funktionen zeichnen horizontale Linien und zwar so viele wie nötig, entsprechend der Länge der y-Achse. Der erste {double}-Parameter bezeichnet die Schrittweite zwischen den Linien. Es ist ratsam, hier denselben Wert zu verwenden wie bei der axes-Funktion. Der zweite {double}-Parameter gibt die Strichdicke an.
(hlines {double} {double} {color}) → {nothing}
Die beiden Implementierungen der vline-Funktion zeichnen eine vertikale Linie in der angegeben Farbe.
(vline {timestamp} {color}) → {nothing} | {timestamp} bezeichnet die Position der Linie auf der x-Achse
(vline {timestamp} {double} {color}) → {nothing} | {timestamp} bezeichnet die Position der Linie auf der x-Achse, {double} bezeichnet die Strichdicke der Linie
(vline {time} {color}) → {nothing} | {time} bezeichnet die Position der Linie auf der x-Achse, speziell für das Zeichnen von Daten, die aus einem Aufruf der Funktion fold stammen
(vline {time} {double} {color}) → {nothing} | {time} bezeichnet die Position der Linie auf der x-Achse, {double} bezeichnet die Strichdicke der Linie, speziell für das Zeichnen von Daten, die aus einem Aufruf der Funktion fold stammen
Beispiele: (diagram 500 375 #FFFDFD (axes day 3.0 9.0 1.0 #0 (unit "*")) (hline 4.5 #C0C0C0) (hline 5.0 #C0C0C0) (hline 5.5 #C0C0C0) (hline 6.0 #C0C0C0) (hline 6.5 #C0C0C0) (hline 7.0 #C0C0C0) (hline 7.5 #C0C0C0) (vline 5:45 #C0C0C0) (vline 12:30 #C0C0C0) (vline 18:30 #C0C0C0) (vline 21:30 #C0C0C0) (curve (fold day first (merge avg (select "*" (week)) (select "x" (week)))) #FF0000 "+") (curve (avg (fold day first (merge avg (select "*" (week)) (select "x" (week)))) 3 3) #000000 2.0) (curve (avg (fold day first (merge avg (select "*" (year)) (select "x" (year)))) 30 30) #000000) ) (diagram 500 375 #FFFDFD (sundays #FF0000) (axes 1.0 #0 (unit "n")) (bars (select "n" (month 1)) #FF1000) ) (diagram 500 375 #FFFDFD (sundays #FF0000) (axes 1.0 #0 (unit "n")) (bars (sum (select "n" (month 1)) day 3:30 11:00) #FF1000 1 4) (bars (sum (select "n" (month 1)) day 11:00 14:30) #FF5000 2 4) (bars (sum (select "n" (month 1)) day 14:30 17:30) #FF5000 3 4) (bars (sum (select "n" (month 1)) day 17:30 21:00) #FF9000 4 4) )

sonstiges
(build) → {string | Die Funktion liefert den build-string von pdx. Dieser enthält Angaben darüber, wann und wie pdx compiliert wurde, d.h. auch welche Optionen benutzt wurden und welche optionalen Fähigkeiten das Programm besitzt.
(database) → {string} | Die Funktion liefert Name und Version des verwendeten Datenbanksystems.
(version) → {string} | Die Funktion liefert die Version von pdx.
Beispiele: (build) Dec 15 2010, 17:25:30, USE_SQLITE, USE_MYSQL, USE_READLINE, USE_BOARD, USE_CAIRO, USE_ETPAN (database) MySQL 5.1.51 (version) 1.2.0

pdx Konfiguration | Index | pdx Interaktiver Betrieb