Aktuelle Version vom 9. September 2026, 14:23 Uhr

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 in der 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 Kernmodul-Scripte unverzichtbar. Bei einem Update des SuperX-Kernmoduls wird die vorhandene SQL_ENV nicht überschrieben. Änderungen der ausgelieferten SQL_ENV.sam müssen deshalb geprüft und bei Bedarf manuell in die produktive SQL_ENV übernommen werden.

Ab Kernmodul 6.0 liegt $SUPERX_DIR innerhalb der SuperX-Webanwendung:

WEBAPP=/home/superx/webserver/tomcat/webapps/superx
SUPERX_DIR=$WEBAPP/WEB-INF/conf/edustore
export WEBAPP SUPERX_DIR

Folgende Variablen müssen geprüft und passend zur Installation gesetzt werden:

Variable	Erläuterung
WEBAPP	Wurzelverzeichnis der SuperX-Webanwendung
SUPERX_DIR	Datenbank- und Modulbereich unter $WEBAPP/WEB-INF/conf/edustore
DATABASE	Datenbanksystem; für SuperX ist POSTGRES einzutragen
DBNAME	Name der SuperX-Datenbank, standardmäßig superx
SX_CLIENT	Verwendeter Datenbankclient; möglich sind psql oder jdbc
DB_PROPERTIES	Pfad zur db.properties, standardmäßig $WEBAPP/WEB-INF/db.properties
JAVA_HOME	Installationspfad der Java-Runtime; für Kernmodul 6.0 wird OpenJDK 17 verwendet
JAVA_OPTS	Java-Optionen für Kernmodul-Shellscripte wie DOSQL, DOQUERY und die Upgrade-Scripte
CATALINA_OPTS	Java-Optionen für einen manuell installierten oder mit SuperX betriebenen Tomcat
MAILPROG	Mailprogramm unter UNIX, beispielsweise s-nail oder mailx
LOGMAIL/ERRORMAIL	Mailadressen für Log- und Fehlermeldungen der ETL-Scripte
LOGGING_PROPERTIES	Logging-Konfiguration des JDBC-Clients
PGHOST	Hostname des PostgreSQL-Servers
DBDELIMITER	Trennzeichen für Unload-Dateien, standardmäßig ^
JDBC_CLASSPATH	Classpath der JDBC-Treiber, Klassen und benötigten Jakarta-Bibliotheken
XML_CLASSPATH	Classpath der XML-Werkzeuge
FM_DEBUG	Wenn FM_DEBUG=true gesetzt wird, bleiben die von DOSQL erzeugten temporären SQL-Dateien zur Fehlersuche erhalten

Java-Optionen für Kernmodul 6.0

Die Java-Optionen werden an dieser Stelle zentral dokumentiert. Andere Artikel sollen auf diesen Abschnitt verweisen, damit die Konfiguration nicht mehrfach gepflegt werden muss.

Tragen Sie folgenden vollständigen Block in die SQL_ENV ein. Bei einem Tomcat aus den Ubuntu- oder Debian-Paketen wird derselbe Block in /etc/default/tomcat10 verwendet. Passen Sie die Speicherwerte an die Größe des Servers an:

WEBAPP=/home/superx/webserver/tomcat/webapps/superx
SUPERX_DIR=$WEBAPP/WEB-INF/conf/edustore
JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
JAVA_OPTS="-Xms1024M -Xmx2520M -Djava.awt.headless=true -Dfile.encoding=UTF-8 -Duser.country=DE -Duser.language=de -Duser.region=DE -Duser.timezone=Europe/Berlin -Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false -DSuperX-DB-PROPERTIES-SET=true -DMODULE_PFAD=$SUPERX_DIR/db/module -DSUPERX_DIR=$SUPERX_DIR -Djava.locale.providers=COMPAT,CLDR -XX:+UseG1GC --add-opens java.naming/com.sun.jndi.ldap=ALL-UNNAMED --add-opens java.base/sun.nio.ch=ALL-UNNAMED --add-opens java.base/sun.net.www.protocol.jar=ALL-UNNAMED --add-opens java.base/javax.crypto=ALL-UNNAMED --add-opens java.base/java.util.stream=ALL-UNNAMED --add-opens java.base/java.util=ALL-UNNAMED --add-opens java.base/java.net=ALL-UNNAMED --add-opens java.base/java.io=ALL-UNNAMED --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.math=ALL-UNNAMED"
export WEBAPP SUPERX_DIR JAVA_HOME JAVA_OPTS

Wenn der eigene Tomcat CATALINA_OPTS verwendet, tragen Sie stattdessen folgenden vollständigen Block in dessen Startumgebung ein:

WEBAPP=/home/superx/webserver/tomcat/webapps/superx
SUPERX_DIR=$WEBAPP/WEB-INF/conf/edustore
JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
CATALINA_OPTS="-Xms1024M -Xmx2520M -Djava.awt.headless=true -Dfile.encoding=UTF-8 -Duser.country=DE -Duser.language=de -Duser.region=DE -Duser.timezone=Europe/Berlin -Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false -DSuperX-DB-PROPERTIES-SET=true -DMODULE_PFAD=$SUPERX_DIR/db/module -DSUPERX_DIR=$SUPERX_DIR -Djava.locale.providers=COMPAT,CLDR -XX:+UseG1GC --add-opens java.naming/com.sun.jndi.ldap=ALL-UNNAMED --add-opens java.base/sun.nio.ch=ALL-UNNAMED --add-opens java.base/sun.net.www.protocol.jar=ALL-UNNAMED --add-opens java.base/javax.crypto=ALL-UNNAMED --add-opens java.base/java.util.stream=ALL-UNNAMED --add-opens java.base/java.util=ALL-UNNAMED --add-opens java.base/java.net=ALL-UNNAMED --add-opens java.base/java.io=ALL-UNNAMED --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.math=ALL-UNNAMED"
export WEBAPP SUPERX_DIR JAVA_HOME CATALINA_OPTS

Zusätzliche Optionen für JMX, eigene Truststores oder besondere LDAP-Konfigurationen werden nur bei Bedarf ergänzt. Ungeschützte JMX-Ports und die Deaktivierung von Sicherheitsprüfungen gehören nicht in die allgemeine Standardkonfiguration.

JDBC-Classpath für Tomcat 10

Tomcat 10 verwendet die Jakarta-Servlet-API. Der JDBC_CLASSPATH muss deshalb die Jakarta-Bibliothek und $WEBAPP/WEB-INF/classes enthalten:

JDBC_CLASSPATH="$WEBAPP/WEB-INF/lib_ext/jakarta.servlet-api-6.0.0.jar:$WEBAPP/WEB-INF/classes"
for i in $LIB_PATH/*.jar; do JDBC_CLASSPATH="$JDBC_CLASSPATH:$i"; done
XML_CLASSPATH=$JDBC_CLASSPATH
export JDBC_CLASSPATH XML_CLASSPATH

Ein alter Classpath mit servlet-api.jar kann zu java.lang.NoClassDefFoundError: jakarta/servlet/http/HttpServlet führen.

Die SQL_ENV sollte in jeder Shell geladen werden, in der Kernmodul-Scripte ausgeführt werden:

. $SUPERX_DIR/db/bin/SQL_ENV

Der Aufruf kann beispielsweise in ~/.bashrc oder ~/.profile eingetragen werden.

Nutzung der SQL_ENV unter HISinOne-BI

Die SuperX-Shellscripte lassen sich auch in HISinOne-BI unter Linux nutzen. Eine Beispielkonfiguration befindet sich unter $WEBAPP/WEB-INF/conf/edustore/db/bin/SQL_ENV_his1.sam. Setzen Sie auch dort WEBAPP, SUPERX_DIR, JAVA_HOME, DB_PROPERTIES und den Jakarta-Classpath entsprechend der tatsächlichen Installation.

Normalerweise wird für HISinOne-BI der JDBC-Client verwendet:

SX_CLIENT=jdbc
export SX_CLIENT

Die Datei muss nicht SQL_ENV heißen. Für eine spezielle Konfiguration kann ein ergänzender Name wie SQL_ENV_FHDO verwendet werden.

Datenbank- und SQL-Scripte

PropAdmin

Der PropAdmin ist ein kleines Werkzeug, um den Zugriff auf JDBC-Datenbanken zu testen und die Verbindungsparameter in einer Properties-Datei zu speichern.

Eine Musterdatei für PostgreSQL liegt unter

$WEBAPP/WEB-INF/db-postgres.properties

Für den Aufruf unter Linux wird die zu bearbeitende Properties-Datei über die Umgebungsvariable PROPFILE festgelegt.

Aufruf unter Linux

Wechseln Sie zunächst in das WEB-INF-Verzeichnis der SuperX-Webanwendung:

cd $WEBAPP/WEB-INF

Anschließend setzen Sie die zu bearbeitende Properties-Datei:

export PROPFILE=db_test.properties

Wenn PROPFILE nicht gesetzt ist, verwendet propadmin.x die Umgebungsvariable DB_PROPERTIES.

Danach wird der PropAdmin aufgerufen:

./conf/edustore/db/bin/propadmin.x

Der Dateipfad zur Properties-Datei wird dabei nicht als Parameter an propadmin.x übergeben, sondern über PROPFILE bzw. alternativ DB_PROPERTIES festgelegt.

Beim Aufruf können die Verbindungsparameter wie

driverName
connectionURL
connectionName

bestätigt oder geändert werden. Anschließend kann das Passwort eingegeben und die Datenbankverbindung getestet werden.

Der benötigte JDBC_CLASSPATH ist normalerweise bereits über die SuperX-SQL-Umgebung gesetzt. Falls dies nicht der Fall ist oder beim Aufruf Klassen wie der JDBC-Treiber nicht gefunden werden, kann er beispielsweise folgendermaßen gesetzt werden:

export JDBC_CLASSPATH="$WEBAPP/WEB-INF/classes:$WEBAPP/WEB-INF/lib/*"

Passwort direkt mit CryptUtils verschlüsseln

Soll lediglich ein Passwort im von SuperX verwendeten Format sx_des... erzeugt werden, ist dafür kein vollständiger PropAdmin-Aufruf notwendig. Das Passwort kann direkt über de.memtext.util.CryptUtils verschlüsselt werden.

Je nach Umgebung unterscheidet sich der benötigte Classpath.

HISinOne

In einer HISinOne-Umgebung wechseln Sie in das Verzeichnis

$WEBAPP/WEB-INF/classes

cd $WEBAPP/WEB-INF/classes

Da sich die kompilierte Klasse de.memtext.util.CryptUtils unterhalb dieses Verzeichnisses befindet, kann als Classpath einfach . verwendet werden.

SuperX

In einer SuperX-Umgebung wechseln Sie dagegen in das Verzeichnis

$WEBAPP/WEB-INF/lib

cd $WEBAPP/WEB-INF/lib

Als Classpath wird die SuperX-JAR der installierten Version angegeben, zum Beispiel:

superx6.0.jar

Passwort direkt im Befehl angeben

Für HISinOne:

printf '%s\n' 'System.out.println("sx_des" + de.memtext.util.CryptUtils.encryptStringDES("anfang12"));' '/exit' | jshell -q --class-path .

Für SuperX, beispielsweise mit Version 6.0:

printf '%s\n' 'System.out.println("sx_des" + de.memtext.util.CryptUtils.encryptStringDES("anfang12"));' '/exit' | jshell -q --class-path superx6.0.jar

Die Ausgabe enthält das verschlüsselte Passwort, zum Beispiel:

sx_des#-107#-62#90#114#112#-9#-73#86#116#120#-97#-28#-54#-55#11#8

Der komplette Wert einschließlich sx_des kann anschließend beispielsweise als

connectionPassword=sx_des#...

in eine Properties-Datei eingetragen werden.

Achtung: Bei dieser Variante steht das Klartextpasswort direkt im Shell-Befehl und kann dadurch in der Shell-History gespeichert werden.

Passwort verdeckt einlesen

Um zu vermeiden, dass das Klartextpasswort im Befehl bzw. in der Shell-History erscheint, kann es zunächst verdeckt eingelesen werden:

Für HISinOne:

read -rsp 'Passwort: ' PW; echo
printf '%s\n' 'System.out.println("sx_des" + de.memtext.util.CryptUtils.encryptStringDES(System.getenv("PW")));' '/exit' \
  | PW="$PW" jshell -q --class-path .
unset PW

Für SuperX, beispielsweise mit Version 6.0:

read -rsp 'Passwort: ' PW; echo
printf '%s\n' 'System.out.println("sx_des" + de.memtext.util.CryptUtils.encryptStringDES(System.getenv("PW")));' '/exit' \
  | PW="$PW" jshell -q --class-path superx6.0.jar
unset PW

Das Passwort wird bei der Eingabe nicht auf dem Bildschirm angezeigt. In der Shell-History wird lediglich der Aufruf von read gespeichert, nicht das eingegebene Passwort.

Auch hier wird als Ergebnis das vollständig verschlüsselte Passwort einschließlich des Präfixes sx_des ausgegeben.

Zeichencodierung

Wenn die Default-Dateiencodierung der aktiven Locale nicht ausreicht, kann eine entsprechende Fehlermeldung ausgegeben werden. Unter Windows / DOS ist die Vorbelegung Cp1252 bei deutscher Codepage in der Regel ausreichend; unter Unix wird die deutsche Locale benötigt.

DOSQL

Zum Absetzen beliebiger SQL-Kommandos werden die Befehle DOSQL und DOQUERY genutzt. DOSQL kann 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 
export FM_DEBUG

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.

XML-Scripte

sx_transform.x

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 XSL-Prozessor Saxon benutzt.

Syntax	sx_transform.x -IN:xml-Datei -XSL:xsl-Datei -OUT:Ausgabedatei -method:Ausgabeformat (text, xml,html,rtf,pdf) (optional) -params:Parameter(optional)
Beispiel	sx_transform.x -IN:myxml.xml -XSL:myxsl.xsl -OUT:output.htm -method:html

Als Parameter "method" kann ein spezielles Ausgabeformat gewählt werden, z.B. text (siehe Xalan-Doku). Bei rtf wird der RTF-Construktor Jfor aufgerufen, bei pdf wird FOP aufgerufen. Die *.fo-Datei wird nach tmp.fo geschrieben und dann nach pdf transformiert. Wir gehen also nicht davon aus, dass .fo-Dateien die Eingabequelle darstellen.

Stylesheet Parameter werden mit "," getrennt optional angefügt, z.B.

sx_transform.x -IN:myxml.xml -XSL:myxsl.xsl -OUT:output.htm -method:html  "-params:Jahr=2020,Monat=12"

saxon_transform.x

Wie sx_transform.x transformiert das Script XML via XSLT, hier werden allerdings Saxon-spezifische Parameter ermöglicht.

Syntax	saxon_transform.x xml-Datei xsl-Datei Ausgabeformat (text, xml,html) (optional) Ausgabedatei (optional) Parameter (optional)
Beispiel	sx_transform.x myxml.xml myxsl.xsl output.htm html

Bei pdf wird FOP aufgerufen. Die *.fo-Datei wird nach tmp.fo geschrieben und dann nach pdf transformiert.

Wenn ein XSL-Script mehrere Ausgabedateien erzeugen soll, kann dieses Script ggü. sx_transform.x Vorteile haben.

show_fop_fontlist.x

Zeigt die installierten Fonts für PDF Erzeugung mit XSL-FO an. Das Script hat keine Argumente.

sx_validate.x

sx_validate.x validiert eine XML-Datei

ob sie wohlgeform ist
ob sie zu einem optional übergebenen Schema (XSD-Datei) valide ist.

sx_validate.x XML-Datei SCHEMA-Datei (optional)

sx_xmlfileappender.x

Das Script sx_xmlfileappender.x faßt mehrere XML-Dateien in einem übergebenen Pfad zu eine rDatei mit einem neuen root-Knoten "artificalroot" zusammen.

Aufruf:

sx_xmlfileappender.x Path file(regex oder Dateiname mehrere mit , getrennt) Outputfile

Codierung in ISO und UTF-8

Ä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.

Aktuelle SuperX-Installationen arbeiten in der Regel mit der UTF-8 Codierung, dies wird bei der Installation gesetzt.

Mit dem Wechsel von ISO-Codierung zu UTF8 bleibt oft der Bedarf bestehen, Dateien hin- und herzucodieren. Sei 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.

Die Scripte wurden bisher nur unter Linux mit bash getestet, andere UNIXe wie BSD 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	/home/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

In SuperX werden ständig Tabellen erstellt / geladen / entladen. Zu diesem Zweck wurden Shellscripte entwickelt.

sx_unload_table.x

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.x

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.x

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.x

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 SQL für PostgreSQL oder ANSI sowie XML beziehungsweise ein XML-Format in Anlehnung an die Datenbank-DTD der HIS.

Modulverwaltung

Die Verwaltung der Module, einschließlich Installation, Aktualisierung, Sicherung und Logdateien, erfolgt über zentrale Shellscripte in $SUPERX_DIR/db/bin. Die Shellscripte bilden die operativen Hüllen um die eigentlichen SQL-Scripte. Diese werden zum Teil manuell und zum Teil automatisch aus einer zentralen Steuerdatei erzeugt:

$SUPERX_DIR/db/module/<<Modulname>>/conf/<<Modulname>>.xml

Für PostgreSQL werden daraus die benötigten Installations- und Aktualisierungsscripte erzeugt.

module_scripts_create.x

Das Script erzeugt die Installationsdateien für ein Modul nach dem Schema
<<Modulname>>_<<Scriptaktion>>_<<Kürzel für Datenbanksystem>>.sql Beispielsweise 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 PostgreSQL lädt.

Syntax	module_scripts_create.x -Modulkürzel- -Modulpfad- -Datenbanksystem-
Beispiel	module_scripts_create.x bau $BAU_PFAD POSTGRES

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.

module_install.x

Installiert ein Modul -Modulname- in der Datenbank, wobei die Installationsdateien sich im -Modulpfad- befinden.

Syntax	module_install.x -Modulkürzel- -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 -Modulkürzel- -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 -Modulname- -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):

Zunächst 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 die Administrator_in 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 ein Update-Script für das BAU-Modul:

bau_update.x

 #!/bin/sh
 . /home/superx/webserver/tomcat/webapps/superx/WEB-INF/conf/edustore/db/bin/SQL_ENV
 ERRORMAIL="bau-admin@hochschule.de"
 export ERRORMAIL
 LOGMAIL=$ERRORMAIL
 export LOGMAIL
 module_etl.x bau $BAU_PFAD >$BAU_ERRORDAT 2>&amp;1

Wie Sie sehen ist es möglich, für jedes Modul unterschiedliche Mailadressen zuzuweisen. Die Mailadressen werden systemweit in der [Kernmodul_Shellscripte#Die_Umgebungssteuerung_SQL_ENV|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-Prozess

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 exisitieren, werden diese jeweils nach dem "normalen" ETL-Schritt ausgeführt.

Wenn also z.B. die Datei

$COB_PFAD/cob_trans_70.sql

existiert und in der SQL_ENV die Umgebungsvariable $MANDANTID auf "70" steht, dann wird das Script nach dem normalen Trans-Schritt ausgeführt und nach

L_cob_trans_mandant_70.log

geloggt.

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/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:

Unload (Entladen aus Vorsystem)
Load (CSV-Upload)
Transformation (Schlüsselharmonisierung, Prüfroutinen)
Aggregation (Aufbau der Hilfstabellen)
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 SQL_ENV.

Kettle-Jobs starten

Da Kettle in der Webanwendung integriert ist, können Sie Kettle Jobs auch ohne die PDI-Standalone-Installation per Kommandozeile ausführen. Wenn die SQL_ENV eingerichtet und geladen ist, geben Sie z.B. einfach ein:

 sx_kitchen.x -file "sospos_res1.kjb" -norep

Die Parameter werden direkt an die Java Anwendung "kitchen" weitergereicht, d.h. weitere Dokumentation finden Sie in unserem Kettle-Kurs.

Installation und Wartung

Patch einspielen

Für SuperX können spezielle Patch-Dateien per Kommandozeile installiert werden. Vorbedingung ist, dass die bash und das Paket unzip installiert sind.

patch_apply.x

Das Script entpackt eine übergebene Patch-Datei (zip-File), und installiert die Dateien und DB-Operationen für die jeweils installierten und zum Patch passenden Module. Sie starten es direkt aus dem Patchordner, in dem der zu installierende Patch liegt:

patch_apply.x -PatchFile-

Ein Beispiel:

patch_apply.x patch_2011-06-01_superx_iso.zip

Dabei wird in dem Verzeichnis der Patch entpackt und ausgeführt. Je nach Patch muss auch ein Tomcat Neustart erfolgen, ein entsprechender Hinweis befindet sich in der Patch-Dokumentation. Wenn ein Patch auch Dateien unterhalb von webapps/superx enthält, müssen Sie im Falle von Tomcat Clusterbetrieb den Patch auf alle Tomcat Hosts übertragen, entweder direkt oder mit git / rsync. Weitere Hinweise zum Script finden Sie im Installationshandbuch.

Bei HISinOne-BI funktioniert das patch-apply Script nicht, der Patch mit dem Kürzel "webapps" im Dateinamen wird einfach in webapps/superx entpackt, und in der Regel sollten die jew. Module geupgradet werden. Weitere Hinweise finden Sie in der jew. Patch-Readme.

JasperReports kompilieren

Wenn Sie mit Unterberichten arbeiten, müssen Sie kompilierte .jasper-Dateien einbinden und ausliefern. Da dieser Dateityp normalerweise (und richtigerweise) im ".gitignore" ist, d.h. nicht über git ausgeliefert werden kann, können Sie die Dateien auch direkt auf dem Applikationsserver mit der exakt passenden JR-Version erzeugen. Typischerweise führen Sie das Script im Ordner WEB-INF/reports aus. Der Aufruf:

cd $WEBAPP/WEB-INF/reports
java $JAVA_OPTS -cp "$JDBC_CLASSPATH" de.superx.bin.SxJasperCompiler <JRXML-Datei>

Der Workflow ist wie folgt:

Die Quelldatei.jrxml ist die XML-Beschreibungsdatei des Berichts
Der compile erzeugt aus der Quelldatei.jrxml eine Datei Quelldatei.jasper im gleichen Verzeichnis
Die Quelldatei.jasper ist kompilierte Beschreibungsdatei für den Bericht, und wird in Unterberichten und Booklets genutzt. Weitere Details siehe unser JR-Handbuch.

LDAP User deaktivieren

Ausschließlich für SuperX-Standalone-Anwender können wir im System eine Gültigkeit von UserAccounts und automatisiertes Sperren von LDAP-Usern mit Sperr-Merkmal einbauen. Die Tabelle userinfo und das entsprechende Formular zum Userbearbeiten hat die Merkmale Beginn Gültigkeit (gueltig_von) und Ende Gültigkeit (gueltig_bis), so dass SuperX-Standalone Hochschulen z.B. für befristete Mitarbeiter_innen in der Userverwaltung direkt eintragen können, dass ein Mitarbeiter sich z.B. nach dem 31.12.2024 nicht mehr anmelden können soll. Wenn die Hochschule eine Passwortkontrolle via LDAP macht, kann diese per Script User mit einem entsprechenden Merkmal wie userLocked=true automatisiert zu sperren. Hierfür setzt das Script den Eintrag userinfo.maxVersuch (also die maximal erlaubten Anmeldeversuche) auf 0 gesetzt, als "Ende Gültigkeit" wird das Vortagsdatum eingetragen sowie die Spalte password_sha (verschlüsseltes SuperX-Passwort) geleert.

Aufruf:

sx_ldap_lockout.x Pfad/zu/db.properties pfad/zu/superx_standalone_ldap.properties

Das Script kann nächtlich ausgeführt werden.

Masken-Verwaltung

Die Masken-Verwaltung ist detailliert im Entwicklerhandbuch SuperX beschrieben. Hier nur 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/bin

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 *) 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: <TID>_felderinfo.unl, <TID>_masken_felder_bez.unl, <TID>_maskeninfo.unl, <TID>_sachgeb_maske_bez.unl, <TID>_maske_system_bez.unl

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 <TID>_felderinfo.unl, <TID>_masken_felder_bez.unl, <TID>_maskeninfo.unl, <TID>_sachgeb_maske_bez.unl, <TID>_maske_system_bez.unl 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>

Masken per Kommandozeile

In diversen Szenarien kann es sinnvoll sein, Masken nicht nur im Browser über die Webanwendung auszuführen, sondern über Kommandozeile, also ohne laufenden Tomcat:

Für Entwicklungszwecke kann es praktisch sein, wenn man keinen laufenden Tomcat braucht, und Masken z.B. in Eclipse ausführt und debuggen kann
Große Ergebnisdateien lassen sich leichter erzeugen, weil man von der Webanwendung unabhängig ist und z.B. dem Kommandozeilenaufruf mehr Arbeitsspeicher zuteilt.
Für die Verteilung von Downloads kann es sinnvoll sein, Berichtsergebnisse in Dateiform zu generieren und im Download-Bereich zu verlinken.

Masken können bei eingerichteter Kommandozeilenumgebung direkt ausgeführt werden:

Unter SuperX: SQL_ENV
Unter HISinOne-BI: Nutzung der SQL_ENV unter HISinOne-BI, oder Einrichtung einer HISinOne-Umgebung unter Eclipse: https://wiki.his.de/mediawiki/index.php/Einrichtung_einer_HISinOne-Arbeitsumgebung

Damit der Aufruf unter Kernmodul 6.0 funktioniert, muss der zentral unter JDBC-Classpath für Tomcat 10 dokumentierte Jakarta-Classpath geladen sein.

Der Kommandozeilenaufruf sieht unter Linux wie folgt aus:

java -cp "$JDBC_CLASSPATH" $JAVA_OPTS de.superx.bin.ExecuteMask -tid:Maskennummer -out:Ausgabedatei -user:Benutzerkennung "-params:Parameter..." -logger:$SUPERX_DIR/db/conf/logging.properties

Hier ein Beispiel für den Aufruf der Maske "Studierende und Studienanfänger (Zeitreihe)" (tid=16000) als Admin-User und deren Ausgabe in die Datei "test.htm":

java -cp "$JDBC_CLASSPATH" $JAVA_OPTS de.superx.bin.ExecuteMask -tid:16000 -out:test.htm -user:admin "-params:Köpfe oder Fälle ?=1=1&Stichtag=1" -logger:$SUPERX_DIR/db/conf/logging.properties

Das Beispiel läßt sich fortführen für andere Ausgabeformate, hier z.B. für PDF:

java -cp "$JDBC_CLASSPATH" $JAVA_OPTS de.superx.bin.ExecuteMask -tid:16000 -out:test.pdf -user:admin "-params:Köpfe oder Fälle ?=1=1&Stichtag=1&stylesheet=tabelle_fo_pdf.xsl&contenttype=application/pdf" -logger:$SUPERX_DIR/db/conf/logging.properties

Das Beispiel zeigt daß über das Params-Argument beliebige Ausgabeformate übergeben werden können, z.B. auch Excel (xlsx):

java -cp "$JDBC_CLASSPATH" $JAVA_OPTS de.superx.bin.ExecuteMask -tid:16000 -out:test.xlsx -user:admin "-params:Köpfe oder Fälle ?=1=1&Stichtag=1&stylesheet=tabelle_xls.xsl&contenttype=application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" -logger:$SUPERX_DIR/db/conf/logging.properties

oder als CSV Export:

java -cp "$JDBC_CLASSPATH" $JAVA_OPTS de.superx.bin.ExecuteMask -tid:16000 -out:test.csv -user:admin "-params:Köpfe oder Fälle ?=1=1&Stichtag=1&contenttype=text/csv" -logger:$SUPERX_DIR/db/conf/logging.properties

Über den "Deep-Link"-Button lassen sich beliebige Parameter-Zeichenketten erzeugen und nutzen. Auch Aufrufe von JasperReports sind damit möglich, z.B. ein Studierendenbericht als Excel-Report:

java -cp $JDBC_CLASSPATH $JAVA_OPTS -Xmx2048m de.superx.bin.ExecuteMask -tid:160440 -out:$OUTFILE "-params:maxoffset=1000000&stylesheet=tabelle_160440_semester_geschlecht.jrxml&tablestylesheet=tabelle_160440_semester_geschlecht.jrxml&contenttype=application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" -user:superx -logger:$SUPERX_DIR/db/conf/logging.properties

Bei Datenblattberichten sollte auch der Parameter tablestylesheet übergeben werden.

Unter Eclipse sieht der Aufruf für das erste Beispiel (Ausgabe nach html) so aus:

Und hier die Parameter:

Das Beispiel lässt sich leicht auf andere Plattformen (DOS, Netbeans) übertragen.

Sie können auch Parameter bewußt leer übergeben, indem Sie den Parameter ohne Wert übergeben, hier z.B. den Parameter „Sprache“:

java -cp "$JDBC_CLASSPATH" $JAVA_OPTS de.superx.bin.ExecuteMask -tid:70170 -out:test.htm -user:admin "-params:Stichwort=REPORT&Sprache=" -logger:$SUPERX_DIR/db/conf/logging.properties

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.

Sie können es mit einer Maskenausführung kombinieren, oder zum Entwickeln. Bei der Maskenausführung können Sie aber im Script ExecuteMask direkt JasperReports aufrufen.

Mailversand

Für den Mailversand empfehlen wir die Unix Anwendung s-nail. Installation unter Ubuntu mit

apt-get install -y s-nail

Unter RedHat

yum install s-nail

Einrichtung .mailrc

Das s-nail in Ubuntu 22.04 (Version 14.9.23) bietet die Möglichkeit, in der Shell mails für verschiedene Accounts zu verschicken. Zur Konfiguration wird die Datei $HOME/.mailrc genutzt.

alt:

set smtp="smtp://smtp.variomedia.de:587"
set from="mail@memtext.de"
set smtp-auth=login
set smtp-auth-user="noreply@superx-projekt.de"
set smtp-auth-password=securepw1234

neu:

set v15-compat
account test {
    set from="Memtext <mail@memtext.de>"
    set mta=smtp://noreply%40superx-projekt.de:securepw1234@smtp.variomedia.de:587
    set smtp-use-starttls
}

Sollte nur für den Benutzer lesbar sein. Es ist nicht sicher, das Passwort direkt in der Konfigurationsdatei zu speichern. Eine sicherere Variante wäre, pass oder gnome-keyring zu nutzen.

Mail verschicken über die bash

Zum Verschicken einer Testmail schreiben Sie z.B.

echo "test" | s-nail --account=test -s "test" support@superx-projekt.de support1@superx-projekt.de support2@superx-projekt.de

Das CLI von s-nail verhält sich etwas UNIX-untypisch: Beachten Sie dass mehrere Mailadressat_innen mit Leerzeichen getrennt hinten angefügt werden - ohne Anführungszeichen um alle Mailadressen.

Mit dem zusätzlichen Parameter -v können detaillierte Debug-Informationen ausgegeben werden:

echo "test" | s-nail -v --account=test -s "test" support@superx-projekt.de support1@superx-projekt.de support2@superx-projekt.de

Damit lässt sich dann prüfen, ob der Versand verschlüsselt (mit set smtp-use-starttls) oder unverschlüsselt stattgefunden hat. Unverschlüsselt sähe dann z.B. so aus:

echo "Testmail" | s-nail -v --account=test-ohne-starttls -s "Testmail" support@superx-projekt.de
s-nail: P(seudo)R(andom)N(umber)G(enerator): *TLS RAND_*
s-nail: Resolving host smtp.superx-projekt.de:587 ... done
s-nail: Connecting to 81.28.224.28:587 ... connected.

Und verschlüsselt so:

 echo "Testmail" | s-nail -v --account=test-starttls -s "Testmail" support@superx-projekt.de
s-nail: P(seudo)R(andom)N(umber)G(enerator): *TLS RAND_*
s-nail: Resolving host smtp.superx-projekt.de:587 ... done
s-nail: Connecting to 81.28.224.28:587 ... connected.
s-nail:  Certificate depth 2
s-nail:   subject = /C=US/ST=New Jersey/L=Jersey City/O=The USERTRUST Network/CN=USERTrust RSA Certification Authority
s-nail:   notBefore = Feb  1 00:00:00 2010 GMT
s-nail:   notAfter = Jan 18 23:59:59 2038 GMT
s-nail:   issuer = /C=US/ST=New Jersey/L=Jersey City/O=The USERTRUST Network/CN=USERTrust RSA Certification Authority
s-nail:  Certificate depth 1
s-nail:   subject = /C=GB/ST=Greater Manchester/L=Salford/O=Sectigo Limited/CN=Sectigo RSA Organization Validation Secure Server CA
s-nail:   notBefore = Nov  2 00:00:00 2018 GMT
s-nail:   notAfter = Dec 31 23:59:59 2030 GMT
s-nail:   issuer = /C=US/ST=New Jersey/L=Jersey City/O=The USERTRUST Network/CN=USERTrust RSA Certification Authority
s-nail:  Certificate depth 0
s-nail:   subject = /C=DE/ST=Brandenburg/O=Memtext AG/CN=*.superx-projekt.de
s-nail:   notBefore = Feb  8 00:00:00 2024 GMT
s-nail:   notAfter = Mar 10 23:59:59 2025 GMT
s-nail:   issuer = /C=GB/ST=Greater Manchester/L=Salford/O=Sectigo Limited/CN=Sectigo RSA Organization Validation Secure Server CA
s-nail: Comparing subject_alt_name: need<smtp.superx-projekt.de> is<*.superx-projekt.de>
s-nail: TLS certificate ok
s-nail: TLS BLAKE2s256 fingerprint: 7A:0A:D3...
s-nail: TLS connection using TLSv1.3 / TLS_AES_256_GCM_SHA384

SQL_ENV mit s-nail

In der SQL_ENV für die neue Konfig-Syntax am besten die Variable MAILPROG mit z.B.

MAILPROG="s-nail --account=test"

angeben.

Shellscripte in der HISinOne-BI

Die Shellscripte von superX sind auch in der HISinOne-BI nutzbar, sofern Linux als Betriebssystem genutzt wird. Vorbedingung ist

die Einrichtung der SQL_ENV
Machen Sie alle Shellscripte im Ordner .../webapps/superx/WEB-INF/conf/edustore/db/bin ausführbar

chmod +x .../webapps/superx/WEB-INF/conf/edustore/db/bin/*

Nützlich ist auch die Installation von psql, also mindestens das Paket postgresql-client

Im folgenden Beispiel wird ein HISinOne-BI-spezifisches Modul eingerichtet.

Shellscripte zur Verwaltung von RES

Das Forschungsmodul RES der HIS e.G. ist ein Beispiel für ein Nicht-SuperX-Modul, das aber auch mit Shellscripten verwaltet werden kann. Hier das Vorgehen:

Entpacken Sie die ZIP-Datei H1-CS-CM-RM_<<Version>>.zip in einem Ordner Ihrer Wahl.
Setzen Sie in der SQL_ENV die Pfade und Variablen:

RES_PFAD=.../webapps/superx/WEB-INF/conf/edustore/db/module/res; export RES_PFAD
RES_ERRORDAT=$RES_PFAD/res_load.err; export RES_ERRORDAT
RES_LOAD_PFAD=$RES_PFAD/rohdaten; export RES_LOAD_PFAD
RES_ERRORMAIL=$ERRORMAIL; export RES_ERRORMAIL
RES_LOGMAIL=$LOGMAIL; export RES_LOGMAIL

Machen Sie die Shellscripte in $RES_PFAD und $RES_LOAD_PFAD ausführbar:

chmod +x $RES_PFAD/*.x
chmod +x $RES_PFAD/rohdaten/*.x
chmod +x $RES_PFAD/upgrade/*.x

Danach können Sie das Modul installieren mit

cd $RES_PFAD
module_install.x res .

Dann entladen Sie aus H1, indem Sie in $RES_LOAD_PFAD die Datei RES_ENV analog einrichten wie Sie z.B. die ZUL_ENV oder SOS_ENV eingerichtet haben

cd $RES_LOAD_PFAD
res_unload.x

Dann starten Sie den Update:

cd $RES_PFAD
module_etl.x res .

Es kann Probleme geben, wenn das Kernmodul nicht zu der ZIP Datei von HIS paßt. Fehler bzgl. "dim_bp_apnr"... können Sie ignorieren.

Eine Datenbank-Dokumentation befindet sich hier:

.../webapps/superx/WEB-INF/conf/edustore/db/module/res/conf/res.html

↑
Aus historischen Gründen liegen die Nummern aus Karlsruhe im Bereich 0-9990, aus Duisburg im Bereich 10000-19990.

[1] 
Aus historischen Gründen liegen die Nummern aus Karlsruhe im Bereich 0-9990, aus Duisburg im Bereich 10000-19990.

[1]

Kernmodul Shellscripte: Unterschied zwischen den Versionen