Handbuch
 

1. allgemeine Funktionsweise

myTextReport benötigt für jeden Job eine eigene Konfigurationsdatei. Diese Datei definiert sämtliche benötigte Optionen. Sie kann während der Laufzeit geladen werden oder wird als Kommandozeilenparameter beim Start übergeben. Es ist möglich, die Konfigurationsdaten während der Laufzeit erneut einzulesen.

In einem Template-File sind neben den Textdaten Feldbefehle eingebettet, die nach einer in der Konfigurationsdatei definierten Syntax SQL-Abfragen enthalten. Der Template-File kann ansonsten alle denkbaren Daten enthalten. Das Deteiformat ist unerheblich. In aller Regel wird man den Template-File zunächst mit einem für sein Format üblichen Werkzeug erstellen und dann mit einem handelsüblichen ASCII-Editor die Feldbefehle einfügen.

myTextReport liest zunächst den Template-File ein und sucht sämtliche darin enthaltene Feldbefehle. Der Template-File wird in einer verketteten Liste gespeichert. Befinden sich unter den Feldbefehlen auch Loops zur Bearbeitung von relationalen Listen, werden diese intern in eigenen Listen verwaltet.

Der aufbereitete Template-File wird nun im Speicher kopiert. In dieser Kopie werden die Feldbefehle ausgeführt und im Speicher durch ihre Resulate ersetzt. Dazu werden zunächst sämtliche definierten Variablen gesucht und ausgewertet. Das Ergebnis wird überall dort eingesetzt, wo die Variable verwendung findet. Erst dann werden die eigentlichen SQL-Statements ausgeführt. myTextReport geht dabei wie folgt vor: Alle Statements, die keine Variable verwenden, werden um den Zusatz Limit i,1 ergänzt, wobei i die aktuell verarbeitete Datenbankzeile darstellt. Statements mit Variablen erhalten diesen Zusatz nicht, weil das sinnlos wäre. Dieses Vorgehen ermöglicht einige Tricks, wenn man den Limit-Zusatz gewaltsam unterdrücken möchte.
Die ausgewerteten Daten werden nun in eine Datei gespeichert. Dazu muß zunächst der Dateiname bestimmt werden, der im Normalfall nicht im Klartext in der Konfigurationsdatei stehen dürfte: Um zu verhindern, daß zahlreiche Ergebnissdateien eines Jobs immer wieder den selben Namen verwenden, müssen die Dateinamen aus einem Datenbankfeld generiert werden. Der Ziel-Dateiname in der Konfigurationsdatei enthält also ebenfalls SQL-Feldbefehle und wird intern ebenso verarbeitet wie der Inhalt des Template-Files (es wäre also theoretisch möglich, auch im Dateinamen oder -pfad relationale Loops anzuwenden, auch wenn dies kaum je Sinn ergeben dürfte).
 
 

2. Die Konfigurationsdatei

Konfigurationsdateien müssen für jeden Job individuell angepaßt werden. Eine Konfigurationsdatei erhält normalerweise das Suffix .cfg, dies ist jedoch nicht zwingend. Diese Datei wird im ASCII-Format erwartet.

2.1. Syntax

Grundsätzlich erfolgen alle Einträge in der Schreibweise

option='wert'

Achtung: myTextReprot verfügt über kein Exception-Handling. Die Syntax der Konfigurationsdatei wird nicht überprüft. Das bedeutet, daß es bei fehlerhaften Einträgen zu Laufzeitfehlern kommen kann, die, Java sei Dank, jedoch folgenlos sind. Das Programm läuft also weiter und erlaubt ein erneutes Einlesen der Datei.

2.2. Einträge

Eine Konfigurationsdatei bestimmt alle notwendigen Parameter für einen Job. Dies sind im Einzelnen:
 

2.2.1. Optionen zur Datenbankanbindung
 

db_server='127.0.0.1'
	Das ist die IP-Adresse oder der Hostname des mySQL-Servers. Ist der Server auf dem lokalen Rechner installiert, gilt oben angegebene '127.0.0.1'  (oder alternativ 'localhost').
db_user='myTextReport-user'
	Der Username, mit dem myTextReport sich beim mySQL-Server anmeldet. Diese Option ist von Bedeutung, wenn die Nutzerverwaltung des Datenbankservers Beschränkungen vorsieht.
db_database='test'
	Die Datenbank, aus der die Daten gelesen werden sollen.
db_table='test_tab1'
	Die Tabelle, anhand der zeilenweise vorgegangen werden soll. Dies ist keine Beschränkung der Bezugsquelle (alle Tabellen einer Datenbank können gleichermassen verwendet werden).
db_startrow='0'
	Die erste Zeile der o.g. Tabelle, die verarbeitet werden soll.
db_endrow='-1'
	Die letzte zu verarbeitende Zeile. -1 bedeutet: Alle Zeilen verarbeiten.

2.2.2. Syntaktische Einstellungen
 

sy_starttag='{SQL'
sy_stoptag ='SQL}'
	Diese beiden Einträge bestimmen die Syntax der SQL-Feldbefehle im Template-File. Details siehe unten.

2.2.3. Dateien
 

fn_template='f:\daten\template\template01_local.html'
	Vollständiger Dateiname des Template-Files.
fn_outputfilename='f:\daten\{SQL SELECT id_member FROM members SQL}.html'
	Vollständiger Dateiname der Datei, in die die Ergebnisse geschrieben werden sollen. Achtung: Da in aller Regel mehrere Dateien erzeugt werden, muß in diesem String definiert werden, wie sich der Dateiname anhand einer Datenbankabfrage erzeugen läßt. Wir sehen hier also einen Feldbefehl, wie er identisch auch im Template-File verwendet  wird. Zur genauen Syntax siehe Erläuterungen zum Template-File weiter unten. Beachte: Die Start- und Stopzeichen entsprechen der in Abschnitt 2.2.2 festgesetzten Zeichenfolge.
txt_filter='html'
	Der Textfilter, nach dem Sonderzeichen und Umlaute in Datenbankergebnissen umgewandelt werden sollen. Zur Zeit sind die Werte 'html' und 'rtf' definiert. Zusätzlich kann 'plain' verwendet werden, wenn kein Filter gewünscht wird (Dummy, da ohnehin kein Filter verwendet wird, wenn diese Option fehlt, auskommentiert oder mit einem ungültigen Wert belegt wurde). Fehlende Filter lassen sich recht einfach programmieren.

 
 

3. Der Template-File

In einen Template-File, bestehend aus ASCII-Text (in allen denkbaren Kodierungen, z.B. HTML), werden Feldbefehle eingefügt, die von myTextReport ausgeführt werden. Dabei gilt, daß die Feldbefehle von den in der Konfigurationsdatei fesgelegten Steuerzeichen umgeben sein müssen. In unserem Beispiel ist das {SQL bzw. SQL}. Leerzeichen zwischen den Steuerzeichen und den eigentlichen Feldbefehlen sind nicht erforderlich, erhöhen aber die Lesbarkeit.

Achtung: myTextReprot verfügt über kein Exception-Handling. Die Syntax des Template-File wird nicht überprüft. Das bedeutet, daß es bei fehlerhaften Einträgen zu Laufzeitfehlern kommen kann, die, Java sei Dank, jedoch folgenlos sind.

3.1. Einfache SQL-Statements

Ein einfaches SQL-Statement könnte etwa so aussehen:

{SQL SELECT name FROM members SQL}

Diese Statement wird vor der Ausführung durch myTextReport automatisch um den Zusatz Limit i,1 ergänzt, wobei i für die aktuell verarbeitete Zeile der Datenbanktabelle steht.

Außerder dieser Einschränkung sind jedoch alle Erweiterungen möglich:

{SQL SELECT name FROM members WHERE gender=1 ORDER BY NAME DESC SQL}

Der SQL-Einsatz ist nicht auf das SELECT-Statement beschränkt, auch wenn beispielsweise nachfolgendes Statement eher selten Verwendung finden dürfte:

{SQL SHOW COLUMNS FROM members SQL}
 

3.2. Definition und Einsatz von Variablen

Für Verknüpfungen zwischen Datenbanktabellen ist häufig der Einsatz von Variablen notwendig. Zur Definition einer Variable werden die Feldbefehl-Steuerzeichen um den Zusatz "-VAR" bzw. "VAR-" ergänzt:

{SQL-VAR v_prio=SELECT prio FROM projects VAR-SQL}

Beim Einsatz der Veriablen wird diese von $-Zeichen umschlossen:

{SQL SELECT string1 FROM priority where id_priority=$v_prio$ SQL}

Grundsätzlich können Variablen an jeder beliebigen Stelle des Templates definiert werden und auch mehrfach verwendet werden. myTextReport durchsucht zunächst die ganze Datei nach Variablen, bevor die Feldbefehle ausgeführt werden. Die Variablendefinitionen hinterlassen in den Ergebnisdateien keine Spuren. Ich persönlich definiere normalerweise eine Variable unmittelbar vor dem (ersten) Feldbefehl, der sie verwendet. Mit einer gebündelten Variablendefinition am Anfang des Template-Files habe ich keine Erfahrung.
 

3.3. Definition und Einsatz von Variablen

Schleifen werden notwendig, wenn mehrere Ergebniszeilen einer oder mehrerer SQL-Abfragen in einer Datei abgebildet werden sollen. Eine Schleife kann neben den SQL-Befehlen auch Variablendefinitionen sowie Textelemente enthalten, die für jede Ergebniszeiel wiederholt werden. Schleifen werden durch den Parameter -LOOP bzw. LOOP- gekennzeichnet:

{SQL-LOOP
{SQL-VAR v_prj=SELECT id_project FROM projects VAR-SQL}
{SQL-TXTName: TXT-SQL}
{SQL SELECT name from members WHERE ref_id_project=$v_prj$ SQL}
{SQL-TXT Vorname: TXT-SQL}
{SQL SELECT fname from members WHERE ref_id_project=$v_prj$ SQL}
{SQL-TXT Email: TXT-SQL}
{SQL SELECT email from members WHERE ref_id_project=$v_prj$ SQL}
{SQL-TXT
TXT-SQL}
LOOP-SQL}

Anmerkungen:

• Variablen, die innerhalb eines Loops verwendet werden sollen, können nur dort definiert werden und haben nur innerhalb dieses Loops Gültigkeit.
• Innerhalb von Loops werden Text-Elemente mit dem Parameter TXT gekennzeichnet. Das beduetet: Innerhalb eines Loops gibt es keine 'losen' Elemente sondern nur durch weitere Begrenzer verschachtelte Feldbefehle! Der TXT-Parameter ist prinzipiell auch außerhalb von Loops verfügbar, macht dort aber wenig Sinn.