Actions by the BAPI Developer

Creating Extension Parameters in BAPI Interfaces

Depending on the requirements put to the BAPI, the BAPI developer creates one extension parameter for the data import ( ExtensionIn ) and/or one extension parameter for the data export ( ExtensionOut ) in the interface of the BAPI function module. You must observe the following guidelines :

1. The naming convention for the extension parameter is ExtensionIn for import parameter enhancements and ExtensionOut for export parameter enhancements.

2. The extension parameters must be defined as table parameters.

3. The extension parameters are always based on reference structure BAPIPAREX .

4. All the BAPI table extensions used in the BAPI and their assignment to the respective BAPI parameters must be described in the documentation of the extension parameter.

   Note

   The section Use with the Standardized BAPIs contains recommendations on which extension parameters to used for the individual standardized BAPIs.

Defining BAPI Table Extensions

This step is only necessary if you plan to think about underlying SAP tables for the BAPI that the customers can sensibly enhance with their own fields and existing fields. If so, use transaction SE11 to create a BAPI table extension as a data structure for every SAP table that can be sensibly extended. The following guidelines have to be observed when creating BAPI table extensions:

1. The naming convention for BAPI table extensions is BAPI_TE_<table_name>. If you cannot follow this naming convention due to the length restriction for structure names, then you must specify this explicitly in the documentation of the table extension and the BAPI.

2. Create one BAPI table extension for each table to be extended. Note, however, that each table can only have one table extension. Therefore, if several BAPIs use the same table, they will have to share the table extension.

   Exception :

   If a BAPI has two or more parameters that refer to the same database table, then a separate BAPI table extension is created for each of these BAPI parameters. The naming convention in this case is BAPI_TE<table_name><consecutive_number>. In our example, the table extensions would be called BAPI_TE_STRAVELAG1, BAPI_TE_STRAVELAG2, and so on.

3. The structure of the BAPI table extension must contain all the identified key fields of the table to which the BAPI table extension relates. The table extension does not contain any other fields except the key fields.

   In the above example, the BAPI table extension must be called BAPI_TE_STRAVELAG and possess key AGENCYNUM.

BAPI Function Module Call

Every BAPI function module can have the following structure:

FUNCTION BAPI_ERWEITERUNG_TEST
        <Programmtext>
<BADI_1>
        <Programmtext>
<Auslesen von ExtensionIn>
        <Programmtext>
<BADI_2>
        <Programmtext>
END FUNCTION
            

Therefore, in the most complex case, BAPI developers must allow customer enhancement to their function modules in three places:

1. BAdI 1

   This BAdI is only required if the BAPI has an ExtensionIn parameter. This BAdI allows the customer to check all the data that is passed on to the BAPI, including the ExtensionIn parameter. The BAdI must have the following parameters:

   1. All BAPI import parameters and tables are passed on as an import. In particular, the ExtensionIn parameter must be available in the BAdI.

   2. The BAdI must return the Return parameter as an export, to allow the BAPI to report any errors that occurred in the BAdI.

   3. If required by the application, additional parameters can also be passed on to the BAdI as import or export.

2. Read from ExtensionIn

   This step is only required when the customer has added their own fields to an SAP table or included existing fields in the BAPI, and the developer wants to make sure that the enhancements passed on in the ExtensionIn are automatically written to the additional table fields. This means no customer programming is required to write the customer enhancements directly to the corresponding database tables.

   In particular, you should program this automatic filling of the extended fields in the case of Create(), Add<sub-object>(), and SaveReplica() BAPIs.

   The extraction of a data record from the container is performed in two steps:

   1. The container format is first converted to the required temporary structure by the corresponding BAPI table extension. Because the values have the same sequence in both the container and the BAPI table extension, this can be implemented with a single MOVE command.

   2. This structure is then used to fill the additional database fields with MOVE-CORRESPONDING. To do this, the corresponding key value must be used to determine the line in the database where the values will be inserted.

      The entire process can be described in pseudo-coding as follows:

      LOOP at ExtensionIn
              IF gesuchte Table Extension in ExtensionIn vorhanden
              THEN MOVE Werte aus ExtensionIn TO Table Extension
              END.
                      Suche richtige Zeile in Datenbanktabelle.
                      Fülle Datenbanktabelle mit Table Extension
                      mittels MOVE-CORRESPONDING.
      END LOOP
                              

   Therefore the table enhancements can only be filled automatically when the fields the customer added to the BAPI table extension correspond exactly with the fields of the extended table, as the MOVE-CORRESPONDING command only works in this case.

   Our concrete example results in the following coding:

   loop at extensionin.
           case extensionin-structure.
                   when 'BAPI_TE_STRAVELAG.
                           move extensionin+c_lenstruc to wa_bapi_te_stravelag.
                           * Die Konstante c_lenstruct besitzt die Länge des Feldes
                           * STRUCTURE der BAPIPAREX-Struktur. Durch diese Konstante
                           * wird sichergestellt, dass nur die Werte aus VALUEPART1
                           * bis VALUEPART4 der Table Extension zugewiesen werden.
                           read table t_stravelag with key agencynum = agencynumber.
                           catch system-exceptions conversion_errors  = 1.
                                   move-corresponding wa_bapi_te_stravelag to t_stravelag.
                           endcatch.
                     

   Exception :

   In the case of Create() BAPIs with internal number assignment, the value of the key is not yet know when the BAPI is called, and therefore cannot be included in the container. As a consequence, the key value generated in the BAPI must be explicitly assigned to the table extension after the container has been extracted. In this case, we would modify the above example as follows:

   loop at extensionin.
           case extensionin-structure.
                   when 'BAPI_TE_SRAVELAG.
                           move extensionin+c_lenstruc to wa_bapi_te_stravelag.
                                   * Jetzt wird nachträglich der erzeugte Schlüssel an die
                                   * Table Extension übergeben:
                                   move agencynumber to wa_bapi_te_stravelag-agencynum.
                                   read table t_stravelag with key agencynum = agencynumber.
                                   catch system-exceptions conversion_errors  = 1.
                                           move-corresponding wa_bapi_te_stravelag to t_stravelag.
                                   endcatch.
                     

3. BAdI 2

   This BAdI is required when the customer is allowed to further process the data passed on with ExtensionIn or otherwise manipulate the database. If the customer has enhanced the export parameters of the BAPI, the second BAdI must be used to fill the ExtensionOut parameter. The BAdI must have the following parameters:

   1. The BAdI is given all BAPI import parameters, including ExtenionIn , as an import. Table parameters in the BAPI function module remain as tables in the BAdI.

   2. The BAdI must return ExtensionOut and the Return parameter as an export.

   3. If required by the application, additional parameters can also be passed on to the BAdI as import or export.

   Note

   The section Use with the Standardized BAPIs contains recommendations on which precautions should be taken for the respective underlying function modules.

   A detailed programming example for implementing a BAPI module is available under Examples .

Filling ExtensionIn Before a BAPI Call

If the coding supplied by SAP calls a BAPI, the developer has to decide whether or not to automatically fill the ExtensionIn parameter with the enhancements before the call. In this case, the filling of ExtensionIn has to be programmed explicitly. The concrete data flow for filling ExtensionIn is described under Actions by the Customer .

Evaluating ExtensionOut After a BAPI Call

If a BAPI is called in coding delivered by SAP then the developer can ensure that the ExtensionOut parameter is evaluated automatically. Note, however, that evaluations of this type can only be anticipated in rare cases.