Return Parameters (Error Handling) 

Use

A BAPI should be able to record and classify all possible errors that may occur.

You have to create a parameter named Return for every BAPI. This parameter returns exception messages or success messages to the calling program.

BAPIs themselves must not trigger any messages (such as MESSAGE xnnn) in the coding. In particular they must not generate terminations or display dialog boxes. Instead, all messages must be intercepted internally and reported back to the calling program in the Return parameter. Otherwise the BAPI will not be processed correctly and control may not be given back to the calling program.

All error messages or indeed any message that may be returned by the BAPI, must be defined in message table (Tools ® ABAP Workbench ® Development ® Programming environment ® Messages) and described in the documentation for the return parameter. This also applies to the most important or most likely error messages generated by other programs that can be indirectly passed via the BAPI to the application program.

 

You must not use exceptions in BAPI interfaces.

When a termination message (message type A) is triggered, a database rollback is executed in the standard programming model, that is, all tasks performed since the last COMMIT WORK are canceled. When you program BAPIs, we recommend that you also execute a database rollback in the return parameter for termination messages. You must describe this process in the documentation for the Return parameter. For messages of type E (error), the calling program performs the error handling.

Application developers are provided with two service BAPIs to diagnose and process error messages from BAPI calls:

Features

The export parameter Return can be implemented as follows:

Before filling the Return parameter you should either initialize the structure with CLEAR or the table with REFRESH and CLEAR.

If the return parameter is not set or is set to an initial value this means that no error has occurred.

The Return parameter may be based on the following reference structures:

You must use this reference structure when developing new BAPIS.

These reference structures are still partly used in old BAPIs.

Both structures must be filled in the logon language.

Reference Structure BAPIRET2

The structure BAPIRET2 is filled via the function module BALW_BAPIRETURN_GET2. It contains the following fields:

Field

Type

Description

TYPE

CHAR 1

S = success message
E = error message
W = warning message
I = information message
A = termination message (abort)

ID

CHAR 20

Message ID The structure BAPIRET2 takes into account the name space extension for the message class as of Release 4.0. If you want messages to be compatible with earlier R/3 Releases, use the message classes before Release 4.0.

NUMBER

NUMC 3

Message number

MESSAGE

CHAR 220

Full message text from the message table. All variables (in fields Message_V1 to Message_V4) have been replaced with text.

LOG_NO

CHAR 20

Application log number This is empty if no log used.

Note that for type A error messages (abort), an application log is not created, as in this case there is no COMMIT WORK.

LOG_MSG_NO

NUMC 6

Current message number in application log

MESSAGE_V1
MESSAGE_V2
MESSAGE_V3 MESSAGE_V4

CHAR 50

Fields for the variable texts of the message specified in fields ID and NUMBER.

PARAMETER

CHAR 32

Parameter containing the invalid value.

ROW

INT 4

Line number of the data record containing the invalid value

FIELD

CHAR 30

Field containing the invalid value.

SYSTEM

CHAR 10

System (logical system) in which the message was generated.

 

Reference Structure BAPIRET1

This structure is filled via the function module BALW_BAPIRETURN_GET1. It consists of the fields in the BAPIRET2 structure excluding the fields PARAMETER, ROW and FIELD.

Return Parameters in the ALE Distributed Environment

Once the function module responsible for converting the IDoc into the appropriate BAPI in the receiving system has been called, IDoc status records are written which log the messages reported by the return parameter.

If the value of the field Type is A (abort) in at least one of the return parameter entries, status 51 (error, application document has not been posted) is written to all the IDoc status records and a ROLLBACK executed. If the value of the field Type is E (error) in at least one of the return parameter entries, status 51 (error, application document has not been posted) is written to all the IDoc status records and a COMMIT WORK is executed anyway. Otherwise status 53 (application document posted) is written and a COMMIT WORK is executed.

Application Log and Application-Specific Error Tables

If the information provided in the Return parameter is not sufficient, you can log errors with the application log. The logging should be done by the BAPI itself so that function modules called directly by this BAPI do not have to be modified. The fields LOG_NO and LOG_MSG_NO of the Return parameter return the application log numbers and their messages.

As of Release 4.6A you can already maintain the log number when you create the application log. Several instances of an application object can be maintained at the same time and can be updated together. The update task can be also used for application logs, that is, log entries are and no longer directly written to the database, they are written via the update task. If you plan to use application logs in your BAPI, you must write these using the update task.

For further information on application logs see Creating Applications Logs in the document BC - Extended Function Library Applications.

If this still does not provide enough information, the calling application can define its own additional error tables. There are no set guidelines for these additional tables. The Return parameter in your BAPI could give details of the messages in the error tables, for example, if there are error messages (type E) in the table. The calling program then has immediate control over the contents of the error table and does not have to first search for error messages.

The use of the application log and error tables enable error messages to be returned if they cannot be adequately returned in the return parameter.

Note that for type A error messages (abort), an application log is not created, as in this case there is no COMMIT WORK.