SuperX-spezifische Scripte: Übersicht
Für die Administration des DataWarehouse sind Shellscripte vorbereitet, die flexible Werkzeuge zur Datenbankadministration bereitstellen. Die Shellscripte werden in den Update-Scripten aufgerufen, können aber auch zur manuellen Administration benutzt werden. Die wichtigsten Bereiche sind die Masken-Verwaltung und die Ladescripte im Umgang mit Tabellen sowie allgemeine Scripte. Alle Scripte befinden sich unter $SUPERX_DIR/db/bin, deshalb muss dieser Pfad inder Umgebungsvariable PATH enthalten sein. Die Scripte wurden unter UNIX entwickelt (ohne Endung oder Endung .x), einige davon sind auch nach DOS portiert worden (erkennbar an der Endung .bat). Einige Scripte lauten "sx_auto_"..., dies bedeutet, dass die Scripte ohne Sicherheitsabfrage ausgeführt werden. Voraussetzung für den Ablauf der Scripte ist die Eintragung der korrekten Umgebungsvariablen in $SUPERX_DIR/db/bin/SQL_ENV bzw. $SUPERX_DIR\db\bin\sql_env.bat. Wenn der Client jdbc verwendet wird, muss ausserdem die korrekte DB_PROPERTIES gesetzt sein.
Die Umgebungssteuerung: SQL_ENV
Das Script $SUPERX_DIR/db/bin/SQL_ENV steuert die Umgebung und ist für den Betrieb der Scripte unverzichtbar. Einige Variablen sind vorbelegt, Beispiele sind auf Kommentar gesetzt. Da die Umgebung von dem System abhängt, muss jeder Anwender die Werte manuell pflegen. Bei einem Update des SuperX-Kernmoduls wird diese Datei nicht überschrieben, lediglich sein SQL_ENV.sam im gleichen Verzeichnis. Von dort müssen relevante Änderungen dann in die "richtige" SQL_ENV manuell übernommen werden. Informix- und Postgres-spezifische Variablen sind in dem Kapitel zur Installation und Konfiguration der Datenbankserver beschrieben. Folgende Variablen sind auf jeden Fall zubelegen:
| SUPERX_DIR | Der Installationspfad von SuperX |
| DATABASE | Das Datenbanksystem ("POSTGRES" / "INFORMIX") |
| DBNAME | Der Name der Datenbank (standardmäßig "superx"). |
| SX_CLIENT | Die Clientanwendung (bei Postgres "psql", bei Informix "dbaccess"). Ein client namens "jdbc" ist generisch und dient dem Zugriff auf beliebige DB-Systeme, für die jdbc-Treiber existieren. Der jdbc-Client wurde bisher mit Informix, Postgres und hsqldb getestet – die jdbc-Treiber für Informix und Postgres werden mitgeliefert und dürfen auf keinen Fall durch andere ersetzt werden. |
| MAILPROG | Das Mailprogramm unter UNIX, z.B. mutt oder mailx; dies muss sich im PATH des users superx befinden. |
| LOGMAIL/ERRORMAIL | Die superx-weite Mailadresse, an die Logdateien von ETL-Scripten geschickt werden. |
| JAVA_HOME | Installationspfad der Java-Runtime. Das Unterverzeichnis bin muss in den PATH aufgenommen werden. |
| JAVA_OPTS | Java-Runtime-Optionen, z.B. RAM JAVA_OPTS="-Xmx200M -Djava.awt.headless=true" |
| CATALINA_OPTS | Tomcat-Runtime-Optionen, z.B. RAM JAVA_OPTS="-Xmx400M -Djava.awt.headless=true -DSuperX-DB-PROPERTIES-SET=true" |
| DB_PROPERTIES | Der Pfad zur DB_PROPERTIES, standardmäßig $SUPERX_DIR/webserver/ tomcat/webapps/superx/WEB-INF/db.properties |
| EDUSTORE_XML_GENERATE | Die edustore.xml wird für outline|Saiku verwendet und beinhaltet die Würfel und Dimensionen, welche angezeigt werden. Bei einem Upgrade kann diese mit allen verfügbaren Daten gefüllt werden. Dafür wird dann diese Variable auf „true“ gesetzt. Bei manueller Anpassung der edustore.xml, diese Variable auf „false“ setzen. |
| MANDANTID | Mandantennummer (Hochschulnummer) bei mandantefähigen Installationen |
| Die folgenden Umgebungsvariablen sind nur für den JDBC-Client sowie für Postgres relevant: | |
| LOGGING_PROPERTIES | Logging-Parameter für den jdbc-Client. Voreingestellt ist "WARNING", mehr Ausgaben erhält man mit "FINE" |
| PG_HOST | Name des Postgres-Servers (für Postgres unter Windows) |
| Die folgenden Umgebungsvariablen werden wahrscheinlich nicht geändert (sollten sie auch nicht): | |
| DBDELIMITER | Standardmäßig "^" |
| PATH | Der PATH wird erweitert um das Verzeichnis ./:$SUPERX_DIR/db/bin |
| JDBC_CLASSPATH | Der Pfad zu den relevanten jdbc-Treibern und Hilfsprogrammen. |
| XML_CLASSPATH | Der Pfad zu den XML-Tools (Xalan, Xerces & co). |
| FM_DEBUG | Wenn FM_DEBUG = true gesetzt wird, werden bei Freemarker Scripten von DOSQL die *.tmp.sql-Dateien nicht gelöscht. |
Die Datei sollte unter UNIX in jedem Aufruf der shell "gesourced" werden, z.B. durch den Befehl:
. ~/db/bin/SQL_ENV
(Leerzeichen zwischen Punkt und Tilde!) in der Datei ~/.bashrc.
Wenn Sie unter Windows den jdbc-Client nutzen, dann müssen Sie die Datei als erstes in der DOS-Shell aufrufen, bzw. in definierten Tasks am Anfang aufrufen.
Nutzung der SQL_ENV unter HISinOne-BI
Die SuperX Shellscripte lassen sich auch in der HISinOne-BI unter Linux nutzen. In der Distribution befindet sich eine Beispiel-SQL_ENV für die Nutzung in HISinOne: webapps/superx/WEB-INF/conf/edustore/db/bin/SQL_ENV_his1.sam Der Unterschied ist in der Verzeichnisstruktur: Unter SuperX gibt es den Ordner $SUPERX_DIR, der normalerweise ganz oben liegt, z.B. in /home/superx. Unter HISinOne liegt der Ordner unterhalb der Webanwendung, z.B. in /var/lib/tomcat7/webapps/superx/WEB-INF/conf/edustore Weiterhin muss man die Umgebungsvariable WEBAPP umsetzen, z.B.: SuperX: /home/superx/webserver/tomcat/webapps/superx HISinOne: /var/lib/tomcat7/webapps/superx
Allgemeine Scripte
DOSQL DOQUERY sx_transform Propadmin
Zum Absetzen beliebiger SQL-Kommandos werden die Befehle DOSQL und DOQUERY genutzt.
DOSQL
Shellvariablen setzen und SQL-Anweisung(en) in der der Datei (als Parameter) in der SuperX-Datenbank ausfuehren.
| Syntax | DOSQL "Dateiname mit sql-Anweisung(en)" header (true,false)(optional) Ausgabedatei(optional) |
| Beispiel | DOSQL "/home/superx/db/isql/test.sql" false "^" output.txt |
Das Ergebnis kann mit Feldüberschriften (header=true) in eine Datei Ausgabedatei ausgegeben werden. Wenn FM_DEBUG = true gesetzt wird, werden bei Freemarker Scripten von DOSQL die *.tmp.sql-Dateien nicht gelöscht.
DOQUERY
Shellvariablen setzen und eingegebene SQL-Anweisung (als Parameter) in der SuperX-Datenbank ausfuehren.
| Syntax | DOQUERY "sql-Anweisung" header (true,false)(optional) Delimiter(optional) Ausgabedatei(optional) |
| Beispiel | DOQUERY "select name from userinfo" false "^" output.txt |
Das Ergebnis kann mit Feldüberschriften (header=true) in eine Datei Ausgabedatei ausgegeben werden.
sx_transform
Transformiert eine xml-Datei mit einer übergebenen XSL-Datei und gibt das Ergebnis in einen Ausgabekanal aus (stdout oder Datei). Dabei wird der in SuperX integrierte XML-Parser Xerces und der XML-Prozessor Xalan benutzt.
| Syntax | sx_transform.x IN:<xml-Datei> -XSL:<xsl-Datei> -OUT:<Ausgabedatei> -method:<Ausgabeformat (text, xml,html,rtf,pdf)>(optional) <Parameter>(optional) |
| Beispiel | sx_transform.x -IN:myxml.xml -XSL:myxsl.xsl -OUT:output.htm -method:html |
Als Parameter kann ein spezielles Ausgabeformat gewählt werden, z.B. TEXT (siehe Xalan-Doku). Bei rtf wird der RTF-Construktor Jfor auferufen, bei pdf wird FOP aufgerufen. Die *.fo-Datei wird nach tmp.fo geschrieben und dann nach pdf transformiert. Wir gehen also nich davon aus, dass .fo-Dateien die Eingabequellse darstellen.
Propadmin
Der PropAdmin ist ein kleines Werkzeug, um den Zugriff auf jdbc-Datenbanken zu testen und die Verbindungsparameter in einer übergebenen properties-Datei zu sichern. Wenn keine graphische Umgebung eingerichtet ist, müssen Sie die alle Verbindungsparameter manuell in die db.properties eintragen. Nur das Passwort kann mit dem propadmin bearbeitet werden.
(Musterdateien für Postgres und Inofrmix liegen vor in
$SUPERX_DIR/webserver/tomcat/webapps/superx/WEB-INF/db-postgres.properties bzw. db-informix.properties). Wenn als weiterer Parameter kein Dateiname übergeben wird, dann wird die Umgebungsvariable DB_PROPERTIES ausgewertet.
| Syntax UNIX | propadmin.x -nogui(optional) <Dateipfad zu db.properties>(optional) |
| Syntax DOS | propadmin.bat <Dateipfad zu db.properties>(optional) |
Wenn die Default-Dateiencodierung der aktiven Locale für die Passwort-Verschlüsselung nicht ausreicht, wird eine Fehlermeldung ausgegeben. Unter Windows / DOS ist die Vorbelegung Cp1252 bei deutscher Codepage ausreichend, unter Unix wird die deutsche Locale benötigt.
Codierung in ISO und UTF-8
sx_show_encoding.x sx_recode_iso2utf.x sx_recode_utf2iso.x sx_list_isofiles.x sx_recode_isofiles.x sx_list_utf8files.x sx_recode_utf8files.x
Ältere Systeme arbeiten in der Regel mit der Zeichencodierung ISO-8859-1 bis ISO-8859-9. Dieser Zeichensatz wird auch LATIN-1 genannt. Die UNIX-Locale de_DE@euro entspricht z.B. ISO-8859-9 und enthält das EUR-Symbol.
Mit dem Wechsel von ISO-Codierung zu UTF8 bleibt oft der Bedarf bestehen, Dateien hin- und herzucodieren. Seit es, weil beim Entladen aus einer entfernten Datenbank noch das ISO-System genutzt wird, oder bei der Migration eines Systems. Nach unserer Erfahrung sollten Umlaute in Dateinamen unbedingt vermieden werden.
SuperX bietet unter UNIX Shellscripte zur Erfassung und Änderung der Zeichencodierung (Verzeichnis $SUPERX_DIR/db/bin). Im Wesentlichen werden dabei die Unix-Kommandos file und recode genutzt, die Shellscripte machen den Umgang mit umfangreichen Dateilisten komfortabler. Bei der Verarbeitung von Dateilisten sollte man die Scripte sehr vorsichtig einsetzen, es finden keine Sicherheitsüberprüfungen statt.
| Achtung: nur unter Linux getestet | Die Scripte wurden bisher nur unter Linux getestet, andere UNIXe wie Solaris und AIX11 verhalten sich ggf. anders als erwartet. Daher bitte mit Vorsicht benutzen. |
sx_show_encoding.x
Das Script zeigt die Encodierung einer Datei an.
| Syntax | sx_show_encoding.x <Datei> |
| Beispiel | sx_show_encoding.x $SUPERX_DIR/webserver/tomcat/webapps/superx/WEB-INF/web.xml |
| Ausgabe | /hopme/superx/webserver/tomcat/webapps/superx/WEB-INF/web.xml: XML
ISO |
Das Script nutzt verschiedene UNIX-Tools, je nach System kann die Ausgabe variieren. Bei XML-Dateien wird auch der Dateiinhalt (XML-Header) ausgewertet.
sx_recode_iso2utf.x
Das Script ändert die Encodierung einer Datei von ISO nach UTF-8:
| Syntax | sx_recode_iso2utf.x <Datei> |
| Beispiel | sx_recode_iso2utf.x $SUPERX_DIR/webserver/tomcat/webapps/superx/WEB-INF/web.xml |
| Ausgabe | --keine-- |
Das Script nutzt das UNIX-Kommando recode. Darüberhinaus werden bei XML-Dateien auch die XML-Header "encoding=..." geändert, so wird z.B. aus
<?xml version="1.0" encoding="ISO-8859-1"?>
der Header
<?xml version="1.0" encoding="UTF-8"?>
Andere Inhalte der Datei unterhalb der ersten Zeile werden keinesfalls geändert.
sx_recode_utf2iso.x
Das Script ändert die Encodierung einer Datei von ISO nach UTF-8:
| Syntax | sx_recode_utf2iso.x <Datei> |
| Beispiel | sx_recode_utf2iso.x $SUPERX_DIR/webserver/tomcat/webapps/superx/WEB-INF/web.xml |
| Ausgabe | --keine-- |
Das Script nutzt das UNIX-Kommando recode. Darüberhinaus werden bei XML-Dateien auch die XML-Header "encoding=..." geändert, so wird z.B. aus
<?xml version="1.0" encoding="UTF-8"?>
der Header
<?xml version="1.0" encoding="ISO-8859-1"?>
Andere Inhalte der Datei unterhalb der ersten Zeile werden keinesfalls geändert.
sx_list_isofiles.x
Das Script listet alle ISO-Dateien im übergebenen Verzeichnis auf (inkl. Unterverzeichnisse).
| Syntax | sx_list_isofiles.x <Pfad> |
| Beispiel | sx_list_isofiles.x webserver/tomcat/webapps/superx/WEB-INF |
| Ausgabe | webserver/tomcat/webapps/superx/WEB-INF/lib/LocalStrings_de.properties
webserver/tomcat/webapps/superx/WEB-INF/lib/hierhin_den_informix_treiber_kopieren.txt [...] webserver/tomcat/webapps/superx/WEB-INF/db.properties |
Die Ausgabe kann in eine Datei umgeleitet werden, welche wiederum für das Script sx_recode_isofiles.x als Eingabedatei genutzt werden. sx_list_isofiles.x webserver/tomcat/webapps/superx/WEB-INF >iso.txt
sx_recode_isofiles.x
Das Script konvertiert alle Dateien in der übergebenen Dateiliste von ISO nach UTF-8:
| Syntax | sx_recode_isofiles.x <Datei> |
| Beispiel | sx_list_isofiles.x iso.txt |
| Ausgabe | --Keine-- |
Die Eingabedatei ist in der Regel die Ausgabe des Scriptes 'sx_list_isofiles.x'.
sx_list_utf8files.x
Das Script listet alle UTF-8-Dateien im übergebenen Verzeichnis auf (inkl. Unterverzeichnisse).
| Syntax | sx_list_utf8files.x <Pfad> |
| Beispiel | sx_list_utf8files.x webserver/tomcat/webapps/superx/WEB-INF |
| Ausgabe | webserver/tomcat/webapps/superx/WEB-INF/lib/LocalStrings_de.properties
webserver/tomcat/webapps/superx/WEB-INF/lib/hierhin_den_informix_treiber_kopieren.txt [...] webserver/tomcat/webapps/superx/WEB-INF/db.properties |
Die Ausgabe kann in eine Datei umgeleitet werden, welche wiederum für das Script sx_recode_utf8files.x als Eingabedatei genutzt werden. sx_list_isofiles.x webserver/tomcat/webapps/superx/WEB-INF >utf.txt
sx_recode_utf8files.x
Das Script konvertiert alle UTF-8 Dateien in der übergebenen Dateiliste von UTF-8 nach ISO:
| Syntax | sx_recode_utf8files.x <Datei> |
| Beispiel | sx_recode_utf8files.x utf.txt |
| Ausgabe | --Keine-- |
Die Eingabedatei ist in der Regel die Ausgabe des Scriptes sx_list_utf8files.x.
Umgang mit Tabellen
sx_unload_table sx_upload_table sx_upload_records sx_schema
In SuperX werden ständig Tabellen erstellt / geladen / entladen. Zu diesem Zweck wurden Shellscripte entwickelt.
sx_unload_table
Entlädt die Inhalte der Tabelle nach <<Dateiname>>(optional) oder <<name>>.unl
| Syntax | sx_unload_table.x <<name>> <<Dateiname>>(optional) |
| Beispiel | sx_unload_table.x userinfo |
sx_upload_table
Löscht die Inhalte der Tabelle <<name>>, und lädt die Inhalte einer Datei in die Tabelle mit sx_upload_records. Wenn kein Dateiname übergeben wurde, wird als Name <<name>>.unl angenommen.
| Syntax | sx_upload_table.x <<name>> <<Dateiname>>(optional) |
| Beispiel | sx_upload_table.x userinfo |
sx_upload_records
Lädt die Inhalte einer Datei in die Tabelle, ohne vorherige Inhalte zu löschen. Wenn kein Dateiname übergeben wurde, wird als Name <<name>>.unl angenommen.
| Syntax | sx_upload_records.x <<name>> <<Dateiname>>(optional) |
| Beispiel | sx_upload_records.x userinfo |
Bei Postgres als DB-System wird eine Java-Klasse (de.superx.bin.UnlFileConverter) aufgerufen, die die Unload-Datei entsprechend einer Spezifikation aufbereitet (siehe $SUPERX_DIR/db/conf/unldescr*). Wenn der jdbc-Client benutzt wird, können umfangreiche Parameter übergeben werden (Import mit Spaltenüberschriften, Ausgabe von Fehlerprotokollen). Vergleichen Sie die Kommentare im Script.
sx_schema
Entlädt das Schema einer Tabelle in einem vorgegebenen Format.
| Syntax | ids|ansi|xml|HIS))>(optional) <Ausgabedatei> (optional) |
| Beispiel | sx_schema.x userinfo ids myschema.sql |
| Die Formate | Die Formate sind entweder sql-Scripte für die jeweiligen Datenbanktypen (Postgres, Informix, ANSI), die aus der Umgebungsvariable DATABASE ausgelesen werden, oder xml bzw. ein xml-Format in Anlehnung an die Datenbank-DTD der HIS GmbH. |
Modulverwaltung
Bisherige SuperX-Implementationen sind an den Hochschulen entstanden und haben dementsprechend eine große Vielfalt von Update-Scripten, die jeweils die Vorlieben und Bedingungen der jewieligen Hochschule wiederspiegeln. Daraus ergibt sich für "Neulinge" ein sehr verwirrendes Bild. Außerdem gestaltet sich der Entwurf eines Moduls recht aufwändig, weil die ETL-Funktionen (Extraction -> Transformation -> Loading) manuell programmiert werden müssen. Eine weitere Anforderung ist, daß SuperX auf zwei Datenbankplattformen lauffähig sein muss, Informix und Postgres. Das Ergebnis ist: SuperX ist (auf Datenbankseite) sehr fehleranfällig, schwer wartbar und praktisch nicht updatebar. Mit SuperX Version 2.1 wurde die Verwaltung der Module (Installieren / Aktualisieren / sichern und die zugehörogen Logdateien) in zentrale Shellscripte verlagert, die sich ebenfalls in $SUPERX_DIR/db/bin befinden. Die Shellscripte sind dabei nur die operativen "Hüllen" um die eigentlichen SQL-Scripte. Diese wiederum werden zum Teil "von Hand" erzeugt (um z.B. hochschulspezifische Erweiterungen oder Anpassungen vorzunehmen), und zum Teil automatisch aus einer zentralen Steuerdatei ($SUPERX_DIR/db/module/<<Modulname>>/conf/<<Modulname>>.xml) jeweils für Postgres und Informix erzeugt.
module_scripts_create.x
Das Script erzeugt die Installationsdateien für ein Modul, jeweils für Postgres und Informix, nach dem Schema
<<Modulname>>_<<Scriptaktion>>_<<Kürzel für Datenbanksystem>>.sql
Z.B. wird für das BAU-Modul aus der Datei $BAU_PFAD/conf/bau.xml das Script bau_load_pg.sql erzeugt, das die Rohdaten unter Postgres lädt, oder die Datei bau_trans_ids.sql für das Script, das die Bau-Tabellen unter Informix transformiert
| Syntax | module_scripts_create.x <<Modulename>> <<Modulpfad>> <<Datenbanksystem(optional)>> <<Versionsnr.(optional)>> |
| Beispiel | module_scripts_create.x BAU $BAU_PFAD INFORMIX 1.0 |
Im Grunde handelt es sich um XML-Transformationen. Die Stylesheets für dieses Script befinden sich im Verzeichnis $SUPERX_DIR/db/conf, und die XML-Datei für das Module in $SUPERX_DIR/db/module/<<Modulname>>/conf. Wenn die Datei nicht gefunden wird, bricht das Script ab. Die folgende Abbildung zeigt die Arbeitsweise:
| Das Script module_scripts_create.x |
module_install.x
Installiert ein Modul <<Modulname>> in der Datenbank, wobei die Installationsdateien sich im <<Modulpfad>> befinden.
| Syntax | module_install.x <<Modulename>> <<Modulpfad>> |
| Beispiel | module_install.x BAU $BAU_PFAD |
module_drop.x
Löscht die Komponenten eines Moduls <<Modulname>> in der Datenbank, wobei die Installationsdateien sich im <<Modulpfad>> befinden.
| Syntax | module_drop.x <<Modulename>> <<Modulpfad>> |
| Beispiel | module_drop.x BAU $BAU_PFAD |
Entladen
Das Entladescript lautet $SUPERX_DIR/db/module/<<Komponentenname>>/rohdaten/<<Komponentenname>>_unload.x. Die Entladeparameter werden in folgender Datei festgelegt:
$SUPERX_DIR/db/module/<<Komponentenname>>/rohdaten/<<Komponentenname>>_ENV
Entladeroutine bei mandantenfähigen Installationen:
$SUPERX_DIR/db/module/<<Komponentenname>>/rohdaten<<Mandantid>>/<<Komponentenname>>_ENV
Dokumentation zu den jew. Parametern finden Sie in den jeweiligen Administrationshandbüchern der Module. Meist kann man Start-Semester oder -Jahre für das Entladen festlegen. Immer muß man auch das Datenbank-Vorsystem festlegen (Hostname, Kennung etc) sowie, bei HIS-Systemen, die Versionsnummer.
module_etl.x
Aktualisiert ein Modul <<Modulname>> in der Datenbank, wobei die Installationsdateien sich im <<Modulpfad>> befinden.
| Syntax | module_etl.x <<Modulename>> <<Modulpfad>> |
| Beispiel | module_etl.x bau $BAU_PFAD |
Die folgende Abbildung zeigt, wie die Komponenten zusammenhängen (klicken Sie auf die Grafik, um sie zu vergrößern):
| Das Modul wird zunächst nach $MODULPFAD/tmp gesichert, danach werden die Rohdaten geladen, die Daten vorbereitet, transformiert, und nachbereitet. Danach werden die Hilfstabellen erzeugt und, bei erfolgreichem durchlaufen, das Standdatum aktualisiert. | 
|
Bei Fehlern im ETL-Prozeß wird die Sicherung wiederhergestellt, und eine Mail an den Administrator verschickt. Außerdem werden die übernommenen Daten überprüft; wenn z.B. Schlüssel fehlen oder Rohdaten falsch zu sein scheinen, wird dies als Attachment an die Log- oder Fehlermail angehängt. In der Praxis wird dieses Script nicht direkt von Cronjobs ausgeführt, sondern von einem Shellscript, das vorher die Umgebung einrichtet. Das folgende Beispiel zeigt das Update-Script für Bau unter Informix:
| bau_update.x | #!/bin/sh
. /home/superx/db/bin/SQL_ENV |
Weil Buisy mit "," als Dezimaltrenner arbeitet, wird ausnahmsweise DBMONEY auf "," gesetzt. Außerdem ist es möglich, für jedes Modul unterschiedliche Mailadressen zuzuweisen. Die Mailadressen werden in der SQL_ENV eingetragen. Im allgemeinen ETL-Prozeß wird standardmäßig auch die Tabelle protokoll in einem festzulegendem Rhythmus (Konstante Löschung Protokoll (Tage)) gelöscht. Beim Vorgabewert 90 werden bei jeder ETL-Routine Einträge, die älter als 90 Tage sind, gelöscht.
Hochschulspezifische Transformationen im ETL-Prozeß
Zusätzlich lassen sich im ETL-Prozeß hochschulspezifische Scripte ausführen (und überwachen). Dazu müssen Dateien mit einem gewissen Namensschema im Stammverzeichnis des Moduls vorhanden sein. Es gibt einen vereinfachten und einen erweiterten Modus für hochschulspezifische Transformationen.
| Einfacher Modus | Wenn im Modulpfad die Datei "preparation.sql" existiert, wird sie nach dem LOAD-Schritt ausgeführt.
Wenn im Modulpfad die Datei "finalize.sql" existiert, wird sie nach dem TRANS-Schritt ausgeführt.
|
| Erweiterter Modus: Mandantenspezifische Scripte |
Wenn im Modulpfad Dateien nach dem Schema <<Modulname>>_<<ETL-Schritt>>_<<Mandatennr.>>.sql |
Der erweiterte Modus erlaubt die beliebige Anpassung eines Modus an eigene Bedürfnisse, z.B. Schlüsselumsetzung o.ä. Gleichzeitig erlaubt er einen echten mandentenfähigen Betrieb der ETL-Scripte.
Logging der Shellscripte
Hinweis: bei mandantenfähigen Installationen steht vor der Endung .log immer die MandantID.
Installation / Upgrade
Fürs Kernmodul lauten die Dateien bei der Installation: $SUPERX_DIR/db/install/L_*.log Beim Upgrade: $SUPERX_DIR/db/install/upgrade.log Für alle anderen Komponenten: $SUPERX_DIR/db/module/<<Komponentenname>>/L_<<Komponentenname>>_<<Installationsschritt>>.log
Laderoutinen
Für alle Module sind die Dateien wie folgt benannt: Entladeroutine: $SUPERX_DIR/db/module/<<Komponentenname>>/rohdaten/<<Komponentenname>>_unload.err Entladeroutine bei mandantenfähigen Installationen: $SUPERX_DIR/db/module/<<Komponentenname>>/rohdaten<<Mandantid>>/<<Komponentenname>>_unload.err
Laderoutine: $SUPERX_DIR/db/module/<<Komponentenname>>/L_<<Komponentenname>>_<<Ladeschritt>>.log • wobei <<Ladeschritt>> wie folgt aufgebaut ist: • 1. Unload (Entladen aus Vorsystem) • 2. Load (CSV-Upload) • 3. Transformation (Schlüsselharmonisierung, Prüfroutinen) • 4. Aggregation (Aufbau der Hilfstabellen) • 5. System (Ladedatum aktualisieren, Datenbank-Wartung) Wenn die Laderoutine erfolgreich ist, werden alle Schritte hintereinander ausgeführt und geloggt. Wenn nicht, dann wird der jew. Schritt zuende geführt, und dann die Laderoutine gestoppt. Wenn also z.B. beim LOAD ein Fehler auftritt, dann wird der Schritt "Transformation" gar nicht erst begonnen. So ist sichergestellt daß die Auswertungen trotz Fehler laufen.
Debugging von Freemarker Scripten
Da die Laderoutinen oft mit Freemarker Scripten arbeiten, werden diverse SQL-Scripte nur zur Laufzeit generiert und ausgeführt, und danach wieder gelöscht. Um die Laderoutinen transparenter "beobachten" zu können, können Sie die die Löschung der Scripte mit dem Parameter FM_DEBUG="true" export FM_DEBUG Wenn FM_DEBUG = true gesetzt wird, werden bei Freemarker Scripten von DOSQL die *.tmp.sql-Dateien nicht gelöscht. Sie können den Parameter in der aktuellen Shell setzen, oder permanent in der outline|SQL_ENV.
Masken-Verwaltung
Die Masken-Verwaltung ist detailliert im 'Entwicklerhandbuch SuperX' beschrieben. Hie rnur ein paar Hinweise zur Verwaltung der Masken. Zum Erzeugen und Verändern von Masken gibt es unter UNIX eine Kommandoschnittstelle, die auf dem Gebrauch folgender Skripte beruht. Die Skripte stehen unter dem Verzeichnis $SUPERX_DIR/db/masken
und erzeugen oder verwenden Dateien in dem gegenwärtigen Arbeitsverzeichnis. Nach dem Einspielen der Datenbank sollten Sie darauf achten, den Dateien Ausführungsberechtigung (chmod 750 sx_*) zu geben.
Eine Maske suchen
Wenn Sie eine Maske suchen, sollten die die Felder tid oder name in der Tabelle maskeninfo durchsuchen. Das folgende Script macht dies automatisch: sx_search_mask
| Aufruf: | sx_search_mask <String> |
| Aktion: | sx_search_mask sucht die Masken, deren Name <String> enthält |
| Ausgabe: . | tid, name der gefundenen Masken |
Eine Maske sichern und entladen
Um eine Maske zu sichern, müssen Sie die entsprechenden Einträge in den Tabellen
- felderinfo,
- masken_felder_bez,
- maskeninfo,
- sachgeb_maske_bez,
- maske_system_bez
selektieren und sichern. Für dies gibt es das Script sx_select_mask. sx_select_mask
| Aufruf: | sx_select_mask <TID> |
| Aktion: | sx_select_mask entlädt alle Metadaten aus den Tabellen maskeninfo, felderinfo, masken_felder_bez, sachgeb_maske_bez, maske_system_bez zur Maske mit tid = <TID>. |
| Ausgabe: | Fünf Dateien:
|
Eine Maske neu einfügen
Um eine Maske neu einzufügen, müssen Sie die entsprechenden Einträge in den Tabellen
- felderinfo,
- masken_felder_bez,
- maskeninfo,
- sachgeb_maske_bez,
- maske_system_bez
einfügen. Dafür gibt es das Script sx_insert_mask.
sx_insert_mask
| Aufruf: | sx_insert_mask <TID> [<neue TID>] [j] |
| Aktion: | sx_insert_mask lädt den Inhalt der fünf Dateien
in die jeweiligen Tabellen der SuperX-Datenbank. Mit "j" wird die Sicherheitsabfrage umgangen. |
Falls <neue TID> nicht angegeben wird, werden die Metadaten wieder mit der alten TID in die Datenbank eingespielt (=Update). Falls <neue TID> angegeben wird, werden die Metadaten mit der neuen TID in die Datenbank eingespielt (=Insert). Dabei werden alle TIDs in den abhängigen Tabellen angepasst. So können Masken sehr einfach kopiert werden. Eine neue TID bekommt man durch die Wahl der nächsten Zehnerzahl, die größer als die größte vorkommende Nummer ist. Die größte vorkommende Nummer erhält man durch Ausführung des folgenden SQL-Ausdrucks mit Hilfe des Kommandos DBACCESS: select max(tid) from maskeninfo;
| ! | Um den Austausch von Abfragen innerhalb der Hochschulen zu erleichtern ("Abfragen-Pooling" über die SuperX-Website), sollten die Masken immer im Nummernkreis xxxx0000 bis xxxx9990 liegen, wobei xxxx der von der HIS verwandten Hochschulnummer entspricht. Die Zehnerschritte ergeben sich daraus, dass die dazwischen liegenden Nummern für die Maskenfelder (Tabelle felderinfo) reserviert sind[1]. |
Wie im Abschnitt 'Userverwaltung' beschrieben, kann die neue Maske Benutzern oder Gruppen zugänglich gemacht werden.
Eine Maske löschen
Um eine Maske zu löschen, müssen Sie die Einträge in den oben genannten Tabellen entfernen. Dafür gibt es das Script sx_delete_mask sx_delete_mask
| Aufruf: | sx_delete_mask <TID> |
| Aktion: | sx_delete_mask löscht alle Metadaten aus den Tabellen maskeninfo, felderinfo, masken_felder_bez, sachgeb_maske_bez und maske_system_bez zur Maske mit tid = <TID>. |
Änderungen an einer Maske vornehmen
1. Selektieren der Metadaten der betreffenden Maske: sx_select_mask <TID> 2. Editieren der fünf Metadaten-Dateien ,,<TID>_..." 3. Abspeichern der neuen Metadaten: sx_insert_mask <TID>
Ausführen von JasperReports
Neben der Ausführung im Browser gibt es eine "Kommandozeilenversion" des Aufrufs: sx_jasper.x
| Aufruf: | sx_jasper.x -JRXML:<JRXML-Datei> -XML:<Datei mit XML-Datenquelle> -db_properties:Pfad_zur_db.properties -IGNORE_PAGINATION:<true oder false> und optional -JASPER:<Jasper-Datei> -JRPRINT:<Jrprint-Datei> -OUT:<Ausgabedatei> |
| Aktion: | sx_jasper.x führt einen JasperReports-Task aus. Die Datenquelle kann entweder xml sein (Parameter -XML), oder eine Datenbankverbindung in der Datei db.properties. Das Ergebnis wird in eine Datei <Ausgabedatei> ausgegeben.
Wenn keine Ausgabedatei angegeben wird, wird der jrxml-Dateiname verwendet, und eine PDF-Ausgabe erzeugt. |
XSL-Transformation
Neben der Ausführung im Browser gibt es eine "Kommandozeilenversion" des Aufrufs: sx_transform.x
| Aufruf: | sx_transform.x -IN:<xml-Datei> -XSL:<xsl-Datei> -OUT:<Ausgabedatei> -method:<Ausgabeformat (text,xml,html,pdf,rtf)>(optional) -param:<Parameter>(optional) |
| Aktion: | sx_transform.x transformiert eine XMl-Datei via XSL. Wenn pdf als Ausgabeformat angegeben ist, dann wird eine PDF-Datei erzeugt. |
- ↑
Aus historischen Gründen liegen die Nummern aus Karlsruhe im Bereich 0-9990, aus Duisburg im Bereich 10000-19990.
