Docstoc

bapiprg

Document Sample
bapiprg Powered By Docstoc
					BAPI PROGRAMMING..............................................................................................3
VERSION ...............................................................................................................................................................4
COPYRIGHT ..........................................................................................................................................................4
CONVENTIONS......................................................................................................................................................4

             BAPI .......................................................................................................................................................5

             BOR.........................................................................................................................................................6


             TRANSACTION M ODEL FOR DEVELOPING BAPI S.............................................................................7


                 USING THE TRANSACTION M ODEL IN RELEASE 3.1.............................................................8
           TRANSACTION M ODEL FOR RELEASE 3.1............................................................................................9


                 USING THE TRANSACTION M ODEL IN RELEASE 4.0A .........................................................9
           EXTENDED TRANSACTION MODEL ....................................................................................................10


             DEFINING AND IMPLEMENTING THE BAPI ......................................................................................10

                        FREQUENTLY USED BAPI S....................................................................................................11


                        DEFINING A BAPI SCENARIO ...............................................................................................12


                        REVIEW ....................................................................................................................................14


                        DEFINING A BAPI AND ITS INTERFACE ...............................................................................14
                        1
                        23
                                     DETERMINING THE SAP BUSINESS OBJECT AND ITS KEY FIELDS.....................15


                                    DEFINING THE INTERFACE STRUCTURE OF THE BAPI..........................................16


                                    NAMING PARAMETERS IN THE FUNCTION M ODULE .............................................17


                                    SPECIFYING THE REQUIRED OBJECTS IN ABAP DICTIONARY ............................18


                                    NAMING THE METHOD IN THE BOR .........................................................................20


                                    NAMING PARAMETERS IN THE BOR.........................................................................20


                       CREATING INDIVIDUAL PROGRAMMING OBJECTS..............................................................21

                                    CONVERSION BETWEEN INTERNAL AND EXTERNAL DATA FORMATS................22
                                   1
                                   23
                                               CONVERTING BETWEEN INTERNAL AND EXTERNAL DATA FORMATS...23


                                                                                                                                                                1
                        APPLICATION EXAMPLE ...............................................................................................24
              1
              23
                  DEFINING M ETHODS IN THE BOR USING THE BOR/BAPI W IZARD ...................26
            EXAMPLE OF A FUNCTION M ODULE .........................................................................................27


     TESTING THE BAPI..............................................................................................................................28
1
23
     RELEASING AND FREEZING THE BAPI ..............................................................................................29


     PROGRAMMING BAPIS.........................................................................................................................30

               PROGRAMMING CHANGE BAPI S............................................................................................31

               PROGRAMMING REPLICATE/CLONE BAPI S..........................................................................33

               PROGRAMMING VALUE RANGES............................................................................................35

               INTERNAL AND EXTERNAL DATA FORMATS........................................................................35

               REPORTING ERRORS.................................................................................................................37


                             Providing Input Help (F4 Help)................................................................. 40


               IMPROVING THE PERFORMANCE OF YOUR BAPI .................................................................42


     ENHANCEMENTS TO EXISTING BAPI S ...............................................................................................43


     CUSTOMER M ODIFICATIONS OF BAPIS .............................................................................................46


     IMPLEMENTING BAPI S IN ALE SCENARIOS .....................................................................................47
1
23
     BAPI IMPLEMENTATION CHECKLIST .................................................................................................48




2
      BAPI Programming
Purpose
This document describes the guidelines you should follow to implement Business
Application Programming Interfaces (BAPIs). It is targeted at developers who want to
implement BAPIs.
This document describes the guidelines valid at the time this document was published.
These guidelines will be updated in subsequent R/3 Releases.
All developments should be done in the customer name space; all changes to existing
development objects are considered to be modifications.

Prerequisites
To program and implement a BAPI you need to have:
•   Basic knowledge of BAPIs, as described in BAPI - Introduction and Overview
•   Knowledge of the ABAP programming language and environment
•   Basic knowledge of the R/3 System

Process Flow
To implement a BAPI follow the processes described in the sections below as closely
as possible:

Transaction Model for Developing BAPIs

Defining and Implementing the BAPI

Creating Individual Programming Objects

Programming BAPIs

Testing the BAPI

Releasing and Freezing the BAPI


A BAPI Implementation Checklist is available to guide you through the implementation.
You should print it out and use it as a reference during the entire implementation
process.


Other topics related to developing BAPIs are:
Enhancements to Existing BAPIs
Customer Modifications of BAPIs
Implementing BAPIs in ALE Scenarios


Select F1 to display help on the help function.
Version
Copyright
Conventions




                                                                                        3
Version
R/3 Release 4.0
December 1997




Copyright

©Copyright 1997 SAP AG. All rights reserved.
No part of this documentation may be reproduced or transmitted in any form or for any
purpose without the express permission of SAP AG.
SAP AG further does not warrant the accuracy or completeness of the information, text,
graphics, links or other items contained within these materials. SAP AG shall not be
liable for any special, indirect, incidental, or consequential damages, including without
limitation, lost revenues or lost profits, which may result from the use of these materials.
The information in this documentation is subject to change without notice and does not
represent a commitment on the part of SAP AG in the future.
Some software products marketed by SAP AG and its distributors contain proprietary
software components of other software vendors.
Microsoft®, WINDOWS®, NT® and EXCEL® and SQL-Server® are registered
trademarks of Microsoft Corporation.
IBM®, OS/2®, DB2/6000®, AIX®, OS/400® and AS/400® are a registered trademark
of IBM Corporation.
OSF/Motif® is a registered trademark of Open Software Foundation.
ORACLE® is a registered trademark of ORACLE Corporation, California, USA.
INFORMIX®-OnLine for SAP is a registered trademark of Informix Software
Incorporated.
UNIX® and X/Open® are registered trademarks of SCO Santa Cruz Operation.
ADABAS® is a registered trademark of Software AG.
SAP®, R/2®, R/3®, RIVA®, ABAP/4®, SAPoffice®, SAPmail®, SAPaccess®, SAP-
EDI®, SAP ArchiveLink®, SAP EarlyWatch®, SAP Business Workflow®, R/3 Retail®
are registered trademarks of SAP AG.
SAP AG assumes no responsibility for errors or omissions in these materials.
All rights reserved.




Conventions


     4
Type style                        Description
Interface Text                    Words or characters that appear on the screen. This
                                  includes field names, screen titles, pushbuttons, menu
                                  names, and menu options.
Document Title                    Cross-references to other documentation
User Entry                        Words and characters that you enter exactly as they appear
                                  in the documentation
<Variable User Entry>             Variable user entry. Pointed brackets indicate that you
                                  replace these words and characters with appropriate entries.
NAME                              Names of elements in the R/3 System. These include
                                  program names, transaction codes, table names, ABAP
                                  language elements, file names, and directories.


Icon                              Description
                                  Descriptions of R/3 System components (such as MM, FI-
                                  SL, HR-PA)

                                  Descriptions of business and system objects (such as cost
                                  center, table, material)

                                  Business processes that can be completed in the R/3
                                  System

                                  Descriptions of R/3 System functions (such as reporting
                                  functions)

 1                                Step-by-step procedures for completing a specific task
 23

                                  Overview information


                                  Concept information



       Note                       Important information like special considerations or
                                  exceptions
                                  Example
       Example

                                  Helps you avoid errors such as those that could lead to data
       Caution                    loss




          BAPI
   Definition
   A Business Application Programming Interface (BAPI) is a precisely defined interface
   providing access to processes and data in business application systems such as R/3.


                                                                                            5
BAPIs are defined as API methods of SAP Objects. These objects and their BAPIs are
described and stored in the BOR (BOR).

Use
BAPIs can be called within the R/3 System from external application systems and other
programs. A BAPI call can either be made as an object oriented method call or as a
remote function call (RFC).
BAPIs are a global communication standard for business applications.
Examples of what BAPIs can be used for include:
•   R/3 satellite systems
•   Distributed R/3 scenarios using Application Link Enabling (ALE)
•   Connecting R/3 Systems to the Internet using Internet application components
    (IACs)
•   Visual Basic programs as frontends to R/3 Systems
•   Work flow applications that extend beyond system boundaries
•   Customers' and partners' own developments
•   Connections to non-SAP software
•   Connections to legacy systems


See also:
BAPI - Introduction and Overview.




        BOR
Definition
The Business Object Repository (BOR) is the object oriented repository in the R/3
System. It contains, among other objects, SAP Business Objects and their methods.
In the BOR a Business Application Programming Interface (BAPI) is defined as an API
method of an SAP Business Object. Thus defined, the BAPIs become standard with full
stability guarantees as regards their content and interface.

Use
With regard to SAP Business Objects and their BAPIs, the BOR has the following
functions:
•   Provides an object oriented view of R/3 System data and processes.
    R/3 application functions are accessed using methods (BAPIs) of SAP Business
    Objects. Implementation information is encapsulated; only the interface
    functionality of the method is visible to the user.
•   Arranges the various interfaces in accordance with the component hierarchy,
    enabling functions to be searched and retrieved quickly and simply.
•   Manages BAPIs in release updates.


    6
    BAPI interface enhancements made by adding parameters are recorded in the
    BOR. Previous interface versions can thus be reconstructed at any time.
    When a BAPI is created the release version of the new BAPI is recorded in the
    BOR. The same applies when any interface parameter is created.
    The version control of the function module that a BAPI is based on is managed in
    the Function Builder.
•   Ensures interface stability.
    Any interface changes that are carried out in the BOR, are automatically checked
    for syntax compatibility against the associated development objects in the ABAP
    Dictionary.



Integration
You should only define a BAPI as a SAP Business Object method in the BOR if the
function module that the BAPI is based on has been fully implemented.
Full access to the BOR is restricted to the persons responsible for the objects involved
and for quality control.

BOR-BAPI Wizard
The BOR-BAPI Wizard assists with creating new BAPI methods in the BOR. It takes
you through the creation process step by step.




       Transaction Model for Developing BAPIs
Purpose
The transaction model in which BAPIs are used determines how you have to program
BAPIs.
The transaction model described here has been used to develop BAPIs for R/3
Releases 3.1 and 4.0A.

Logical Unit of Work (LUW) and Statelessness
Within the context of this transaction model a transaction represents one processing
step or one logical unit of work (LUW). When a transaction is called, database
operations are either fully executed or not at all. The whole transaction must be
programmed to be stateless.
This transaction model requires that:
•   No data is imported that may indirectly affect the result. If a transaction is called
    more than once, each call must have the same result.
    For BAPIs this means, for example, that Set or Get parameters cannot be used.
    However, you can keep Customizing data in a global memory as this data remains
    unchanged even if transaction calls are repeated.
•   There must be no functional dependencies between two transactions.
•   Either all relevant data has to be changed in the database or none at all.


The following sections describe how the transaction model effects BAPI development:
•   Using the Transaction Model in Release 3.1


                                                                                            7
 •    Using the Transaction Model in Release 4.0A




              Using the Transaction Model in Release
3.1
 Purpose
 The example below of an external program calling a BAPI to change data in an R/3
 System, illustrates how the transaction model affects BAPI development in Release
 3.1. Assume the transaction was written in, for instance, Visual Basic and that data is to
 be changed in the R/3 System only.
 The RFC connection is live the whole time the external program is logged on to the R/3
 System to avoid having to connect and disconnect repeatedly. When the RFC
 connection is already established, an RFC call does not essentially take up any more
 CPU time than a direct call to the function module from within the R/3 System.
 There is one BAPI call for each transaction in the transaction model supported in 3.1.
 BAPIs can only be called synchronously. A BAPI call is essentially the call of the
 underlying RFC capable function module.

 Process Flow
 The process flow of the program consists of the steps below (see graphic):


 Log on
      .....     (Visual Basic source code)
      Call BAPI to read and/or change data
      .....     (Visual Basic source code)
      Call BAPI to read and/or change data
      .....     (Visual Basic source code)
 Log off

 Prerequisites
 What do the terms "LUW" and "statelessness" mean to BAPIs that are implemented in
 the framework of this transaction model?
 If a transaction represents one Logical Unit of Work and in addition is supposed to be
 stateless, BAPIs are affected as follows:
 •    Initial state each time a BAPI is called
      A repeated call of one BAPI must produce the same result. Only data that is not
      affected by the execution of the BAPI, for example, Customizing data, can be
      buffered.
 •    No functional dependency between two BAPIs
      A BAPI call must not be negatively affected by an earlier call of another BAPI. A
      follow up call must not presuppose an earlier call.
 •    All or nothing principle
      A database change, for example, creating a new sales order, must be carried out

       8
     completely or not at all (LUW).
     This is why BAPIs to be implemented in 3.1 are created with integrated commit
     control. The "Commit Work" command is always invoked at the end of the function
     module of a BAPI that modifies data.




 Transaction Model for Release 3.1




             Using the Transaction Model in Release
4.0A
 Purpose
 In Release 4.0A the Commit control must be taken out of write BAPIs, that is, those
 BAPIs that cause database changes. However, the existing transaction model used in
 Release 3.1 should not be changed. This is achieved by using the RFC capable
 function module BAPI_TRANSACTION_COMMIT which executes the command
 "Commit Work".
 This procedure is required because BAPIs are used for continued development of the
 R/3 System, for example, for separating individual R/3 components. If this is the case,
 BAPIs must support the transaction model used in the R/3 System.

 Features
 A program based on this transaction model could consist of the following steps (see
 graphic):
 Log on
     .....     (Visual Basic source code)
     Call BAPI to read and/or change data



                                                                                           9
    Call BAPI_TRANSACTION_COMMIT
    .....    (Visual Basic source code)
    Call BAPI to read and/or change data
    Call BAPI_TRANSACTION_COMMIT
    .....    (Visual Basic source code)
Log off




Extended Transaction Model




       Defining and Implementing the BAPI
Purpose
A BAPI is an API method of a business object and is defined as such in the Business
Object Repository (BOR). However, a BAPI is implemented as an RFC capable
function module which is maintained in the Function Builder.
For function modules that implement BAPIs certain standards and rules must be
adhered to over and above the standard programming rules for function modules. This
section describes how to define a BAPI and which particular guidelines to comply with.
When implementing BAPIs follow the requirements below to ensure you achieve
consistent behavior and representation of BAPIs as object oriented methods of SAP
Business Objects.
There is a range of BAPIs that provide basic functions and these can be implemented
for most of the SAP Business Objects. For information on these BAPIs see the section
Frequently Used BAPIs. Check if the BAPI you want to implement is in one of these
general categories.




     10
Process Flow
The process of defining and implementing a BAPI consists of the following steps:
•   Describing the Scenario the BAPI is Used in
•   Reviewing the BAPI Concept and BAPI Scenario
•   Defining a BAPI and Its Interface
•   Creating Individual Programming Objects
•   Testing the BAPI
•   Releasing and Freezing the BAPI




      Frequently Used BAPIs
Definition
Some BAPIs and methods provide basic functions and can be used for most SAP
Business Objects. These BAPIs are:

BAPIs for Reading Data
The following BAPIs provide you with read-only access to data in the associated
Business Object:
•   GetList
    With this BAPI you can select a range of object key values, for example, company
    codes and material numbers. To specify appropriate selection requirements the
    calling program must pass the relevant parameters to the interface.
    The key values selected by the BAPI GetList are returned to the calling program in
    a table, together with other useful information, for example, short texts. The key
    values can then be passed on to another BAPI for further processing, for example,
    the BAPI GetDetail, as listed below.
    For further information on programming GetList BAPIs see Programming Value
    Ranges.
•   GetDetail
    The BAPI GetDetail uses a key to retrieve details about a specific instance of an
    object and returns this data to the calling program.
•   GetStatus
    The BAPI GetStatus is used to query the status of an SAP Business Object, for
    example, to determine the processing status of a sales order. This BAPI is used
    only for displaying the status of an object and does not retrieve full details like the
    BAPI GetDetail.
•   ExistenceCheck
    The BAPI ExistenceCheck checks whether an entry exists for an SAP Business
    Object, for example, whether the customer master has been created. You should
    implement this method as a workflow method and not as a BAPI (RFC capable
    function module).
    The method CompanyCode.ExistenceCheck of the business object CompanyCode
    (BUS0002) is an example of this. This workflow method is indirectly invoked when


                                                                                              11
    the calling program instantiates an object, for example, by using
    GetSAPObject("CompanyCode") from within Visual Basic.

BAPIs for Creating or Changing Data
The following BAPIs can create, change or delete instances of a business object:
•   Create or CreateFromData
    The BAPI Create or CreateFromData creates an instance of an object, for example,
    a sales order.
•   Change
    The BAPI Change changes an existing instance of a SAP Business Object, for
    example, a sales order.
    For more information about the BAPI Change see Programming Replicate/Clone
    BAPIs.
•   Delete
    The BAPI Delete deletes an instance of a SAP Business Object, for example, a
    sales order.

BAPIs for Replicating Business Object Instances
The BAPIs below can be implemented as methods of business objects that can be
replicated. For further information about these BAPIs see Programming
Replicate/Clone BAPIs:
•   Replicate
    The BAPI Replicate is used by a client system to request clones of business
    objects in a server system.
    This method must be implemented for each business object to be cloned.
At least one of the following BAPIs must be implemented for each business object to be
cloned:
•   Clone
    The BAPI Clone is used by a system to replicate one business object on another
    system or to modify one business object that has already been cloned.
•   CloneMultiple
The BAPI CloneMultiple is used by a system to replicate several business objects on
another system or to modify several business objects that have already been cloned.
Unlike the BAPI Clone, the BAPI CloneMultiple can replicate or modify several
business object instances at the same time.




     Defining a BAPI Scenario
Purpose
Before you program a BAPI you should clearly define the processes and situations the
BAPI will be used for.

Process Flow
To define the scenario the BAPI is to be used for, consider the following issues:


     12
•   Which scenario is to be implemented?
    Every BAPI should be based on a model of a scenario in which it can be usefully
    employed. You can describe the scenario in the form of a process model.
•   Which SAP Business Objects are involved?
    From the scenario definition and with the help of the process model you can get
    information about the SAP Business Objects relevant to the BAPI scenario.

       Example

       In the scenario to be implemented, a BAPI is required to read data about a
       creditor. First of all, a list of creditors is to be displayed from which a specific
       creditor can be selected. Then, using another BAPI, specific details about this
       creditor are to be displayed.
       The relevant SAP Business Object for this scenario is Creditor.
•   What functionality should the BAPI provide and how does it affect related BAPIs,
    especially the other BAPIs of the SAP Business Object in question?
    In line with the scenario concept BAPIs must complement each other to create a
    complete scenario. Their relationships with each other must be clearly defined.

       Example

       To read a creditor's details as described in the above scenario, two BAPIs are
       required:
       -     Display list of creditors
       -     Display details of a specific creditor
       The interdependency between these two BAPIs is evident because first the
       creditor list is displayed to obtain the ID of the specific creditor sought. From this
       ID, details of this creditor can then be displayed.
       However, the two BAPIs remain functionally independent of each other,
       because if the creditor ID is known, the BAPI "Display details of a specific
       creditor" can be used without first calling the BAPI "Display list of creditors".
•   To what extent can the BAPI's functionality be implemented within the scope of the
    business object?
    A BAPI should be developed so that it provides functionality exclusively within the
    context of its associated SAP Business Object. If the data of a different SAP
    Business Object is to be read or updated then the appropriate interface for this
    object must be used. The functions or methods of these other objects are used
    implicitly (delegation principle).

       Example

       The BAPIs required to read creditor details in the above scenario are only able
       to access data in the SAP Business Object Creditor. Other object types are not
       involved.
•   Is the BAPI assigned to the SAP Business Object in a meaningful and semantically
    correct way?

Result
Once you have considered these issues you will be able to clearly conceptualize the
functionality of the planned BAPI(s). You will also have identified the SAP Business
Objects relevant to the BAPI scenario.




                                                                                                13
     Review
Purpose
In the previous step you created a concept for a scenario a BAPI could be applied to.
You also defined relevant SAP Business Objects.
Before you implement the scenario and begin defining and developing the BAPI, you
should carry out a review of the scenario concept.

Process Flow
You should carry out the review of the BAPI scenario in cooperation with all persons
involved in the BAPI development and those responsible for quality control in your
development group.

Result
Start developing the BAPI only after you have successfully completed the review.




     Defining a BAPI and Its Interface
Purpose
After you have carried out the review of the BAPI concept and it has been accepted,
you can start defining the BAPI itself.
In this step, you will decide on the names, parameters, and characteristics of the BAPI
and determine the structures the BAPI will be based on.
Only after you have planned and defined these required details can you start to
implement the BAPI, as described in Creating Individual Programming Objects and
Programming BAPIs.

Process Flow
To define the scope and required components of the BAPI to be implemented, the
following steps must be completed:
•   Determining the SAP Business Object and Its Key Fields
•   Defining the Interface Structure of the BAPI
•   Identifying the name of the function group, or if a function group does not exist
    already, planning a name for one.
    All BAPIs belonging to one SAP Business Object should be stored as function
    modules in one function group. Ascertain whether a function group has already
    been created for the BAPIs of the SAP Business Object in question. If a function
    group does not already exist, then plan a name for the one to be created.
    You can use the default technical name (object type) of the SAP Business Object
    as the basis of the function group name. The technical name of a SAP Business
    Object usually takes the form of BUSnnnn, where n is a number. Use the suffix
    "nnnn" as the name of the function group. For example, if the technical name of the


    14
      object is BUS1008 then the associated BAPI function group is called 1008.
      To ascertain the technical name of the Business Object, open the Business Object
      in the Business Object Repository (BOR), as described in Determining the SAP
      Business Object and Its Key Fields. To display further details, for example, the
      object type, double click the name of the Business Object.
 •    Assigning a name to the function module
      Choose a name that gives an indication of what the BAPI is used for. The naming
      convention is: BAPI_<Business Object name>_<method name>. For information
      about naming a method refer to Naming the Method in the BOR.
      For example, in the case of a BAPI which reads details for the object type Creditor,
      the name of the associated function module is BAPI_CREDITOR_GETDETAIL.
 •    Naming Parameters in the Function Module
 •    Defining the format for passing the values in the function module interface.
      Parameters must not be converted before they are passed to and from the BAPI
      interface. This is because BAPIs are programming interfaces and not end user
      interfaces. Exceptions are currency codes, ISO codes and fields with an internal
      key.
 •    Specifying the Required Objects in ABAP Dictionary
 •    Naming the Method in the BOR
 •    Naming Parameters in the BOR




 1
 23
      Determining the SAP Business Object and
Its Key Fields
 You have to identify the relevant SAP Business Object in the Business Object
 Repository (BOR) and determine whether the key fields of the Business Object are
 relevant for your BAPI.
 A key is defined in the BOR for most SAP Business Objects. This key can consist of
 several key fields. The contents of these key fields uniquely identifies one individual
 instance of an SAP Business Object.
 You can differentiate between instance-dependent and instance-independent BAPI
 methods. Unlike instance-independent methods, instance-dependent methods relate to
 one instance (one specific occurrence) of an SAP Business Object type, for example to
 one specific sales order.
 In the case of instance-dependent BAPIs, the key fields of the corresponding SAP
 Business Object must be used as parameters in the function module the BAPI is based
 on so that the associated object instance can be identified. The names of the key fields
 in the SAP Business Object and the corresponding parameters in the BAPI function
 module must be the same, because the name links the key fields to the parameters.
 All the key fields defined in the BOR for the SAP Business Object in question must be
 used as the parameters in the function module. For further information see Defining the
 Interface Structure of the BAPI.

         Example

         SAP Business Object Creditor has a key field named CreditorId.


                                                                                             15
          This key field must be defined as a parameter with the name CREDITORID in
          the function modules of the instant-dependent BAPIs for this Business Object.
To display the Business Object and its key fields follow the steps below:
1.   Select Tools → ABAP Workbench → Overview →Business Object Browser . The
     business objects are displayed in the order of the R/3 application hierarchy.
2.   Select the required SAP Business Object in the application hierarchy and double
     click it to open it.
3.   To display the Business Object's key fields, expand the node Key fields.




      Defining the Interface Structure of the BAPI
Purpose
In this step you are going to define the BAPI interface, that is, the individual import,
export and table parameters required for calling the BAPI.

         Caution

          You cannot use Changing and Exception parameters in a function module
          which implements a BAPI.

Process Flow
To define the interface parameters, proceed as follows:
1. Check whether the key fields of the SAP Business Object are required in the
   interface. The key fields of the SAP Business Object are some of the most important
   BAPI parameters.

     -    If a key value is to be passed to the BAPI by the calling program, the key field
          must be set as an import parameter in the function module of the BAPI. That
          way a specific instance of the Business Object is identified.
          For example, this could be a customer number (CustomerNo) in the BAPIs
          Customer.GetDetail and Customer.CheckPassword, or the number of a sales
          document in the BAPI SalesOrder.GetStatus.
     -    For BAPIs that generate instances, for example, the BAPIs Create or
          CreateFromData, the key field of the Business Object should be set as an
          export parameter in the BAPI function module.
          These BAPIs return one key value, for example, an order number in the BAPI
          SalesOrder.CreateFromData.
     -    For BAPIs that are class methods a key field is neither set as an import nor as
          an export parameter in the BAPI function module.
          Class methods are instance-independent and are called without the use of key
          values. Usually they return a table with a selection of key values. Exceptions
          are write BAPIs, as described in the list item above.
2.   Specify what other data is relevant as import, export or table parameters for the
     BAPI.
     Every BAPI must have an Export parameter return that reports messages back to
     the calling program.


     16
       Example

       The BAPI to be developed is to read data from the SAP Business Object
       Creditor. To read creditor details, the calling program has to pass the ID of the
       creditor and the company code. The creditor data returned is to include general
       details, specific details and bank details.
       To map these requirements onto the BAPI interface, the following parameters
       must be set in the function module which the BAPI is based on:
        •   The key field CreditorID of the SAP Business Object as an import
            parameter
        •   An import parameter for the company code
        •   A Return parameter that reports messages back to the calling program
        •   A parameter for general details of the creditor
        •   A parameter for specific details of the creditor
        •   A parameter for bank details of the creditor




     Naming Parameters in the Function Module
Purpose
In the previous step you identified the contents of the interface parameters. Now you
can specify the names of these parameters in the function module.

Prerequisites
You can only define export, import and table parameters in the function module
interface of the BAPI.
Give meaningful names to the parameters in the function module interface to give the
BAPI an easy-to-use interface. This is because the names you choose for the function
module parameters are used in the Business Object Repository (BOR) as the names of
the corresponding method parameters.
When assigning parameter names follow the guidelines below:
•   The names must be in English
•   The names of parameters in the function module can generally be a maximum of
    30 alphanumeric characters. The names of parameters in a function module that
    implements a BAPI can only have a maxiumum of 20 alphanumeric characters,
    because the names of parameters in the function module must be identical to the
    parameter names in the BOR, and the latter are restricted to a maxiumum of 20
    characters.
•   The names of parameters in the function module must be written in capitals.
•   Choose meaningful names and do not use abbreviations.

       Example

       In the above example based on the creditor scenario, the following parameters
       were identified:
        •   An import parameter for the key field CreditorId of the SAP Business


                                                                                           17
               Object
           •   An import parameter for the company code
           •   A Return parameter
           •   A parameter for general details of creditor
           •   A parameter for specific details of creditor
           •   A parameter for bank details of creditor
           You could use the following names for these parameters in the function
               module:

           Parameters and their Names in the Function Module

     Contents                           Name in Function Module       Parameter
                                                                      Type
     Creditor number                  CREDITORID                      IMPORTING


     Company code                     COMPANYCODE                     IMPORTING

     General creditor details         CREDITORGENERALDATA             EXPORTING


     Specific creditor details        CREDITORCOMPANYDATA             EXPORTING


     Return parameter                 RETURN                          EXPORTING

     Bank details                     CREDITORBANKDATA                TABLES




     Specifying the Required Objects in ABAP
Dictionary
 Purpose
 After you have specified the contents and names of the required interface parameters
 you can identify and define the required data objects in the ABAP Dictionary.
 Note the following:
 •   You can use individual fields, structures and tables as parameters. Every
     parameter must refer to a Dictionary object.
 •   You have to create your own data structures for the BAPI interface that are
     independent of the data structures generally used in the R/3 application. This
     enables changes to be made in R/3 applications without affecting BAPIs.
     Give meaningful names to the data structures you create. Names should begin with
     the prefix BAPI.
 •   Chose meaningful names in English for the structure fields. Up until Release 4.0
     ten characters were available for naming structures; from Release 4.0 you can use
     up to 30 characters. You can use alphanumeric characters and underscores.


      18
You can use existing data elements and domains for the fields in the BAPI
structures. As of Release 4.0 it is possible to assign English names to the data
elements in the ABAP Dictionary. Whenever possible use these names for the field
and parameter names.

   Example

   In the example in the previous steps the reference fields/tables shown below
   were identified for the parameters.
   The first example here uses structures created in Release 3.1. In this Release
   structure names had a maximum of 10 characters.
   The second example shows how you could name the structures more
   meaningfully in Release 4.0.

   Parameters and their Reference Fields in Release 3.1

   Parameter in the Function Module                  Reference Field/Table


   CREDITORID                                        BAPI1008-VENDOR_NO

   COMPANYCODE                                       BAPI1008-COMP_CODE


   CREDITORGENERALDATA                               BAPI1008_4


   CREDITORCOMPANYDATA                               BAPI1008_5

   RETURN                                            BAPIRETURN2


   CREDITORBANKDATA                                  BAPI1008_6


   Parameters and their Reference Fields in Release 4.0

   Parameter in the Function Module          Reference Field/Table


   CREDITORID                                BAPI1008-VENDOR_NO

   COMPANYCODE                               BAPI1008-COMP_CODE


   CREDITORGENERALDATA                       BAPI1008_CREDITORGENERALDATA



   CREDITORCOMPANYDATA                       BAPI1008_CREDITORCOMPANYDATA



   RETURN                                    BAPIRETURN2


   CREDITORBANKDATA                          BAPI1008_CREDITORBANKDATA




                                                                                    19
     Naming the Method in the BOR
Purpose
You can now plan the name of the BAPI method in the Business Object Repository
(BOR).

Prerequisites
The individual components of BAPI names are identified by the use of upper and lower
case letters, for example, ChangePassword.
BAPI names must be meaningful and be in English, and can only have a maximum of
30 characters. For example:
•   ExistenceCheck
•   ChangePassword
•   GetDetail
If you are implementing one of the frequently used BAPIs use the appropriate generic
name.
To get an idea about naming BAPIs take a look at existing BAPIs of an SAP Business
Object in the BOR. Select an SAP Business Object in the application hierarchy in the
Business Object Browser and expand the node Methods.
BAPIs are identified by the API indicator (green circle) to the right of the method name.




     Naming Parameters in the BOR
Purpose
The parameter names of the methods in the Business Object Repository (BOR) are
based on the parameter names in the function module. You have already named the
parameters of the function module in Naming Parameters in the Function Module.

       Caution

          From Release 4.0 the names of the BAPI parameters in the BOR and the
          names of the parameters in the corresponding function module must be
          identical. This was not necessarily the case in earlier releases.


When naming parameters of a BAPI in the BOR take account of the following:
•   The parameters must be in English.
•   Unlike parameter names in the function module that must be written completely in
    upper case, the components of parameter names in the BOR are separated by
    upper and lower case letters. Every new word in the parameter name begins with a
    capital letter, for example, ChangePassword.
•   A parameter name in the BOR cannot have more than 20 characters.
To get an idea about naming BAPI parameters, take a look at the parameters of
existing BAPIs in the BOR. Select an object type in the application hierarchy in the
Business Object Browser. Expand the node for the object's methods, then select a
BAPI, then finally select Parameter.

     20
       Example

       In the example in the previous steps six parameters for a BAPI were identified
       and names given to these parameters in the function module.
       The table below shows what the parameter names could look like in the function
       module and in the BOR.

        Parameters and their Names in the Function Module and in the BOR

        Contents                 Name in Function                          Name in the BOR
                                 Module
        Creditor number          CREDITORID                                Defined as a key field
                                                                           of the Business Object
                                                                           Creditor and NOT as a
                                                                           BAPI parameter.




                                                                           CompanyCode
                                 COMPANYCODE
        Company code
                                                                           CreditorGeneralData
                                 CREDITORGENERALDATA
        General creditor
        details
                                                                           CreditorCompanyData
                                 CREDITORCOMPANYDATA
        Specific creditor
        details
                                                                           Return
                                 RETURN
        Return parameter
                                                                           CreditorBankData
                                 CREDITORBANKDATA
        Bank details




     Creating Individual Programming Objects
Purpose
After you have identified the individual programming objects and given them names you
should create them in the R/3 System as required.

Process Flow
To create the required programming objects in R/3 the following steps are required:
•   Creating the Dictionary objects, for example, structures, fields and domains, in the
    ABAP Dictionary.
•   Creating the function group in the Function Builder (if required).
•   Creating the function module in the Function Builder.
•   Writing documentation for the BAPI.



                                                                                           21
     BAPI documentation is essential because it is very difficult to use a BAPI that has
     not been well documented.
     The BAPI documentation must be written in the Function Builder for the function
     module that the BAPI is based on.
     Make sure that the documentation is translated into the required languages.
 •   Using the program to map the internal data format onto the external data format, as
     described in Conversion Between Internal and External Data Formats.
 •   Writing the program for the function module. Refer to Example of a Function
     Module.
     Also, see Programming BAPIs for more information.
 •   Defining the function module as a method of the corresponding SAP Business
     Object in the BOR, as described in Defining Methods in the BOR Using the
     BOR/BAPI Wizard.
 You should then verify that the parameters and parameter types of the method in the
 BOR match the parameters of the underlying function module in the Function Builder.




      Conversion Between Internal and External
Data Formats
 Use
 According to the guidelines BAPI interfaces should only have English field names.
 However, in the internal working structures of a BAPI German field names are often
 used.
 Moreover in one of the previous steps you created your own structures for your BAPI
 which are different from the structures used in R/3 applications. This is necessary to be
 able to freeze the BAPI structure and to maintain a stable BAPI interface, yet at the
 same time, to enable further development in the R/3 application. For more information
 refer to Internal and External Data Formats.
 As a result of these discrepancies the fields of the internal working structure of the
 BAPI must be mapped onto the fields of the BAPI interface before the BAPI is called.
 You can generate function modules which help to automatically convert and map the
 data.
 You can use the generated function modules in the source code of your BAPI for:
 •   Mapping the internal working structures of the BAPI onto the external BAPI
     structures before the BAPI is called
 •   Mapping the result onto the internal structures after the BAPI call
 •   When implementing the BAPI, mapping the inbound parameters onto the internal
     structure (structuring import parameters)
 •   When implementing the BAPI, mapping the result from the internal structure onto
     the BAPI (structuring export parameters)

 Features
 The function modules generated have the following functions:
 •   They map between German and English field names


      22
 •    They convert ISO codes
 •    They convert currency amounts into the required internal or external format
 •    They convert internal and external keys such as those used by the PSP Element
      (Project structure plan)
 Any problems that could arise during data conversions are reported back using the
 RETURN parameter.


 Limitations
 Occasionally you may have to manually edit the source code of a function module after
 it has been automatically generated.
 Existing function modules can not yet be regenerated with this transaction. To
 regenerate an existing function module you have to manually delete the function
 module and then generate it anew.

 Activities
 To generate the required function modules see Converting Between Internal and
 External Data Formats.
 The Application Example illustrates the use of these function modules.



1
23
    Converting Between Internal and External
Data Formats
 Prerequisites
 Before you can generate the function modules to map between the internal working
 structures and the external BAPI structures, you must make sure that the internal and
 external structures exist.

 Step by Step Procedure
 To generate the function module follow the steps below:
 1.   Select Tools → Business Framework → BAPI Development → Generate module
      to map fields.
 2.   In the appropriate input fields enter the names of the external BAPI structure and
      the internal working structure you are making the conversion between.
      Specify the required direction for mapping, i.e. is the internal structure to be
      mapped onto the external structure or vice versa.
 3.   Select Function module → Generate

      A dialog box is displayed in which you can enter details of the function module to
      be generated. The input fields for the name of the function module and the short
      text contain suggested values which you can accept or change.

      In the field Function group enter the name of the function group to which the
      generated function module is to be added.

      In addition to the source text for the function module you can have a blank FORM
      routine added for your own program code if you have to make manual
      modifications. To do this, select Form to edit. The FORM routine contains the same

                                                                                           23
         parameters as the generated function module.
   4.   Select Continue.

         A table is displayed containing suggestions for the conversion of each field of the
         external BAPI structure. The table contains the following columns:

         - Status
          Indicates if the conversion is possible or if data is missing.

         - Field in external structure
          Contains the field names of the external BAPI structure.
         - Conv. type
            Displays the conversion type.
         - Field in internal structure
             Displays the fields of the internal structure to which/from which mapping is to
             be carried out.
        For further information select F1 help for columns Status and Conv. type.
   5.   To generate the function module, select Save.

   Result
   The function module is stored in the Function Builder in the function group you
   specified. You can incorporate it into the source code of your BAPI as required.




  Application Example
   The BAPI used in this fictitious example can read the standard price of a material:
         bapi_material_get_price
         importing
                  material like mara-matnr
         exporting
                  material_price like bapi_material_price.


   The external structure bapi_material_price contains the fields:

   Fields in the external BAPI structure

Field                    Description               Data element            Domain
currency_iso             ISO currency code         isocd                   isocd
currency                 Currency code             waers                   waers
amount                   Amount                    bapimatprice            bapicurr


   The application programmer in the R/3 System who intends to use this BAPI uses the
   internal structure mat_preis in his or her own program. This structure consists of the
   following fields:



         24
   Fields in the internal working structure

Field                  Description             Data element         Domain
matnr                  Material number         matnr                matnr
waers                  Currency code           waers                waers
stprs                  Unit price              stprs                strps


   The BAPI structure bapi_material_price contains an ISO currency code and a currency
   amount. After invoking the BAPI the application programmer must convert these fields
   into the internal format used in R/3 in order to be able to process the fields.
   Using the function Generate module to map fields, the application developer can
   generate the function module, map2i_bapi_material_price_to_mat_preis, which
   converts the currency and amount fields. This function module has the following
   interface:
        function map2i_bapi_material_price_to_mat_preis
            importing
              external structure bapi_material_price
            changing
              internal structure mat_preis
            exceptions
              error_during_iso_convertion
              error_converting_currency_amount.


   The application code could be as follows:
        ...
            data: matnr like mara-matnr,
                  preis like mat_preis,
                  bapi_preis like bapi_material_preis.
        ...
        *     Call BAPI
            Call function bapi_material_get_price
              exporting
                material = matnr
              changing
                material_price = bapi_preis.
        *     Map and convert the result to internal format
            call function map2i_bapi_material_price_to_mat_preis
                exporting
                  external = bapi_preis
                changing
                  internal = preis.
        *       exceptions



                                                                                          25
      *            error_during_iso_convertion
      *            error_during_currency_amount_conversion
      preis-matnr = matnr.




1
23
   Defining Methods in the BOR Using the
BOR/BAPI Wizard
 Prerequisites
 If the function module which your BAPI is based on has been fully implemented you
 can define it as a method of an SAP Business Object in the Business Object Repository
 (BOR).
 You use the BOR/BAPI-Wizard to do this.

 Step by Step Procedure
 First find the relevant SAP Business Object in the BOR:
 1.   Select Tools → Business Framework → BAPI Development →Business Object
      Builder.
      On the initial Business Object Builder screen you can directly access the SAP
      Business Object if you know the technical name of the object (object type). You
      have already identified the technical name in Defining a BAPI and Its Interface.
      Otherwise select Business Object Repository. In the next dialog box indicate
      whether you want to display all object types or only business objects. Then select
      Continue.
      The application hierarchy is displayed. Select the required SAP Business Object in
      the application hierarchy and open it.
 2. When the relevant SAP Business Object is displayed, select Change.

 To define your BAPI as a method of the Business Object:
 1.   Select Utilities → API Methods →Add method.
 2.   In the next dialog box enter the name of the function module, for example,
      BAPI_CREDITOR_GETDETAIL and select Continue.
 3.   In the next dialog box specify the following information for the method to be
      defined:

      -    Method
           A default name for the method is provided, based on the name of the function
           module. You will have to modify the suggested name. Delete the prefix BAPI
           and the business object name, so that only the method name is left. Begin
           every new word of the method name with a capital letter and do not use
           underscores.
           Example: If the name of the function module is
           BAPI_SALESORDER_GETSTATUS, the suggested method name might be
           BapiSalesorderGetstatus. You should edit this so that the resulting name is
           GetStatus.
      -    Texts


      26
         Enter meaningful descriptions for your BAPI.
     -   Radio buttons Dialog, Synchronous, Instance-independent
         Enter relevant details for your BAPI. Make sure that a BAPI is not dialog
         orientated. BAPIs are usually implemented synchronously.
4.   Select Next Step.
     A list of parameters and default names is displayed which you need to edit as
     required. Make sure that the parameter names of the method in the BOR are
     identical to the parameter names in the function module. Each new word in the
     parameter name must start with a capital letter.
     Also specify whether the individual table parameters are used for data import or
     data export. Table parameters are marked with a tick in the column 'MLine'
     (multiple lines).
5.   Select Next Step.
     To create the method select Yes in the next dialog box.

Result
After the program has been generated and executed, check that all the definitions have
been made correctly by the BOR/BAPI Wizard. To do this look at the method in the
BOR.




Example of a Function Module
This example function module implements the BAPI CompanyCode.GetDetail of the
SAP Business Object CompanyCode (BUS0002).
The BAPI CompanyCode.GetDetail reads details of a company code.
Note the following in the source code:
•    The name of the function module is in the format: BAPI_<Business Object
     name>_<Method name>.
•    Specific BAPI data structures are used, identified by the prefix BAPI.
•    The key field parameter "COMPANYCODEID" is defined as the import parameter.
•    The function module performs authorization checks.
•    The function module covers all exceptions.


Source Code
function bapi_companycode_getdetail.
*"------------------------------------------------------
*"*"Local interface:
*"    IMPORTING
*"      VALUE(COMPANYCODEID) LIKE BAPI0002_2-COMP_CODE
*"       EXPORTING
*"         VALUE(COMPANYCODE_DETAIL) LIKE BAPI0002_2
*"                                STRUCTURE BAPI0002_2
*"         VALUE(COMPANYCODE_ADDRESS) LIKE BAPI0002_3
*"                                STRUCTURE BAPI0002_3
*"         VALUE(RETURN) LIKE BAPIRETURN



                                                                                         27
*"                             STRUCTURE BAPIRETURN
*"------------------------------------------------------
...
* authority check: S_TABU_DIS V_T001
    perform check_authority_t001 changing return.
    check return is initial.

* company code
  call function 'FI_COMPANY_CODE_DATA'
       exporting
            i_bukrs       = companycodeid
       importing
            e_t001        = t001
       exceptions
                 error_message = 1
                 others        = 0.

  if sy-subrc ne 0.
     perform set_return using '10' changing return.
  endif.
  check return-code is initial.
...
endfunction.




      Testing the BAPI
Purpose
After you have implemented the function module your BAPI is based on and you have
defined the BAPI as an SAP Business Object method in the Business Object
Repository (BOR) you should check that the BAPI functions properly.

Prerequisites
Carry out the test together with persons responsible for quality control in your
development group.
Before you start testing make sure that the underlying function module has been
completely implemented and that the BAPI has been correctly defined in the BOR as a
Business Object method.

Process Flow
You can test the BAPI in the following ways:
•    By calling the underlying function module
     You can individually test the function module in the Function Builder. You can enter


     28
    the appropriate test values in the parameters of your function module and by
    running the test you can verify that the source code in the function module is
    processed without errors.
•   Testing the BAPI in the BOR
    You can test the BAPI by testing the individual method of the Business Object in
    the Business Object Builder. You need to know the technical name of the Business
    Object (object type) that you have already specified in Defining a BAPI and Its
    Interface.
    Call the Business Object Builder by selecting Tools → Business Framework →
    BAPI Development →Business Object Builder. Specify the appropriate object type
    and then start running the test by selecting Test. To test the BAPI implementation,
    you need to specify appropriate test values in the parameters of the BAPI.
    Note that for an instance-dependent BAPI you have to first specify an instance
    before you can run the BAPI test. Select Create instance and specify the required
    instance.
•   By calling the BAPI in a Visual Basic program
    If possible write a program in Visual Basic to call the BAPI.
    -   Check that the BAPI can be called by BAPI ActiveX Control.
    -   Check that the BAPI can be called by making RFC calls to the underlying
        function module.
•   Check the availability of documentation in the different logon languages.

Result
If you find any errors in the BAPI implementation, correct them and repeat the tests
until you and the quality control team in your group are fully satisfied with the BAPI
implementation.




1
23
        Releasing and Freezing the BAPI
After you have completed the function module and BAPI tests and you are satisfied that
they function properly, the implementation is complete.
You can now release the function module the BAPI is based on and the method in the
Business Object Repository (BOR), and freeze the BAPI as a method in the BOR.
Once the BAPI has been released and frozen, it becomes available as a fully
implemented Business Object method.
Releasing and freezing also prevents anyone making incompatible changes to the
BAPI, because all changes made to a released and frozen BAPI are automatically
checked for compatibility in the BOR and the ABAP Dictionary, and incompatible
changes are rejected. For more information about what to look out for when making
changes to existing BAPIs see Enhancements to Existing BAPIs.
Releasing and freezing the BAPI should be done in cooperation with the persons
responsible for the development objects involved and those responsible for quality
control.
To release and freeze a BAPI follow the steps below:
•   First release the function module in the Function Builder. Select
    Function module → Release → Release.


                                                                                          29
•   Set the status of the method to 'released' in the Business Object Builder. Select the
    relevant SAP Business Object in the Business Object Builder and expand the node
    Methods. Place the cursor on your BAPI and select Edit → Change status →
    Released.
•   Freeze the method. Place the cursor again on your BAPI in the Business Object
    Builder and select Utilities → API methods → Freeze method.
Check the new status of the function module in the Function Builder and the method in
the BOR.




      Programming BAPIs
Use
This section describes how to program the BAPI you defined in the previous sections.
It is not easy to formalize the functional scope of a BAPI. Every BAPI has a different
functional content, even those that perform similar functions, such as the frequently
used BAPIs. The differences are mainly due to the different characteristics and
contents of SAP Business Objects.

Prerequisites
To ensure that BAPIs, as interfaces of SAP Business Objects, provide access to R/3
data and processes in a consistent way, you must follow certain rules when
programming BAPIs. These are:

Mandatory Rules
•   A BAPI must not contain any dialogs; in other words, the BAPI must not return any
    R/3 screen dialogs to the calling application. This is true for the BAPI itself and for
    any function module that may be indirectly called by the BAPI.
•   BAPIs must not produce any screen output, for example, display a list on the
    screen.
•   Database changes can only be made through updates.
•   Set and Get parameters and the global memory must not be used to transfer
    values.
•   If required every BAPI must be able to carry out its own authorization checks.

Recommendations
•   Minimize interface complexity. Use the object/method model when choosing
    parameters and combining them in structures. In other words, select the most
    important parameters and combine them in structures in a meaningful way.
•   Application servers might not support ASCII, but use a different character set
    instead. If this is the case a problem may arise when you select quantities or
    ranges or when these are sorted. Because of this a BAPI should always select a
    range between A-Z, a-z and 0-9.

Other Features
Also pay attention to the following when you program BAPIs:
•   Programming Change BAPIs



     30
•   Programming Replicate/Clone BAPIs
•   Programming Value Ranges
•   Internal and External Data Formats
•   Reporting Errors
•   Providing Input Help (F4 Help)
•   Improving the Performance of your BAPI




        Programming Change BAPIs
Use
The BAPI Change modifies an existing instance of a SAP Business Object, for
example, one specific purchase order.
As the Change BAPI can carry out changes to existing data, a Change BAPI must be
able to identify fields that have been modified and fields that have stayed the same.
Using an initial value is no solution because an initial value could also represent a valid
new value. Moreover, in the ABAP programming language or on other development
platforms you cannot assign the value "null" to all data types in order to mark fields and
thus indicate that the remaining fields contain update values.

Features
Two different approaches can be used to identify fields containing values that have
been modified in a Change BAPI:
•   Flagging fields to identify those fields containing modified values
•   Comparing fields to identify those fields containing modified values

1. Flagging Fields to Identify Those Fields Containing Modified Values
In this approach parameter fields containing modified values are identified by a suitable
flag in an additional "change parameter".
•   An additional change parameter must be created with the same number of fields
    and the same field names for every parameter in the BAPI containing modified field
    values.
•   When the BAPI is called, the fields in the additional change parameter whose
    counterparts in the corresponding parameter contain modifications, must be
    marked with an update flag.
That way the BAPI can identify both modified and unmodified fields in the parameter.
Follow the conventions below when you create change parameters to identify modified
fields:
•   The name of the additional change parameter consists of the parameter name with
    the suffix "X". For instance, if the parameter is called EquiSales, the name of the
    additional change parameter is EquiSalesX.
•   The additional change parameter must contain exactly the same number of fields
    and the same field names as the parameter. You must use the data element
    BAPIUPDATE as the data element for the update fields. This can have the
    following values:
    -   'X'


                                                                                              31
             This value means that the corresponding parameter field contains a modified
             value.
       -     ' ' (no value)

             This means that the corresponding parameter field does not have to be
             updated.
   •   If the parameter is a table, the additional change parameter must also be a table.

            Example

             A Change BAPI is used to change the value of the existing distribution channel
             (Distr_Chan) to Distr_Chan="US". The program objects in the R/3 System
             affected by this change are:
Program Object                                     Name
SAP Business Object                                PieceOfEquipment
BAPI                                               Change
Parameter                                          EquiSales
Fields in parameter                                SalesOrg='abcd'
EquiSales
                                                   Distr_Chan='US'
                                                   Division='efgh'
                                                   ...
Change parameter that identifies modified fields EquiSalesX
Fields in EquiSalesX
                                                   SalesOrg=' '
                                                   Distr_Chan='X'
                                                   Division=' '


             In the parameter EquiSalesX the value in the field Distr_Chan is 'X'. This
             indicates that the field Distr_Chan of the parameter EquiSales contains a
             modified value.
             The BAPI Change then overwrites the existing value in the field Distr_Chan with
             the current value in the field Distr_Chan in the parameter EquiSales.


   2. Comparing Fields to Identify Those Fields Containing Modified Values
   In this approach parameter fields containing modified values are identified by
   comparing them with the fields in an additional "compare parameter":
   •   An additional compare parameter must be created with the same structure for each
       BAPI parameter containing update values.
   •   When the Change BAPI is called all relevant fields in the compare parameter must
       be filled with the data at the time the database is read. This data could be, for
       example, the result of a previous GetDetail BAPI call.
       The fields of the corresponding parameter may contain modified values.
   •   The data in the compare parameter can first be checked against the current
       database contents to ascertain whether it has changed in the meantime. This way
       any database changes made between the time the data was read and the time the
       database is updated can be identified.
   •   Then, the data in the compare parameter can be compared field by field with the


        32
       data in the corresponding parameter. If data in any field is different then the field
       contains data that must be changed.
   When you create compare parameters follow these conventions:
   •   The name of the additional compare parameter consists of the parameter name
       with the suffix "X". For instance, if the parameter is called EquiSales, the name of
       the additional compare parameter is EquiSalesX.
   •   The additional compare parameter must contain exactly the same fields and the
       same structure as the parameter.

   Advantages of Both Approaches
   The advantages of each approach are shown in the table below:
Area                         Advantage
Performance                  Approach 1: Flag table can be compressed. Compare data does
                             not have to be read.

Programming                  Approach 2: BAPI programming is simpler.


Check facilities             Approach 2: Can carry out check against current database to
                             identify and prevent inconsistencies.

Comprehension                Approach 1: Fields containing modifications can be flagged, that
                             means, less demands are placed on caller.

Application                  Approach 1: Better for performance critical applications.
                             Approach 2: Better for dialog-orientated applications with critical
                             data.




              Programming Replicate/Clone BAPIs
   Use
   To replicate a business object you can implement Replicate/Clone BAPIs. The interface
   of these BAPIs depends on the characteristics and contents of the business object that
   is to be cloned. For this reason these BAPIs must be implemented for each business
   object.
   The objective of replication is to make specific instances of a business object available
   on one or more additional systems. The cloned business objects are created under the
   same object key.
   Business objects can be cloned in two ways:
   •   By request ("Pull")
       System "A" requests clones from system "B". Then system "B" replicates the
       requested business objects on system "A".
   •   Using subscription lists ("Push")
       System "B" maintains a list of systems requiring clones. At regular intervals system
       "B" replicates the business objects on all the systems in the list.

   Features

                                                                                                   33
Both of the above cloning methods can be implemented with the following BAPIs:
•   Replicate
    A client system uses the Replicate BAPI to request clones of business objects from
    a server system. This method must be implemented for each business object to be
    cloned.
    The BAPI's import parameters have to identify the business objects to be cloned.
    You can do this by using a range table for the key fields of the business object. You
    can also add other import parameters, for example, to request all the materials
    belonging to a material group or to delimit the amount of data in the business object
    to be cloned (for example, material with or without plant data).
    Each Replicate BAPI must contain the parameter CloneReceivers which specifies
    the systems on which the business objects are to be replicated.
    Only create the Parameter RETURN as an export parameter.
    The BAPI Replicate requests the replication of a business object. The actual
    replication is carried out when the server system invokes one of the Clone BAPIs
    described below on the client system. You can specify whether the replication is
    carried out immediately or at a later time and in a separate step, depending on
    what is most practical for the business object.
Moreover, at least one of the BAPIs below must be implemented for each business
object to be cloned. You should decide to implement one of these BAPIs, depending on
the specific requirements of your BAPI:
•   Clone
    The BAPI Clone is used by a system to replicate one business object on another
    system or to modify one business object that has already been cloned.
    All the data required for cloning an individual business object must be provided in
    the import parameters. Each Clone BAPI must contain the import parameter
    Sender which identifies the system that sends or owns the business object. If only
    parts of an object are to be cloned rather than the whole object, you can use other
    optional import parameters.
    Only create the Parameter RETURN as an export parameter.
    This BAPI should be used for more complex objects that will not be cloned in large
    numbers.
•   CloneMultiple
    The BAPI CloneMultiple is used by a system to replicate several business objects
    on another system or to modify several business objects that have already been
    cloned. Unlike the BAPI Clone, the BAPI CloneMultiple can clone or modify several
    instances of an object at the same time.
    All the relevant data for cloning several business objects must be provided in the
    import parameters. Each CloneMultiple BAPI must contain the import parameter
    Sender which identifies the system that sends or owns the business objects. If only
    parts of objects are to be cloned rather than whole objects, you can use other
    optional import parameters.
    Only create the Parameter RETURN as an export parameter.
    This BAPI should be used for objects with small amounts of data. Although the
    BAPI CloneMultiple is more efficient than the BAPI Clone, it does require a far
    more complex interface and error handling process.




    34
         Programming Value Ranges
  Use
  The parameters in BAPIs that can be used to search for specific instances of a
  business object, for example, BAPI CustomerCode.GetList, have to enable BAPI users
  to specify appropriate selection criteria.

  Prerequisites
  To enable the use of selection criteria you have to create the relevant selection
  parameters of the BAPI as a structure or table with the following fields:

  Fields for Value Ranges

Field Name        Description                                     Data element
SIGN              Selection operator that determines whether      BAPISIGN
                  the range specified is to be included or
                  excluded.


OPTION            Compare operator, e.g. CP (contains pattern) BAPIOPTION
                  or NP (does not contain pattern)



LOW               Lower limit of value range                      Application specific, e.g.
                                                                  MATNR

HIGH              Upper limit of value range                      Application specific, e.g.
                                                                  MATNR


  You can use the function module BALW_RANGES_CHECK to check the values
  entered in SIGN and OPTION.




         Internal and External Data Formats
  Use
  BAPIs are programming interfaces used in the most diverse application areas, for
  instance, to connect non-SAP systems or PC products to the R/3 System.
  To meet the requirements of this diverse range of applications, a shared strategy for
  representing data in the BAPI interface must be used. In particular, the use of values
  that affect Customizing or are language dependent must be avoided.
  BAPIs are programming interfaces, not application interfaces. Fields such as a date
  field, should not be used in the BAPI interface in any other format than the format used
  in the database, i.e. YYYYMMDD, where YYYY is the year, MM the month and DD the
  day.

  Exceptions
  Because of the reasons above, BAPIs should only carry out data conversions between
  the data format used in the database and external formats used by the calling program


                                                                                               35
in exceptional circumstances.
These exceptions are listed below. To convert data formats in these exceptional
circumstances, you can use the transaction described in Converting Between Internal
and External Data Formats.
These exceptions are:
•   Currency amount fields
    In an R/3 System a currency amount field is only useful when a currency code
    accompanies it, so that the decimal point in the amounts can be set correctly.
    Accordingly, a field for the currency code must be assigned to each currency
    amount field. For example, if two Yen are stored in the field of data type CURR as
    0.02, a non-SAP system cannot reasonably be expected to understand these
    semantics.
    All R/3 currency data types have two digits after the decimal point, even though
    currencies do exist with three digits after the decimal point.
    For these reasons, the data type CURR cannot be used in the BAPI interface.
    Adhere to the following guidelines when using currency amount fields in BAPIs:
    -    You must not use parameters and fields of data type CURR in the interface
    -    All parameters and fields for currency amounts must use the domain
         BAPICURR
    -    The position of the decimal point in currency amount fields must be converted
         correctly
         You can use two function modules for this conversion. The function module
         BAPI_CURRENCY_CONV_TO_EXTERNAL converts currency amounts from
         R/3 internal data formats into external data formats. The function module
         BAPI_CURRENCY_CONV_TO_INTERNAL converts currency amounts from
         external data formats into internal data formats.
•   Quantity fields
    Like currency amount fields, the decimal point in quantity fields must be converted
    correctly. A unit of measure field must be assigned to every quantity field. Quantity
    fields have no general domain that can be used for BAPI structures.
•   Internal keys
    In some situations an internal technical key is maintained in the database alongside
    the external key. Examples are work breakdown structure plans or networks in
    project systems.
    You must always use the external key in the BAPI interface.
•   ISO codes
    In R/3 Systems ISO codes are currently supported for language, country, currency,
    and unit of measure fields.
    If you use one or more of these fields in your BAPI you have to make two fields
    available for each of these fields in the BAPI interface: one field containing the SAP
    code and another containing its corresponding ISO code. Use the naming
    convention, Fieldname_for_SAPCode_ISO for the field containing the ISO code.
    For example, the field LANGU contains the country codes used internally in R/3, for
    instance E. The corresponding field for the ISO code would then be named
    LANGU_ISO and would contain the corresponding ISO code E N.
    Implement the BAPI as follows:
    -    When you export data from the BAPI both fields must contain corresponding
         values.



    36
    -   When you import data into the BAPI the ISO code is only significant if no value
        was given in the SAP code.
    Use the domains below for the ISO codes:

    Domains for SAP internal codes and ISO codes

    Size                              ISO Code Domain                SAP Code Domain
    Currency key                      isocd                          waers
    Unit of measure                   isocd_unit                     meins
    Language key                      laiso                          spras
    Country key                       intca                          land1


    For every domain there is a data element of the same name.

BAPIs for Converting Between Internal and External Data Formats (Converting
Domains)
BAPIs are programming interfaces in which, with a few exceptions, only the internal
data format should be used. However, application programmers calling a BAPI from
within their program may sometimes require the external format, for example, to display
data on the screen. In such cases the calling program must be able to convert between
the internal and external data formats.
The following conversion BAPIs exist for this purpose. The calling program uses them
to obtain the required data formats:
•   BapiService.DataConversionInt2Ext
    This BAPI converts the internal data format into the required external data format.
•   BapiService.DataConversionExt2Int
    This BAPI converts the external data format into the required internal data format.
Conversion routines are maintained in the ABAP Dictionary for the domains on which
the data to be converted are based. If this is not the case, no conversion takes place
and the values are returned unconverted.




        Reporting Errors
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.
All error messages or indeed any message that may be returned by the BAPI must be
defined in table T100. A general error message has to be sent for those error situations
that cannot sufficiently be identified and distinguished. This message can then be
processed by the calling program in a different program branch.
The parameter RETURN can either be implemented as an export parameter and thus
as a structure, or as a table parameter. 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 an error
has occurred.


                                                                                            37
              Caution

              From Release 4.0 you must not use Exceptions in a BAPI interface.

  Features
  The structure of the parameter RETURN is dependent on the R/3 Release the BAPI is
  developed for.

  Return parameter in Release 3.1
  In Release 3.1 the Return parameter is based on the structure BAPIRETURN, whose
  components are described in the table below. In this Release the Return parameter is
  filled by the function module BALW_BAPIRETURN_GET.

  Structure of BAPIRETURN

Field                   Type               Description
TYPE                    CHAR 1             S = success message
                                           E = error message
                                           W = warning message
                                           I = information message
                                           A = termination message (Abort)
CODE                    CHAR 5             The first two characters are used for the message
                                           class and the remaining ones for the message
                                           number (key fields from table T100).


MESSAGE                 CHAR 220           Full message text from table T100. All variables
                                           have been replaced with text.

LOG_NO                  CHAR 20
                                           Number of application log. This is empty if no log
                                           used.
LOG_MSG_NO              NUMC 6             Current number of message in application log.


  Return Parameter from Release 4.0 onwards
  From Release 4.0 the return parameter must be based on one of the two reference
  structures described below.
  Both structures take into account the name space extension of the message ID made in
  Release 4.0. However, if you want messages to be compatible with earlier R/3
  Releases, use only the first two characters of the message ID.
  Both structures must be filled in the logon language.
  The two structures are:
  •     BAPIRETURN1
        This structure is filled via the function module BALW_BAPIRETURN_GET1. 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)




        38
                                                    Message ID
    ID                          CHAR 20

                                                    Message number
    NUMBER                      NUMC 3


                                                    Full message text from table T100. All
    MESSAGE                     CHAR 220
                                                    variables have been replaced with text



                                                    Number of application log. This is empty if
    LOG_NO                      CHAR 20
                                                    no log is used



                                                    Current number of message in application
    LOG_MSG_NO                  NUMC 6
                                                    log




•        BAPIRET2
         This reference structure contains the additional fields PARAMETER, ROW and
         FIELD in which error messages can be assigned to a specific field.
         If a BAPI ascertains that an invalid value has been entered in a field, it can identify
         the field containing this value in the returned error message using the additional
         fields in the structure BAPIRET2.
         Only use this structure if you need the functionality of the additional fields to
         minimize the complexity of the parameter.
         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


    NUMBER                      NUMC 3               Message number


    MESSAGE                     CHAR 220             Full message text from table T100. All
                                                     variables have been replaced with text



    LOG_NO                      CHAR 20              Number of application log. This is empty if
                                                     no log is used



    LOG_MSG_NO                  NUMC 6               Current number of message in application
                                                     log


                                                                                                   39
 PARAMETER                 CHAR 32             Identifies the parameter containing the
                                               invalid value


 ROW                       INT 4               Identifies the line number of the data record
                                               containing the invalid value




 FIELD                     CHAR 30             Identifies the field containing the invalid
                                               value


Application Log and Application 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.
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/or error tables is optional.




      Providing Input Help (F4 Help)
Use
Users of an R/3 System can use the F4 key to obtain information about the possible
input values for a certain field on the screen.
Information about the possible input values for a field should also be available to those
users who are working with the data in the R/3 System from an external program, via
BAPI calls. For example, the user of a Visual Basic program which incorporates a BAPI
to display or modify data in R/3 should have transparent access to the functionality of
the F4 input help.
In order to provide input help for a field, a calling program can use the method
HelpValues.GetList. This method is based on the RFC-capable function module
BAPI_HELPVALUES_GET, which obtains the possible input values for a field that is
passed in a BAPI call.
Detailed information about the structure and use of the HelpValues.GetList method is
available in the documentation for the function module BAPI_HELPVALUES_GET.

Features
In order to enable the HelpValues.GetList method to obtain the valid input values for a
field in your BAPI and return them to the calling program, you must create or specify
the appropriate check table, matchcodes or domain fixed values for that field in the
field's reference structure. For information about check tables, matchcodes and domain
fixed values see the ABAP Dictionary.
This is necessary because the HelpValues.GetList method refers to the help view for

     40
the check table, matchcodes or domain fixed values linked to the field in the ABAP
Dictionary.

        Note

        Whenever possible, you should therefore specify the appropriate check table,
        matchcodes or domain fixed values in the reference structure of a field in order
        to enable a calling program to access the valid input values for the field.

Authorization Check
In some situations it will be necessary to only allow those persons with a particular user
profile to access to information in F4 possible entries. To do this you can carry out
authorization checks within your BAPI:
Table BAPIF4T is provided for this purpose. This table comprises the following fields
which you have to fill with the corresponding entries of your BAPI.
•   OBJTYPE (object type)
    The technical name of the SAP Business Object, for example, BUS1065.
•   METHOD (verb)
    The name of a BAPI for the Business Object named above, for example, GetList.
•   DTEL (data element)
    The name of a data element for which a possible entry is specified. For example,
    an elementary input help could be specified for the data element PERNR_D and be
    protected from unauthorized access.
•   FNAM (name of function module)
    The name of the function module you have to create and that carries out the
    authorization check for the data element. This function module must have the
    following predefined interface:
    *"-------------------------------------------------------
    *"*"Local interface:
    *"       IMPORTING
    *"             VALUE(OBJTYPE) LIKE BAPIF4F-OBJTYPE
    *"             VALUE(METHOD) LIKE BAPIF4F-METHOD
    *"             VALUE(DTEL) LIKE BAPIF4F-DTEL
    *"             VALUE(SHLPNAME) LIKE BAPIF4F-SHLPNAME
    *"             VALUE(TABNAME) LIKE BAPIF4F-TABNAME
    *"       EXPORTING
    *"             VALUE(RETURN) LIKE BAPIF4F-RETURN
    *"---------------------------------------------------------



    As the template for your function module you can use the function module
    BF_BAPI_F4_AUTHORITY which provides exactly this interface. Copy this function
    module and follow the documentation provided with it.
    The additional parameter SHLPNAME contained in the function module interface
    provides the name of the active input help for the table or for the data element. The
    parameter TABNAME contains the name of the value table.
    The return code of the parameter RETURN is:
    -   'X' if the user of the BAPI is not authorized to call up the valid input values for a
        field.
    -   ' ' (no value) if the user of the BAPI is authorized to display the input values for
        a field.
        During runtime the function module is called dynamically by the BAPI
        HelpValues.GetList.


                                                                                                41
   An authorization check can be carried out at Business Object, method or data element
   level:
To carry out authorization check at this ......the following fields in table BAPIF4T must
level.......                             be filled.
Business Object                              OBJTYPE, FNAM
BAPI                                         OBJTYPE, METHOD, FNAM
Data element                                 OBJTYPE, METHOD, DTEL, FNAM




         Improving the Performance of your BAPI
   Use
   In order to improve the performance of your BAPI, you should adhere to the general
   guidelines of ABAP programming, such as:
   •   Use only complete WHERE conditions to minimize the amount of data to be
       transferred.
   •   Avoid unnecessary database access.
   •   Do make use of arrays.
   •   Buffer data, for example in the local memory of the function module. Note that you
       must not buffer data in the global memory.
   •   Try not to lock entire development objects; if possible, lock only parts of a
       development object.
   •   Do not generate programs at runtime.

   Additional guidelines for BAPI programming
   The function module on which a BAPI is based can be accessed by external programs
   via RFC. For this reason, you should follow these additional guidelines when
   programming BAPIs:
   •   Large amounts of data
       Mass data is treated differently in ABAP programs, which use the SAPgui
       (graphical user interface) as a front end, and in programs developed on external
       development platforms such as Visual Basic.
       If large amounts of data are read in the R/3 System, for example a list containing
       many entries, the majority of the data remains on the application server. Only the
       data that is actually displayed is sent to the front end. In contrast, on a Visual Basic
       platform, the entire data is transferred to the client system from the application
       server, resulting in a heavy network load and increased memory requirements on
       the part of the client system.
       You need to cover the situation when your BAPI has to read mass data. For
       example, you could specify a limit so that only the first n data records are read, or
       your BAPI could return a message to the calling programm indicating that the
       amount of data has exceeded a certain limit and that a new selection should be
       made.
   •   Do not define parallel processes.



       42
•   Make use of buffers when assigning numbers to reduce lock periods.
•   Minimize the duration of database locks by making updates after inserts. In
    contrast to updates, inserts do not lock the database.
•   You can reduce the duration of database locks and the risk of blocking other
    processes by making database updates as close as possible to the commit work
    command.
•   The less specific the key of a modified data record is, the more likely it is that the
    data record will be accessed by multiple BAPIs, causing the record to be locked.
    For example, running a statistic on plant level will have a negative impact on the
    performance of the BAPI, whereas a statistic based on plant and material will
    cause fewer locks because it will apply to fewer BAPIs.
•   Minimize the use of read transactions which depend on a previous database
    commit (committed read). These read transactions have to wait for the commit
    work command of the update transaction to be processed.
•   Ensure that you have chosen the correct order of the update modules.
•   All tables that are not protected by SAP internal locks must always be updated in
    the same order to prevent a deadlock.




     Enhancements to Existing BAPIs
Purpose
Application developers who are using BAPIs in their application programs must be able
to rely on the fact that the BAPI's interface is not going to change. As a result of this,
once a BAPI is released and frozen, it must fulfill certain requirements as to the stability
of its interface.
If you continue developing your BAPI after you have released and frozen it, you need to
ensure that any syntax changes or changes to the contents or functionality of the BAPI
are upward and downward compatible. Examples of syntax changes are changes to
parameter names, or changes to the type or length of a domain.
Whereas the compatibility of syntax changes is automatically checked by the ABAP
Dictionary, the compatibility of changes to the contents or functional scope of a BAPI
can only be safeguarded by the person developing the BAPI.

       Note

       Enhancements to BAPIs only take effect when you have defined the changes in
       the BOR, that is, changes have been saved and generated. The BOR also
       provides version control for your BAPIs.
You can differentiate between compatible and incompatible BAPI enhancements:

Compatible Interface Enhancements
Compatible interface enhancements are modifications to a BAPI which do not
compromise the BAPI's upward or downward compatibility. Applications which access
the BAPI are not affected by compatible interface enhancements.
Compatible interface enhancements are:
•   New optional parameters
    A parameter is considered to be optional if it can be left out completely in a BAPI


                                                                                               43
    call.

       Example

          A new parameter is added to the BAPI SalesOrder.GetList which can be used
          as an additional selection criteria for selecting sales orders in the R/3 System.
•   New optional fields, if these are added to the end of a structure
    A field is considered to be optional if it can be left out completely in a BAPI call.

       Example

          An additional input field for the applicant's educational background is added to
          the BAPI Applicant.CreateFromData.


Incompatible Interface Enhancements
Changes to the contents or functionality of a BAPI often result in the introduction of new
parameters without which the interface can no longer function. Often, these changes
also cause existing parameters to lose their original meaning. Such modifications are
considered to be incompatible, because they no longer enable the BAPI to be upward
or downward compatible.
Incompatible interface enhancements are:
•   Changes to the field length
•   Changes to the field type
•   Inserting a field within a structure
•   Deleting parameters and fields
•   Adding new mandatory fields or mandatory parameters

Process Flow
When continuing the development of your BAPI, you should attempt to make
compatible changes in order to limit the impact of your modifications on existing
programs which use the BAPI. When adding a new import parameter, consider whether
the interface would function without the parameter. If so, the new parameter can be
added as a compatible interface enhancement. Otherwise you will have to make an
incompatible interface enhancement, as described in this section.

Procedure With Incompatible Interface Changes
If it is necessary to make an incompatible change to your BAPI, you must not make this
change to the existing BAPI. Instead, create an additional BAPI (or more, if required).
Give the new BAPI the same name as the existing BAPI and add a number at the end
of the name. This number can then be incremented should further enhancements
become necessary.

       Example

          A number of incompatible changes must be made to the BAPI
          SalesOrder.CreateFromData. To implement these changes, a new BAPI,
          SalesOrder.CreateFromData1, is created, in order to maintain the interface
          integrity of the existing BAPI SalesOrder.CreateFromData.
          If additional incompatible modifications must be made to the BAPI at a later
          date, yet another BAPI, SalesOrder.CreateFromData2, must be created.
Do not remove the original BAPI from the Business Object Repository (BOR) once it
has been superseded by an additional BAPI. Instead, you first identify this BAPI as


     44
expired and continue its support in the release in which you have introduced the new
BAPI as well as in the release subsequent to that. During this time the original BAPI
must remain fully functional and executable.
The graphic below illustrates the expiry phase of a BAPI.

BAPI Expiry Phase




The following tasks are required when a BAPI has expired:
•   Identify the status of the original BAPI as 'expired' in the BOR.
    To do so, select the relevant SAP Business Object in the Business Object Builder
    and open the node Methods. Position the cursor on the BAPI and select Edit →
    Change status to → Expired.
•   In the BOR, document which method or methods are to be used as alternatives to
    the expiring BAPI.
•   Provide release notes during the entire retirement phase of the BAPI to inform your
    users about the changes.

Checks in the ABAP Dictionary
Syntax changes to a BAPI are automatically checked against the ABAP Dictionary:
•   Incompatible changes to data elements, domains or structures that are being used
    by a BAPI that has been released are rejected by the ABAP Dictionary.
•   Compatible changes or changes to data elements, domains or structures of a BAPI
    that has not been released are accepted by the ABAP Dictionary.
This prevents unintentional and erroneous modifications to BAPI structures.




                                                                                          45
      Customer Modifications of BAPIs
Purpose
You can make enhancements or modifications to existing BAPIs. Before you decide to
modify an SAP BAPI familiarize yourself with the general procedure for making
customer enhancements to the SAP standard system. Refer to Enhancements to the
SAP Standard. For further information see also "Guidelines for Modifying the SAP
Standard System" in SAPnet.
This section focuses specifically on customer enhancements and modifications of
BAPIs rather than on customer enhancements in general.

Process Flow
There are four ways the standard R/3 System can be adapted to meet customer needs:
Customizing, enhancements, modifications and customers' own developments. The
following sections describe how BAPIs can be adapted within the framework of each of
these four ways.

Customizing
There are no special Customizing settings for BAPIs.

Enhancements
At present there are no customer exits or application-specific exits for BAPIs.
Changes can be made, however, in the ABAP Dictionary. New fields can be added at
the end of a BAPI interface structure. See also Enhancements to Existing BAPIs.

Modifications
You can modify an existing BAPI interface provided that only new optional parameters
are involved. See also Enhancements to Existing BAPIs.
You can also modify the BAPI source code but do follow the "Guidelines for Modifying
the SAP Standard System". Keep in mind that an improved mechanism for making
customer modifications of the SAP Standard System will be introduced in a later R/3
Release. For this reason SAP recommends that, for the time being you use one of the
procedures described below to make modifications to a BAPI's source code so as not
to change the SAP Standard System in the process:
Creating a BAPI for an existing Business Object
You can copy an existing BAPI and add it to an existing Business Object as a new
BAPI. To do this:
•   Copy the function module the BAPI is based on into the customer name space. For
    example, you could copy the function module BAPI_CUSTOMERCODE_GETLIST
    into Y_BAPI_CUSTOMERCODE_GETLIST.
•   Make the required changes to the new function module by changing the interface
    and the source code as required.
•   When you have changed and tested the function module and its interface you can
    define it as a new method of the appropriate business object, as described in
    Defining Methods in the BOR Using the BOR/BAPI Wizard
    Make sure you give the method a name taken from the customer name space. For
    example, if you have modified the BAPI GetList of the Business Object
    CustomerCode, you should define your development as the method YGetList.
Creating a BAPI for a new Business Object
You can create a subtype for an existing object type. This way all methods of the object

     46
are inherited by the subtype. You can then make changes to the copied method. To do
this:
•   Copy an existing Business Object type into the customer name space. This object
    type (subtype) acquires all methods of the existing object type. For example, you
    could copy the Business Object SalesOrder into YSalesOrder.
•   You can now change the required BAPI of the Business Object YSalesOrder by
    creating a new function module for the BAPI and assigning it to the method using
    the BOR/BAPI-Wizard.

Your Own Developments
Using the information in these guidelines you can also create new methods for
Business Objects. If you do, make sure that you have given your method in the BOR
and the function module a name from the customer name space, this means the names
must begin with X or Y.
Follow the "Guidelines for Modifying the SAP Standard System" when creating other
required development objects.




     Implementing BAPIs in ALE Scenarios
Purpose
Since Release 3.0 ALE (Application Link Enabling) technology has enabled data to be
exchanged between individual distributed SAP Systems and non-SAP systems.
In distributed environments it is particularly important that the individual systems are
loosely coupled together and are independent of each other. Even if one of the systems
fails, or a communications link is interrupted, the remaining systems must be able to
continue to function. Loose coupling means that the individual systems for the most
part communicate asynchronously with each other. For these reasons asynchronous
messaging is used for data communication between the participating systems in ALE
distribution scenarios.
From Release 4.0 you can implement an asynchronous BAPI interface by generating
an IDoc from the BAPI and using it in an appropriate ALE distribution scenario.
For further information on ALE technology and using BAPIs in the context of ALE see
ALE Programming.
This section provides a general overview of points you should keep in mind when
implementing a BAPI to exchange data asynchronously.

Process Flow
When a BAPI is used to exchange data asynchronously within the context of ALE the
following processes are involved:
•   When the BAPI is called in the sending system, a function module fills the
    corresponding IDoc with the data from the BAPI call.
•   This IDoc is dispatched to the target system.
•   In the target system another function module is used to call the BAPI with the data
    from the IDoc.
You can use a transaction to create the additional objects required for the BAPI in this
process, that is, the associated IDoc and the two function modules. This transaction is
described in detail in ALE Programming.


                                                                                           47
  Prerequisites
  Before you can implement a BAPI used to transfer data asynchronously in ALE, make
  sure that a BAPI of this type is actually required for the task in hand. If one of the
  following conditions applies then you should implement your BAPI as an asynchronous
  interface:
  •   Consistent database changes in both systems
      Data must be updated consistently on both the local system and on the remote
      system.
  •   Loose coupling
      A synchronous interface would constitute too narrow a coupling between the client
      and the server system. If the connection is interrupted the client system would not
      be able to function properly.
  •   Performance
      The interface is frequently used or it deals with large volumes of data. In this
      situation a synchronous interface cannot be used because performance would be
      too low.

  Additional Guidelines
  If you are sure you want to implement your BAPI as an asynchronous interface you
  should keep in mind the following points in addition to the usual BAPI programming
  guidelines:
  •   The BAPI must not issue a Commit Work command.
  •   The BAPI Return parameter must use the reference structure BAPIRETURN1 or
      BAPIRET2.
  •   All BAPI export parameters with the exception of the Return parameter are ignored
      and are not included in the IDoc that is generated.
  •   After the function module which converts the IDoc into the corresponding BAPI in
      the receiving system has been called, status records are written for the IDoc in
      which messages sent in the Return parameter are logged.
      If the field type is filled with E (error) or A (abort) in at least one of the transferred
      Return parameter entries, the status 51 (application document has not been
      posted) is assigned to all the status records of the IDoc. Otherwise status 53 is
      assigned (application document posted).




1
23
       BAPI Implementation Checklist
  This checklist summarizes the individual steps you need to complete when
  implementing a BAPI.
  Print this checklist and use the printout during the entire implementation phase of your
  BAPI. Ensure that you are can answer "yes" to each item on the list.

  BAPI Implementation Checklist

OK?               Task
                  Defining the scenario in which the BAPI will be used




       48
Have you defined the scenario in which the BAPI is to be used?


Have you identified the SAP Business Object involved?


Have you defined the functional scope of the BAPI?


Have you defined the relationship between the BAPI you are planning
to implement and other, related BAPIs?


Is the functionality to be implemented by the BAPI exclusively within
the scope of the associated Business Object?


Is the BAPI assigned to the appropriate SAP Business Object?


Has there been a review of the BAPI concept and scenario?


Defining the BAPI


Have you identified the SAP Business Object in the Business Object
Repository to which the BAPI will be added as a method?


Have you identified the key fields of this Business Object?


Have you defined the interface of the BAPI?


Have you included the key fields of the SAP Business Object in the
BAPI interface?


Have you included a Return parameter?


Have you identified the name of the function group or have you
planned a name for a new function group to be created?


Have you planned the name of the function module on which the BAPI
is based, using the format
BAPI_<Business Object name>_<method name>?


Defining the interface parameters in the function module


Have you defined the function module interface using only
EXPORTING, IMPORTING and TABLES parameters?




                                                                        49
     Have you included the key fields of the SAP Business Object as
     parameters of the function module (i.e. depending on whether the
     BAPI is instance-dependent or instance-independent)?


     Have you assigned correct names to the parameters in the function
     module?


     Do the function module parameters for the Business Object's key fields
     have the same name as the key fields of the Business Object in the
     BOR?


     Is the name of each parameter in the function module a maximum of
     20 characters in length?


     Are the names of the parameters in the function module in English?


     Have you avoided the use of abbreviations in the names of function
     module parameters?


     Did you ensure that none of the parameters in the function module is
     customizing-relevant or affects system settings in any other way?


     Is the interface independent of the current customizing settings of the
     system?


     Are all IMPORTING parameters independent from each other, i.e. did
     you ensure that none of the parameters is derived from another?


     Have you defined the formats in which the values must be transferred
     in the function module interface?


     Are you using the Dictionary structure BAPIRETURN1 or BAPIRET2
     for the Return parameter (as of Release 4.0)?


     Defining the structures and fields of the function module
     parameters


     Have you assigned a corresponding currency code field to each field
     with currency amounts?


     Have you assigned a field for the unit of measure to each quantity
     field?


     Have you defined Dictionary structures for each function module
     parameter?


50
Do the names of the Dictionary structures start with BAPI?


Are these structures independent of the structures used in the R/3
application?


Have you defined the fields in the Dictionary structures?


Have you defined Help views or fixed values for the fields in order to
enable your BAPI to provide input help (F4 help) for each field?


Are the field names a maximum of 10 characters in length?


Have you used English names for the fields, preferably those names
that have been assigned to the corresponding data elements in the
ABAP Dictionary?


Can the user of your BAPI access the values for each import field
either by referring to the documentation, by obtaining input help (F4
help), or by using a GetDetail BAPI?
Have you used a structure with the fields SIGN, OPTION, LOW and
HIGH for the corresponding BAPI parameter that selects values (for
example, Material.GetList)?


Defining the BAPI in the Business Object Repository


Have you planned the name of the method in the BOR?


Have you defined the names of the parameters in the BOR?


Are the names of the parameters a maximum of 20 characters in
length?


Did you choose English names for the parameters?


Are the names of the parameters of the method in the BOR and the
names of the parameters in the function module the same?


Did you ensure that there are no underscores in the parameter
names?


Did you start each new word in a method name with a capital letter?




                                                                         51
     Creating the objects in the R/3 System


     Did you create the required Dictionary objects?


     Did you create the function group, if required?


     Did you create the function module?


     Did you create the documentation for the BAPI in the Function Builder?


     Did you use the program to map between internal and external data
     formats?


     Did you write the program for your function module?


     Did you use the BOR/BAPI wizard to define the BAPI as a method in
     the BOR?


     Are the parameter names and types of the method in the BOR and of
     the function module in the Function Builder the same?


     Documentation


     Did you write appropriate documentation for the BAPI in the Function
     Builder?


     Is the documentation complete?


     Has the documentation been translated into the required languages?


     Testing the BAPI


     Did you test the function module using the test environment of the
     Function Builder?


     Did you test the BAPI using the test environment of the Business
     Object Builder?


     Did you test the BAPI by calling the method via the BAPI ActiveX
     Control?


     Did you test the BAPI by making an RFC call to the underlying function


52
module?


Did you test the documentation for its completeness, correctness and
availability in the required logon languages?


Has the BAPI been released and frozen?




                                                                       53
                                                                                         Index
               A
ALE .............................................................................................................................................................................47
Application Link Enabling ......................................................................................................................................47
Application logs.......................................................................................................................................................37

               B
BAPI
  Application Link Enabling ..................................................................................................................................47
  asynchronous data transfer ...............................................................................................................................47
  defining and implementing ................................................................................................................................10
  definition.................................................................................................................................................................5
  HelpValues.GetList .............................................................................................................................................40
  use ...........................................................................................................................................................................5
BAPI scenarios
  defining .................................................................................................................................................................12
  Review ..................................................................................................................................................................14
BAPIs
  creating in BOR ...................................................................................................................................................26
  defining .................................................................................................................................................................10
  freezing .................................................................................................................................................................29
  frequently used ....................................................................................................................................................11
  implementing .......................................................................................................................................................10
  instance-dependent ............................................................................................................................................15
  instance-independent .........................................................................................................................................15
  naming in BOR .....................................................................................................................................................20
  releasing ...............................................................................................................................................................29
  testing ...................................................................................................................................................................28
  testing in BOR ......................................................................................................................................................28
BOR
  creating BAPIs ....................................................................................................................................................26
  Definition ................................................................................................................................................................6
  searching ..............................................................................................................................................................15
  use ...........................................................................................................................................................................6
BOR/BAPI Wizard ...................................................................................................................................................26
Business Object Repository
  BAPIs
     creating ............................................................................................................................................................26
  definition.................................................................................................................................................................6
  use ...........................................................................................................................................................................6
Business objects ......................................................................................................................................................16

               C
CAALC .........................................................................................................................................................................3
Change BAPIs ..........................................................................................................................................................11
  programming ........................................................................................................................................................31
Class methods ..........................................................................................................................................................16
Clone BAPIs
  programming ........................................................................................................................................................33
CloneMultiple BAPIs
  programming ........................................................................................................................................................33
Compatible changes ......................................................................................................................................... 44, 45
Converting
  currency codes.....................................................................................................................................................22
  English and German field names......................................................................................................................22
  external and internal structures.......................................................................................................................22
  field names...........................................................................................................................................................22
  ISO codes..............................................................................................................................................................22
  technical keys ......................................................................................................................................................22


               54
Create BAPIs ............................................................................................................................................................11
CreateFromData BAPIs ..........................................................................................................................................11
Creating
  BAPIs ....................................................................................................................................................................26
  development objects ..........................................................................................................................................18
Currency codes ........................................................................................................................................................22
Currency fields .........................................................................................................................................................35
Customer modifications ..........................................................................................................................................46
Customizing ..............................................................................................................................................................46

               D
Data formats
  internal and external ..........................................................................................................................................35
Data structures.........................................................................................................................................................18
Defining
  BAPI scenarios ....................................................................................................................................................12
  interfaces .............................................................................................................................................................14
Defining BAPIs ........................................................................................................................................................10
Definition
  BAPI ........................................................................................................................................................................5
Delete BAPIs............................................................................................................................................................11
Development objects
  creating .................................................................................................................................................................18
Documentation .................................................................................................................................................. 21, 22
  testing ...................................................................................................................................................................28
  writing ...................................................................................................................................................................21

               E
English and German field names
  converting .............................................................................................................................................................22
enhancements ......................................................................................................................................43, 44, 45, 46
Enhancing
  interfaces .............................................................................................................................................................43
Example...................................................................................................................................................9, 10, 24, 27
Examples.....................................................................................................................................................................4
ExistenceCheck BAPIs ...........................................................................................................................................11
Export parameters
  function modules .................................................................................................................................................16
External structures..................................................................................................................................................22

               F
Field names
   converting .............................................................................................................................................................22
Freezing
   BAPIs ....................................................................................................................................................................29
Function ............................................................................................22, 23, 30, 31, 33, 35, 36, 38, 39, 40, 41, 42
Function groups
   specifying names.................................................................................................................................................14
Function modules
   releasing ...............................................................................................................................................................29
   specifing names...................................................................................................................................................14
   testing ...................................................................................................................................................................28

               G
Generic BAPIs .........................................................................................................................................................11
GetDetail BAPIs ......................................................................................................................................................11
GetList BAPIs ...........................................................................................................................................................11
GetStatus BAPIs......................................................................................................................................................11

               I
Implementing BAPIs................................................................................................................................................10
Import parameters
  function modules .................................................................................................................................................16
Improving


                                                                                                                                                                           55
   performance .........................................................................................................................................................42
Incompatible changes ...................................................................................................................................... 44, 45
Input help ........................................................................................................................................................... 40, 41
Instance-dependent
   BAPIs ....................................................................................................................................................................15
Instance-independent
   BAPIs ....................................................................................................................................................................15
Interfaces
   defining .................................................................................................................................................................14
   enhancing .............................................................................................................................................................43
   function modules .................................................................................................................................................16
Internal and external structures
   converting .............................................................................................................................................................22
Internal keys.............................................................................................................................................................36
Internal structures ...................................................................................................................................................22
ISO codes ........................................................................................................................................................... 23, 36

               K
Key fields
  Business objects.................................................................................................................................................15
  Use in function modules ....................................................................................................................................16

               L
Logical unit of work ..................................................................................................................................................7
LUW .............................................................................................................................................................................7

               M
Modifications
  BAPIs .....................................................................................................................................................................46

               N
Naming in BOR
  BAPIs ....................................................................................................................................................................20
Naming in function modules
  parameter names ................................................................................................................................................17

               O
Object ................................................................................................................................................................. 11, 12
Objects............................................................................................................................................................... 5, 6, 7
Own developments..................................................................................................................................................47

               P
Parameter names
  BOR .......................................................................................................................................................................20
  naming in function modules ..............................................................................................................................17
Parameters
  determining in function modules......................................................................................................................16
  return ....................................................................................................................................................................37
Performance
  improving ..............................................................................................................................................................42
Possible values ........................................................................................................................................................40
Procedure....................................................................................................................................... 15, 23, 26, 29, 48
Process ...................................................................3, 7, 8, 9, 11, 12, 13, 14, 16, 17, 18, 20, 21, 28, 44, 46, 47
Programming
  Change BAPIs......................................................................................................................................................31
  Clone BAPIs..........................................................................................................................................................34
  CloneMultiple BAPIs ..........................................................................................................................................33
  guidelines .............................................................................................................................................................30
  RequestClone BAPIs ..........................................................................................................................................33
  value ranges .........................................................................................................................................................34
Programming objects
  creating .................................................................................................................................................................21




               56
               Q
quantity fields ..........................................................................................................................................................36

               R
Releasing
  BAPIs ....................................................................................................................................................................29
  function modules .................................................................................................................................................29
Reporting errors ......................................................................................................................................................37
RequestClone BAPIs
  Programming .......................................................................................................................................................33
Return parameters ..................................................................................................................................................37

               S
Searching
  BOR .......................................................................................................................................................................15

               T
Table parameters
  in function modules ............................................................................................................................................16
Technical keys
  converting .............................................................................................................................................................22
Testing
  BAPIs ....................................................................................................................................................................28
  BAPIs in BOR .......................................................................................................................................................28
  documentation .....................................................................................................................................................28
  Function modules ................................................................................................................................................28
Transaction model .................................................................................................................................................7, 8
  Release 3.1 ............................................................................................................................................................8
  Release 4.0 ............................................................................................................................................................9

               U
Use
  Business Object Repository ................................................................................................................................6

               V
Value ranges
  programming ........................................................................................................................................................34




                                                                                                                                                                          57

				
DOCUMENT INFO
Shared By:
Tags:
Stats:
views:15
posted:2/25/2010
language:English
pages:57