Return-Parameter (Fehlerdarstellung) 

Verwendung

Ein BAPI soll alle möglichen Fehlersituationen erfassen und angemessen klassifizieren können.

Für jedes BAPI müssen Sie daher einen Parameter mit dem Namen Return anlegen, mit dem Nachrichten über Ausnahmesituationen oder Erfolgsmeldungen an das aufrufende Programm zurückgemeldet werden.

Ein BAPI selbst darf im Coding keine Meldungen (wie beispielsweise MESSAGE xnnn) auslösen. Insbesondere darf es keinen Abbruch erzeugen oder ein Dialogfenster ausgeben. Stattdessen müssen alle Meldungen intern abgefangen und im Parameter Return an die aufrufende Anwendung zurückgegeben werden. Andernfalls wird das BAPI nicht korrekt abgearbeitet und es ist nicht gewährleistet, daß die Kontrolle an das aufrufende Programm zurückgegeben wird.

Alle Fehlermeldungen bzw. Nachrichten, die von dem BAPI zurückgemeldet werden können, müssen Sie in der Nachrichtentabelle definieren (über Werkzeuge ® ABAP Workbench ® Entwicklung ® Programmierumfeld ® Nachrichten) und in der Dokumentation zum Parameter Return beschreiben. Dies gilt auch für die wichtigsten bzw. wahrscheinlichsten Fehlermeldungen, die von anderen Programmen generiert werden und indirekt über das BAPI an das Anwendungsprogramm gelangen können.

 

Ausnahmen (Exceptions) an einer BAPI-Schnittstelle sind nicht mehr erlaubt.

Beim Auslösen einer Abbruchmeldung (Meldungstyp A) im normalen Programmiermodell wird ein Datenbank-Rollback durchgeführt, d.h. alle Aktivitäten seit dem letzten "COMMIT WORK"-Kommando werden zurückgenommen. Bei der Programmierung von BAPIs wird empfohlen, bei Abbruchmeldungen im Return-Parameter ebenfalls einen Datenbank-Rollback durchzuführen. Dies muß dann explizit in der Dokumentation zum Return-Parameter beschrieben werden. Bei Meldungen vom Typ E (Fehlermeldung), wird die Fehlerbehandlung vom aufrufenden Programm durchgeführt.

Für die Diagnose und Behandlung von Fehlermeldungen aus BAPI-Aufrufen stehen Anwendungsentwicklern zwei Service-BAPIs zur Verfügung:

Funktionsumfang

Der Export-Parameter Return kann folgendermaßen implementiert werden:

Initialisieren Sie vor dem Füllen des Parameters Return die Feldleiste mit einem CLEAR, bzw. die Tabelle mit einem REFRESH und CLEAR.

Wenn der Parameter Return nicht gesetzt bzw. auf initial gesetzt ist, bedeutet dies, daß kein Fehler aufgetreten ist.

Dem Parameter Return können folgende Bezugsstrukturen zugrundeliegen:

Für neu zu entwickelnde BAPIs ist diese Bezugsstruktur zu verwenden.

Diese Bezugsstrukturen werden noch teilweise in alten BAPIs verwendet.

Beide Strukturen müssen in der Anmeldesprache versorgt werden.

Bezugsstruktur BAPIRET2

Die Struktur BAPIRET2 wird über den Funktionsbaustein BALW_BAPIRETURN_GET2 gefüllt. Sie besteht aus den folgenden Feldern:

Feld

Typ

Bedeutung

TYPE

CHAR 1

S ist eine Erfolgsmeldung (Success).
E ist eine Fehlermeldung (Error).
W ist eine Warnmeldung (Warning).
I ist eine Informationsmeldung (Information).
A ist eine Abbruchmeldung (Abort).

ID

CHAR 20

Meldungs-ID. (Die Struktur BAPIRET2 berücksichtigt die Namensraumerweiterung der Nachrichtenklasse ab R/3-Release 4.0. Wenn Sie weiterhin die Kompatibilität der Meldungen mit R/3-Releases vor 4.0 gewährleisten möchten, verwenden Sie die Nachrichtenklassen vor Release 4.0).

NUMBER

NUMC 3

Meldungs-Nummer

MESSAGE

CHAR 220

Vollständiger Meldungstext aus der Nachrichtentabelle, wobei alle Variablen (in den Feldern Message_V1 bis Message_V4) durch Texte ersetzt sind.

LOG_NO

CHAR 20

Nummer des Anwendungslogs. Ist initial, wenn kein Log verwendet wird.

Beachten Sie, daß bei Fehlermeldungen des Typs A (Abbruch) kein Anwendungslog erstellt wird, da in diesem Fall kein COMMIT WORK erfolgt.

LOG_MSG_NO

NUMC 6

Laufende Nummer der Nachricht im Anwendungslog.

MESSAGE_V1
MESSAGE_V2
MESSAGE_V3 MESSAGE_V4

CHAR 50

Felder für die variablen Texte der Meldung, die in den Feldern ID und NUMBER identifiziert ist.

PARAMETER

CHAR 32

Parameter, in dem sich der fehlerhafte Wert befindet.

ROW

INT 4

Zeilennummer des Datensatzes, in dem sich der fehlerhafte Wert befindet.

FIELD

CHAR 30

Feld, in dem sich der fehlerhafte Wert befindet.

SYSTEM

CHAR 10

System (logisches System), in dem die Nachricht erzeugt wurde.

 

Bezugsstruktur BAPIRET1

Diese Struktur wird über den Funktionsbaustein BALW_BAPIRETURN_GET1 gefüllt. Sie besteht aus den Feldern der Struktur BAPIRET2 mit Ausnahme der Felder PARAMETER, ROW und FIELD.

Return-Parameter im Verteilten Umfeld von ALE

Nach dem Aufruf des Funktionsbausteins, der im empfangenden System für die Umsetzung des IDocs in das entsprechende BAPI zuständig ist, werden für das IDoc Statussätze geschrieben, in denen die vom Return-Parameter zurückgegebenen Meldungen protokolliert werden.

Wenn in mindestens einem übergebenen Eintrag des Return-Parameters das Feld Type mit A (Abbruch) gefüllt ist, wird für alle Statussätze des IDocs der Status 51 (Fehler, Anwendungsbeleg nicht gebucht) geschrieben und ein 'Rollback Work' durchgeführt. Wenn in mindestens einem übergebenen Eintrag des Return-Parameters das Feld Type mit E (Fehler) gefüllt ist, wird für alle Statussätze des IDocs der Status 51 (Fehler, Anwendungsbeleg nicht gebucht) geschrieben, aber trotzdem ein 'Commit Work' durchgeführt. Andernfalls wird der Status 53 (Anwendungsbeleg gebucht) geschrieben und ein 'Commit Work' durchgeführt.

Anwendungslogs und anwendungsspezifische Fehlertabellen

Sollten die Rückmeldungen mit Hilfe des Parameters Return für Ihr BAPI nicht ausreichen, können Sie darüber hinaus Fehler mit dem Anwendungslog protokollieren. Diese Protokollierung soll vom BAPI selbst vorgenommen werden, damit direkt von diesem BAPI aufgerufenen Funktionsbausteine nicht umgeschrieben werden müssen. Die Nummern der Anwendungslogs und der darin enthaltenen Nachrichten können über die Felder LOG_NO und LOG_MSG_NO des Parameters Return zurückgegeben werden.

Ab Release 4.6A ist es möglich, bereits beim Anlegen des Anwendungslogs die Lognummer zu erhalten. Zudem können mehrere Instanzen eines Anwendungsobjekts gleichzeitig verwaltet und gemeinsam verbucht werden. Zusätzlich kann für Anwendungslogs die Verbuchung verwendet werden, d.h. Logeinträge werden nicht mehr direkt, sondern über den Verbucher auf die Datenbank geschrieben. Wenn Sie Anwendungslogs in Ihrem BAPI vorsehen, müssen Sie diese über die Verbuchung schreiben.

Weitere Informationen zum Anwendungslog finden Sie unter Anwendungslog erstellen im Dokument BC - Erweiterte Funktionsbibliothek Anwendungen.

Ist dies immer noch nicht aussagekräftig genug, kann die aufrufende Anwendung eigene, zusätzliche Fehlertabellen definieren. Für diese Fehlertabellen gibt es keine festen Richtlinien. Der Parameter Return in Ihrem BAPI könnte dann Auskunft über die Meldungen in der Fehlertabelle geben, beispielsweise wenn sich Fehlermeldungen in der Tabelle befinden. Das aufrufende Programm hat damit sofort Kontrolle über den Inhalt der Fehlertabelle und muß nicht erst nach Fehlermeldungen suchen.

Die Verwendung von Anwendungslogs und eigener Fehlertabellen bietet sich an, wenn der Parameter Return nicht ausreicht, um Fehler adäquat zurückzumelden.

Beachten Sie, daß bei Fehlermeldungen des Typs A (Abbruch) kein Anwendungslog erstellt wird, da in diesem Fall kein COMMIT WORK erfolgt.