= prtr-public-db Generator = 

Copyright (C) 2012 Rory Michele, ENDA GmbH & Co. KG 
Copyright (C) 2014 Marcus Fritsche, ENDA GmbH & Co. KG 


== Software licence agreement / Softwarelizenzvertrag==

ENGLISH:
This program is free software; you can redistribute it and/or modify it under 
the terms of the GNU General Public License as published by the Free Software 
Foundation; either version 3 of the License, or (at your option) any later 
version. 
This program is distributed in the hope that it will be useful, but WITHOUT ANY 
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A 
PARTICULAR PURPOSE. See the GNU General Public License for more details. 
You should have received a copy of the GNU General Public License along with 
this program; if not, see <http://www.gnu.org/licenses/>. 

DEUTSCH: 
Dieses Programm ist freie Software. Sie können es unter den Bedingungen der GNU 
General Public License, wie von der Free Software Foundation veröffentlicht, 
weitergeben und/oder modifizieren, entweder gemäß Version 3 der Lizenz oder 
(nach Ihrer Option) jeder späteren Version. 
Die Veröffentlichung dieses Programms erfolgt in der Hoffnung, dass es Ihnen von 
Nutzen sein wird, aber OHNE IRGENDEINE GARANTIE, sogar ohne die implizite 
Garantie der MARKTREIFE oder der VERWENDBARKEIT FÜR EINEN BESTIMMTEN 
ZWECK. Details finden Sie in der GNU General Public License. 
Sie sollten ein Exemplar der GNU General Public License zusammen mit diesem 
Programm erhalten haben. Falls nicht, siehe <http://www.gnu.org/licenses/>. 


== Programmbeschreibung == 

Dieses Programm extrahiert die für das Web-Portal 'http://www.thru.de/' relevanten Daten aus der e-PRTR Qualitätssicherungsdatenbank und erzeugt daraus eine leichtgewichtige SQLite Datenbank.
Dazu verbindet sich das Programm mit der in db_source.yml angegebenen zentralen 
e-PRTR Datenbank, extrahiert die Daten und schreibt diese anschließend in die in db_target.yml angegebene Datenbank. 


== Voraussetzungen zur Inbetriebnahme ==

Folgende Voraussetzungen müssen erfüllt sein, damit das Programm lauffähig ist:
- Ruby Version 1.9.1, 
- Postgres Version 8.4,
- Ruby Postgres-Adapter pg Version 0.9.0
- Ruby SQLite-Adapter sqlite3 1.3.5 und sqlite3-ruby 1.3.3, 
- Datenbank-Schnittstelle dbi und die dazugehörigen adapter dbd-pg 0.3.9 und dbd-sqlite3 1.2.5. 

Andere Versionen können ebenfalls funktionieren. 
Für andere Datenbanken werden andere Adapter benötigt. 
 

==  Inbetriebnahme ==

Die folgenden Schritte beziehen sich darauf, das Sie sich bereits im Hauptverzeichnis des Programms befinden.


=== I Automatisierter Programmablauf ===
Bei dieser Version des Programmablaufs handelt es sich eigentlich um ein sogenanntes Wrapper-Script. Dieses umgibt und führt das eigentliche Programm welches in ruby geschrieben ist aus. Das Script wurde zur vereinfachten Bedienung programmiert. Nach wie vor können die ruby scripte von Hand ausgeführt werden, dazu mehr im Abschnitt 'II von Hand ausführen'.
Das Wrapper-Script hat den Name prtr2sqlite.sh und kann aus dem Programm Hauptverzeichnis ausgeführt werden.
Eine Übersicht und Hilfe erhalten Sie mittels Eingabe von ./prtr2sqlite.sh -h

==== 1. Initial Setup ====
Falls das Initial Setup bereits ausgeführt wurde, können Sie diesen Abschnitt überspringen.

a. Passen Sie die Datei './setup/db_source.yml' so an, dass sich die benötigten Schnittstellendaten zur Verbindung mit der ePRTR Datenbank in der Datei befinden.

Das Schema der Datei lautet:
url: DBI:Pg:<db_name>:<host-url> 
user: <username> 
password: <password> 


b. - db_target_de.yml, db_target_en.yml, db_target_inspire.yml (Zieldatenbanken)
Enthalten bereits die benötigten Schnittstellendaten, diese können oder müssen evt. Angepasst
werden. 
Achtung! Falls Sie die Dateien anpassen, sollten Sie auch die dazugehörigen Setup-Variablen in der Datei 'prtr2sqlite.sh' anpassen. Diese befinden sich in dem Abschnitt zwischen 'setup' '/setup'.
Andernfalls kommt es bei der Ausführung des Scripts wahrscheinlich zu Fehlern.

c. Wechseln Sie in das Programm Hauptverzeichnis und führen Sie den Befehl ' ./prtr2sqlite.sh -n' aus.

Der Parameter -n bewirkt folgendes:
- Erstellen der Verzeichnisse 'data' und 'config'
- Kopieren der eben bearbeiteten '.yml' Dateien in das 'config' Verzeichnis
- Erstellen und Kopieren der benötigten SQLite Datenbank-Templates. Die Templates werden aus den im Verzeichnis 'create_sql' befindlichen '.sql' Dateien erzeugt und danach in die Verzeichnisse 'data' und '/dev/shm/' kopiert.

==== 2. Programm ausführen ====
a. Zunächst sollten Sie überprüfen ob sich im /dev/shm/ Verzeichnis die benötigten Datenbankdateien befinden (prtr_de.db, prtr_en.db, prtr_inspire.db).
ls -la /dev/shm/
Ist dies nicht der Fall, kann einfach der Befehl './prtr2sqlite.sh -n' aus dem Programm Hauptverzeichnis ausgeführt werde.

b. Nun können die SQLite Datenbanken gefüllt werden. Eine Übersicht der Optionen erhalten wir mittels  './prtr2sqlite.sh -h'.

Beschreiben der deutschen SQLite db
./prtr2sqlite.sh -d
Beschreiben der englischen SQLite db
./prtr2sqlite.sh -e
Beschreiben der deutschen inspire SQLite db
./prtr2sqlite.sh -i
Beschreiben der deutschen, der deutschen inspire- und der englischen SQLite db
./prtr2sqlite.sh -a

Nachdem die Datenbanken mit den extrahierten werten gefüllt wurden, werden sie automatisch in das Verzeichnis /home/uba/prtr/db/ kopiert. Die Versionsnummer im Dateinamen der Datenbank (relXXX) wird automatisch inkrementiert.


=== II von Hand ausführen ===
Wie bisher kann das eigentliche ruby Programm auch von Hand ausgeführt werden.
Es gelten dabei die gleichen Regeln wie bisher.

==== 1. Setup ====
Falls das Setup bereits ausgeführt wurde, können Sie diesen Abschnitt überspringen.

Als ersten müssen die Konfigurationsdateien erstellt und bearbeitet werden.
Dazu wechseln Sie bitte in das 'setup' Verzeichnis und führen dort das Programm 'setup.sh' aus.
Passen Sie dann die dadurch erstellten Dateien im Verzeichnis 'config' an Ihre Datenbank an.
db_source.yml -  benötigt Daten um sich mit der ePRTR Datenbank zu verbinden
db_target_de.yml  -  benötigt Daten um sich mit der deutschen SQLite db zu verbinden
db_target_en.yml -  benötigt Daten um sich mit der englischen SQLite db zu verbinden
db_target_inspire.yml  -  benötigt Daten um sich mit der deutschen inspire SQLite db zu verbinden

Das Schema der Dateien lautet:
url: DBI:Pg:<db_name>:<host-url> 
user: <username> 
password: <password> 

Wir empfehlen beim Anpassen der Schnittstellendaten darauf zu achten, die SQLite Datenbanken in einen RAMfs-Mountpunkt zu legen, da sich sonst die Schreibzugriffszeiten der INSERT Befehle als Flaschenhals erweisen werden. 

Erstellen Sie die benötigten SQLite Datenbanken und Kopieren Sie diese in die von ihnen dafür vorgesehenen Verzeichnisse. Um die Datenbanken zu erstellen können Sie die vorhandenen SQL-Statements im Verzeichnis 'create_sql' verwenden.

==== 2. Programm ausführen ====
Bevor Sie das Programm ausführen, sollten Sie darauf achten, dass sich die SQLite Datenbanken bereits in den vorgesehenen Verzeichnissen befinden (wie in den Konfigurationsdateien angegebenen).
Wechseln Sie in das Hauptverzeichnis des Programms und rufen Sie einen der folgenden Befehle auf:
ruby lib/main.rb  – Zum beschreiben der deutschen SQLite db
uby lib/main_en.rb  –  Zum beschreiben der englischen SQLite db
ruby lib/main.rb –inspire  – Zum beschreiben der deutschen inspire SQLite db

Wichtig! Falls sich Ihre SQLite Datenbanken in einem RAMfs-Mountpunk befinden:
Kopieren Sie die erstellten und beschriebenen Datenbanken aus dem RAMfs-Mountpunk, da dieses Verzeichnis bei einem Neustart oder Ausschalten des Computers geleert wird.




Marcus Fritsche, ENDA GmbH & Co. KG, 2014