Struktur der Parameter-Dokumentation (SAP-Bibliothek - Referenz zum BAPI-Programmierleitfaden (CA-BFA))

Struktur der Parameter-Dokumentation

Voraussetzungen

Parameter-Dokumentation besteht aus den Keyblöcken Bedeutung, Wertebereich und Vorbelegung. Wie Sie diese Keyblöcke füllen, ist abhängig davon, um welchen Parameter es sich handelt. Finden Sie deshalb zunächst folgendes heraus:

Ob der zu dokumentierende Parameter eines der Schlüsselfelder des Business-Objektes implementiert

Sehen Sie hierzu im BAPI Explorer (Transaktion BAPI) nach, ob der zu dokumentierende Parameter im zugehörigen Business-Objekt als Schlüsselfeld oder tatsächlich als Parameter im BAPI angezeigt wird.

Ob der zu dokumentierende Parameter der Parameter Return ist

Ob sich der zu dokumentierende Parameter auf ein Feld, eine Struktur oder eine Tabelle bezieht

Um dies herauszufinden, wählen Sie im Function Builder das entsprechende Register "Import", "Export" oder "Tabellen", bis der gewünschte Parameter gelistet wird. Im Feld "Bezugsfeld/Bezugsstruktur" gelangen Sie über einen Doppelklick in das ABAP-Dictionary. Dort können Sie Informationen über die Struktur des Parameters herausfinden:

Bei Parametern, die auf einer Struktur basieren, steht im Feld "Bezugsfeld/Bezugsstruktur" der Name der Struktur. Zum Beispiel liegt dem Parameter PR_HEADER im Funktionsbaustein BAPI_PO_CREATE (der das BAPI PurchaseOrder.CreateFromData() implementiert) die Struktur BAPIEKKOC zugrunde.

Bei Parametern, die aus einem Feld bestehen, steht im Feld "Bezugsfeld/Bezugsstruktur" der Name der Struktur, gefolgt von einem Bindestrich, gefolgt von dem Namen des Feldes in der Struktur, auf dem der Parameter basiert. Zum Beispiel liegt dem Parameter FROM_DATE im Funktionsbaustein BAPI_JOBREQUIRE_GETLIST (der das BAPI JobRequirement.GetList() implementiert) das Feld BAPIQUALIFIC-FROM_DATE zugrunde, d.h. das Feld FROM_DATE in der Struktur BAPIQUALIFIC.

Vorgehensweise

Gleiche Parameter in mehreren BAPIs verwenden

Für Parameter, die gleichzeitig in mehreren BAPIs verwendet werden, können Sie in der Transaktion SE61 einen allgemeinen Text anlegen.

Diesen können Sie über einen INCLUDE-Verweis aus der jeweiligen Parameter-Dokumentation aufrufen. Geben Sie dazu in der Parameter-Dokumentation links in der Formatspalte des SAPscript-Editors die Zeichen /: und in der entsprechenden Zeile im SAPscript-Editor das Kommando INCLUDE <name-des-allg.Textes> ein.

Ein-Feld-Parameter dokumentieren

Bezieht sich der Parameter nur auf ein einzelnes Feld, finden Sie heraus, ob zu diesem Feld Datenelement-Dokumentation existiert. Dies ist unter Datenelement-Dokumentation überprüfen oder anlegen beschrieben. Existiert keine Datenelement-Dokumentation, so müssen Sie diese anlegen.

Überprüfen Sie, ob die Datenelement-Dokumentation ausreicht, um den Parameter umfassend zu beschreiben.

Beschreiben Sie dann den Parameter selbst wie folgt:

Keyblock	Inhalt
Bedeutung	Beschreibt die Datenelement-Dokumentation den Parameter ausreichend, fügen Sie in diesem Keyblock folgenden Standardsatz ein: "Informationen zur Bedeutung der/des <Kurztext> finden Sie in der entsprechenden Datenelement-Dokumentation: <Hyperlink auf DE-DOku>." Sollte noch weitere Information zu diesem Parameter von Bedeutung sein, geben Sie diese zusätzlich zu dieser Referenz an. Ist die Datenelement-Dokumentation nicht passend, beschreiben Sie hier den betriebswirtschaftlichen Inhalt des Parameters.
Wertebereich	Geben Sie mögliche feste Werte und deren Wirkung an. Geben Sie auch an, ob eine Prüfung erfolgt und welche Reaktion auf ungültige Werte zu erwarten ist. Generell gilt: Geben Sie keine Informationen über Datentypen aus dem ABAP Dictionary an, da diese im ABAP Dictionary selbst eingesehen werden können. Geben Sie Informationen über Datentypen nur dann an, wenn es sinnvoll ist. Dieser Abschnitt soll keine Customizing-Informationen enthalten, die von System zu System unterschiedlich sein können.
Vorbelegung	Eventuelle Vorbelegung des Parameters Diese Information müssen Sie nur bei Importparametern beschreiben. Dokumentieren Sie, ob das Feld eventuell über das Customizing mit einem Default-Wert vorbelegt und daher schreibgeschützt ist.

Parameter dokumentieren, die sich auf Strukturen/Tabellen beziehen

Bezieht sich der Parameter auf eine Struktur oder Tabelle, müssen Sie sicherstellen, daß zu jedem Feld der Struktur/Tabelle eine Datenelement-Dokumentation existiert. Wie Sie dies tun, ist unter Datenelement-Dokumentation überprüfen oder anlegen beschrieben.

In diesem Fall sollten Sie den Parameter selbst folgendermaßen beschreiben:

Keyblock	Inhalt
Bedeutung	Definieren Sie die betriebswirtschaftliche Bedeutung des Parameters. Verwenden Sie dabei keine Informationen, die in der Datenelement-Dokumentation vorhanden sind. Geben Sie an, ob es sich um einen Import-, Export- oder Import/Export (Tabellen)-Parameter handelt. Diese Information können Sie im BAPI-Explorer herausfinden. Beschreiben Sie nicht die Felder selbst, da die Datenelement-Dokumentation zu jedem Feld automatisch im BAPI-Explorer gezogen und angezeigt wird. Geben Sie stattdessen an: Welches Feld gefüllt sein muß, damit der Parameter als gefüllt gilt, d.h. die obligatorischen Felder Welche Abhängigkeiten zwischen den Feldern existieren, z.B. wenn entweder das eine oder das andere Feld gefüllt sein kann oder muß Geben Sie links in der Formatspalte des SAPscript-Editors die Zeichen /: und in der entsprechenden Zeile im SAPscript-Editor das Kommando INCLUDE BAPI_DATAELEMENT ein. Dies fügt automatisch folgenden Standardsatz ein: "Informationen zur Bedeutung der einzelnen Parameterfelder finden Sie in der entsprechenden Datenelement-Dokumentation im ABAP Dictionary."
Wertebereich	Geben Sie mögliche feste Werte und deren Wirkung an. Geben Sie auch an, ob eine Prüfung erfolgt und welche Reaktion auf ungültige Werte zu erwarten ist. Bei ExtensionIn- und ExtensionOut-Parametern: Wenn diese mit BAPI Table Extensions kombiniert werden, führen Sie hier alle verfügbaren BAPI Table Extensions auf. Generell gilt: Geben Sie keine Informationen über Datentypen aus dem ABAP Dictionary an, da diese im ABAP Dictionary selbst eingesehen werden können. Geben Sie Informationen über Datentypen nur dann an, wenn es sinnvoll ist! Dieser Abschnitt soll keine Customizing-Informationen enthalten, die von System zu System unterschiedlich sein können.
Vorbelegung	Eventuelle Vorbelegung der Parameter. Diese Information müssen Sie nur bei Importparametern beschreiben. Dokumentieren Sie, ob Felder eventuell über das Customizing mit einem Default-Wert vorbelegt und daher schreibgeschützt sind.

Ein Beispiel finden Sie unter Dokumentation zu Parametern.

Return-Parameter dokumentieren

Jedes BAPI hat einen Parameter Return, mit dem es Meldungen an die aufrufende Anwendung zurückgibt. Der Anwendungsprogrammierer, der ein BAPI verwenden möchte, muß genau wissen, welche Rückmeldungen vom BAPI zu erwarten sind, so daß er diese in seiner Anwendung entsprechend verarbeiten kann.

Ein BAPI kann, wenn es abläuft, weitere Funktionsbausteine aufrufen, die wiederum eigene Meldungen ausgeben können. Deswegen müssen in der Dokumentation des Return-Parameters die Rückmeldungen des BAPIs aufgelistet werden und wichtige/wahrscheinliche Rückmeldungen, die von anderen Funktionsbausteinen oder Programmierobjekten generiert und über das BAPI an die aufrufende Anwendung weitergereicht werden. Fragen Sie hierzu den BAPI-Entwickler.

Alle Meldungen eines BAPIs sind in der Tabelle T100 eingetragen. Es ist am einfachsten, wenn Sie den zuständigen Entwickler bitten, Ihnen eine Liste der Fehlermeldungen in der unten beschriebenen Tabellenstruktur zu geben. Wichtig in diesem Zusammenhang ist, daß Sie in der Tabelle T100 keine Änderungen an den Meldungen machen, ohne diese mit dem Entwickler abzusprechen. Derartige Änderungen könnten die von SAP garantierte Schnittstellenstabilität des BAPIs untergraben, da es sich um semantisch inkompatible Änderungen handeln kann.

Strukturieren Sie die Parameter-Dokumentation wie folgt:

Keyblock	Inhalt
Bedeutung	Definieren Sie den Parameter, indem Sie mit einem INCLUDE-Kommando einen Standardsatz eingeben. Gehen Sie hierzu wie folgt vor: Geben Sie links in der Formatspalte des SAPscript-Editors die Zeichen /: und in der entsprechenden Zeile im SAPscript-Editor das Kommando INCLUDE BAPI_TABLE ein. Dies fügt automatisch folgenden Standardsatz ein: "Diese Tabelle enthält die Rückmeldungen aus dem Methodenaufruf." Wenn das BAPI beim Auftreten einer Abbruchmeldung (Meldungstyp A) im Parameter Return ein Datenbank-Rollback durchführt, muß dies explizit erwähnt werden, da dies bewirkt, daß alle Aktivitäten seit dem letzten COMMIT WORK-Kommando zurückgenommen werden.
Wertebereich	Hier geben Sie alle Rückgabewerte Ihres BAPIs an, sowie die möglichen Rückmeldungen, die indirekt über das BAPI an die aufrufende Anwendung gelangen können. Verwenden Sie dafür eine Tabelle mit folgenden Spalten (und verwenden Sie in der Formatspalte die Formatzeichen PE, nicht AS): Type ID Nummer Meldung Sie sollten die Tabelle nach Themenbereichen unterteilen, um die Fehlermeldungen zu gruppieren, z.B: Meldungen zu Berechtigung Type ID Nummer Meldung E FN 019 Kein Zugriff auf … E FN 020 Keine Berechtigung… Meldungen zu Eingabeprüfungen Type ID Nummer Meldung E FN 021 Buchungskreis .....ist nicht vorhanden Geben Sie zuletzt unter der Überschrift: Weitere mögliche Meldungen tabellarisch die wichtigsten/wahrscheinlichen Meldungen an, die von anderen Funktionsbausteinen erzeugt werden und über das BAPI an die aufrufende Anwendung gelangen können. Hinweis für BAPIs im Release 3.1: Wenn Sie ein BAPI dokumentieren, das in Version 3.1 implementiert wurde, besteht die Tabelle nur aus folgenden Spalten: Type Code Meldung Zum Beispiel: Type Code Meldung E FN020 Buchungskreis ..... ist nicht vorhanden.
Vorbelegung	Hier sind keine Angaben zu machen.

Ein Beispiel finden Sie unter Dokumentation zu Parametern.

Parameter dokumentieren, die Schlüsselfelder implementieren

Manche BAPIs verwenden die Schlüsselfelder ihres Business-Objekts. Diese werden im Funktionsbaustein, der einem BAPI zugrundeliegt, als Parameter implementiert.

Finden Sie heraus, ob das Schlüsselfeld des Business-Objektes dokumentiert ist. Bei Bedarf legen Sie die Dokumentation in Form von Datenelement-Dokumentation an, wie unter Datenelement-Dokumentation überprüfen oder anlegen beschrieben.

In der Parameter-Dokumentation selbst verweisen Sie dann wie folgt auf die Dokumentation des Schlüsselfelds:

Keyblock	Inhalt
Bedeutung	Definieren Sie den Parameter, indem Sie mit einem INCLUDE-Kommando einen Standardsatz eingeben. Gehen Sie hierzu wie folgt vor: Geben Sie links in der Formatspalte des SAPscript-Editors die Zeichen /: und in der entsprechenden Zeile im SAPscript-Editor das Kommando INCLUDE BAPI_KEYFIELD ein. Dies fügt automatisch folgende Standardformulierung ein: "Dieser Parameter implementiert das gleichnamige Schlüsselfeld des Business-Objekts. Informationen zur Bedeutung dieses Parameters finden Sie in der Dokumentation zum Schlüsselfeld."
Wertebereich	Hier sind keine Angaben zu machen.
Vorbelegung	Hier sind keine Angaben zu machen.

Ein Beispiel finden Sie unter Dokumentation zu Parametern.