Dokumentenformate für den JDBC-Empfänger-Adapter (SAP-Bibliothek

Dokumentenformate für den JDBC-Empfänger-Adapter

XML-Dokumentenformat für das Message-Protokoll XML SQL-Format

Es können eine oder mehrere Datenbanktabellen durch eine Nachricht verändert werden. Abhängig vom Inhalt der Nachricht können die Daten hierbei eingefügt (INSERT), verändert (UPDATE) oder gelöscht (DELETE) werden. Im synchronen Fall können auch Ergebnisse von Abfragen (SELECT) als XML-Format in der Rückantwort mitgegeben werden. Das XML-Dokument muss hierzu folgendes Schema haben:

<root>

<StatementName1>

<dbTableName action=”UPDATE” | “UPDATE_INSERT”>

<table>realDbTableName</table>

<access>

<col1>val1</col1>

<col2>val2new</col2>

</access>

<key1>

<col2>val2old</col2>

<col4>val4</col4>

</key1>

<key2>

<col2>val2old2</col2>

</key2>

</dbTableName>

</StatementName1>

<dbTableName action=”INSERT”>

<table>realDbTableName</table>

<access>

<col1>val1</col1>

<col2>val2</col2>

</access>

<access>

<col1>val11</col1>

</access>

</dbTableName>

</StatementName2>

<StatementName3>

<dbTableName action=”DELETE”>

<key1>

<col2>val2old</col2>

<col4>val4</col4>

</key1>

<key2>

<col2>val2old2</col2>

</key2>

</dbTableName>

</StatementName3>

<StatementName4>

<dbTableName action=”SELECT”>

<table>realDbTableName</table>

<access>

<col1/>

<col2/>

<col3/>

</access>

<key1>

<col2>val2old</col2>

<col4>val4</col4>

</key1>

<key2>

<col2>val2old2</col2>

</key2>

</dbTableName>

</StatementName4>

<StatementName5>

<storedProcedureName action=” EXECUTE”>

<table>realStoredProcedureeName</table>

<param1 [isInput=”true”] [isOutput=true] type=SQLDatatype>val1</param1>

</storedProcedureName >

</StatementName5>

<StatementName6>

<anyName action=” SQL_QUERY” | “SQL_DML”>

<access>SQL-String with optional placeholder(s)</access>

<key>

<placeholder1>value1</placeholder1>

<placeholder2>value2<placeholder2>

</key>

</anyName >

</StatementName6>

</root>

Erläuterungen

· Das Dokument hat ein frei wählbares Tag <root>. Darunter enthält es ein oder mehrere Statement-Elemente mit ebenfalls frei wählbaren Namen. Jedes dieser Statements enthält die Beschreibung einer Datenbankaktion. Mit Ausnahme der Ausführungsbeschreibung für eine Stored Procedure (im Beispiel unter dem Element <StatementName5>) haben alle Statements eine gemeinsame Struktur:

¡ Der Name des Elements unterhalb des Statement-Elements gibt den Namen der Datenbanktabelle an und enthält das Attribut action mit dem Wert INSERT, UPDATE, UPDATE_INSERT, DELETE oder SELECT. Wird das optionale Element <table> verwendet, wird der hier angegebene Wert als Datenbanktabellenname verwendet. (Hiermit kann man z.B. Tabellennamen definieren, die nicht XML-konforme Zeichen enthalten oder Zeichen, mit denen sie nicht in Interface-Definitionen des Integration Builder/des PCK verwendet werden können.). <table> muss, wenn es angegeben wird, das erste Element des Blocks innerhalb von <dbTableName> sein.

¡ Innerhalb dieses Elements gibt es (außer bei der Action DELETE) ein Element mit Namen access und ein oder mehrere Elemente mit frei wählbaren Namen. Im Beispiel oben heißen sie keyN. Das Element access enthält die Tabellenspalten, auf die zugegriffen werden soll. Es muss als erstes Element angegeben werden. Die <key>–Elemente beschreiben eine Bedingung für den Zugriff. Sind keine solchen Elemente angegeben, erfolgt der Zugriff bedingungslos. Dies kann dann bei der Action UPDATE zu einer Veränderung und bei der Action DELETE zu einem Löschen der gesamten Tabelle führen. Dieses Verhalten kann durch Setzen des folgenden Parameters explizit verhindert werden:

db.conditionRequired=YES

¡ Die unten beschriebenen Antwortdokumente können nur bei synchronem Aufruf vom Integration Server/vom PCK ausgewertet werden, da im asynchronen Fall der Inhalt des Antwortdokuments nicht mehr zugänglich ist. Die Antwort wird für jedes Statement-Element separat in einem Element <StatementName_response> gesetzt.

· action=UPDATE

Bei einem Statement mit dieser Action werden bestehende Tabellenwerte verändert. Das Statement entspricht damit einer SQL UPDATE-Anweisung.

Der Block <access> enthält die neuen Spaltenwerte, ein <key>-Element enthält die Spalten, deren Werte identisch mit dem angegeben Wert sein müssen, um die neuen Spaltenwerte zu erhalten. Der Name des <key>-Elements ist frei wählbar. Spaltenwerte innerhalb eines <key>-Elements werden mit einem logischen UND kombiniert, verschiedene <key>-Elemente mit einem logischen ODER.

Ein Statement mit der Action UPDATE muss genau ein <access>-Element haben. Es kann beliebig viele <key>-Elemente mit frei definierten Namen haben.

Die entsprechende SQL-Anweisung zu StatementName1 im obigen Beispiel lautet:

“

UPDATE dbTableName SET col1=’val1’, col2=’val2new’ WHERE ((col2=’val2old’ AND col4=’val4’) OR (col2=’val2old2’))

“

Hier wie in den übrigen Beispielen wird für alle Spalten der Spaltentyp STRING angenommen. Bei anderen Spaltentypen fallen unter Umständen die Zeichen “ weg.

Das Antwortdokument enthält das folgende Element sowie die Anzahl der veränderten Tabellenzeilen einschließlich 0.

<update_count>count</update_count>

Kein <key>-Element oder ein leeres <key>-Element bedeutet, dass keine Bedingung spezifiziert ist und die gesamte Tabelle verändert werden soll. Dies kann aus Sicherheitsgründen durch die Konfiguration des JDBC-Adapters verboten sein und führt dann zu einem Fehler in der Nachrichtenverarbeitung mit entsprechender Fehlerausgabe.

· action=INSERT

Bei einem Statement mit dieser Action werden Tabellenwerte hinzugefügt. Das Statement entspricht damit einer SQL INSERT-Anweisung.

Der Block <access> enthält die neuen Spaltenwerte.

Ein Statement mit der Action INSERT muss mindestens ein <access>-Element haben. Es kann kein <key>-Element haben.

Die entsprechende SQL-Anweisung zu StatementName2 im obigen Beispiel lautet:

“

INSERT INTO dbTableName (col1, col2) VALUES(‘val1’, ‘val2’)

INSERT INTO dbTableName (col1) VALUES(‘val11’)

“

Das Antwortdokument enthält das folgende Element sowie die Anzahl der eingefügten Tabellenzeilen einschließlich 0.

<insert_count>count</insert_count>

· action=UPDATE_INSERT

Das Statement hat das gleiche Format wie bei der Action UPDATE. Zunächst wird die gleiche Aktion ausgeführt wie bei UPDATE. Wenn bei dieser Aktion keine Änderung an der Datenbanktabelle vorgenommen werden kann (die formulierte Bedingung also auf keinen Tabelleneintrag zutrifft), werden die im <access>-Element beschriebenen Werte der Tabelle hinzugefügt, gemäß der Beschreibung der Action INSERT. <key>-Elemente werden in diesem Fall ignoriert.

Das Antwortdokument hat folgendes Format, wobei einer der beiden Werte 0 ist, da immer entweder eine UPDATE- oder eine INSERT-Aktion durchgeführt wird:

<update_count>count</update_count>

<insert_count>count</insert_count>

· action=DELETE

Bei einem Statement mit dieser Action werden Tabellenwerte gelöscht. Ein oder mehrere <key>-Elemente formulieren die Bedingung, bei der Tabellenwerte gelöscht werden. Der Name eines <key>-Elements ist frei wählbar. Spaltenwerte innerhalb eines <key>-Elements werden mit einem logischen UND kombiniert, verschiedene <key>-Elemente mit einem logischen ODER.

Die entsprechende SQL-Anweisung zu StatementName3 im obigen Beispiel lautet:

“

DELETE FROM dbTableName WHERE ((col2=’val2old’ AND col4=’val4’) OR (col2=’val2old2’))

“

Das Antwort Dokument enthält ein Element:

<delete_count>count</delete_count>

Kein <key>-Element oder ein leeres <key>-Element bedeutet, dass keine Bedingung spezifiziert ist und die gesamte Tabelle gelöscht werden soll. Dies kann aus Sicherheitsgründen durch die Konfiguration des JDBC-Adapters verboten sein und führt dann zu einem Fehler in der Nachrichtenverarbeitung mit entsprechender Fehlerausgabe.

· action=SELECT

Bei einem Statement mit dieser Action werden Tabellenwerte ausgewählt. Das Statement entspricht damit einer SQL SELECT-Anweisung.

Der Block <access> enthält die auszuwählenden Spaltennamen, ein <key>-Element enthält die Spalten, deren Werte identisch mit dem angegeben Wert sein müssen, um die neuen Spaltenwerte zu erhalten. Der Name des <key>-Elements ist frei wählbar. Spaltenwerte innerhalb eines <key>-Elements werden mit einem logischen UND kombiniert, verschiedene <key>-Elemente mit einem logischen ODER.

Ein Statement mit der Action SELECT muss genau ein <access>-Element haben. Es kann beliebig viele <key>-Elemente mit frei definierten Namen haben.

Die entsprechende SQL-Anweisung zu StatementName4 im obigen Beispiel lautet:

“

SELECT col1,col2,col3 FROM dbTableName WHERE ((col2=’val2old’ AND col4=’val4’) OR (col2=’val2old2’))

“

Kein <key>-Element oder ein leeres <key>-Element bedeutet, dass keine Bedingung spezifiziert ist und die gesamte Tabelle ausgewählt werden soll. Dies kann aus Sicherheitsgründen durch die Konfiguration des JDBC-Adapters verboten sein und führt dann zu einem Fehler in der Nachrichtenverarbeitung mit entsprechender Fehlerausgabe.

Das Antwortdokument enthält das Ergebnis der Aktion im XML-Format in der Form:

“

<row>

<column1>value11</column1>

<column2>value12</column2>

...

</row>

...

<row>

<column1>valueN1</column1>

<column2>valueN2</column2>

...

</row>

“

· action=EXECUTE

Bei einem Statement mit dieser Action wird eine Stored Procedure ausgeführt. Der Name des Elements wird hierbei als Name der Stored Procedure in der Datenbank interpretiert. Wird das optionale Element <table> verwendet, wird der hier angegebene Wert als Stored Procedure Name verwendet (Hiermit kann man z.B. Stored Procedure Namen definieren, die nicht XML-konforme Zeichen enthalten oder Zeichen, mit denen sie nicht in Interface-Definitionen des Integration Builder/des PCK verwendet werden können.). <table> muss, wenn es angegeben wird, das erste Element des Blocks innerhalb von <dbTableName> sein.

Die Elemente innerhalb der Stored Procedure werden als Parameter interpretiert. Optional könnnen sie das Attribut isInput=“1“ (Input-Parameter), isOutput=“1“ (Output-Parameter) oder beide (INOUT-Parameter) besitzen. Fehlen beide Attribute, wird das Element als Input-Parameter interpretiert. Die Parameternamen müssen mit denen der Stored Procedure Definition übereinstimmen.

Zwingend bei allen Parameterarten (IN, OUT, INOUT) ist das Attribut type=<SQL-Datatype>, das den gültigen SQL-Datentyp beschreibt.

Unterstützte SQL-Datentypen sind:

INTEGER, BIT, TINYINT, SMALLINT, BIGINT, FLOAT, REAL, DOUBLE, NUMERIC, DECIMAL, CHAR, VARCHAR, STRING, LONGVARCHAR, DATE, TIME, TIMESTAMP, BINARY, VARBINARY, LONGVARBINARY, BLOB (input und output), CLOB (input und output)

Alle Rückgabewerte werden in einer XML-Struktur zurückgegeben. Die Ergebnisse innerhalb der Stored Procedure werden entweder als Tabelle oder als Element <update_count> zurückgegeben. Dies ist abhängig von den innerhalb der Stored Procedure ausgeführten SQL-Statements. Die Rückgabeparameter einer Stored Procedure werden in einer separaten Struktur angehängt.

· action= SQL_QUERY | SQL_DML Diese Struktur bietet die Möglichkeit, komplexere SQL-Anweisungen direkt über den Adapter an die Datenbank zu übergeben. Optional können Sie in diesen SQL-Anweisungen Platzhalter vorgesehen, die im nachfolgenden Key-Block aufgelistet werden können. Damit können leicht auch komplexe, parametrisierbare SQL-Statements erzeugt werden.

Details zum Aufbau:

¡ Der Name der Struktur ist beliebig. Es wird nicht standardmäßig ein Tabellen- oder Stored Procedure-Name erwartet wie bei den übrigen Statement-Typen.

¡ Wählen Sie Action=SQL_QUERY, wenn das SQL Statement eine Query-Abfrage an die Datenbank darstellt (SELECT).

¡ Wählen Sie Action=SQL_DML, wenn es sich um einen Aufruf aus der SQL Data Manipulation Language handelt (UPDATE, INSERT, DELETE).

¡ Die Struktur muss als erstes ein Element namens <access>besitzen, dessen Inhalt ein gültiger SQL-Aufruf für den jeweiligen Modus darstellt, optional mit Platzhaltern (siehe unten).

¡ Wenn Sie Platzhalter verwenden, dann müssen diese innerhalb des Elements namens <key> aufgelistet sein. Die Namen der Platzhalter-Elemente müssen identisch mit denen im SQL-String verwendeten Namen sein, wobei sie im SQL-String noch mit $ Zeichen markiert werden. Im obigen Beispiel <StatementName6> würden also im SQL-String enthaltene Strings $placeholder1$ und $placeholder2$ durch value1 oder value2 ersetzt, bevor das SQL-Statement ausgeführt wird.

¡ Wenn Sie keine Platzhalter verwenden, dann kann der <key>-Block entfallen oder leer gesetzt werden. In beiden Fällen dürfen Sie in der Konfiguration das Feld Key-Tags erforderlich nicht ausgewählen, da es sonst zu einem Laufzeitfehler kommt.

Beispiel (ohne Platzhalter):

<root>

<stmt>

<access> UPDATE Customers SET CompanyName='Firma', Address='Strasse 3' WHERE CustomerID='FI'

</access>

</Customers>

</stmt>

</root>

In der Datenbank wird das unveränderte SQL-Statement ausgeführt:

UPDATE Customers SET CompanyName='Firma', Address='Strasse 3' WHERE CustomerID='FI'

Beispiel (mit Platzhaltern):

<root>

<stmt>

<access> UPDATE Customers SET CompanyName=’$NAME$’, Address=’$ADDRESS$' WHERE CustomerID='$KEYFIELD$’

</access>

<key>

<NAME>Firma</NAME>

<ADDRESS>Strasse 3 </ADDRESS>

</key>

</Customers>

</stmt>

</root>

In der Datenbank wird nach Ersetzung der Platzhalter das gleiche SQL-Statement wie oben ausgeführt:

UPDATE Customers SET CompanyName='Firma', Address='Strasse 3' WHERE CustomerID='FI'

Anmerkungen:

¡ Der Einsatz von Platzhaltern beschränkt sich nicht auf einzelne Feldwerte wie in diesem Beispiel, es können beliebige Teile des SQL-Statements auf diese Art gesetzt werden. Es kann auch die Logik des Statements beeinflusst werden.

¡ Überzählige und undefinierte Platzhalter in der <key>-Sektion werden toleriert. Undefinierte Platzhalter werden im SQL-String unverändert gelassen. Dies kann zu einem Syntax-Fehler oder zu unerwarteten Ergebnissen in der Datenbank führen.

Attribute in den <key>-Elementen

Die xml-Elemente innerhalb der <key>-Elemente können optional die folgenden Attribute besitzen:

· compareOperation= <compareType>

Mit diesem Attribut kann die logische Vergleichsoperation für das jeweilige Element gesetzt werden. Erlaubte Werte sind:

Werte für compareOperation

Attribut	Wert und Prüfung
EQ	Gleichheit (Vorgabewert)
NEQ	Ungleichheit
LT	Keiner
LTEQ	Kleiner oder gleich
GT	Größer
GTEQ	Größer oder gleich
LIKE	Gleichartigkeit (von Strings). Im zugehörigen Wert können hier dann auch die SQL-Platzhalter „%“ bzw. „_“ verwendet werden.

Im obigen Beispiel-XML Dokument wird für das SELECT-Statement (StatementName4) der Block <key1> wie folgt abgeändert:

<key1>

</key1>

Das ausgeführte SQL-Statement wird dann wie folgt abgeändert:

“

SELECT col1,col2,col3 FROM dbTableName WHERE ((col2<>’val2old’ AND col4 LIKE ’val%’) OR (col2=’val2old2’))

“

· hasQuot= YES|NO Beim Aufbau der WHERE-Bedingung des SQL-Statements wird als Vorgabe aufgrund des Tabellenspaltentyps entschieden, ob die Werte in Hochkomma (textartige Spaltentypen) oder nicht in Hochkommata (numerische Spaltentypen) gesetzt werden. In seltenen Fällen (z.B. bei der Verwendung von Funktionen) kann die Notwendigkeit bestehen, dieses Verhalten zu übersteuern. Dies ist mit dem Attribut möglich. Bei YES werden immer, bei NO niemals Hochkomma um die so attributierten Werte in der SQL-Syntax gesetzt. Verwenden Sie dieses Attribut nur in Einzelfällen.

· isNull= TRUE Werte mit diesem Attribut werden beim Aufbau der WHERE-Bedingung ignoriert. Dieses Attribut hat die gleiche Wirkung, als ob der zugehörige Wert nicht vorhanden ist. Dies ist in Mapping-Programmen oft schwerer darzustellen.

Zusätzlich können für die SQL-Syntax noch folgende Parameter spezifiziert werden, die für alle Aktionen verwendet werden:

· db.emptyStringValue= NULL | EMPTY

Bei Datenbankfeldern vom Typ String, Date, Time oder Timestamp wird mit diesem Parameter unterschieden, ob leere Werte in der XML-Struktur als leerer Wert (EMPTY) (Datenbankfeld gesetzt mit Länge Null) oder als NULL-Wert (NULL) (Datenbankfeld nicht gesetzt) interpretiert werden sollen. Bei allen anderen Parametertypen werden leere Werte immer als NULL-Werte interpretiert. Vorbelgt ist der Wert NULL.

· db.apostropheEsc=<apostropheEscapeString>

Das Apostrophzeichen (‘) ist in der SQL-Syntax ein reserviertes Zeichen und wird daher durch ein Escape-Zeichen ersetzt, wenn es innerhalb von Wertezeichenketten vorkommt. Dieses Ersatzzeichen kann abhängig von der Datenbank sein. Typisch sind die Zeichen \’ oder ’’. Voreingestellt ist ’’.

Wird ein für die verwendete Datenbank ungültiges Zeichen verwendet, gibt der Adapter eine Fehlermeldung (SQL Exception) zur SQL-Syntax aus, die von der Datenbank erzeugt wird.

· db.columnNameDelimiter=<DelimiterSign>

Abhängig von der Datenbank können Spaltennamen von einem speziellen Abgrenzungszeichen (Delimiter) umschlossen sein, beispielsweise wenn sie Sonderzeichen enthalten dürfen (z.B. “). Dieses Zeichen kann hier spezifiziert werden. Voreingestellt ist kein Abgrenzungszeichen.

Wird ein für die verwendete Datenbank ungültiges Zeichen verwendet, gibt der Adapter eine Fehlermeldung (SQL-Exception) zur SQL-Syntax aus, die von der Datenbank erzeugt wird.

XML-Dokumentenformat für das Message-Protokoll Natives SQL-Format

Dieses Protokoll dient hauptsächlich zu Testzwecken. Hier wird kein XML-Dokumentenformat erwartet, sondern ein Text, der eine beliebige, gültige SQL-Anweisung darstellt.

Zum Einfügen einer Zeile in eine Tabelle würde das entsprechende Dokument zum Beispiel lauten:

„

INSERT INTO tableName (column-name1, column-name2, column-name3) VALUES(‘column-value1’, ‘column-value2’, ‘column-value3’)

“