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 Message verändert werden. Abhängig vom Inhalt der Message können die Daten hierbei eingefügt (INSERT), verändert (UPDATE) oder gelöscht (DELETE) werden. Bei synchronen Messages können auch Ergebnisse von Abfragen (SELECT) im XML-Format in der Rückantwort mitgegeben werden. Das XML-Dokument muss hierzu folgendes Schema aufweisen:

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

Kommentare

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

○ Der Name des Elements unterhalb des Anweisungselements 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 z. B. Tabellennamen definieren, die nicht XML-konforme Zeichen enthalten oder Zeichen, mit denen sie 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 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.

Wenn Sie diesen Fall ausschließen wollen, dann wählen Sie in der Adapterkonfiguration Key-Tags erforderlich.

○ 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 einer Anweisung mit dieser Action werden bestehende Tabellenwerte verändert. Die Anweisung entspricht damit einer SQL UPDATE-Anweisung.

Der Block <access> enthält die neuen Spaltenwerte und ein <key>-Element enthält die Spalten, deren Werte mit dem angegeben Wert übereinstimmen 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.

Eine Anweisung mit der Action UPDATE muss genau ein <access>-Element haben. Es kann über beliebig viele <key>-Elemente mit frei definierten Namen verfügen.

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 unzulässig sein und führt dann zu einem Fehler in der Nachrichtenverarbeitung mit entsprechender Fehlerausgabe.

● action=INSERT

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

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

Eine Anweisung mit der Action INSERT muss mindestens ein <access>-Element haben. Es kann kein <key>-Element enthalten.

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

Die Anweisung 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 immer 0 ist, da entweder eine UPDATE- oder eine INSERT-Action durchgeführt wird:

<update_count>count</update_count>

<insert_count>count</insert_count>

● action=DELETE

Bei einer Anweisung 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 Antwortdokument enthält folgendes 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 unzulässig sein und führt dann zu einem Fehler in der Nachrichtenverarbeitung mit entsprechender Fehlerausgabe.

● action=SELECT

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

Der Block <access> enthält die auszuwählenden Spaltennamen und ein <key>-Element enthält die Spalten, deren Werte mit dem angegeben Wert übereinstimmen 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.

Eine Anweisung mit der Action SELECT muss genau ein <access>-Element haben. Es kann über beliebig viele <key>-Elemente mit frei definierten Namen verfügen.

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 unzulässig 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 einer Anweisung 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ö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 (input und output),CLOB (input und output), CURSOR (output; nur in Verbindung mit dem Oracle-JDBC-Treiber).

Hinweis

Die Binärdaten für BLOB sind als Hexadezimalwert kodiert.

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-Anweisungen. 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 verwenden, die im nachfolgenden Key-Block aufgelistet werden können. Damit können leicht auch komplexe, parametrisierbare SQL-Anweisungen erzeugt werden.

Details zum Aufbau:

○ Der Name der Struktur ist beliebig. Anders als bei den übrigen Anweisungstypen wird standardmäßig kein Tabellen- oder Stored-Procedure-Name erwartet.

○ Wählen Sie Action=SQL_QUERY, wenn die SQL-Anweisung 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 <key> aufgelistet sein. Die Namen der Platzhalter-Elemente müssen mit den im SQL-String verwendeten Namen übereinstimmen, wobei sie im SQL-String noch mit dem Zeichen $ markiert werden. Im obigen Beispiel <StatementName6> würden also im SQL-String enthaltene Strings $placeholder1$ und $placeholder2$ durch value1 oder value2 ersetzt, bevor die SQL-Anweisung ausgeführt wird.

○ Wenn Sie keine Platzhalter verwenden, dann kann der <key>-Block entfallen oder leer sein. In beiden Fällen dürfen Sie in der Konfiguration das Feld Key-Tags erforderlich nicht auswä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 die unveränderte SQL-Anweisung 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 die gleiche SQL-Anweisung wie oben ausgeführt:

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

Anmerkungen:

○ Die Verwendung von Platzhaltern ist nicht, wie in diesem Beispiel, auf individuelle Feldwerte beschränkt. Sie können auf diese Weise jeden Teil der SQL-Anweisung setzen. Es kann auch die Logik der Anweisung 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. Folgende Werte sind möglich:

Werte für compareOperation

Attribut	Wert und Prüfung
EQ	Gleichheit (Vorgabewert)
NEQ	ungleich
LT	kleiner als
LTEQ	kleiner oder gleich
GT	größer als
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 die SELECT-Anweisung (StatementName4) der Block <key1> wie folgt abgeändert:

<key1>

</key1>

Die ausgeführte SQL-Anweisung 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 der SQL-Anweisung wird als Vorgabe aufgrund des Tabellenspaltentyps entschieden, ob die Werte in Hochkommata (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 die Werte in Anführungszeichen gesetzt, für die dieses Attribut in der SQL-Syntaxquotation eingestellt ist. Bei NO werden nie Anführungszeichen 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.

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

“