Programmieren von Change()-BAPIs 
Verwendung
Mit dem BAPI Change() wird eine bestehende Instanz eines SAP-Business-Objekttyps geändert, zum Beispiel eine Bestellung.
Das BAPI Change() ist eine Instanzmethode, das BAPI ChangeMultiple() dagegen eine Klassenmethode (instanzunabhängig).
Funktionsumfang
BAPI-Schnittstelle
Import-Parameter
Bei der Festlegung der Import-Parameter sind folgende Aspekte zu beachten:
- Da das BAPI Change() eine Instanzmethode ist, sind im Funktionsbaustein die Schlüsselfelder des zugehörigen Business-Objekttyps als Import-Parameter anzulegen. Dabei müssen die Namen dieser Parameter mit den Namen der Objektschlüssel im BOR übereinstimmen und die gleichen Datenelemente besitzen.
Bei der entsprechenden Methodendefinition im BOR dürfen die Schlüsselfelder jedoch nicht zusätzlich als Parameter aufgeführt werden. Aus diesem Grund nimmt der BOR/BAPI-Wizard beim Anlegen eines BAPIs die Funktionsbaustein-Parameter für die Schlüsselfelder nicht in die Methodendefinition auf.
- Das BAPI muß zusätzlich einen TestRun-Parameter besitzen, der es ermöglicht, Testläufe durchzuführen. Ist dieser Parameter mit dem Wert "X" gefüllt, wird das BAPI zwar normal abgearbeitet, die Ergebnisse werden aber nicht vom BAPI in den Verbucher geschrieben. Somit können nach Ausführen des BAPIs BapiService.TransactionCommit sämtliche Ergebnisse, wie beispielsweise der Application Log, ausgewertet werden, die Datenbank bleibt aber vom BAPI unberührt. Weitere Informationen finden Sie unter
TestRun-Parameter.
- Soll einem Kunden die Möglichkeit gegeben werden, die Import-Parameter des BAPIs modifikationsfrei zu erweitern, so ist der Parameter ExtensionIn anzulegen. Informationen zu Extension-Parametern und Empfehlungen, wie das Kundenerweiterungskonzept in einem Change()-BAPI realisiert werden sollte, finden Sie unter
Kundenerweiterung von BAPIs..
- Implementieren Sie die Change()-Methode nach dem Konzept Änderung durch Markierung. Hierbei ist für jeden Parameter, der änderungsrelevante Felder besitzt, ein Änderungsparameter anzulegen. Mit Hilfe dieser Änderungsparameter kann zwischen den Parameterfeldern unterschieden werden, die geänderte Werte enthalten und denen, die unverändert geblieben sind.
Wird dagegen das Konzept Änderung durch Vergleich implementiert, ist für jeden Parameter mit änderungsrelevanten Felder zusätzlich ein äquivalenter Parameter anzulegen. Informationen finden Sie unter
Änderungsparameter.
Export-Parameter
Bei der Festlegung der Export-Parameter sind folgende Aspekte zu beachten:
- Soll einem Kunden die Möglichkeit gegeben werden, die Export-Parameter des BAPIs modifikationsfrei zu erweitern, so ist der Parameter ExtensionOut anzulegen. Informationen zu Extension-Parametern und Empfehlungen, wie das Kundenerweiterungskonzept in einem Change()-BAPI realisiert werden sollte, finden Sie unter
Kundenerweiterung von BAPIs.
- Legen Sie den Export-Parameter Return an, um Meldungen aus dem Methodenaufruf an das aufrufende Programm zurückzugeben. Um ein umfangreiches Monitoring der Ergebnisse des Change()-BAPIs sowohl bei einem synchronen als auch bei einem asynchronen Aufruf zu gewährleisten, müssen beim Füllen des Return-Parameters die folgenden Konventionen eingehalten werden:
- Wird das Change()-BAPI erfolgreich abgearbeitet, muß im Return-Parameter folgende standardisierte T100-Nachricht übergeben werden:
Dabei sind folgende Aspekte von Bedeutung:
- Das Feld MESSAGE_V1 enthält den externen Namen des Business-Objekttyps, wie z.B. SalesOrder.
- In dem Feld MESSAGE_V2 wird derjenige Schlüssel zurückgegeben, unter dem auf zu ändernde Objekte zugegriffen wurde. Dies kann entweder bei externer Nummervergabe der externe Schlüssel oder bei interner Nummernvergabe der interne Schlüssel sein. Besitzt das Objekt mehrere Schlüsselfelder, dann müssen die Werte dieser Schlüsselfelder in MESSAGE_V2 konkateniert werden. Bei der Konkatenation ist die diejenige Reihenfolge einzuhalten, in der die Schlüsselfelder im BOR definiert sind. Außerdem muß für jedes Schlüsselfeld die maximale Länge verwendet werden, so daß gegebenenfalls ein Auffüllen notwendig ist.
Ist der Gesamtschlüssel länger als die maximale Kapazität von MESSAGE_V2 (also 50 Zeichen), so wird er auf die beiden Felder MESSAGE_V2 und MESSAGE_V3 aufgeteilt. Dabei werden die ersten 50 Zeichen in MESSAGE_V2 gespeichert und der Rest MESSAGE_V3 zugewiesen.
- Tritt bei der Abarbeitung des Change()-BAPIs ein Fehler auf, ist neben den anwendungsspezifischen Fehlermeldungen folgende standardisierte T100-Nachricht im Return-Parameter zu übergeben:
Die Bedeutung der einzelnen Felder ist äquivalent zum Erfolgsfall.
- Neben der standardisierten Meldung können weitere Meldungen in den Return-Parameter geschrieben werden.
Insbesondere im Fehlerfall müssen Meldungen zurückgegeben werden, die den Fehler konkret beschreiben. Deshalb sollte der volle Funktionsumfang des Typs BAPIRET2 Verwendung finden. Insbesondere sollten die Felder
Parameter, Row und Field gefüllt werden. Informationen zu diesem Parameter finden Sie unter
Return-Parameter (Fehlerdarstellung).
BAPI-Coding
Mögliche Strategien für die Implementierung eines Change()-BAPIs
In BAPIs, die Änderungen auf der Datenbank hervorrufen, z.B. Change()- und Create()-BAPIs, muß man zwischen den Parameterfeldern unterscheiden können, die geändert werden sollen (den "änderungsrelevanten Feldern"), und denen, die unverändert bleiben sollen.
Zu diesem Zweck genügt die Verwendung eines Initialwerts nicht, da es sich bei dem Initialwert auch um einen gültigen, neuen Wert handeln kann. Ebensowenig kann in der ABAP-Programmiersprache und auch auf anderen Entwicklungsplattformen einem Datentyp der Wert "NULL" zugewiesen werden, um ein Feld als nicht belegt zu markieren.
Aus diesem Grund müssen die änderungsrelevanten Felder über ein Hilfskonstrukt identifiziert werden. Dabei gibt es zwei Möglichkeiten:
- Identifizieren der änderungsrelevanten Felder durch Markierung
In diesem Ansatz werden änderungsrelevante Felder in einem Parameter durch eine entsprechende Markierung in einem zusätzlichen Änderungs-Parameter identifiziert:
- Für jeden Parameter des BAPIs, der änderungsrelevante Felder beinhaltet, muß ein zusätzlicher Änderungs-Parameter mit der gleichen Anzahl Felder und den gleichen Feldnamen angelegt werden.
- Beim Aufruf des BAPIs müssen in dem zusätzlichen Änderungs-Parameter genau die Felder mit einem Update-Kennzeichen (Flag) markiert werden, die im korrespondierenden Parameter änderungsrelevante Daten beinhalten.
Auf diese Weise kann das BAPI genau identifizieren, welche Felder des Parameters modifizierte Daten enthalten, und in welchen Feldern keine Änderungen vorgenommen wurden.
Beachten Sie folgende Konventionen, wenn Sie Änderungs-Parameter anlegen:
- Der Name des zusätzlichen Änderungs-Parameters setzt sich aus dem Namen des Parameters und dem Suffix "X" zusammen. Heißt der Parameter beispielsweise EquiSales, ist der Name des zusätzlichen Änderungs-Parameters EquiSalesX.
- Der zusätzliche Änderungs-Parameter muß genau die gleiche Anzahl Felder sowie die gleichen Feldnamen wie der Parameter haben. Als Datenelement für die änderungsrelevanten Felder müssen Sie das Datenelement BAPIUPDATE (CHAR 1) verwenden. Dieses kann folgende Werte annehmen:
| |
|
'X':
Dieser Wert bedeutet, daß das zugehörige Feld im Parameter einen änderungsrelevanten Wert enthält. |
| |
|
' ' (kein Wert):
Kein Wert bedeutet, daß das entsprechende Feld des Parameters nicht aktualisiert werden muß. |
- Handelt es sich bei dem Parameter um eine Tabelle, muß der zusätzliche Änderungs-Parameter auch eine Tabelle sein.
Weitere Informationen zu diesem Konzept finden Sie unter
Änderungsparameter.
- Identifizieren der änderungsrelevanten Felder durch Vergleich
In diesem Ansatz werden änderungsrelevante Felder durch den Vergleich zweier Parameter identifiziert, von denen der eine die aktuell gültigen Daten und der andere die neuen, geänderten Daten enthält.
Beim Aufruf des Change()-BAPIs müssen die aktuellen Daten aus der Datenbank, sowie die neuen, geänderten Daten in die entsprechenden Parameter eingetragen werden. Der aktuelle Datenbestand kann dabei beispielsweise aus dem vorausgegangenen Aufruf eines GetDetail()-BAPIs übernommen werden.
Folgende Vergleiche sind nun möglich:
- Die aktuellen Daten können zunächst gegen den tatsächlichen Datenbankbestand geprüft werden, um festzustellen, ob sich dieser in der Zwischenzeit verändert hat. So können Datenbankänderungen erkannt werden, die zwischen dem Lesevorgang mit dem GetDetail()-BAPI und dem Datenbank-Update stattgefunden haben.
- Die Daten beider Parameter können Feld für Feld verglichen werden. Werden in einem Feld unterschiedliche Daten festgestellt, müssen die entsprechenden Werte aus dem Parameter mit den neuen Daten übernommen werden.
Beachten Sie folgendes, wenn Sie änderungsrelevante Felder durch Vergleich identifizieren:
- Ein aufrufendes Programm muß in der Lage sein, alle Parameterfelder des Change()-BAPIs zu versorgen. Aus diesem Grund müssen Sie die Parameterfelder des Change()-BAPIs genau mit den Feldern eines entsprechenden GetDetail()-BAPIs am gleichen Business-Objekttyp abstimmen.
- Die Namen der zu vergleichenden Parameter müssen gleich sein, wobei der Parameter mit den geänderten Daten zusätzlich das Suffix 'New' erhält.
Heißt der Parameter mit den aktuell gültigen Daten beispielsweise EquiSales, ist der Name des Parameters mit den geänderten Daten EquiSalesNew.
- Beide Parameter müssen genau die gleichen Felder und die gleiche Struktur besitzen.
Vermeidung von Konflikten mit Customizing-Einstellungen
Es ist möglich, daß bestimmte Werte durch das Customizing festgelegt werden, jedoch an der BAPI-Schnittstelle weiterhin als variabel erscheinen. Diese Werte dürfen von einem Change()-BAPI nicht überschrieben werden.
Um Konflikte mit Customizing-Einstellungen zu vermeiden, sollten Sie ein Change()-BAPI folgendermaßen implementieren:
- Das BAPI sollte alle Felder übernehmen und gegen die Customizing-Einstellungen prüfen. Wenn ein Feld durch entsprechende Customizing-Einstellungen schreibgeschützt ist, darf dieser Wert nicht durch einen Wert aus der BAPI-Schnittstelle überschrieben werden.
- Für jeden Konfliktfall muß im Return-Parameter des BAPIs eine Nachricht vom Typ "Error" an die aufrufende Anwendung zurückgemeldet werden, z.B. "Feld 'MyAsset-AssetName' laut Customizing nicht änderbar".
- Alle Felder, die eventuell über das Customizing mit Default-Werten vorbelegt und daher schreibgeschützt sind, müssen entsprechend dokumentiert werden.
Siehe auch:
Beispiel für ein Change()-BAPI