15. Modul MYSQLOUT - MySQL-Datenbank schreiben

15.1. Allgemeines

Mit dem Skriptmodul können Objekte in eine MySQL-Datenbank via ODBC geschrieben werden. Der Modul unterstützt speziell die MySQL Extension Spatial für räumliche Daten. Der Modul kann mit RUN1 verwendet werden.

MYSQLOUT unterstützt die Geometry-Typen POINT,LINESTRING,POLYGON von MySQL nach der OGC Simple Feature Specification.

Der Modul beinhaltet folgende Besonderheiten:

  • Schreibt Daten nach MySQL.

  • Legt Tabellen für die Daten an.

  • Schreibt die notwendigen Definitionen für MySQL.

  • Schreibt die Geometrien für MySQL nach OGC Simple Feature Specification.

  • Schreibt den Spatial Index für die Geometrien von MySQL.

  • Die Datenbank kann nach dem Schreiben der Daten direkt mit MySQL weiterbearbeitet werden.

Der Modul wird mit:

|INCL \script\mysqlout.mod

in einer ICS Konfiguration verfügbar gemacht.

15.2. Abhängigkeiten von anderen Modulen

Der Modul MYSQLOUT ist eine Erweiterung des Moduls DBOUT. Alle im Modul DBOUT beschriebenen Anteile gelten auch für das Modul MYSQLOUT. Ziehen Sie deshalb die Dokumentation des Modules DBOUT bei, insbesondere die Abschnitte über die Parametermaps DB_PARAM und DBOUT_PARAM.

15.3. Parametermap DB_PARAM

Folgende Parameter können in der Map DB_PARAM für den Modul gesetzt werden:

Parameterreq/optBeschreibung
SOURCEoODBC-Source der Datenbank. Muss gesetzt werden, falls die ODBC-Source nicht interaktiv abgefragt wird.
USERoDatenbank User für die Verbindung mit der ODBC-Source. Muss gesetzt werden, falls die ODBC-Source nicht interaktiv abgefragt wird.
PASSWORDoDatenbank Password für die Verbindung mit der ODBC-Source. Muss gesetzt werden, falls die ODBC-Source nicht interaktiv abgefragt wird.
TRACEoON oder OFF, Default = OFF. Für jedes gelesene Objekt eine Zeile ausgeben.

15.4. Parametermap DBOUT_PARAM

Folgende Parameter können in der Map DBOUT_PARAM für den Modul gesetzt werden:

Parameterreq/optBeschreibung
CREATE_TABLEoON, OFF,Default = OFF. Definiert ob die Tables definiert mit Record-Definitionen (siehe weiter unten) in der Datenbank erzeugt werden sollen. Mit OFF werden die Tabellen nicht erzeugt. Mit ON werden die Tabellen erzeugt und zwar zum Zeitpunkt, wenn das erste Objekt in die Tabelle geschrieben wird. Tables in die keine Objekte geschrieben werden, werden auch nicht erzeugt.
DELETE_OLDoON, OFF oder DROP, Default = OFF. Löscht bestehende Daten in Tables definiert mit Record-Definitionen (siehe weiter unten). Mit OFF werden keine Daten gelöscht. Mit ON werden die Daten über ein delete-sql-statement gelöscht. Mit DROP wird die Table und damit die Daten gelöscht. Zusammen mit DROP und dem Parameter CREATE_TABLE => ON werden die Tables gelöscht und wieder erzeugt.
SQLTRACEoON oder OFF, Default = OFF. Zeigt alle sql-statements im Logfile an.
STATISTICSoON oder OFF, Default = OFF. Statistik anzeigen.
DATASEToON oder OFF, Default = OFF. Definiert, ob die in die Datenbank geschriebenen Daten als Datasets verwaltetet werden. Sie dazu mehr unter dem Kapitel Datasets. Der Wert ON hebt den Parameter DELETE_OLD auf.

15.5. Parametermap MYSQLOUT_PARAM

Folgende Parameter können in der Map MYSQLOUT_PARAM für den Modul gesetzt werden:

Parameterreq/optBeschreibung
SPATIAL_STROKEo<real> , Default = 0.001. PostGIS basiert auf der OGC Simple Feature Specification. Diese Spezifikation unterstützt keine Kreisbögen, deshalb müssen Kreisbögen in Liniensegmente aufgelöst werden. Als Stroke-Tolerance können dieselben Werte wie für die ICS-Methode ICS.STROKE verwendet werden (s.a. iG/Script Benutzer- und Referenzhandbuch).
SPATIAL_INDEXCREATEoON oder OFF, Default = OFF. Definiert ob die Indexe für die Geometrie-Spalten für MySQL erzeugt werden sollen. Aufgrund der Tabelle und des Attributes wird automatisch ein Indexname erzeugt.
SPATIAL_INDEXDROPoON oder OFF, Default = OFF. Definiert ob die Indexe für die Geometrie-Spalten vor dem Schreiben der Daten gelöscht werden sollen. Dies ermöglicht das schnellere Schreiben der Daten. Mit MYSQLOUT_PARAM.SPATIAL_INDEXCREATE => ON werden die Indizes nach dem Schreiben wieder angelegt.
SPATIAL_SRIDo<integer> oder OFF, Default = OFF. Definiert die MySQL-SRID-Identifikation für die Geometrien. Jede Geometrie wird mit dem definierten SRID nach MySQL geschrieben. Das SRID muss in MySQL definiert sein.
[Anmerkung]

MySQL erlaubt das indexieren von Spatial Typen nur, wenn der Geometry-Type mit NOT NULL definiert ist, und daher auch keine NULL Einträge vorkommen. Die zu transferierenden Daten garantieren diese NOT NULL Definition in der Regel nicht. Deshalb sollte unter MySQL ein Geometry Attribut nicht als NOT NULL definiert werden und auch der Spatial Index nicht automatisch generiert werden. DIe Indexierung sollte nachträglich anlysiert und vorgenommen werden.

15.6. Objektmodell

Der Modul verlangt pro OUT-Objekt folgende Systemkomponenten:

Komponentereq/optBeschreibung
OUT.TABLE(s)rTablename des OUT Objekts.
OUT.<Attribut>(s)oAttributname der Tabelle. Der Wert der Komponente beinhaltet den Wert für die Datenbank. Der Type des Wertes muss mit dem Type des Attributes in der Datenbank übereinstimmen. Es können beliebig viele Attribute definiert werden. Geometrien werden mit der MySQL-Funktion GeomFromText(OGC-WKT-Geometry) geschrieben. Eine ICS-Geometry wird in eine OGC-WKT-Geometry mit der Methode OGC.GEOM2WKT umgewandelt (siehe w. u.).

Dieses Objektmodell gilt für die Anwendung mit der Prozedur MYSQLOUT_WRITE_OBJECT0. Die Tabellen mit den Attributen müssen in der Datenbank bereits bestehen oder in einer Konfiguration mit Prozeduren und Methoden vorgängig kreiert werden. Falls die Datenbankstrukturen automatisiert mit dem Modul erstellt werden sollen, so beachten Sie das Kapitel mit den Record-Definitionen und die Prozedur MYSQLOUT_WRITE_RECORD1.

15.7. Record Definitionen

Mit Record Definitionen können nicht nur Objekte in die Datenbank geschrieben werden, sondern auch Datenbank-Tabellen automatisiert in der Datenbank angelegt werden. Die Record Definitionen werden von der Prozedur MYSQLOUT_WRITE_RECORD1 verarbeitet. Eine Record Definition sieht wie folgt aus.

MAP RECORD_<n>
   TABLE => <Table-Name>
   :
   <Attribute-Name> => <Attribute-Type>,<Attribute-Value>
   :
END_MAP

Die einzelnen Bestandteile einer Record-Definition sind:

RECORD_<n>

Eine Record Definition ist eine Map. Der Map-Name muss mit dem Prefix RECORD_ beginnen und eine eindeutige Nummer <n> für die Record Definition beinhalten.

TABLE

Diese Komponente ist obligatorisch und definiert die Datenbank-Tabelle.

<Table-Name>

Definiert als Wert der Komponente TABLE die Datenbank-Tabelle.

<Attribute-Name>

Definiert als Komponente einen Attribut-Namen innerhalb der Tabelle. Es können beliebig viele Attribute als Komponenten definiert werden.

<Attribute-Type>

Definiert den Attribut-Type in der Datenbank. Im Normalfall können der Datenbank bekannt Typen verwendet werden. Spezialtypen einer Datenbank werden eventuell nocht nicht unterstützt. Solche Spezialtypen werden bei Bedarf und auf Anfrage implementiert. Bei den Typen ist auf folgendes zu achten.

CHAR(<length>)

Stringtypen sind immer als CHAR mit der Länge <length> zu definieren. Je nach Datenbank wird der Typ vom Modul in einen der Datenbank bekannten Type umgewandelt z.B. MySQL als VARCHAR.

NUMBER

Number-Typen ohne Argumente werden vom Modul als NUMBER(38,5) interpretiert.

OGC_GEOMETRY(<type>;<dimension>)

PostGIS Spatial Geometrien müssen als Type OGC_GEOMETRY definiert werden. Dabei sind folgende weiteren Definitionen notwendig.

<type>

Type der Geometrie, einer der Werte: point|line|area.

<dimension>

Dimension der Geometrie, einer der Werte: 2D|3D.

[Anmerkung]

MySQL 5.0 unterstütz 3D nicht. Deshalb ignoriert der Modul 3D und verwendet 2D.

<Attribut-Value>

Definiert den Wert für das Attribut. Als Wert können Konstanten oder ICS-Variablen, die einen Wert beinhalten - z.B. IN.OBJID - verwendet werden.

Beispiel einer Record Definition.

MAP RECORD_1
   TABLE => Fixpunkte_LFP
   OBJID => CHAR(10),IN.OBJID
   ENTSTEHUNG => CHAR(10),IN.Entstehung.OBJID
   NUMMER => CHAR(12),IN.Nummer
   GEOMETRIE => OGC_GEOMETRY(point;2D),IN.Geometrie
   LAGEZUV_TXT => CHAR(4),IN.LageZuv_TXT
   HOEHEZUV_TXT => CHAR(4),IN.HoeheZuv_TXT
   BEGEHBARKEIT_TXT => CHAR(14),IN.Begehbarkeit_TXT
   SYMBOLORI => NUMBER,IN.SymbolOri
   ART_TXT => CHAR(4),IN.Art_TXT
   HERKUNFT => CHAR(30),IN.Herkunft
END_MAP

15.8. Datasets

Zur Verwaltung von Datasets in der Datenbank ist das analoge Kapitel des Modules DBOUT zu beachten.

15.9. Datenbank Modellgenerierung mit CONFIG_PARAM.GENERATE_MODEL

Falls basierend auf den Record-Definitionen vor einem Datentransfer das gesamte Datenbankmodell inklusive den notwendigen MySQL Spatial Definitionen erstellt werden soll, so ist der Parameter CONFIG_PARAM.GENERATE_MODEL auf ON zu setzen und das Script il2mysql.lib zu includen:

MAP CONFIG_PARAM
   GENERATE_MODEL => ON
END_MAP
:
|INCL \script\il2db\il2pgres.lib

Entsprechend den Record-Definitionen wird vor einem Datentransfer das Datenbankmodell angelegt, falls es nicht schon angelegt wurde.

15.10. Prozeduren und Methoden

Der Modul beinhaltet alle Prozeduren und Methoden wie der Modul DBOUT. Ziehen Sie deshalb die Dokumentation des Modules DBOUT bei.

Zusätzlich stellt der Modul MYSQLOUT folgende Prozeduren und Methoden zur Verfügung.

ProzedurMYSQLOUT_OPEN [][]
BeschreibungÖffnet eine Datenbank definiert mit DB_PARAM.SOURCE. Die Prozedur wird von RUN1 automatisch aufgerufen.
Beispiel
MYSQLOUT_OPEN
ProzedurMYSQLOUT_WRITE_OBJECT0
Beschreibung

Schreibt einen Objekt in die Datenbank. Das OUT-Objekt muss gemäss dem Objektmodell vorbereitet sein.

Beispiel
MYSQLOUT_WRITE_OBJECT0
ProzedurMYSQLOUT_WRITE_RECORD1 ! s recordname
Beschreibung

Schreibt ein Objekt definiert in <recordname> in die Datenbank. <recordname> ist der Name einer Record-Definition (siehe weiter oben). Je nach den gesetzten Parametern führt die Prozedur beim ersten Aufruf für eine Record-Definition folgende Aktionen auf der Datenbank aus:

  1. Die Tabelle oder deren Inhalt wird gelöscht, falls definiert durch Parameter.

  2. Die Tabelle wird erzeugt, falls definiert durch Parameter.

  3. Die MySQL Metadefinitionen werden generiert.

  4. Das Objekt wird in die Datenbank geschrieben.

Beispiel
... => MYSQLOUT_WRITE_RECORD1,RECORD_1
ProzedurMYSQLOUT_CLOSE [][]
BeschreibungSchliesst den Modul und gibt die durch den Modul belegten Resourcen wieder frei. Die Prozedur wird von RUN1 automatisch aufgerufen.
Beispiel
MYSQLOUT_CLOSE
MethodeOGC.GEOM2WKT [g|li geometry][s ogc-wkt-geometry]
BeschreibungÜbersetzt eine ICS-Geometrie point,line oder area in eine OGC WKT Geometrie als String. Als Input können auch Listen von Geometrien übergeben werden. Falls die Geometrien nicht übersetzt werden können, wird auf dem Stack ein NULL-String zurückgegeben. (WKT: Well Known Text nach OGC Simple Feature Specification).
Beispiel
IN.GEOM OGC.GEOM2WKT => VAR.GEOM
 

Folgende Konversionen werden durchgeführt:

point

to OGC-POINT

line

to OGC-LINESTRING

area

to OGC-POLYGON

list of points

to OGC-MULTIPOINT

list of lines

to OGC-MULTILINESTRING

list of areas

to OGC-MULTIPOLYGON

list of points and/or lines and/or areas

to OGC-GEOMETRYCOLLECTION

Neben diesen Prozeduren des Modules stehen auch die Prozeduren und Methoden des Modules DBOUT zur Verfügung. Diese Prozeduren und Methoden sind im Modul DBOUT beschrieben.

15.11. Skriptbeispiel

! Diese ICS Konfiguration liest ein INTERLIS FIle,
! kreiert eine Tabelle für LFP's in der Datenbank
! und schreibt die LFP's in die Tabelle.

|LICENSE \license\iltools.lic

MAP USER_INPUT1
   DIALOG        => FILE
   MESSAGE       => 'Enter INTERLIS Input File'
   FILE_FILTER   => itf
   FILE_EXISTS   => TRUE
   OPT           => input
END_MAP

MAP USER_INPUT2
   DIALOG        => ODBC
   OPT           => output
END_MAP

MAP ILIN_PARAM
   INTERLIS_DEF => \models\Grunddatensatz.ili
   STATISTICS   => ON
   CALC_SURFACE => ON
   ENUM_TO_TEXT => ON
   TRACE        => OFF
END_MAP

MAP ILIN_TOPO
   DEFAULT => OFF
END_MAP

MAP DB_PARAM
   SOURCE     => '' ! ODBC-Source
   USER       => '' ! ODBC-User
   PASSWD     => '' ! ODBC-Password
   TRACE      => OFF
END_MAP

MAP DBOUT_PARAM
   STATISTICS      => ON
   CREATE_TABLE    => ON
   DATASET         => ON
END_MAP

MAP MYSQLOUT_PARAM
   SPATIAL_STROKE          => 0.001 ! a real Stroke-Tolerance
   SPATIAL_INDEXDROP       => ON    ! ON|OFF Spatial Index Drop   before Insert
   SPATIAL_INDEXCREATE     => ON    ! ON|OFF Spatial Index Create after Insert
   SPATIAL_SRID            => -1
END_MAP

MAP RECORD_1
   TABLE => Fi_LFP
   OBJID => CHAR(10),IN.OBJID
   ENTSTEHUNG => CHAR(10),IN.Entstehung.OBJID
   NUMMER => CHAR(12),IN.Nummer
   GEOMETRIE => OGC_GEOMETRY(point;3D),IN.Geometrie
   LAGEZUV_TXT => CHAR(4),IN.LageZuv_TXT
   HOEHEZUV_TXT => CHAR(4),IN.HoeheZuv_TXT
   BEGEHBARKEIT_TXT => CHAR(14),IN.Begehbarkeit_TXT
   SYMBOLORI => NUMBER,IN.SymbolOri
   ART_TXT => CHAR(4),IN.Art_TXT
   HERKUNFT => CHAR(30),IN.Herkunft
END_MAP

MAP INPUT_SOURCES
   I1 => ILTOPO,OPT.input
END_MAP

MAP INOUT
   I1                => IN.TOPIC,IN.TABLE
   I1,Fixpunkte,LFP  => MYSQLOUT_WRITE_RECORD1,RECORD_1
   I1,*              => OFF
END_MAP

|INCL \script\iltopo.mod
|INCL \script\mysqlout.mod
|INCL \script\run1.prg