Dokumentenformat für JDBC-Empfänger-Adapter (SAP-Bibliothek - SAP NetWeaver Exchange Infrastructure)

Dokumentenformat für JDBC-Empfänger-Adapter

Abhängig von der gewählten Verarbeitungsart (dem Modus) des JDBC-Empfänger-Adapters erwartet der Adapter spezielle XML-Dokumentenformate in der empfangenen Nachricht vom Integration Server.

Die möglichen Verarbeitungsarten sind:

· XMB2DB

· XMB2DB_XML

· XMB2DB_RAWSQL

In zukünftigen Versionen des JDBC-Empfänger-Adapters können weitere mögliche Verarbeitungsarten dazukommen.

XML-Dokumentenformat für den Modus XMB2DB

In diesem Modus wird ein zusätzlicher Parameter benötigt:

· db.table=<tablename>

Geben Sie die Datenbanktabelle an, in die die eingehenden Daten geschrieben werden sollen. Im Modus XMB2DB des JDBC-Adapters ist es nicht möglich, die Inhalte eines eingehenden Dokuments auf verschiedene Datenbanktabellen aufzuteilen.

Zusätzlich können Sie folgende Parameter angeben:

¡ 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. Diese Ersatzzeichen können datenbankabhängig sein. Typisch sind \’ oder ’’. Voreingestellt ist die Zeichenfolge ’’. 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 umschlossen sein, beispielsweise wenn die Namen Sonderzeichen enthalten dürfen (z.B. ein “). Dieses Zeichen kann hier angegeben 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.

Die eingehende Nachricht muss eine XML-konforme Tabelle repräsentieren, deren Inhalt in die unter db.table spezifizierte Datenbanktabelle geschrieben wird. Es wird das gleiche Dokumentenformat erwartet, wie es der File/FTP- und der JDBC-Sender-Adapter erzeugen können. Dies bedeutet, dass das Dokument im Prinzip folgendermaßen aussieht:

<resultset>

<row>

<column-name1>column-value</column-name1>

<column-name2>column-value</column-name2>

<column-name3>column-value</column-name3>

</row>

<row>

<column-name1>column-value</column-name1>

<column-name2>column-value</column-name2>

<column-name3>column-value</column-name3>

</row>

</resultset>

Dies ist ein Beispiel für drei Spalten und zwei Zeilen. Erlaubt ist natürlich eine beliebige Anzahl von Zeilen und Spalten.

Aus den Elementnamen im XML-Dokument werden die Namen der Spalten der Datenbanktabellen ermittelt (zum Beispiel: column-name1, column-name2, column-name3), und für jede Zeile werden die entsprechenden Werte eingefügt.

Das Dokument muss nicht alle Spalten einer Datenbanktabelle enthalten, wenn die Definition der Datenbanktabellen für die fehlenden Spalten Nullwerte erlaubt. Elementnamen des XML-Dokuments, die nicht als Tabellenspaltennamen existieren, werden ignoriert.

XML-Dokumentenformat für den Modus XMB2DB_XML

In diesem Modus 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>

<table>realDbTableName</table>

<dbTableName action=”INSERT”>

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

</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 angegebene Wert als Datenbanktabellenname verwendet. Hiermit kann man zum Beispiel Tabellennamen definieren, die Zeichen enthalten, die nicht XML-konform sind, oder Zeichen, mit denen diese Tabellennamen nicht in Interface-Definitionen des Integration Builder verwendet werden können.

Wenn angegeben, muss <table> 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 namens key mit frei wählbaren Namen. Das Element access enthält die Tabellenspalten, auf die zugegriffen werden soll und muss als erstes Element angegeben werden. Die Elemente key beschreiben eine Bedingung für den Zugriff. Sind keine solcher 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 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 angegebene Wert als Name der Stored Procedure verwendet. Hiermit kann man zum Beispiel Namen für Stored Procedures definieren, die Zeichen enthalten, die nicht XML-konform sind, oder Zeichen, mit denen diese Namen nicht in Interface-Definitionen des Integration Builder verwendet werden können.

Wenn angegeben, muss <table> das erste Element des Blocks innerhalb von <dbTableName> sein.

Die Elemente innerhalb der Stored Procedure werden als Parameter interpretiert. Optional können 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 (nur Output),CLOB (nur 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.

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
EQ	Prüfen auf Gleichheit (Vorgabewert)
NEQ	Prüfen auf Ungleichheit
LT	Prüfen auf kleiner
LTEQ	Prüfen auf kleiner oder gleich
GT	Prüfen auf größer
GTEQ	Prüfen auf größer oder gleich
LIKE	Prüfen auf 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.

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. Voreingestellt ist NULL.

· db.apostropheEsc=<apostropheEscapeString>

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 den Modus XMB2DB_RAWSQL

Dieser Modus 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’)

“