BAPI Programming

Release 4.6B

HELP.CABFABAPIREF

BAPI Programming

SAP AG

Copyright
©

Copyright 2000 SAP AG. All rights reserved.

No part of this brochure may be reproduced or transmitted in any form or for any purpose without the express permission of SAP AG. The information contained herein may be changed without prior notice. Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors. Microsoft , WINDOWS , NT , EXCEL , Word and SQL Server are registered trademarks of Microsoft Corporation. IBM , DB2 , OS/2 , DB2/6000 , Parallel Sysplex , MVS/ESA , RS/6000 , AIX , S/390 , ® ® ® AS/400 , OS/390 , and OS/400 are registered trademarks of IBM Corporation. ORACLE is a registered trademark of ORACLE Corporation, California, USA. INFORMIX -OnLine for SAP and Informix Dynamic Server Informix Software Incorporated.
® ® ® ® ® ® TM ® ® ® ® ® ® ® ® ® ® ® ® ® ® ® ®

are registered trademarks of

UNIX , X/Open , OSF/1 , and Motif are registered trademarks of The Open Group. HTML, DHTML, XML, XHTML are trademarks or registered trademarks of W3C , World Wide Web Consortium, Laboratory for Computer Science NE43-358, Massachusetts Institute of Technology, 545 Technology Square, Cambridge, MA 02139. JAVA is a registered trademark of Sun Microsystems, Inc. , 901 San Antonio Road, Palo Alto, CA 94303 USA. JAVASCRIPT is a registered trademark of Sun Microsystems, Inc., used under license for technology invented and implemented by Netscape. SAP, SAP Logo, mySAP.com, mySAP.com Marketplace, mySAP.com Workplace, mySAP.com Business Scenarios, mySAP.com Application Hosting, WebFlow, R/2, R/3, RIVA, ABAP, SAP Business Workflow, SAP EarlyWatch, SAP ArchiveLink, BAPI, SAPPHIRE, Management Cockpit, SEM, are trademarks or registered trademarks of SAP AG in Germany and in several other countries all over the world. All other products mentioned are trademarks or registered trademarks of their respective companies.
® ® ®

2

December 1999

SAP AG

BAPI Programming

Icons
Icon Meaning Caution Example Note Recommendation Syntax Tip

December 1999

3

..... 15 BAPI Explorer.................................................................................................................. 52 Releasing the BAPI............................... 7 BAPIs ................................................ 58 BAPI Transaction Model with Commit.............................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................. 73 Providing Interface Descriptions ............................................................................................................ 88 Programming Standardized BAPIs ............................................................................................. 11 Terminology ............................................................................................................... 20 Defining the Scenario.................................................................................................................................................................................................................................................. 21 Reviewing the Scenario Concept .. 41 Naming the Function Module and the Function Module Group........................... 90 Programming GetList() BAPIs ........................... 92 Programming GetDetail() BAPIs ........................................................................................................................................................ 29 Determining the Object Type and Its Key Fields ........... 48 Testing the BAPI and Its Documentation ............... 54 Transaction Model for Developing BAPIs ........................................................................ 93 4 December 1999 .................................................. 34 Defining Data Formats............................................................................................. 43 BAPIs Used for Outbound Processing ........... 37 Naming the Method in the BOR ..................................................BAPI Programming SAP AG Contents BAPI Programming ....................................................................................... 23 Defining a BAPI and Its Interface ...................................................................................................................... 24 Standardized BAPIs .................. 63 Customer Enhancement Concept for BAPIs ...................................................................................................... 17 Working with Display Functions ................................................................................................................................................................................................................................................. 46 BAPI Interface and Function Module.......................................................................................................................................... 45 Creating Development Objects and Documentation ......................... 69 Providing Input Help (F4 Help) ............................................................................................................................................ 77 Example of Implementation and Process Flow .............. 36 Specifying Development Objects in ABAP Dictionary.................................................................................................................... 9 BOR .................................................................................. 75 Buffering with Write BAPIs ................................................................................ 65 Internal and External Data Formats ........................................................................ 13 Further Documentation on BAPIs............................................................................... 31 Defining the Interface Structure of the BAPI ................................... 40 Naming Parameters in the BOR........................................................................................................... 83 Improving Performance .............................................................................................................. 26 Standardized Parameters........................................................................................................... 86 Documentation Guidelines .................................................................................................................................................................................................................... 60 BAPI Transaction Model Without Commit ................................................... 91 Example of a GetList() BAPI...................................... 18 Working with Tools and Projects .................... 53 General Programming Guidelines for BAPIs ................................................................................................ 32 Naming Parameters in the Function Module ..................................................................... 14 Defining and Implementing the BAPI ..........6 BAPI Programming Guide........................................................................................................................................................................................................................................................

...................................................................... 144 Compatible Enhancements..................................................... 159 Creating Subtypes ....................................................... 148 Customer Modifications and Developments........................................ 108 Programming Delete() BAPIs............................................................................................................................................................................................................................ 102 Example of a Create() BAPI ................................................................................................................................................ 158 BAPI Development........................... 122 Address Parameters................................ 157 Defining Delegation Relationships ......................... 134 TestRun Parameters............................................................................................................................................................................. 110 Example of a Delete() BAPI......................................................................................................................................................... 140 Application Example ... 114 Programming Replicate()/SaveReplica() BAPIs................................................... 113 Example of a Cancel() BAPI................................................................................................................................. 152 Creating Subtypes ................ 146 Incompatible Enhancements ....................................... 161 Using BAPIs in Distributed Systems (ALE) ................................................. 135 Text Transfer Parameters ................................................................................ 151 BAPI Modifications .....................................................................................................................................................................................................................................................................................................................................................................................................................................SAP AG BAPI Programming Example of a GetDetail() BAPI....................................................... 130 Selection Parameters . 137 Defining Methods in the BOR Using BOR/BAPI Wizard ........................................................................................... 138 Converting Internal and External Data Formats .................................................................... 125 Extension Parameters ......................................................................... 156 Redefining BAPIs ........................................................................................................................................... 118 Programming Methods for Sub-Objects ......................................................... 115 Example of a SaveReplica() BAPI.......................... 106 Example of a Change () BAPI .............. 104 Programming Change() BAPIs ........................................................................................................................... 129 Return Parameters (Error Handling)................................ 96 Example of a GetStatus() BAPI....................................................................................................................................................................................................... 94 Programming GetStatus() BAPIs ................................................... 100 Programming Create() BAPIs ........................................................................................................................ 164 BAPI Quality Checklist .................. 112 Programming Cancel() BAPIs.......................................................................................................................... 97 Programming ExistenceCheck() BAPIs..................................................................................................................................................................................................... 166 December 1999 5 ................................................................................................................................... 142 SAP Enhancements to Released BAPIs............................................................. 98 Example of an ExistenceCheck() BAPI ....................................... 123 Change Parameters ........................................................................................................................................................................ 160 Namespaces.................................................................................................................................... 136 Tools for Developing BAPIs ........................................................................................................... 120 Programming Standardized Parameters .....................................................................................................................................................................................................

BAPI Programming BAPI Programming SAP AG BAPI Programming 6 December 1999 .

SAP AG

BAPI Programming BAPI Programming Guide

BAPI Programming Guide
Purpose
This document describes the SAP guidelines for developing and implementing Business Application Programming Interfaces [Page 9] (BAPIs). It is targeted at SAP developers and SAP partners who want to implement BAPIs. Customers are also recommended to follow these guidelines when developing BAPIs. All developments should be done in the customer name space; all changes to existing developments objects of the SAP standard are considered to be modifications. (See Namespaces [Page 161]). As these guidelines are targeted for internal use at SAP, procedures or tools may be mentioned that do not apply or are not available to customers. Information that applies internally to SAP is indicated. This document describes the guidelines valid at the time this document was published.

Prerequisites
To program and implement a BAPI with these guidelines you need to have: • • • Basic knowledge of BAPIs, as described in the BAPI User Guide [Ext.] Knowledge of the ABAP programming language and ABAP Workbench 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: Defining and Implementing the BAPI [Page 15] Creating Development Objects and Documentation [Page 46] General Programming Guidelines for BAPIs [Page 54] Testing the BAPI and Its Documentation [Page 52] Releasing the BAPI [Page 53] Programming Standardized BAPIs [Page 90] Programming Standardized Parameters [Page 122] SAP Enhancements to Existing BAPIs [Page 144].

In Release 4.6A in the BAPI Explorer [Page 17] project forms are provided that take you step by step through the implementation procedure for BAPIs and enable you to

December 1999

7

BAPI Programming BAPI Programming Guide

SAP AG

document the development of your BAPIs. For SAP internal development it is obligatory to use a project form. The BAPI Quality Checklist [Page 166] from earlier releases is still provided at the end of this document. Other topics related to developing BAPIs are: Modifications and Customers’ Own Developments [Page 151] Using BAPIs in Distributed Systems (ALE) [Page 164]

8

December 1999

SAP AG

BAPI Programming BAPIs

BAPIs
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.

BAPIs of SAP Business Object Types
BAPIs are defined as API methods of SAP business object types. These business object types and their BAPIs are described and stored in the Business Object Repository [Page 11] (BOR). A BAPI is implemented as a function module, that is stored and described in the Function Builder.

BAPIs of SAP Interface Types
As of Release 4.5A BAPIs can also describe interfaces, implemented outside the R/3 System that can be called in external systems by R/3 Systems. These BAPIs are known as BAPIs used for outbound processing. The target system is determined for the BAPI call in the distribution model of Application Link Enabling (ALE). BAPIs used for outbound processing are defined in the Business Object Repository (BOR) as API methods of SAP Interface Types. Functions implemented outside the R/3 System can be standardized and made available as BAPIs. For further information see BAPIs Used For Outbound Processing [Page 45].

Integration
BAPIs can be called within the R/3 System from external application systems and other programs. BAPIs are the communication standard for business applications. BAPI interface technology forms the basis for the following developments: • • • • Connecting:

New R/3 components, for example, Advanced Planner and Optimizer (APO) and Business Information Warehouse (BW). Non-SAP software Legacy systems • • • • • • Isolating components within the R/3 System in the context of Business Framework Distributed R/3 scenarios with asynchronous connections using Application Link Enabling (ALE) Connecting R/3 Systems to the Internet using Internet Application Components (IACs) PC programs as frontends to the R/3 System, for example, Visual Basic (Microsoft) or Visual Age for Java (IBM). Workflow applications that extend beyond system boundaries Customers' and partners' own developments

The graphic below shows how BAPI interfaces enable different types of applications to be linked together.

December 1999

9

. 10 December 1999 . BusinessObject BAPI Business Object Business Component BAPI Business B Component Isolating components in the Business Framework (R/3.BAPI Programming BAPIs SAP AG BAPIs . R/2) Business BAPI Object BAPI BAPI Business Component Customers and partners‘ own developments For further background information on BAPIs refer to the document BAPI User Guide [Ext.Interfaces to the R/3 System R/3 satellite systems / distributed systems (ALE) Business Workflow BAPI BAPI BAPI Business Object Business Object BAPI BAPI Internet / Intranet BAPI Business Object VisualBasic/JAVA.]..

It takes you through the process step by step. Access to the BOR is restricted at SAP. It contains the SAP business object types and SAP interface types as well as their components. BAPI interface enhancements made by adding parameters are recorded in the BOR. Implementation information is encapsulated. BOR/BAPI Wizard The BOR/BAPI Wizard [Page 138] helps you to create new BAPIs in the BOR. BAPIs are defined as methods of SAP business object types (or SAP interface types) in the BOR. R/3 application functions are accessed using methods (BAPIs) of SAP Business Objects. are automatically checked for syntax compatibility against the associated development objects in the ABAP Dictionary. • Arranges the various interfaces in accordance with the component hierarchy. When a BAPI is created the release version of the new BAPI is recorded in the BOR.]. Any interface changes that are carried out in the BOR. For general information on creating business objects see the documentation on SAP Business Workflow [Ext. This finds the functionality searched for quickly and simply. the BAPIs become standard with full stability guarantees as regards their content and interface. Thus defined. December 1999 11 . Integration A BAPI is implemented as a function module. if the function module that the BAPI is based on has been fully implemented. that is stored and described in the Function Builder. You should only define a BAPI as a method of an SAP business object type in the BOR. attributes and events. only the interface functionality of the method is visible to the user. The version control of the function module that a BAPI is based on is managed in the Function Builder. Use The BOR has the following functions for SAP business object types and their BAPIs: • Provides an object oriented view of R/3 System data and processes. • Ensures interface stability. Previous interface versions can thus be reconstructed at any time. • Manages BAPIs in release updates. The same applies when any interface parameter is created.SAP AG BAPI Programming BOR BOR Definition The Business Object Repository (BOR) is the object-oriented repository in the R/3 System. such as methods. enabling functions to be searched and retrieved quickly and simply.

BAPI Programming BOR SAP AG 12 December 1999 .

SAP AG BAPI Programming Terminology Terminology Definition The table below contains definitions of the terms used in this document: Term/Synonym Object type Business object type SAP business object type Business object Business object instance SAP business object instance BOR Business Object Repository BAPI Business Application Programming Interface Central repository within the R/3 System containing all the business object types and SAP interface types together with their definitions and methods. Interface type SAP interface type Definitions of attributes. methods and events grouped together in one context. An object type can support one or more interface types. December 1999 13 . Describes the general characteristics and common attributes of instances of SAP business object types. One instance of an SAP business object type Definition Generic definition of business objects. Standardized programming interface enabling external applications to access business processes and data in the R/3 System. BAPIs are defined in the BOR as methods of SAP business object types that carry out specific business functions. methods and events defined for the interface type together with their interfaces are used by the object type and are inherited by the respective subtypes of the object. BAPIs are implemented as RFC-enabled function modules and are created in the Function Builder of the ABAP Workbench. The functional group of associated attributes.

Describes how external client applications can use SAP’s BAPI ActiveX Control to access SAP business objects. Describes how BAPIs are developed in SAP and what guidelines you have to follow. SAP business objects and their BAPIs can be called directly from COMbased development tools.BAPI Programming Further Documentation on BAPIs SAP AG Further Documentation on BAPIs In the Open BAPI Network under the URL www.com/bapi application developers can view the latest information on BAPI developments undertaken by SAP and by partners.] in the Tutorial: Communication Interfaces [Ext. Describes how the R/3 DCOM Component Connector developed jointly by SAP and Microsoft is used to integrate R/3 objects and COM objects seamlessly.] R/3 DCOM Component Connector [Ext. The R/3 DCOM Component Connector SDK is shipped as part of RFC SDK for Windows NT.] BAPI Programming Guide [Page 7] Information about using BAPIs in application programs. This document can also be used by customers and partners. including guidelines on using and programming BAPIs implemented in ALE distributed environments. Describes how business objects are called from the R/3 System using SAP’s BAPI ActiveX Controls and how the data is displayed using Table View Controls Describes how C++ and Java class libraries are used to access BAPIs on C++ and Java platforms. The following R/3 documentation contains further information about developing BAPIs and developing with BAPIs: Document BAPI User Guide [Ext. Overview of ALE business processes (application scenarios of Application Link Enabling). who want to develop their own BAPIs. Library of ALE Business Processes [Ext.] Calling BAPIs with BAPI Control [Ext.sap. ALE business processes delivered in the standard system are preconfigured and include important application examples of the distribution of business functions and processes.] 14 December 1999 . or enhance SAP BAPIs. COM components are also provided in the SAP development environment. ALE Programming Guide [Ext.] SAP Automation RFC and BAPI Interfaces [Ext.] Information about ALE technology (Application Link Enabling).] BAPI ActiveX Control [Ext.

The definitions and descriptions of the data structures used by the BAPI are stored in the ABAP Dictionary. When implementing BAPIs follow the requirements below to ensure you achieve consistent behavior and representation of BAPIs as object-oriented methods of SAP business object types or SAP interface types. These are shown in the graphic below. BAPIs are implemented in the Function Builder as RFC-enabled function modules.SAP AG BAPI Programming Defining and Implementing the BAPI Defining and Implementing the BAPI Purpose Various components of the ABAP Workbench are used when you define and implement a BAPI. BAPIs are defined in the Business Object Repository (BOR) as API methods of SAP business object types. Function Builder and ABAP Dictionary ABAP Workbench Business Object Repository Business Object BO: Method 1 = M1 Method 2 = M2 Function module BAPI_BO_M2 Function Builder ABAP Dictionary Function module BAPI_BO_M1 Definition and description of data structures Prerequisites For function modules that implement BAPIs. certain standards and rules must be adhered to over and above the standard programming rules for function modules. BOR. The sections contain information about the guidelines and conventions that you should adhere to when defining and implementing a BAPI. December 1999 15 . The following sections guide you through the steps involved in developing a BAPI.

Defining the scenario in which the BAPI will be used 2. Testing the BAPI and its documentation 7. Enhancing existing BAPIs. if required For further information see: Defining the Scenario [Page 21] Reviewing the Scenario Concept [Page 23] Defining the BAPI and Its Interface [Page 24] Creating Development Objects and Documentation [Page 46] General Programming Guidelines for BAPIs [Page 54] Testing the BAPI and Its Documentation [Page 52] Releasing the BAPI [Page 53] SAP Enhancements to Existing BAPIs [Page 144] 16 December 1999 . Programming BAPIs 6. Releasing the BAPI 8.BAPI Programming Defining and Implementing the BAPI SAP AG Process Flow The development of a BAPI is divided into the steps below (see also the appropriate project template in the BAPI Explorer [Page 17] or the BAPI Quality Checklist [Page 166]): Task 1. Reviewing the BAPI scenario and how the BAPIs interact with one another 3. Creating individual programming objects 5. Defining a BAPI and Its Interface 4.

The entire development process of a BAPI takes place in the framework of form-controlled "projects" to achieve maximum quality. Structure The BAPI Explorer is divided into two areas: • Hierarchy display Here all the business object types or interface types for which BAPIs have been defined are displayed. For this reason to work with the BAPI Explorer. The BAPI Explorer is used internally in SAP to develop BAPIs.6A. December 1999 17 . or from an alphabetical list.6A and enhances or replaces the BAPI Browser used in earlier releases. If you are using a SAPgui from an earlier release. Integration To call the BAPI Explorer choose Tools → Business Framework → BAPI Explorer. the BAPI Browser (Transaction BAPI45) is automatically called instead of the BAPI Explorer. For further information see Working with Display Functions [Page 18]. Use Prerequisites The BAPI Explorer is available as of Release 4. The tools used to develop BAPIs are also available in the work area. you must be using a SAPgui of version 4. For information about working in the BAPI Browser see BAPI Browser [Ext. The BAPI Explorer provides all the tools used to create BAPIs and the required development objects in an integrated programming environment. Purpose In the BAPI Explorer. For further information see Working with Tools and Projects [Page 20].SAP AG BAPI Programming BAPI Explorer BAPI Explorer Definition The BAPI Explorer is the R/3 System working environment for developing BAPIs themselves and for developing with BAPIs. • Work area Here the details and documentation of the development object selected in the hierarchy display can be viewed. stability and usability of the BAPI. All information required to use a particular BAPI is provided in the BAPI Explorer. To call it directly use Transaction BAPI.] in the BAPI User Guide. The BAPI Explorer uses the latest HTML control technology. application developers can get an overview of the status of BAPIs in the BOR. but can also be used by customers and partners. The BAPIs can be determined either by the position of the associated obect or interface type in the component hierarchy in the BOR.

To make it easier to find a business object type and its BAPIs. If you have installed Microsoft Internet Explorer Version 4. For example. you can print the documentation using the standard SAPgui print function. By expanding the relevant nodes you can navigate up to the parameter level of individual BAPIs. by double clicking on the name of the function module. that is BAPIs of SAP interface types and BAPIs that have not yet been released. To display these. in the detail display for a particular method.BAPI Programming Working with Display Functions SAP AG Working with Display Functions Use In the hierarchy display of the BAPI Explorer all the business object types or interface types for which BAPIs have been defined are displayed. • Displaying and Printing Documentation In the Documentation view of the work area the documentation for the development object selected in the hierarchy is displayed. Features The following display functions are also provided which enable you to directly access BAPIs and their details in the BOR.0 on the front-end computer. you can select whether the business object types or interface types are displayed alphabetically or as they are assigned in the component hierarchy in the BOR. • Displaying details Under the Detail view of the work area all the technical details of the development object selected in the hierarchy are displayed. choose Goto → Display legend. you can use the function Goto → Change hierarchy level to limit the display to two hierarchy levels. In most cases you can double-click on a field in the Detail display to get to the developent environmnt or to display further information. it will be displayed in the Function Builder. Using the tabs Alphabetical and Hierarchical in the hierarchy display. The data element documentation for each parameter field is contained in the documentation for structured BAPI parameters. you can display all the BAPIs contained in the BOR. • Specifying the BAPIs to be displayed The default is to display only released BAPIs of business object types. • Changing the level of the hierarchy display The component hierarchy may have many hierarchy levels. By choosing Goto → BAPIs to display. Business object types and interface types are identified by different symbols. • Searching for BAPIs Using the standard functions Find and Find next you can search the displayed business object types or interface types using specified criteria (placeholders such as ' * ' can be used): 18 December 1999 .

e. object list* December 1999 19 . e. Plan* Method name.g.g.SAP AG BAPI Programming Working with Display Functions − − − − − Object name. e.g.g. GetList Method description. e.g. SAP0001 Object description. BusinessProcess Object type (technical object name) e.

Within the project management you can save and delete your projects and you can edit the projects managed by other users by selecting Other users. List generator to create lists of BAPIs using specified selection criteria. In the Project view you can create projects to assist you with following and documenting the development procedures below: • • • Implementing new BAPIs (for internal SAP use. in the Tools view. Features Depending on the development object selected in the hierarchy display. If you have installed Microsoft Internet Explorer Version 4.0 on the front-end computer. Function Builder and ABAP Dictionary. BAPI developments must be carried out and documented using a project in the BAPI Explorer) Changing released BAPIs (only for SAP internal use) Requesting a new business object type (only for SAP internal use) For each of these projects there is a project form that takes you step by step through the entire development process and provides direct navigation options to the required development tools and information. 20 December 1999 .BAPI Programming Working with Tools and Projects SAP AG Working with Tools and Projects Use The views Tools and Projects in the work area are mainly used for developing BAPIs. you can print the project form using the standard SAPgui print function. the following tools and navigation options are provided: • • Direct access to the Business Object Builder.

COMMIT WORK commands can adversely effect the process flow of the scenario and how the BAPIs in the scenario work together. a list of all company codes is to be displayed. For SAP internal development you have to complete a business object request form in the BAPI Explorer. SAP developers will also find templates for defining and documenting BAPI scenarios. If the business object types required do not exist. BAPIs must complement each other to create a complete scenario. Process Flow To define the scenario the BAPI is to be used in. Keep in mind whilst you are planning the scenario that COMMIT WORK commands must not be used in BAPIs. consider the following issues: • Which scenario is to be implemented? Every BAPI should be based on a model of a scenario in which it can be usefully employed.]. especially the other BAPIs of the SAP business object type in question? In line with the scenario concept. A BAPI is required to read the data of a company code.SAP AG BAPI Programming Defining the Scenario Defining the Scenario Purpose Before you program a BAPI you should clearly define the processes and situations the BAPI will be used for. To read the details of a company code as described in the above example scenario. The relevant SAP business object type for this scenario is CompanyCode. SAP Business Workflow [Ext. From this list a company code can be selected.= • Which SAP business object types are required and do they exist? From the scenario definition you can get information about the SAP business object types relevant to the BAPI scenario. For examples of BAPI scenarios refer to Overview of ALE Integration Scenarios [Ext. and then using another BAPI. BAPIs should only be implemented within the context of a meaningful business scenario. First of all.] in the Library of ALE Business Processes. Their relationships with each other must be clearly defined. • What functionality should the BAPI provide and how does it affect related BAPIs. details about this company code are to be displayed. two BAPIs are required: • • To display all the company codes To display a specific company code December 1999 21 . For information about creating SAP business object types see the documentation. they must be created.

You will also have identified the SAP business object types relevant to the BAPI scenario. 22 December 1999 . If the data of a different SAP business object type is to be read or updated then the appropriate interface for this object type must be used. However. because if the company code ID is known. Other object types are not involved. • Is the BAPI assigned to the SAP business object type 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). the two BAPIs remain functionally independent of each other. • 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 type. The functions or methods of these other object types are used implicitly. From this ID details of the company code can be displayed.BAPI Programming Defining the Scenario SAP AG The interdependency between these two BAPIs is evident because first the list of company codes is displayed to obtain the ID of the specific company code sought. the BAPI "Display details of a specific company code" can be used without first calling the BAPI "Display list of all company codes". The BAPIs required to read the details of a company code in the above example scenario are only able to access data in the SAP business object type CompanyCode.

Process Flow You should carry out the review of the BAPI scenario together with all the people involved in the development of the BAPI and those responsible for quality control in your development group. December 1999 23 . Before you implement the scenario and begin defining and developing the BAPI. you should carry out a review of the scenario. You also defined the relevant SAP business object types.SAP AG BAPI Programming Reviewing the Scenario Concept Reviewing the Scenario Concept Purpose In the previous step you created a concept for a scenario a BAPI could be applied to. Start developing the BAPI only after you have successfully completed the review. Confirm that the scenario as it stands is meaningful and that the BAPIs in the scenario can interoperate without any problems.

Follow the instructions in the references given in the second column. For further information see: Standardized BAPIs [Page 26] 24 December 1999 . Function Builder Function module : BAPI_COMPANYCODE_GETDETAIL Parameter Importing : COMPANYCODEID Exporting : COMPANYCODE_DETAIL COMPANYCODE_ADDRESS RETURN ABAP Dictionary Structures Fields BAPI 0002_2 : COMP_CODE : BAPI0002_3 : BAPIRET2 : Process Flow To implement your BAPI in accordance with the required conventions. Task 1. parameters... : CompanyCodeId : . : GetDetail : CompanyCodeDetail CompanyCodeAddress Return Events : ... These BAPIs provide basic functions and can be implemented for most of the SAP business object types.. Function Builder and ABAP Dictionary Business Object Repository (BOR) Business object : CompanyCode Interfaces Key fields Attributes Methods Parameters : .BAPI Programming Defining a BAPI and Its Interface SAP AG Defining a BAPI and Its Interface Purpose After you have carried out the review of the BAPI concept and it has been accepted. you will decide on the names. you can start defining the BAPI itself. follow the guidelines for each of the tasks below. Check if the BAPI is in the Standardized BAPIs category. In this step.. Check whether the BAPI can be implemented as a standardized BAPI. Information in the BOR.. Only after you have planned and defined these required details can you start to implement the BAPI and create the required programming objects. and characteristics of the BAPI and determine the structures in the ABAP Dictionary which the BAPI will be based on. The table below illustrates where the planned information is written and how it fits together...

SAP AG BAPI Programming Defining a BAPI and Its Interface 2. Defining the Interface Structure of the BAPI [Page 32] and Standardized Parameters [Page 29] 4. You have to identify the SAP business object type in the Business Object Repository or if necessary. Define the structure and the scope of the BAPI interface Determining the Object Type and Its Key Fields [Page 31] For information about creating SAP business object types see the documentation. Give names to the required parameters in the function module. Test whether the key fields of the business object type are relevant for your BAPI. Specify the required data objects in the ABAP Dictionary. 7. Assign a name to the method parameter in the BOR. 5. Specify the name of the function module that the BAPI is based on. create one. Naming Parameters in the Function Module [Page 34] Defining Data Formats [Page 36] Specifying Development Objects in the Dictionary [Page 37] Naming the Method in the BOR [Page 40] Naming Parameters in the BOR [Page 41] Naming the Function Module and the Function Module Group [Page 43] Result Once you have completed these steps. December 1999 25 . Define the data formats in which the values must be transferred in the function module interface. Assign a name to the method in the BOR. 9. and the name of the function group in which the function module is to be stored.]. 8. 6. you will have defined your BAPI. 3. SAP Business Workflow [Ext.

for example. For more information see Programming GetStatus() BAPIs [Page 96]. company codes and material numbers. GetStatus() The BAPI GetStatus() is used to query the status of an SAP business object instance. GetDetail() The BAPI GetDetail() uses a key to retrieve details about an instance (one specific occurrence) of a business object type and returns this data to the calling program. BAPIs for Creating or Changing Data The following BAPIs can create. For more information see Programming GetDetail() BAPIs [Page 93]. ExistenceCheck() The BAPI ExistenceCheck() checks whether an entry exists for a business object instance. the processing status of a sales order. The ExistenceCheck() BAPI is an instance method. Then this information is reported back to the calling program. BAPIs for Reading Data The following BAPIs provide you with read-only access to data in the associated business object type: GetList() With the BAPI GetList() you can select a range of object key values. for example. The BAPIs GetList() is a class method. The BAPI GetStatus() is an instance method. For more information see Programming GetList() BAPIs [Page 91]. Instance methods refer to precisely one instance (one specific occurrence) of an SAP Business Object type. for example. to one explicitly specified customer order. you can differentiate between instance methods and class methods. for example. This BAPI is used only for displaying the status of an object and does not retrieve full details like the BAPI GetDetail(). Features With object methods and especially with BAPIs. change or delete instances of a business object type: 26 December 1999 . Whereas class methods are instance-independent.BAPI Programming Standardized BAPIs SAP AG Standardized BAPIs Use Some BAPIs and methods provide basic functions and can be used for most SAP business object types. Such BAPIs are known as “standardized” BAPIs. The BAPI GetDetail() is an instance method. whether the customer master has been created. For more information see Programming ExistenceCheck() BAPIs [Page 98].

CreateMultiple(). BAPIs for Mass Processing The BAPIs listed in the above section. for example. ChangeMultiple(). The BAPI Undelete() removes a deletion flag. a purchase order. Add<subobject> and Remove<sub-object> The BAPI Add<sub-object> adds a sub-object to an existing object instance and the BAPI and Remove<sub-object> removes a sub-object from an object instance. when a BAPI is called. Cancel() Unlike the BAPI Delete () the BAPI Cancel() cancels an instance of a business object. These BAPIs are instance methods. for example. For further information see Buffering for Write BAPIs [Page 77]. For more information see Programming Delete() BAPIs [Page 110]. These BAPIs are instance methods. can also be used for mass processing. several business object instances are processed at the same time. With BAPIs for mass processing. that is the instance to be cancelled remains in the database and an additional instance is created that is canceled). For more information see Programming Change() BAPIs [Page 106]. the suffix “Multiple” is added to the method name. for example. Change() The BAPI Change() changes an existing instance of a SAP business object type. The Cancel() BAPI is an instance method. for example. a purchase order. For more information see Programming Create() BAPIs [Page 102].SAP AG BAPI Programming Standardized BAPIs Create() or CreateFromData() The BAPI Create() or CreateFromData() creates an instance of an SAP business object type. “BAPIs for Creating or Changing Data”. For further information see Programming Methods for Sub-Objects [Page 120]. The () BAPI is an instance method. The BAPIs here are always class methods. Here. DeleteMultiple(). If you are implementing BAPIs that create or change data you should consider using buffering. a purchase order. December 1999 27 . For more information see Programming Cancel() BAPIs [Page 113]. Delete() and Undelete() The BAPI Delete() deletes an instance of an SAP business object type from the database. These BAPIs are class methods.

These BAPIs are used mainly to transfer data between distributed systems within the context of Application Link Enabling (ALE). 28 December 1999 . These BAPIs are class methods. They enable specific instances of an object type to be copied to one or more different systems. BAPIs for Replicating Business Object Instances The following BAPIs are used for replicating business object instances: Replicate() and SaveReplica() The BAPIs Replicate() and SaveReplica() are implemented as methods of replicable business object types(). For more information see Programming Replicate()/SaveReplica() BAPIs [Page 115].BAPI Programming Standardized BAPIs SAP AG We strongly recommend that you create instance-dependent BAPIs with buffering instead of Multiple() BAPIs. For further information see Buffering with Write BAPIs [Page 77].

all Return parameters must be implemented in the same. Extension parameters The parameters ExtensionIn and ExtensionOut provides customers with a mechanism that enables BAPIs to be enhanced without modifications. Return Parameters Each BAPI must have an export Return parameter for returning messages to the calling application. BAPI GetList(). For more information see Change Parameters [Page 125]. For more information see Selection Parameters [Page 134]. For more information see Address Parameters [Page 123]. Such parameters are known as “standardized” parameters. They should be implemented the same in all BAPIs.SAP AG BAPI Programming Standardized Parameters Standardized Parameters Use There are some parameters that can be created for various BAPIs because they contain the same or equivalent data in all BAPIs. Selection Parameters The parameters in BAPIs used to search for specific instances of a business object type. To provide application programmers with a consistent error handling process for BAPI calls. Change Parameters In BAPIs that cause database changes (for example.Create() or CreateFromData(). December 1999 29 . standardized way. Standardized selection parameters are used to do this. especially if the underlying object type uses the central address management (CAM). have to enable the caller of the BAPIs to specify appropriate selection criteria. You should copy these structures to use in your BAPI. This distinction is made through the use of standardized parameters. The creation of the object instance is only simulated and data is not updated. Features Address parameters Specific reference structures are defined for address parameters in BAPIs. Change() and Create() BAPIs) you must be able to distinguish between parameter fields that contain modified values and parameter fields that have not been modified. For further information see Return Parameters (Error Handling) [Page 130]. to check the entries for the object instance in the database before actually creating the object instance. Test Run Parameters The parameter TestRun is used in the BAPIs that generate instances . For further information see Customer Enhancement Concept for BAPIs [Page 65]. for example.

documentation of a business object type. you have to create standardized text transfer parameters. 30 December 1999 .BAPI Programming Standardized Parameters For further information see Test Run Parameters [Page 135]. SAP AG Text Transfer Parameters To transfer BAPI documentation texts. For more information see Text Transfer Parameters [Page 136]. for example.

CompanyCode. This key may consist of several key fields which are used to identify an individual single instance of the SAP business object type. The SAP business object type.SAP AG BAPI Programming Determining the Object Type and Its Key Fields Determining the Object Type and Its Key Fields Purpose Object type You have to identify the SAP business object type required for your BAPI in the Business Object Repository or if necessary. This key field must be defined as a parameter with the name COMPANYCODEID in the function modules of the instant-dependent BAPIs for this business object type. December 1999 31 . create one. To display the business object type’s key fields. Unlike instance-independent methods. expand the node Key fields. The business object types are displayed in the order of the R/3 application hierarchy. For further information see Defining the Interface Structure of the BAPI [Page 32]. instance-dependent methods relate to one instance (one specific occurrence) of an SAP business object type. 3. You can differentiate between instance-dependent (instance methods) and instance-independent (class methods) BAPIs. has a key field named CompanyCodeId. the key fields of the corresponding SAP business object type must be used as parameters in the function module the BAPI is based on so that the associated object instance can be identified. 2. for example to one specific sales order. Process Flow To display a business object type and its key fields: 1. Select the required SAP business object type in the application hierarchy and double click it to open it. For SAP internal development you have to complete a business object request form in the BAPI Explorer.]. SAP Business Workflow [Ext. The names of the key fields in the SAP business object type and the corresponding parameters in the BAPI function module must be the same. because the name links the key fields to the parameters. For information about creating SAP business object types see the documentation. Select Tools →=ABAP Workbench → Overview →=Business Object Browser=. Key Fields A key is defined in the BOR for the majority of SAP business object types. In the case of instance-dependent BAPIs.

CreateFromData(). for example. Return. • For BAPIs that are class methods no key field is set as the BAPI function module’s own parameter. that is. the calling program has to specify the ID 32 December 1999 . Specify what other data is relevant in import. That way a specific instance of the business object type is identified. Process Flow Try to structure the BAPI as clearly as possible. each key field of the business object type should be set as an export parameter in the BAPI function module. as described in the list item above. 2. • For BAPIs that generate instances. the individual import.GetStatus(). You have to create an export parameter. These BAPIs return one key value. the BAPIs Create() or CreateFromData(). export or table parameters for the BAPI. To read the company code.GetDetail() and Customer. For details see Return Parameters (Error Handling) [Page 130]. this could be a customer number (CustomerNo) in the BAPIs Customer. Exceptions are write BAPIs. an order number in the BAPI SalesOrder. to send messages back to the calling program. For example. The BAPI to be developed is to read data from the SAP business object type CompanyCode. Usually they return a table with a selection of key values. Check that the key fields of the SAP business object type in question are required and specify how they are going to be used in the BAPI interface.BAPI Programming Defining the Interface Structure of the BAPI SAP AG Defining the Interface Structure of the BAPI Purpose In this step you are going to define the scope and interface structure of the BAPI. Check that the parameters can be implemented as standardized parameters. the key field must be set as an import parameter in the function module of the BAPI. export and table parameters required for calling the BAPI. for example. Class methods are instance-independent and are called without the use of key values. or the number of a sales document in the BAPI SalesOrder.CheckPassword(). Match the import parameters with each other to avoid having redundant data in the interface. To identify the interface parameters for your BAPI. proceed as follows: 1. You will specify the names of these parameters in the section Naming Parameters in the Function Module [Page 34] You cannot use change and exception parameters in a function module which implements a BAPI. The key fields of the SAP business object type are some of the most important BAPI parameters. • If a key value is to be passed to the BAPI by the calling program.

To map these requirements to the BAPI interface. December 1999 33 . the following parameters must be created in the function module which the BAPI is based on: • • • • The key field CompanyCodeID of the SAP business object type as an import parameter A Return parameter that reports messages back to the calling program A parameter for the details of the company code. The returned information should include detailed data and address data. A parameter for the address data of the company code.SAP AG BAPI Programming Defining the Interface Structure of the BAPI of the company code.

Choose meaningful names and do not use abbreviations. (In earlier Releases names of parameters in the BOR could only be a maximum of 20 characters long. A return parameter that reports messages back to the calling program You could use the following names for these parameters in the function module: Contents Company code Detailed data of company code Address data of company code Return Parameters Name in Function Module COMPANYCODEID COMPANYCODEDETAIL COMPANYCODEADDRESS RETURN Parameter Type IMPORTING EXPORTING EXPORTING EXPORTING 34 December 1999 . Process Flow You are only allowed to define export. Parameter names in function modules that implement the BAPIs can therefore also have up to 30 alphanumeric characters. An export parameter for the address data of the company code.BAPI Programming Naming Parameters in the Function Module SAP AG Naming Parameters in the Function Module Purpose In the previous step you identified the scope and the required contents of the interface parameters. The names you choose for the function module parameters are used in the Business Object Repository (BOR) as the names of the associated method parameters. Now you have to specify the names of these parameters in three function module. • In the above example based on the company code scenario. The names of BAPI parameters in the BOR and the names of the parameters in the associated function module must be identical. import and table parameters for the BAPI function module interface. For this reason parameters in function modules must have meaningful names in English to ensure the BAPI method call can be carried out without any problems.5A the names of method parameters in the BOR can be up to 30 characters long. the following parameters were required: • • • • An import parameter for the key field CompanyCodeID of the SAP business object type CompanyCode An export parameter for the detailed data of the company code. As of Release 4. Change and exception parameters are not allowed. When assigning parameter names follow the guidelines below: • • The names must be in English. The associated parameter names in the function module could only be 20 characters long).

SAP AG BAPI Programming Naming Parameters in the Function Module December 1999 35 .

Fields in BAPI parameters must be presented in a neutral form used in the database and not in a form formatted in the BAPI interface. for example: • • • • Currency amount fields Quantity fields Fields that have an internal key Specific fields in address structures To do this you can generate function modules that can map the relevant data to each other and perform the conversion. • Data must not be presented in a user-dependent or language-dependent format. This applies to. 36 December 1999 . where YYYY is the year. to connect non-SAP systems and PC products to the R/3 System. whenever possible. For further information about these exceptions see Internal and External Data Formats [Page 69].BAPI Programming Defining Data Formats SAP AG Defining Data Formats Purpose Here you specify the formats in which the data has to be transferred in the function module interface. such as ISO codes must be used. For example. Standard codes. MM the month and DD the day. • Exceptions SAP-specific data formats must be converted into the data format required externally. BAPIs are not end user interfaces. they are programming interfaces that can be used in diverse application areas. for instance. the date in a BAPI must be in the internally used format YYYYMMDD.

December 1999 37 . This enables changes to be made in R/3 applications without affecting BAPIs. If a parameter consists of one field only. Every parameter must refer to a Dictionary object. The associated development classes begin with B or S. Structure S1 consists of fields F1 and F2. because enhancements to INCLUDE structures generally lead to incompatible changes to the BAPI structure. Names should begin with the prefix BAPI. Structure S2 includes structure S1 and has a field F3. this must be linked to a field in a BAPI structure. structures and tables as parameters. Process Flow Note the following guidelines: • You can use individual fields. such as table fields in structures. Complex data types. If possible only use central data elements and domains contained in Basis Development or in Application Basis. BAPI structures themselves should not be used in other structures. Note that all the parameters must be defined as structures. Give meaningful names to the data structures you create. you can identify and define the required data objects in the ABAP Dictionary. For further information see Incompatible Enhancements [Page 148]. • 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. are not allowed.SAP AG BAPI Programming Specifying Development Objects in ABAP Dictionary Specifying Development Objects in ABAP Dictionary Purpose After you have specified the contents and names of the required interface parameters. The graphic below illustrates the problem: Original structures: Structure S1 Structure S2 F1 F1 F2 F2 Structure S2 includes structure S1 F3 Structures after adding field F3: Structure S1 Structure S2 F1 F1 F2 F2 F3 F3 F3 Problems in structure S2: • Field added in the middle of structure (incompatible change) • Two fields have the same name (naming conflict) • You can use existing data elements and domains for fields in BAPI structures. If a field F3 is added to structure S1. • You must not use INCLUDE structures in BAPI structures. this causes an incompatible change to structure S2 and leads to a name clash of the F3 fields.

Whenever possible use these names for the field and parameter names. The report BBAPIFLD generates the English default names for the fields and parameters. • Choose meaningful names in English for the fields in the structures.BAPI Programming Specifying Development Objects in ABAP Dictionary SAP AG Before you use an existing data element or domain. from Release 4.1. In this Release structure names had a maximum of 10 characters. the reference fields/tables shown below were identified for the parameters. The second example shows how you could name the structures more meaningfully in Release 4.0 you can use up to 30 characters. Up until Release 4.1 Parameter in the Function Module COMPANYCODEID COMPANYCODEDETAIL COMPANYCODEADDRESS RETURN Reference Field/Table BAPI0002_2-COMP_CODE BAPI0002_2 BAPI0002_2 BAPIRETURN1 Parameters and their Reference Fields in Release 4. In the example in the previous steps. As of Release 4.0 ten characters were available for naming structures.0 Parameter in the Function Module COMPANYCODE COMPANYCODEDETAIL COMPANYCODEADDRESS RETURN Reference Field/Table BAPI0002_2-COMP_CODE BAPI0002_COMPANYCODEDETAIL BAPI0002_COMPANYCODEADDRESS BAPIRETURN1 38 December 1999 . Parameters and their Reference Fields in Release 3. If German field names are used in the internal work structures of a BAPI you can use the transaction described in Converting Between Internal and External Data Formats [Page 140]. you should consult the respective colleague responsible for the object.0 default field names in English exist for data elements in the ABAP Dictionary. You can use alphanumeric characters and underscores.0. The first example here uses structures created in Release 3. To use this report refer to the report documentation. to convert the German field names into English.

SAP AG

BAPI Programming Specifying Development Objects in ABAP Dictionary

December 1999

39

BAPI Programming Naming the Method in the BOR

SAP AG

Naming the Method in the BOR
Process Flow
You can now specify the name of the BAPI as a method of a SAP business object type in the Business Object Repository (BOR). 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

For standardized BAPIs use the corresponding generic name, for example, GetList, GetDetail. For further information about these BAPIs see Standardized BAPIs [Page 26].

In standard, object-oriented language use, parentheses() are added to the method name, for example GetList(), in documentation and user guides. This convention is also used in the document. However, no parentheses are used when assigning BAPI names. To get an idea about naming BAPIs, you should take a look at the existing BAPIs of an SAP business object type in the BOR.

40

December 1999

SAP AG

BAPI Programming Naming Parameters in the BOR

Naming Parameters in the BOR
Process Flow
You can now assign names to the individual method parameters in the Business Object Repository (BOR). These names are based on the names of the parameters in the function module that you assigned in Naming Parameters in the Function Module [Page 34]. When naming BAPI parameters in the BOR follow the guidelines below: • The components of parameter names in the BOR are separated by upper and lower case letters to make them easier to read. Each new word in the parameter name begins with a capital letter, for example, CompanyCodeDetail. From Release 4.0 the names of BAPI parameters in the BOR and the names of the parameters in the associated function module must be identical except for the use of upper and lower case letters. This was not necessarily the case for BAPIs developed before Release 4.0. Standardized parameters have specified names. For more information see Programming Standardized Parameters [Page 122]. If you create your BAPI in the BOR using the BOR/BAPI Wizard, the Wizard uses the parameter names in the function module as the default names of the method parameters. For information about the BOR/BAPI Wizard see Defining Methods in the BOR Using the BOR/BAPI Wizard [Page 138]. • • Parameter names in the BOR must be in English. Parameter names in the BOR cannot be more than 30 characters.

In the example in the previous steps, four parameters for one BAPI were identified and the names of these parameters specified 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
Company code Detailed data of company code Address data of company code Return Parameters

Name in Function Module
COMPANYCODE COMPANYCODEDETAIL COMPANYCODEADDRESS RETURN

Name in the BOR
CompanyCode CompanyCodeDetail CompanyCodeAddress Return

December 1999

41

BAPI Programming Naming Parameters in the BOR SAP AG 42 December 1999 .

Use the suffix "nnnn" as the technical name of the function group. If a function group does not already exist. for example. but the BAPI_<Name of object type> should always be written in full. as described in the section Determining the Object Type and Its Key Fields [Page 31] To display further details. December 1999 43 . which reads details for the object type CompanyCode. To find out the technical name of the business object type. As the basis for naming the function group. For example. For example. BAPIs belonging to different SAP business object types must not be created in the same function group. You must also specify the function group which this function module is to be assigned to. the technical name. Process Flow Assigning a Name to the Function Module Choose a name for the function module which gives an indication of what the BAPI is used for. • The object name of an SAP business object type can be used for the name of the function group. Specifying the Function Group All the BAPIs belonging to an SAP business object type should be created in one or more function groups. If there is not an appropriate function group. you have to specify a name for a new function group. where n is a number. all BAPIs associated with the business object type. you can shorten the name of the method. You cannot exceed the maximum length of 30 characters. could be stored in a function group called Companycode. the name of the associated function module is BAPI_COMPANYCODE_GETDETAIL.SAP AG BAPI Programming Naming the Function Module and the Function Module Group Naming the Function Module and the Function Module Group Purpose Here you specify the name of the function module the BAPI is based on. The naming convention for BAPIs is BAPI_<Name of object type>_<method name>. Ascertain whether a function group has already been created for the BAPIs of the SAP business object type in question. CompanyCode. you can use either the default technical name (object type) of the SAP business object type or its object name. then the associated BAPI function group is called 1008. if the technical name of the object type is BUS1008. open the object type in the Business Object Repository (BOR). double click on the name of the business object type . In the case of a GetDetail() BAPI. • The technical name (object type) of an SAP business object type usually takes the form of BUSnnnn. specify a name for one to be created. If required.

BAPI Programming Naming the Function Module and the Function Module Group SAP AG 44 December 1999 .

The target system is determined for the BAPI call in the distribution model of Application Link Enabling (ALE). Functions implemented outside the R/3 System can be standardized and made available as BAPIs. In Release 4. The information contained in the BAPI User Guide [Ext. December 1999 45 .5A API methods of interface types must have the status “implemented”. For further information see Determining BAPIs of Interface Types [Ext. the documentation will explain what the differences are. Features When creating BAPIs for outbound processing keep in mind: • • • • BAPIs used for outbound processing simply require the interface definition. Integration BAPIs used for outbound processing are defined in the Business Object Repository as API methods of SAP interface types.SAP AG BAPI Programming BAPIs Used for Outbound Processing BAPIs Used for Outbound Processing Use As of Release 4. For further information see Defining Methods in the BOR Using the BOR/BAPI Wizard [Page 138]. Unlike the conventional BAPIs that are implemented in the R/3 server system and also called here (inbound). If this is not the case. These BAPIs are known as BAPIs used for outbound processing.] in the BAPI User Guide.with the exception of the above-mentioned points BAPIs of both SAP interface types and SAP business object types. BAPIs used for outbound processing can be determined from the BOR using Transaction SWO1. BAPIs both for outbound processing and for inbound processing can be called in the same way via the ALE distribution model. Use the BOR/BAPI Wizard to create a BAPI of an SAP interface type.] and in the BAPI Programming Guide refers to . There are always separate systems for defining (client) and for implementing (server) outbound BAPIs.5A BAPIs can also be defined which have been implemented outside the R/3 System yet can still be called from the R/3 System. outbound BAPIs are interfaces implemented on the client system. the function module cannot be programmed.

If necessary. For further information see the BC ABAP Workbench: Tools [Ext. identified the relevant programming objects and given them names. Documentation on the BAPI and its parameters is essential because it is very difficult to use a BAPI that has not been well documented. you can create the programming objects in the R/3 System. 3. generating the function modules that can convert between the internal and external data formats. fields and domains are stored in the ABAP Dictionary. 4. structures. 46 December 1999 .]. 5. Writing the program for the function module that the BAPI is based on.]. For details on how to do this see Converting Between Internal and External Data Formats [Page 140]. for example. If required. The data objects. Process Flow Task 1. For internal BAPI documentation you must follow the current BAPI documentation guidelines which you can get from your contact person in the BAPI Development group. For general information about creating business object types refer to the documentation on SAP Business Workflow [Ext. For further information see the ABAP Dictionary [Ext.]. Create the documentation for the BAPI and for each interface parameter and for each parameter field. Create the function module in the Function Builder and the function group. create the required SAP business object type in the Business Object Repository. 2. Note that the COMMIT WORK command must not be used in the function module. See the general Documentation Guidelines [Page 88]. if required. For further information see General Programming Guidelines for BAPIs [Page 54] and Programming Standardized BAPIs [Page 90] For an example of a function module that implements a BAPI see BAPI Interface and Function Module [Page 48].BAPI Programming Creating Development Objects and Documentation SAP AG Creating Development Objects and Documentation Purpose After you have defined your BAPI. Tools / Further Information For SAP internal development you have to complete a business object request form in the BAPI Explorer. 6.

Finally. December 1999 47 . Using the BOR/BAPI Wizard. define the function module as a method of the associated SAP business object type in the BOR. make sure that the parameters and parameter types of the method in the BOR match the parameters of the underlying function module in the Function Builder. For more information see Defining Methods in the BOR Using the BOR/BAPI Wizard [Page 138]. For an example of a function module that implements a BAPI see BAPI Interface and Function Module [Page 48].SAP AG BAPI Programming Creating Development Objects and Documentation 7.

displays details of a purchase order The method consists of several import. Note the following: • • The business object type has a key field PurchaseOrder.BAPI Programming BAPI Interface and Function Module SAP AG BAPI Interface and Function Module The definition of a BAPI in the Business Object Repository and its associated function module in the Function Builder must correspond to each other. export. Business Object PurchaseOrder with Key Fields and Methods Function Module BAPI_PO_GETDETAIL This function module BAPI_PO_GETDETAIL implements the BAPI GetDetail() of the business object type PurchaseOrder. This example shows the relationships between the method and the function module. and import/export (table) parameters. Keep in mind the following points when reading the source code extract below: • The name of the function module BAPI_PO_GETDETAIL is in the format: BAPI_<Name of object type>_<method name>. The method we are looking at. Standard abbreviations can be used for business 48 December 1999 . GetDetail(). The graphic below shows the SAP business object type PurchaseOrder (BUS2012) in the BAPI Browser view of the BOR.

5A the reference structure BAPIRET2 or BAPIRET1 must be used. • • • Source Code Function Module BAPI_PO_GETDETAIL *"---------------------------------------------------------------------*" *"local interface: *" IMPORTING *" VALUE(PURCHASEORDER) LIKE BAPIEKKO-PO_NUMBER *" VALUE(ITEMS) LIKE BAPIMMPARA-SELECTION DEFAULT 'X' *" VALUE(ACCOUNT_ASSIGNMENT) LIKE BAPIMMPARA-SELECTION *" DEFAULT SPACE *" VALUE(SCHEDULES) LIKE BAPIMMPARA-SELECTION *" DEFAULT SPACE *" VALUE(HISTORY) LIKE BAPIMMPARA-SELECTION *" DEFAULT SPACE *" VALUE(ITEM_TEXTS) LIKE BAPIMMPARA-SELECTION *" DEFAULT SPACE *" VALUE(HEADER_TEXTS) LIKE BAPIMMPARA-SELECTION *" DEFAULT SPACE *" VALUE(SERVICES) LIKE BAPIMMPARA-SELECTION *" DEFAULT SPACE *" *" *" *" *" *" *" *" *" *" *" *" *" *" *" *" *" *" *" EXPORTING VALUE(PO_HEADER) LIKE BAPIEKKOL STRUCTURE VALUE(PO_ADDRESS) LIKE BAPIADDRESS STRUCTURE BAPIADDRESS TABLES PO_HEADER_TEXTS STRUCTURE BAPIEKKOTX OPTIONAL PO_ITEMS STRUCTURE BAPIEKPO OPTIONAL PO_ITEM_ACCOUNT_ASSIGNMENT STRUCTURE BAPIEKKN OPTIONAL PO_ITEM_SCHEDULES STRUCTURE BAPIEKET OPTIONAL PO_ITEM_TEXTS STRUCTURE BAPIEKPOTX OPTIONAL PO_ITEM_HISTORY STRUCTURE BAPIEKBE OPTIONAL PO_ITEM_HISTORY_TOTALS STRUCTURE BAPIEKBES OPTIONAL PO_ITEM_LIMITS STRUCTURE BAPIESUH OPTIONAL PO_ITEM_CONTRACT_LIMITS STRUCTURE BAPIESUC OPTIONAL PO_ITEM_SERVICES STRUCTURE BAPIESLL OPTIONAL PO_ITEM_SRV_ACCASS_VALUES STRUCTURE BAPIESKL OPTIONAL RETURN STRUCTURE BAPIRETURN OPTIONAL BAPIEKKOL December 1999 49 .SAP AG BAPI Programming BAPI Interface and Function Module object types. These are recognized by the prefix BAPI. better to write the name of the object type in full. From Release 4. The function module picks up exceptions in the Return parameter. Underscores in parameter names are no longer allowed. The key field PURCHASEORDER of the business object type is defined as an import parameter. if necessary. for example. however. As of Release 4. for example. BAPIEKKOL. BAPI_PURCHASEORDER_GETDETAIL and. It is. to shorten the method name.0 the names of the parameters in the method in the BOR must be exactly the same as the names of the parameters in the function module. • • BAPI data structures are used. The function module performs authorization checks.

RETURN. PO_ITEM_LIMITS. PERFORM FILL_BAPIRETURN TABLES RETURN USING 'E' 'W5' '107' PURCHASEORDER SPACE SPACE SPACE. ……. PO_ITEM_SERVICES. CEKET. SAP AG ENDFUNCTION. PO_ITEM_TEXTS. PO_ITEM_ACCOUNT_ASSIGNMENT. ENDIF. PO_ITEM_HISTORY_TOTALS. PO_ITEM_HISTORY_TOTALS BY PO_ITEM SERIAL_NO. PO_ITEM_LIMITS BY PCKG_NO PO_ITEM_CONTRACT_LIMITS BY PCKG_NO LINE_NO. CEKKN. CADR. PO_ITEM_SERVICES BY PCKG_NO LINE_NO. PO_ITEM_SRV_ACCASS_VALUES. CEKPO. PO_ITEMS. SEKPO. PO_ITEM_SCHEDULES BY PO_ITEM SERIAL_NO. REFRESH: PO_HEADER_TEXTS. PO_ITEM_LIMITS. PO_ITEM_TEXTS. IF SY-SUBRC NE 0. PO_ITEM_CONTRACT_LIMITS. RETURN. 50 December 1999 . * select the header data from database SELECT SINGLE * FROM EKKO WHERE EBELN EQ PURCHASEORDER. PO_HEADER_TEXTS. EXIT. SEKKO. PO_ADDRESS. PERFORM FILL_BAPIRETURN TABLES RETURN USING 'E' 'W5' '033' SPACE SPACE SPACE SPACE. ……. PO_ITEM_ACCOUNT_ASSIGNMENT. CEKET. * authority check PERFORM PO_AUTHORITY_HEADER TABLES RETURN USING EKKO.BAPI Programming BAPI Interface and Function Module *"---------------------------------------------------------------------* reset all structures and tables CLEAR: PO_HEADER. IF NO_AUTHORITY NE SPACE. SEKKO. ENDIF. PO_ITEM_HISTORY. EKPOKEY. PO_ITEM_HISTORY. SEKPO. PO_ITEM_HISTORY BY PO_ITEM SERIAL_NO. SORT SORT SORT SORT SORT SORT SORT SORT SORT PO_ITEMS BY PO_NUMBER PO_ITEM. PO_ITEM_SRV_ACCASS_VALUES. EXIT. CEKKO. PO_ITEM_SCHEDULES. PO_ITEM_HISTORY_TOTALS. PO_ITEM_CONTRACT_LIMITS. PO_ITEM_SRV_ACCASS_VALUES BY PCKG_NO LINE_NO SERNO_LINE. PO_ITEM_ACCOUNT_ASSIGNMENT BY PO_ITEM SERIAL_NO. CEKAN. PO_ITEMS. EKPOKEY. CEKKN. PO_ITEM_SERVICES. PO_ITEM_SCHEDULES.

SAP AG BAPI Programming BAPI Interface and Function Module December 1999 51 .

each BAPI and for each interface parameter is available and that you can understand it.BAPI Programming Testing the BAPI and Its Documentation SAP AG Testing the BAPI and Its Documentation Purpose After you have implemented the function module your BAPI is based on and you have defined the BAPI as a method of an SAP business object type in the Business Object Repository (BOR) you should check that the BAPI functions properly. for example. • By testing the BAPI call from an external program. 52 December 1999 . Result If you find any errors in the BAPI implementation. Process Flow Testing the Documentation Check that the documentation for each business object type. 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 method of a business object type. Testing the BAPI You can test the BAPI in the following ways: • By testing the underlying function module in the Function Builder You can individually test the parameters in your function module by entering the appropriate test values in the parameters to verify that the source code in the function module can run without errors. Prerequisites Carry out the test together with persons responsible for quality control in your development group.]. from a Visual Basic program using SAP’s BAPI ActiveX Control [Ext. correct them and repeat the tests until you and the quality control team in your group are fully satisfied with the BAPI implementation and with the documentation. You should ensure that your BAPI can be called from within external programs.

SAP AG

BAPI Programming Releasing the BAPI

Releasing the BAPI
After you have completed the function module and BAPI tests, the development of the BAPI is complete. You can now release the function module the BAPI is based on and the method in the Business Object Repository (BOR). Once the BAPI has been released, it becomes available as a fully implemented method of a business object type. Releasing also prevents anyone making incompatible changes to the BAPI, because all changes made to a released 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 SAP Enhancements to Existing BAPIs [Page 144]. The BAPI must be released in cooperation and agreement with the persons responsible for the development objects involved and those responsible for quality control. To release a BAPI follow the steps below: 1. First release the function module in the Function Builder. Select Function module → Release → Release. 2. Set the status of the method to 'released' in the Business Object Builder. 3. Select the relevant SAP business object type in the Business Object Builder and open the node Methods. 4. Place the cursor on your BAPI and select Edit → Change release status → Object type component → In Released. 5. Verify the new status of the function module in the Function Builder and the method in the BOR.

Releasing BAPIs in the Context of ALE
If you are implementing the BAPI in an asynchronous context of Application Link Enabling (ALE), you have to also release the IDoc associated with the BAPI. For more information see the ALE Programming Guide [Ext.].

December 1999

53

BAPI Programming General Programming Guidelines for BAPIs

SAP AG

General Programming Guidelines for BAPIs
Use
To ensure that BAPIs, as interfaces of SAP business object types, provide access to R/3 data and processes in a consistent way, you must follow certain rules when programming BAPIs. This section contains general information and guidelines on programming BAPIs. It is difficult to formalize the contents and functional scope of a BAPI. Every BAPI has a different functional content, even those that perform similar functions, for example, the standardized BAPIs. The differences are mainly due to the different characteristics of SAP business object types and their contents.

Guidelines Specific to BAPIs
In addition to the general guidelines, you should follow the specific guidelines for programming BAPIs: Programming Standardized BAPIs [Page 90] Using BAPIs in Distributed Systems (ALE) [Page 164]

General Recommendations
Keep in mind the following recommendations when developing your BAPI:

Recommendation
Minimize interface complexity. Supply the BAPI with the minimum of data and group the data from a business perspective. Structure your BAPI in the most efficient way

For Further Information See:

Improving Performance [Page 86]

Mandatory Rules
You must follow these rules for all BAPIs:

General Mandatory Rules
BAPIs must not invoke COMMIT WORK commands. BAPIs must not contain the following commands: • • • CALL TRANSACTION SUBMIT REPORT SUBMIT REPORT AND RETURN

For Further Information See:
Transaction Model for Developing BAPIs [Page 58] Transaction Model for Developing BAPIs [Page 58]

INCLUDE structures must not be used in BAPI structures.

Specifying Development Objects in the Dictionary [Page 37]

54

December 1999

SAP AG

BAPI Programming General Programming Guidelines for BAPIs

Database changes can only be made through updates. The global memory must not be used to transfer values. Due to transparency it is strongly recommended not to use Set and Get. If required every BAPI must be able to carry out its own authorization checks. Values relevant for Customizing are not allowed to be changed. Language-dependent values cannot be used as interface parameters. BAPIs must not produce any screen output. This means that lists, queries and dialog boxes must not be returned to the calling program. This is true for the BAPI itself and for any function module that may be indirectly called by the BAPI. BAPIs must not cause program terminations, they can only return a message (type A: termination message) in the return parameter. Messages of type E (error) and A (termination) cannot be output in the program.

Transaction Model for BAPIs Without Commit [Page 63] Transaction Model for Developing BAPIs [Page 58] Transaction Model for Developing BAPIs [Page 58]

Programming Create() BAPIs [Page 102] and Programming Change() BAPIs [Page 106]

Return Parameters (Reporting Errors) [Page 130]

Fields and Parameters
You must follow these rules for BAPI fields and parameters:

Mandatory Rules for Fields and Parameters
Standardized parameters must be implemented consistently. Each BAPI must have a return parameter for returning messages to the calling application. All field and parameter names must be in English

For Further Information See:
Programming Standardized Parameters [Page 122] Return Parameters (Reporting Errors) [Page 130] Naming Parameters in the Function Module [Page 34] Specifying Development Objects in the Dictionary [Page 37]

All quantity and amount fields must be assigned quantity unit fields. All currency amount fields must be assigned currency IDs. All key fields in GetDetail() and GetList() BAPIs must be displayed as text fields.

Internal and External Data Formats [Page 69]

December 1999

55

For example.12" and not as "1012". the value "10.BAPI Programming General Programming Guidelines for BAPIs Whenever possible. F4 input help for fields in BAPI parameters must be made available SAP AG Providing Input Help (F4 Help) [Page 73] Data conversion You must follow these rules for data conversions: Mandatory Rules for Data Conversion Only the internal data format can be used in BAPIs Except for: • • • • • Currency amount fields Quantity fields ISO codes Fields that have an internal key Specific fields in address structures For Further Information See: Internal and External Data Formats [Page 69] You must always use a period for the decimal point Currency amounts with decimal points must be formatted with a decimal point in the interface.12" must be formatted as "10. Internal and External Data Formats [Page 69] Documentation You must follow these rules for the documentation: Mandatory Rules for Documentation The business object type must be documented For Further Information See: Business object type documentation is stored in the Business Object Repository. You can get these from your contact person in BAPI development. 56 December 1999 . SAP information developers must follow the latest business object type documentation guidelines.

Documentation on mandatory parameters must specify which fields must be filled. The documentation must be checked for completeness and comprehensibility. You can get these from your contact person in BAPI development. The documentation on return parameters must describe all possible return values and messages. this must be explained in the documentation on the return parameter. Note the following guidelines: • BAPIs with buffering must be identified as such. Providing Interface Descriptions [Page 75] December 1999 57 . a database rollback is executed in the return parameter. SAP information developers must follow the latest BAPI documentation guidelines. this must be documented. All mandatory fields in a parameter must be documented as mandatory parameters. « In the case of exceptions: If the BAPI contains a COMMIT WORK command. All available BAPI table extensions must be listed in the documentation on the extension parameter. for termination messages. • The documentation on the BAPI and the interface parameters is created in the Function Builder for the function module that the BAPI is based on. • • • • • Data element documentation must be written for all the fields in BAPI parameters. If.SAP AG BAPI Programming General Programming Guidelines for BAPIs The business object must be documented All interface parameters must be documented.

each call must have the same result. "Collective Note for BAPIs with the Commit Work Command". An R/3 LUW is all the steps involved in a transaction including updating the database.BAPI Programming Transaction Model for Developing BAPIs SAP AG Transaction Model for Developing BAPIs Use The transaction model in which BAPIs are used determines how you have to program BAPIs.1. • Durable Changes cannot be reversed and transactions cannot be canceled. the BAPIs themselves executed the COMMIT WORK command. Features In Release 3. This is the only way users are able to know that the BAPI contains a COMMIT WORK command. database operations are either fully executed or not at all. Either all relevant data has to be changed in the database or none at all. • Isolated (isoliert) There must be no functional dependencies between two transactions. this must be mentioned in the BAPI documentation. a transaction represents one processing step or one logical unit of work (LUW). No data is imported that may indirectly affect the result.0 BAPIs cannot execute 'COMMIT WORK' commands. The outcome is two transaction models: Transaction Model for BAPIs with Commit [Page 60] Transaction Model for BAPIs Without Commit [Page 63] 58 December 1999 . BAPIs had the same purpose as an LUW or transaction. The ACID principle applies to transaction models. As of Release 4. The whole transaction must be programmed to be stateless. Logical Unit of Work (LUW) and Statelessness Within the context of the transaction model used to develop BAPIs. This enables several BAPIs to be combined in one LUW. • Consistent If a transaction is called more than once.R/3 Frontend in Note 0131838. meaning that transactions are: • Atomic When a transaction is called. If a BAPI executes a COMMIT WORK command. These BAPIs must also be documented in the SAPNet . one transaction must not affect another transaction.

SAP AG BAPI Programming Transaction Model for Developing BAPIs December 1999 59 .

. For example. The process flow of the program consists of the following steps below (see graphic below): Log on . Only data from the R/3 System is to be changed.. There is one BAPI call for each transaction in this transaction model. Log off Source code Source code Source code Call BAPI to read and/or change data Call BAPI to read and/or change data 60 December 1999 ... BAPIs can only be called synchronously. When the RFC connection is already established.BAPI Programming BAPI Transaction Model with Commit SAP AG BAPI Transaction Model with Commit Use The example below of an external program calling a BAPI to change data in an R/3 System.. 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. . illustrates how the transaction model affects BAPI development using commit. . A BAPI call is essentially the call of the underlying RFC capable function module.. this could involve a transaction implemented with Visual Basic. 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.

SAP AG BAPI Programming BAPI Transaction Model with Commit BAPI Transaction Model with Commit BAPI call (RFC call of function module) Visual Basic R/3(ABAP) . December 1999 61 . Log off . Log on .1 are created with integrated commit control. . must be carried out completely or not at all (LUW). This is the only way users are able to know that the BAPI contains a COMMIT WORK command. The COMMIT WORK command is always invoked at the end of the function module of a BAPI that modifies data.. can be buffered. that due to transparency. you can keep Customizing data in a global memory as this data remains unchanged even if transaction calls are repeated. Set and Get parameters and the global memory should not be used.. If a BAPI executes a COMMIT WORK command. However... • All or nothing principle A database change. BAPIs are affected as follows: • Initial state each time a BAPI is called A repeated call of one BAPI must produce the same result.. this must be mentioned in the BAPI documentation. Time Logical Unit of Work Logical Unit of Work “Commit Work“ call RFC session What do the terms "LUW" and "stateless" mean to BAPIs that have been 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. creating a new sales order. Customizing data. for example.. for example. for example. For BAPIs this means.. This is why BAPIs to be implemented in 3. Only data that is not affected by the execution of the BAPI..

• No functional dependency between two BAPIs A BAPI call must not be negatively affected by an earlier call of another BAPI. and not the memory of the function group. For this reason also. "Collective Note for BAPIs with the Commit Work Command". For this reason BAPIs must not contain the following commands: • • • CALL TRANSACTION SUBMIT REPORT SUBMIT REPORT AND RETURN 62 December 1999 . you should not use Set and Get parameters in the BAPI nor use the global memory.BAPI Programming BAPI Transaction Model with Commit SAP AG In later releases BAPIs can only be implemented with integrated COMMIT WORK commands in exceptional cases.R/3 Frontend in Note 0131838. BAPIs with COMMIT WORK must be documented in the SAPNet . The global data of the function group remains and could prevent another BAPI from being called. A follow up call must not presuppose an earlier call. and thus impair the BAPI’s functional independence. Make sure that a COMMIT WORK command only deletes the memory of the function module. • Other separate LUWs are not triggered The call of a BAPI must not trigger further LUWs that are independent of the BAPI.

The existing transaction model should not be changed.SAP AG BAPI Programming BAPI Transaction Model Without Commit BAPI Transaction Model Without Commit Use As of Release 4.. that is. those BAPIs that cause database changes.. This is achieved by using the method TransactionCommit of the business object type BapiService which executes the command COMMIT WORK.TransactionCommit() .. Source code * Call BAPI Source code * Call BAPI …... Source code Call BAPI BapiService.. Source code Log off December 1999 63 . The process flow of the program consists of the following steps (see graphic below): Log on .TransactionCommit() . Source code * Call BAPI Source code * Call BAPI Source code Call BAPI BapiService.0 the commit control must be taken out of write BAPIs.

This causes all the activities carried out since the last COMMIT WORK command to be canceled.. Log off ... • 64 December 1999 .. .. a database rollback can be executed by the BAPI... Commit Work Log on Logical Unit of Work RFC Session The same rules apply in this model as in the BAPI Transaction Model With Commit [Page 60]. ..BAPI Programming BAPI Transaction Model Without Commit SAP AG BAPI Transaction Model Without Commit BAPI call BAPI call BAPIService Transaction Commit call Visual Basic R/3(ABAP) .. This situation must be described in the Return parameter documentation for the BAPI in question. . Operations that change the database must be carried out through the updating process. But also keep in mind: • If a termination message is displayed (message type A) in the Return parameter..

The customer enhancement concept is not intended for developing individual industry solutions within SAP. a special enhancement concept has been defined for industry solutions. Customer exits implemented using the enhancement concept valid before do not have to be reprogrammed. Conventional customer exits that can be individually implemented. create. because customer enhancements can be automatically used by the BAPI and do not require customers to rewrite any programs. The customer enhancement concept is converted in the BAP interface by standardized extension parameters which can be combined with one or both of the enhancement mechanisms below: • • By the BAPI table extensions developed by BAPI programmers. With this structure the extension parameter can be used as a generic data container. Define the extension parameter as a table parameter.5B. You should create customer exits to enable customers to enhance BAPI interfaces in situations where it was not anticipated enhancements may be needed. Then. Note the following guidelines: • • • The naming convention for the extension parameter is ExtensionIn for import parameter enhancements and ExtensionOut for export parameter enhancements. Customers must not program these extensions. for example. For further information contact the BAPI Development. Customer-defined data can then be read and processed by the BAPI automatically. one extension parameter for the data import and/or one extension parameter for the data export. Extension parameters can relate to BAPI table extensions and/or to customer exits already in the program (see below). Features Extension Parameters in BAPI Interfaces First consider which tables used by the BAPI may be suitable for customer enhancements. BAPI Table Extensions BAPI table extensions and help structures are used to copy data from a customer table extension and to place it in an extension parameter. December 1999 65 . Use the reference structure BAPIPAREX for extension parameters. We recommend you use BAPI table extensions. if possible. and then to reflect these enhancements in the BAPIs of the business object types. The customer concept described here has been introduced in Release 4. depending on the requirements of the BAPI. make table enhancements to master data.SAP AG BAPI Programming Customer Enhancement Concept for BAPIs Customer Enhancement Concept for BAPIs Use The customer enhancement concept for BAPIs enables customers to enhance business object types without modifications.

If the fields inserted by a customer in a BAPI table extension exactly match the fields in the table extended by the customer. The key of the extended table (AGENCYNUM) and the customer-defined data part (CUSTOMER FIELD1 to CUSTOMER FIELD3) are transferred to the data fields VALUEPART1 to VALUEPART4 in the extension parameter. These are the fields with which the customer extended table STRAVELAG. The graphic below shows how extension parameters and BAPI table extensions function together: The BAPI TravelAgency. The name of the active BAPI table extension (here BAPI_TE_STRAVELAG) is inserted in the STRUCTURE field of the ExtensionIn parameter..CreateFromData Parameter: AgencyDataIn AgencyNumber Return ExtensionIn Fields from ExtensionIn: Structure Valuepart1 Valuepart2 Valuepart3 Valuepart4 BAPI Table Extension: BAPI_TE_STRAVELAG Felder AGENCYNUM . cannot have a BAPI table extension that supports a table extension of the business object type Equipment. This consists of: • • A key part predefined by SAP (AGENCYNUM).APPEND CUSTOMER FIELD _1 CUSTOMER FIELD _2 CUSTOMER FIELD _3 Database table: STRAVELAG Key field AGENCYNUM Fields NAME STREET . the Create() BAPI of the business object type Material. As shown by the arrows and color in the graphic. . When creating BAPI table extensions..CreateFromData has a standardized parameter ExtensionIn for extending the import parameter to be read. make sure you: 66 December 1999 . The parameter ExtensionIn relates to the BAPI table extension BAPI_TE_STRAVELAG. to assure that customer data can be processed without errors occurring..BAPI Programming Customer Enhancement Concept for BAPIs SAP AG BAPI table extensions can only refer to tables whose contents belong to the business object type. The key field of the database table STRAVELAG which the BAPI table extension refers to. specific guidelines and naming conventions must be followed for the implementation and when using extension parameters with BAPI table extensions. the BAPI can read or write the data using 'move-corresponding'. CUSTOMER FIELD _3 … … Customer-defined fields are able to be automatically processed because the use of BAPI table extensions are searched for in the ExtensionIn parameter in the BAPI program code. TELEPHONE URL LANGU .APPEND CUSTOMER FIELD _1 CUSTOMER FIELD _2 CUSTOMER FIELD _3 BAPI_TE_ STRAVEL AG Values from CUSTOMER FIELD_1. For example. CUSTOMER FIELD _2.. BAPI: TravelAgency. Data part (CUSTOMER FIELD1 to CUSTOMER FIELD3) determined by the customer in an append technique .

case extensionin-structure. Customers cannot use fields from the standard table in the append of the BAPI table extension because a 'move corresponding' would overwrite the SAP field. The BAPI table extension BAPI_TE_MARA relates to table MARA.CreateFromData shows how the ExtensionIn parameter and the BAPI table extension are used. • Customers can use only fields of data type CHAR and similar data types in BAPI table extensions. The methods are called TravelAgency.CreateFromData() and TravelAgency. endcatch. This restriction is due to the reference structure BAPIPAREX of the extension paramters.GetDetail(). catch system-exceptions conversion_errors = 1. • • Programming examples are provided in the function modules BAPI_TRAVELAGENCY_CREATE and BAPI_TRAVELAGENCY_GETDETAIL.SAP AG BAPI Programming Customer Enhancement Concept for BAPIs • • Create one BAPI table extension for each table to be extended. The BAPI table extension BAPI_TE_MARA has a field MATNR. loop at extensionin. move agencynumber to wa_bapi_te_stravelag-agencynum. A BAPI table extension can have a maximum length of 960 characters. as MATNR is the key field of table MARA. The naming convention for BAPI table extensions is BAPI_TE_<Table name>. December 1999 67 . • The structure of the BAPI table extension must contain the key fields of the table that the BAPI table extension relates to. All available BAPI table extensions must be listed in the documentation on the extension parameter. move-corresponding wa_bapi_te_stravelag to t_stravelag. move extensionin+c_lenstruc to wa_bapi_te_stravelag. when 'BAPI_TE_STRAVELAG'. The extract below from the program code for the BAPI TravelAgency. read table t_stravelag with key agencynum = agencynumber. For further information see the Customer Enhancement Concept [Ext.] in the BAPI User Guide.

Create(). you should insert customer exits in suitable places in the source code of the BAPI. • BAPIs with read function. Note the following: • BAPIs that cause database changes. The standard rules for customer exits apply and maintenance with Transaction SMOD (SAP internal) and CMOD (for customers).g. Change() Create a customer exit that checks all the data and transfers data to internal. A second customer exit must be provided for writing data to customer-defined tables.Enhancing the SAP Standard [Ext. customerdefined structures.] (for Transaction CMOD). For further information see the documentation on SAP Enhancement Management (for Transaction SMOD) and in BC . for example GetDetail() Create a customer exit after the SAP data retrieval to enable customers to then import their own data. 68 December 1999 . e. to enable customers to program their own exits and to include them in the BAPI.BAPI Programming Customer Enhancement Concept for BAPIs SAP AG Customer Exits If BAPI table extensions cannot be used.

MM the month and DD the day. BAPI Programming Interface GUI GUI External data format. YYYYMMDD. except in the circumstances outlined below. they are programming interfaces that can be used in diverse application areas. General Guidelines Fields in BAPI parameters must be presented in the internal form used in the database and not in a form formatted in the BAPI interface. To meet the requirements of this diverse range of applications. Because of the reasons above. For example. a common strategy for representing data in the BAPI interface must be used. BAPIs should not convert data between the internal and external data formats. on the screen (GUI) Application program BAPI Application program Internal data format Exceptions There are exceptions where the calling program has to map and convert the data between the internal and external data formats in a BAPI. for instance.SAP AG BAPI Programming Internal and External Data Formats Internal and External Data Formats Use BAPIs are not end user interfaces. the date in a BAPI must be in the format used internally. where YYYY is the year. to connect non-SAP systems and PC products to the R/3 System. for example. The graphic below shows the BAPI programming interface where data is transferred at the source code level and not at the application interface level. December 1999 69 .

The section Converting Between Internal and External Data Formats [Page 140] describes how to generate these function modules.BAPI Programming BAPI Programming Interface SAP AG For these exceptions you can generate function modules that can map and. The function module BAPI_CURRENCY_CONV_TO_INTERNAL converts currency amounts from external data formats into internal data formats. The position of the decimal point in currency amount fields must be converted correctly You can use two function modules for this conversion. You can use these function modules in the source code of your BAPI for the following: • • • • To map the internal work structures to the external BAPI structures before calling the BAPI To map the result to the internal work structure after the BAPI has been called To map the imported parameters to the internal structures (import parameter structures) when you are implementing the BAPI To map the result from the internal structure to the BAPI (export parameter structures) when you are implementing the BAPI Currency amount fields In an R/3 System a currency amount field can only be used when accompanied by a currency code. Examples are work breakdown structure plans or networks in project systems. 70 December 1999 . For example. A currency code field must be assigned to each currency amount field. if required. even though currencies do exist with three digits after the decimal point. the data type CURR cannot be used in the BAPI interface. convert between the internal and external data formats. • These exceptions are: • − Quantity Fields and Unit of Measurement Fields Like currency amount fields. Non-SAP systems will not understand this syntax. 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 with the data element BAPICURR_D or BAPICUREXT with the data element BAPICUREXT. Only then can the decimal point be set correctly. For these reasons. • Internal keys In some situations an internal technical key is maintained in the database alongside the external key. two yen are stored as 0. All R/3 currency data types have two digits after the decimal point.02 in the field of data type CURR in the database. The function module BAPI_CURRENCY_CONV_TO_EXTERNAL converts currency amounts from R/3 internal data formats into external data formats. Quantity fields have no standard domain that can be used for BAPI structures. the decimal point in quantity fields and unit of measurement fields must be converted correctly. A field to indicate the amount or the unit of measure must be assigned to all amount and quantity fields.

SAP AG BAPI Programming BAPI Programming Interface You must always use the external key in the BAPI interface. 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. UTC is the equivalent of the formerly used term GMT (Greenwich Mean Time) and is now used as the unique time reference across the globe. to convert from the external activity into the internal activity INT_ACTIVITY_GET_EXT_ACTIVITY. The naming convention for the UTC time stamp field is <Field name for time zone>_ISO. Fieldname_for_SAPCode_ISO for the field containing the ISO code. To convert activity codes in networks. You can also specify the local time. country. The corresponding field for the ISO code would then be named LANGU_ISO and would contain the corresponding ISO code EN. and unit of measure fields. For example. as well as a field for the UTC time stamp. When you import data into the BAPI the ISO code is only significant if no value was given in the SAP code. to convert from the internal activity into the external activity. for instance E. Use the domains below for the ISO codes: Domains for SAP internal codes and ISO codes Size Currency key Quantity unit Language key Country key • ISO Code Domain ISOCD ISOCD_UNIT LAISO INTCA SAP Code Domain WAERS MEINS SPRAS LAND1 For every domain there is a data element of the same name. • ISO codes In R/3 Systems ISO codes are currently supported for language. December 1999 71 . Implement the BAPI as follows: − − When you export data from the BAPI both fields must contain corresponding values. These conversion transactions are not included in the transactions described in the section Converting Between Internal and External Data Formats [Page 140]. the field LANGU contains the country codes used internally in R/3. currency. In the BAPI interface you have to provide a field for the time zone. the location of an object with respect to its local time. the following function modules are provided: − − EXT_ACTIVITY_GET_INT_ACTIVITY. that is. Use the naming convention. Dates and Time In accordance with ISO standard 8601 dates an time must be transferred between two external systems in Universal Coordinated Time (UTC).

for example. "van der" (fields PREFIX1 and PREFIX2) Names affixes. for example "von". However.]. to display data on the screen. BAPIs for Converting Between Internal and External Data Formats (Converting Domains) BAPIs are programming interfaces in which. − − • • • • • TIMESTAMP TIMEZONE SAP AG Specific fields in address structures These fields are: Address text (fields TITLE_P. The calling program can use conversion BAPIs to convert data into the required format: These are described in the BAPI User Guide in the section Service BAPIs for General BAPI Functions [Ext. TITLE and FORMOFADDRESS) Academic title (fields TITLE_ACA1 and TITLE_ACA2) Name prefixes.BAPI Programming BAPI Programming Interface The following types are provided for dates and time. with a few exceptions. 72 December 1999 . for example. titles (field TITLE_SPPL) For more information see Address Parameters [Page 123]. application programmers calling a BAPI from within their program may sometimes require the external format. In such cases the calling program must be able to convert between the internal and external data formats. only the internal data format should be used.

BUS1065. matchcodes and domain fixed values see the ABAP Dictionary [Ext. This table comprises the following fields which you have to fill with the values for your BAPI. 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. matchcodes or domain fixed values linked to the field in the ABAP Dictionary. Authorization Check In some cases you will only want to allow only those persons with a specific user profile to access information in F4 input help. an elementary input help could be specified for the data element PERNR_D and be protected from unauthorized access. The BAPI HelpValues.GetList() method refers to the help view for the check table. for example. Information about the possible 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. match codes or domain fixed values. via BAPI calls.SAP AG BAPI Programming Providing Input Help (F4 Help) Providing Input Help (F4 Help) Use Users of R/3 Systems can use the F4 key to retrieve information about the possible input values for screen fields. For information about check tables. for example. For this reason. you have to create or specify relevant check tables. Features In order to provide input help. DTEL (data element) The name of a data element for which a possible entry is specified. For example.GetList().GetList() is available in the documentation for this BAPI. This method is based on the RFC-enabled function module BAPI_HELPVALUES_GET.]. As of Release 4. a calling program can use the BAPI HelpValues. GetList.5A you have to specify a foreign key. which obtains the possible input values for a field that is passed in a BAPI call. December 1999 73 . if a check table has been defined in the domain. METHOD (verb) The name of a BAPI for the business object type named above. Otherwise F4 input help cannot be displayed. Detailed information about the structure and use of the BAPI HelpValues. Only then can the calling program access the relevant input values for your BAPI fields using the BAPI HelpValues.GetList(). To do this you can carry out authorization checks within the BAPI using table BAPIF4T. • • • OBJTYPE (object type) The technical name of the SAP business object type.

. ' ' (no value)...the following fields in table BAPIF4T must be filled. 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..... OBJTYPE. During runtime the function module is called dynamically by the BAPI HelpValues. method or data element level: To carry out authorization check at this level. An authorization check can be carried out at business object type.. The parameter TABNAME contains the name of the value table. FNAM OBJTYPE.. METHOD.BAPI Programming Use • FNAM (name of the function module) SAP AG The name of the function module that you have to create and that carries out the authorization check for the data element. FNAM OBJTYPE. METHOD... 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. Business object type BAPI 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. FNAM 74 December 1999 .GetList(). if the user of the BAPI is authorized to display the input values for a field. DTEL..

via BAPI calls. you have to maintain the short and long error texts for the BAPI. F1 help should also be available to users who are working with data in an R/3 System from an external program. You should follow the standard ABAP programming rules. For internal use SAP provides detailed guidelines on writing BAPI documentation. • BapiService. To support application developers with their work. F1 help provides information on specific input fields.InterfaceGetDocu() This method reads the whole interface documentation for a BAPI. You can use this method to access the documentation on the business object type. • BapiService. for example. To enable application developers to process BAPI error messages.MessageGetDetail() This method returns the short and long texts of BAPI error messages. For example. • BapiService. For information about these BAPIs see the relevant BAPI documentation. method.SAP AG BAPI Programming Providing Interface Descriptions Providing Interface Descriptions Use Descriptive text. Various functions are provided that support R/3 users in carrying out the tasks required of them. Features Service BAPIs are provided that are used by external programs to call documentation and descriptions of BAPI interfaces.FieldHelpGetDocu(). You can get a copy of the guidelines from your contact person in the BAPI Development group. the documentation on BAPI interfaces must be complete. parameters and parameter fields. data element documentation must be written for each parameter field in the BAPI. December 1999 75 . See the general Documentation Guidelines [Page 88].FieldHelpGetDocu() This method reads the documentation (F1 help) for the fields in a BAPI parameter. Application developers can use this method to provide end-users with descriptions of fields in a BAPI parameter. To ensure that F1 help for your BAPI can be called via the method BapiService. short texts and texts on how to write help functions are very useful for using BAPI interfaces.

BAPI Programming Providing Interface Descriptions SAP AG 76 December 1999 .

All changes (to one or more instances) are updated together by the BAPI BapiService. this procedure allows error handling of individual instances. The buffering mechanism enables application instances to be processed separately in the ALE layer. SaveReplicaMultiple(). BAPIs that create and change data). Integration The Transaction Model for BAPIs Without Commit [Page 63] in use since Release 4. With the next change.0 can be enhanced on the basis of these advantages: • • Within one Logical Unit of Work (LUW) several changes or detailed changes can be carried out for one instance. the first change would have to be updated before a second change could be made. • Several changes to an application instance With the first change the data is read from the database into the buffer and the change is made in the buffer. BAPIs with buffering mean that there is no need to use or implement multiple BAPIs. such as. If buffering is not used. Data to be created or changed by a BAPI is not created in the update buffer. predefined buffering mechanisms should be implemented in all write BAPIs (i. Unlike multiple BAPIs. For BAPIs standard R/3 System mechanisms can be used to buffer application data.SAP AG BAPI Programming Buffering with Write BAPIs Buffering with Write BAPIs Use To save external systems each having to define their own data. This has the following advantages: • Improvement in performance of the whole system. it is first collected in the global buffer of the BAPI function module group. Then the whole buffer is updated at a specified time. If buffering is not used. • Using in Application Link Enabling BAPIs with buffering are especially suited in situations where mass data is exchanged between systems via Application Link Enabling (ALE). This graphic shows the transaction model for BAPIs without buffering: December 1999 77 . If you want to implement a buffer for BAPIs in an earlier release.6A. while still enabling the instances to be updated together. Techniques such as "array insert" improve system performance. each change must be updated separately.TransactionCommit().e. For SAP internal use this is particularly relevant for BAPIs developed as of Release 4. The updating of individual operations is delayed and they can all be updated together. the system recognizes that the data already exists in the buffer and also makes the change in the buffer. you should first contact a colleague in the central BAPI development group.

TransactionCommit Create i2 Change i1 BapiService.TransactionCommit Client (e.BAPI Programming Buffering with Write BAPIs SAP AG Transaction Model Without Buffering Create i1 BapiService.g. Visual Basic) Server (R/3) LUW LUW i1 is passed to pdate i2 passed to update Update performed: i1 and i2 are updated separately i1 passed to update Update performed: i1 updated 78 December 1999 .

this affects the read BAPIs of this object type. the following implementation steps and characteristics described below are required. December 1999 79 . the caller must not have to control the buffering. you have to provide one or more function modules to carry out the final update of the buffer contents. If write BAPIs with buffering have been implemented for a business object type. A calling program must be able to use. The buffer is updated implicitly in R/3. in addition to the standard guidelines. These function modules should not be implemented as BAPIs. Refer to the information in the Activities section below.SAP AG BAPI Programming Buffering with Write BAPIs This graphic shows the transaction model for BAPIs with buffering: Transaction Model with Buffering Create i1 Change i1 Create i2 BapiService. as these are only used in the system in which the buffer is also used. Visual Basic) Server (R/3) LUW Instances are created and processed in the buffer Buffer contents passed to update. a Create()or Change() BAPI with buffering as well as it can use a BAPI without buffering. If buffering has been implemented for a business object type. Features For BAPIs with buffering. all write BAPIs of this business object type must also be implemented with buffering. that is.B. These update modules transfer the entire contents of the buffer to the update program. for example.TransactionCommit Client (z. Function Modules for Updating the Contents of the Buffer As BAPIs with buffering can only create or change instances in the buffer. Update is performed: i1 and i2 are updated together Prerequisites The buffering mechanism for BAPIs must be implicit.

The update modules must be called using the command CALL <Business object name>_SAVEBUFFER IN UPDATE TASK to flag the execution in the update program. SAP AG Exceptions must not be defined for the update modules. as these are not run until the end of the program. no action can take place. executes the form routine and also each update 80 December 1999 . The consistency of all instances created or changed in the buffer must be guaranteed by the application. must be carried out before calling the update module. In these cases the error situation must be reported in the BAPI return parameter.BAPI Programming Buffering with Write BAPIs The naming convention for these function modules is: <Business object name>_SAVEBUFFER. except for updating. This delete function module deletes the entire contents of the buffer and removes any locks on the instances.it is carried out in the next COMMIT WORK. By adding 'ON COMMIT' to the command PERFORM <routine> ON COMMIT. these BAPIs must be able to deal with errors because a caller cannot reprocess data in the buffer. All other steps required before updating. Neither should you implement this function module as a BAPI. This means that: • • • Only operations that can be updated with consistency guaranteed can be carried out in the buffer. you must provide a function module that deletes the contents of the buffer. For operations that cannot be updated consistently. using the command PERFORM <routine> ON COMMIT call a form routine <routine> which then calls the update module(s). updating is not carried out immediately. For example. As data is buffered implicitly. This way any number of BAPI calls can be collected together. when error handling is no longer possible (see Special Characteristics below). because it is only used in the system in which the buffer is also used. Consistency of the Buffer Contents A BAPI with buffering must carry out all the processing steps. Special Characteristics BAPIs with buffering need to have special characteristics. Function Modules for Deleting the Contents of the Buffer To ensure that the buffer is empty at the start of a transaction. such as assigning numbers or creating application blocks.TransactionCommit(). Calling Update Modules After the buffer operations have been successfully carried out. No exceptions can be defined for delete modules because these are not run until the end of the transaction. no administration BAPIs are provided for callers. when error handling is no longer possible (see Special Characteristics below). The final COMMIT WORK command that is executed via the BAPI BapiService. The naming convention for this function module is: <Business object name>_CLEARBUFFER. The update module itself cannot perform consistency checks.

Read BAPIs must be implemented in such a way that they first try to read an instance in the buffer and only start searching the database. December 1999 81 . To supply these BAPIs with the necesary information. To guarantee the consistent behavior. Subsequent read operations would first access the buffer and read the potentially outof-date data. Subscribing the Delete Module At the start of each LUW the buffer must be empty. thereby avoiding further database accesses. BapiService. read BAPIs are not allowed to use the buffer for the same business object type. At the end of each LUW. Activities Keep in mind the following important information about how write BAPIs with buffering interact with read BAPIs of the same business object. Documentation Each BAPI with buffering must be explicitly documented as such. so that data read from the database can be stored. which were updated in an earlier LUW. if the instance is not found in the buffer.SAP AG BAPI Programming Buffering with Write BAPIs module once only. are no longer blocked and may be older than the versions in the database. the corresponding data in the buffer would become outdated over time. all read BAPIs must handle existing instances that are in the buffer. as valid instances. if this data is not in the buffer. inconsistencies would result. For example. As the imported data is not locked.TransactionRollback(). as data in the database can only be read. Write BAPIs with Buffering and Read BAPIs for the Same Business Object No Buffering for Read BAPIs If write BAPIs with buffering are implemented for the same business object type. the buffer contents must be deleted by calling the delete module. This can only be done by the BAPIs BapiService. No COMMIT WORK or ROLLBACK WORK Command BAPIs with buffering must not execute COMMIT WORK or ROLLBACK WORK commands. and not yet in the database. They can be used by other change BAPIs for further processing within the same LUW.TransactionRollback(). The delete module is subscribed by calling the central function module BUFFER_SUBSCRIBE_FOR_REFRESH. Buffer Instances Are "Real" Instances All instances created or changed by write BAPIs in the buffer are consistent. Any instances that may exist in the buffer. whereby the parameter NAME_OF_DELETEFUNC must contain the name of the delete module. BAPIs with buffering must subscribe thier delete module for the BAPI BapiService. If this instance is updated again.TransactionCommit() bzw. A buffer instance is therefore "real" instance.TransactionCommit() and BapiService. a BAPI ExistenceCheck() must search for the existience of an instance in the buffer also. For this reason error handling cannot be performed in this form routine nor in the function module.

BAPI Programming SAP AG Documenting Read BAPIs Each read BAPI that handles the buffering of corresponding write methods must be documented. 82 December 1999 .

• Function module for the Create() BAPI function bapi_<object>_create. {Update buffer} . in particular Create() and Change() BAPIs.. {Read buffer} {Update buffer} . ... the following routines or function modules are created. In the BAPI function group <object>. {Operations in buffer} perform <buffersave> on commit.SAP AG BAPI Programming Example of Implementation and Process Flow Example of Implementation and Process Flow The example below describes the implementation and process flow of BAPIs with buffering. endfunction. . A more detailed example is the BOR is the BAPI CreateFromData() of business object type TravelAgency (SAGENCY.. • Form routine for the update form <buffersave>.. • Function module for the Change() BAPI December 1999 83 . endfunction. endfunction. Implementation For the business object <object>. BAPIs with buffering should be provided. • Update module function <object>_savebuffer. call buffer_subscribe_for_refresh exporting name_of_deletefunc = <object>_clearbuffer. call <object>_savebuffer in update task. belonging to the business object. • Delete module function <object>_clearbuffer. endform.... The development class is SAPBC_BOR.

it is not subscribed again. it is not subscribed again. Instance 4711 exists in the buffer. Then another change is made to instance 4711 using the BAPI Change().BAPI Programming Example of Implementation and Process Flow function bapi_<object>_change. call buffer_subscribe_for_refresh exporting name_of_deletefunc = <object>_clearbuffer. endfunction. Instance 4711 is created in the buffer. SAP AG Process Flow An external application executes the BAPI Create() of business object <object> twice. {Operations in buffer} perform <buffersave> on commit. The call of the update module is <object>_savebuffer is flagged using the form routine <buffersave>.TransactionCommit(). Call meth od <obje ct.TransactionCommit().TransactionCommit(). The delete module <object>_clearbuffer is subscribed by calling the buffer buffer_subscribe_for_refresh for BAPI BapiService. The delete module <object>_clearbuffer is subscribed by calling the buffer_subscribe_for_refresh for BAPI BapiService.TransactionCommit() is executed. the BAPI BapiService. The steps are: Step 1. Instance 4712 does not yet exist in the buffer. Call meth od <obje ct>.C reate( ) for insta nce 4712 3. it is changed here. 84 December 1999 . it is created here. The buffer is empty. it is not flagged again. The call of the update module is <object>_savebuffer is flagged using the form routine <buffersave>. As this is already subscribed. As this is already subscribed. To complete the LUW.> Chan ge() for insta nce 4711 Process Flow The delete module <object>_clearbuffer is subscribed by calling buffer_subscribe_for_refresh for the BAPI BapiService. As this is already flagged.C reate( ) for insta nce 4711 2. Call meth od <obje ct>. to create the two instances 4711 and 4712.

SAP AG BAPI Programming Example of Implementation and Process Flow The call of the update module is <object>_savebuffer is flagged using the form routine <buffersave>. December 1999 85 . 4. that is.TransactionCommit() are called. it is not flagged again. After the COMMIT WORK command. Call meth od Bapi Servi ce.Tr ansa ction Com mit() The form routine <buffersave> of the function group <object> is executed once only by the COMMIT WORK command. This executes the update module and the contents of the buffer is transferred to the update program. As this is already flagged. the function module <object>_clearbuffer is executed and the buffer for the business object <object> is emptied. the delete modules subscribed for the BAPI BapiService.

Alternatively your BAPI could return a message to the calling program indicating that the amount of data has exceeded a certain limit and that a new selection should be made. This increases the load on the network and the amount of memory required in the client system. If large amounts of data are read in the R/3 System. you should follow the standard ABAP programming guidelines: • • • • • • Use only complete WHERE conditions to minimize the amount of data to be transferred. for example in the local memory of the function module. Do not generate programs at runtime. the majority of the data remains on the application server. • • • Do not define parallel processes. for example a list containing many entries. you could specify a limit so that only the first n data records are read. • 86 December 1999 . The locking granularity must correspond to the instance granularity in the object model. Lock periods can be minimized by making database updates as close as possible to the COMMIT WORK command. Instead make use of the buffers. See the internal SAPnet for further notes about effective programming in the R/3 environment. Avoid unnecessary database access. all the data will be sent from the application server to the client system.BAPI Programming Improving Performance SAP AG Improving Performance Use In order to improve the performance of your BAPI. Do use of arrays. you should not assign numbers to them individually. You need to cover the situation when your BAPI has to read mass data. If no COMMIT WORK is triggered after a BAPI is called. For example. Only the data that is actually displayed is sent to the front end. For this reason. Buffer data. if you are programming with Visual Basic. Additional Guidelines for BAPI Programming The function module on which a BAPI is based can be accessed by external programs using RFC. and in programs developed on external development platforms such as Visual Basic. Note that you must not buffer data in the global memory. you should follow these additional guidelines when programming BAPIs: • Large amounts of data Mass data is treated differently in ABAP programs. To reduce the duration of database locks. which use the SAPgui (graphical user interface) as a front end. Read the numbers to a buffer and assign the numbers directly from the buffer. In contrast. This reduces the duration of database locks and the risk of blocking other processes. a lock that has been set has to be explicitly deleted.

running a statistic on plant level will have a negative impact on the performance of the BAPI. These read transactions have to wait for the COMMIT WORK command of the update transaction to be processed. For example. Minimize the use of read transactions which depend on a previous database COMMIT (committed read). • • December 1999 87 . whereas a statistic based on plant and material will cause fewer locks because it will apply to fewer BAPIs. All tables that are not protected by SAP internal locks must always be updated in the same order to prevent a deadlock.SAP AG BAPI Programming Improving Performance • The less specific the (partial) 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.

you must include this in the documentation. This section contains general guidelines for documenting BAPIs. that is what are the parameters and fields of the BAPI interface. The purpose of this documentation is to explain what the method does and how the communication with external programs works. SAP provides detailed guidelines on writing BAPI documentation. Prerequisites BAPIs are business interfaces to the R/3 System and users are not required to have a thorough knowledge of the R/3 System and the R/3 development environment. 88 December 1999 . is special authorization required to use this BAPI? Are there any Customizing dependencies? What dependencies are there between this BAPI and other BAPIs. How the BAPI is called. Application developers access the technical meta data and documentation of BAPIs from the Business Object Repository. functions that this BAPI cannot perform? What must you pay particular attention to with this BAPI? For example. For internal use. and between individual method parameters? If the BAPI uses a COMMIT WORK command or works with buffering. the following documentation must be provided: Documentation on Methods Create this documentation in the Function Builder in the function module that the BAPI is based on. Readers of BAPI documentation are often not R/3 experts or business application experts. they need to know what the BAPI can do. that is. Process Flow To give application developers a complete picture of the functionality of a BAPI. You can get a copy of the guidelines from your contact person in the BAPI Development group. The documentation should help customers decide whether a method is appropriate to perform the task in question and it should therefore provide answers to the following questions: • • • • • • What is the business function of the BAPI and what can it be used for? What exactly are the functions of the BAPI? Are there any important limitations.BAPI Programming Documentation Guidelines SAP AG Documentation Guidelines Purpose To use a BAPI in an application program. that is. application developers need to know: • • Which BAPI provides the required data.

that is. December 1999 89 .FieldHelpGetDocu (see Providing Input Help [Page 73]).SAP AG BAPI Programming Documentation Guidelines Documentation on Method Parameters Documentation on the individual parameters is also written in the Function Builder in the associated function module. must be documented. Which return codes may be returned to the calling program directly or indirectly in the Return parameter? Data Element Documentation on Parameter Fields A calling program can call data element documentation (F1 help) for a field in a BAPI parameter using the Service BAPI BapiService. Parameter documentation should provide answers to the following questions: • • • • • • What is the parameter used for? Which fields must be filled. the information below must also be available: • • Documentation on the business object type the BAPI is implemented for. For this reason you have to write data element documentation for each field in BAPI parameters. what are the mandatory fields? What are the dependencies between fields? Are there any fixed values and what do they do? What are the default values of the parameter? All the fields that are assigned default values by Customizing and are therefore write-protected. Documentation on the key fields of the business object type. Further Documentation To provide the complete context of a BAPI.

90 December 1999 .BAPI Programming Programming Standardized BAPIs SAP AG Programming Standardized BAPIs Purpose Some BAPIs and methods provide basic functions and can be used for most SAP business object types. you should implement it following the programming guidelines described in the following sections. These BAPIs are called “standardized” BAPIs. Process Flow If your BAPI is a standardized BAPI.

To report messages from the method call back to the calling program. together with other useful information. Extension parameters You can create extension parameters to enable customers to enhance the functionality of BAPIs without making modifications. For more information about this parameter see Return Parameters (Error Handling) [Page 130]. Import Parameters The interface of a GetList() BAPI must provide selection parameters. Export Parameters The key values selected by the BAPI GetList() are returned to the calling program in a table. Use the data element BAPIMAXROW as the reference type for the MaxRows parameter. for example. the BAPI GetDetail(). How complex and extensive you structure the interface. for example. For information about extension parameters see Customer Enhancement Concept for BAPIs [Page 65]. company codes and material numbers. The BAPIs GetList() is a class method (instance-independent). The key values returned by this BAPI can be passed on to another BAPI for further processing. This parameter prevents too large a value set from being selected. short texts. in which the required selection criteria can be passed on by the calling program. Features Provide all the relevant fields in the interface of the GetList() BAPI. You must also create the parameter MaxRows that enabes you to limit the number of entries selected. if the selection parameter specification is not very precise. The structure of selection parameters is described in the section Selection Parameters [Page 134]. depends on the requirements the BAPI is to fulfill. you should create the export parameter RETURN. December 1999 91 . for example.SAP AG BAPI Programming Programming GetList() BAPIs Programming GetList() BAPIs Use With the BAPI GetList() you can select a range of object key values.

The graphic below shows this BAPI in the BAPI Browser. 92 December 1999 .BAPI Programming Example of a GetList() BAPI SAP AG Example of a GetList() BAPI The BAPI GetList of the business object type CostCenter (BUS0012) is used here as an example.

Extension Parameters You can create extension parameters to enable customers to enhance the functionality of BAPIs without making modifications. For the associated method definition in the BOR. To report messages from the method call back to the calling program. you should create the export parameter Return. the key fields must not also be specified as method parameters. December 1999 93 . the BOR/BAPI Wizard does not include the function module parameters for the key fields in the method definition. Features Import Parameters The import parameters of the GetDetail() BAPI must contain the key fields of the business object type. For information about extension parameters see Customer Enhancement Concept for BAPIs [Page 65]. According to the amount of information. For more information about this parameter see Return Parameters (Error Handling) [Page 130]. The BAPI GetDetail() is an instance method.SAP AG BAPI Programming Programming GetDetail() BAPIs Programming GetDetail() BAPIs Use The BAPI GetDetail() is used to read details of specific object instances. For this reason. this should be structured in several parameters with meaningful names. Export Parameters The export parameters of a BAPI contain details of the instance. when it creates a BAPI.

94 December 1999 .BAPI Programming Example of a GetDetail() BAPI SAP AG Example of a GetDetail() BAPI The BAPI GetDetail() of the business object type CompanyCode (BUS0002) is used here as an example. The graphic below shows this BAPI in the BAPI Browser.

SAP AG BAPI Programming Example of a GetDetail() BAPI December 1999 95 .

Export Parameters The export parameters of the BAPI contain information about the status of an object instance. Features Import Parameters The import parameters of the GetStatus() BAPI must contain the key fields of the business object type. Extension Parameters You can create extension parameters to enable customers to enhance the functionality of BAPIs without making modifications. you should create the export parameter RETURN. The BAPI GetStatus() is an instance method. when it creates a BAPI. For the associated method definition in the BOR. For more information about this parameter see Return Parameters (Error Handling) [Page 130]. the BOR/BAPI Wizard does not include the function module parameters for the key fields in the method definition. the key fields must not also be specified as parameters.BAPI Programming Programming GetStatus() BAPIs SAP AG Programming GetStatus() BAPIs Use With the BAPI GetStatus() you can retrieve information about the status of a particular object instance. For information about extension parameters see Customer Enhancement Concept for BAPIs [Page 65]. 96 December 1999 . To report messages from the method call back to the calling program. For this reason.

SAP AG BAPI Programming Example of a GetStatus() BAPI Example of a GetStatus() BAPI The BAPI GetStatus() of the business object type DebtorCreditAccount (BUS1010) is used here as an example. December 1999 97 . The graphic below shows this BAPI in the BAPI Browser.

you should reduce the number of columns to as few as possible before selecting the table rows. We recommend therefore. you can create an ExistenceCheck() BAPI using the BOR/BAPI Wizard. that you redefine the existing method ExistenceCheck() manually in the BOR. Export Parameters To report messages from the method call back to the calling program. it inherits a definition of the method ExistenceCheck() through the interface IFSAP. • Enter the function module that implements the ExistenceCheck() BAPI. you should create only the export parameter Return . For more information about this parameter see Return Parameters (Error Handling) [Page 130]. because an ExistenceCheck() BAPI can also be used by SAP Business Workflow. Import Parameters The BAPI’s import parameters in the function module only contain the key fields of the business object type. select single bukrs from bkpf into lv_bukrs where bukrs = bkpf-bukrs and and instead of select single * from bkpf where bukrs = bkpf-bukrs and and belnr = bkpf-belnr gjahr = bkpf-gjahr. For this reason. The ExistenceCheck() BAPI is an instance method. Activities When a business object type is created. Features You can implement this method as a BAPI and/or as a method of SAP Business Workflow. whether the customer master has been created. If you implement this method as a BAPI. via the menu path Edit → Redefine. as the default. as the method name ExistenceCheck() already exists for the business object type. belnr = bkpf-belnr gjahr = bkpf-gjahr. To get the highest possible performance from the BAPI ExistenceCheck(). for example.BAPI Programming Programming ExistenceCheck() BAPIs SAP AG Programming ExistenceCheck() BAPIs Use The BAPI ExistenceCheck() checks whether an entry exists in the database for an SAP business object type. it only has to be implemented once. 98 December 1999 .

SAP AG BAPI Programming Programming ExistenceCheck() BAPIs • Create the method parameter RETURN (the key fields of the business object type are not included in the method definition in the BOR). December 1999 99 .

The graphic below shows this BAPI in the BAPI Browser.BAPI Programming Example of an ExistenceCheck() BAPI SAP AG Example of an ExistenceCheck() BAPI The BAPI ExistenceCheck() of the business object type CompanyCode (BUS0002) is used here as an example. 100 December 1999 .

SAP AG BAPI Programming Example of an ExistenceCheck() BAPI December 1999 101 .

the BAPI CreateMultiple() creates several instances of a business object type simultaneously. The BAPIs Create() and CreateMultiple() are class methods (instance-independent). For each Create() BAPI a method must be provided with which the created business object instance can be deleted or cancelled. Export Parameters To make the object key available to the calling program. If required. To report messages from the method call back to the calling program. We recommend that you identify the change-relevant fields by flagging them. 102 December 1999 . you should implement one of the BAPIs below: • • Delete(). you can use the name CreateFromData() for your BAPI. For further information see Test Run Parameters [Page 135]. depending on the business application practice. If a workflow method called Create already exists for the business object type in question. Likewise. the entire key fields must be returned in the export parameters. For more information see Programming Delete() BAPIs [Page 110]. To do this. For information about extension parameters see Customer Enhancement Concept for BAPIs [Page 65]. which deletes a business object instance from the database. Features Import Parameters The BAPI’s import parameters in the function module contain the data required to uniquely identify an instance. you should create the export parameter RETURN. Create() is the preferred name for this BAPI. For more information see Programming Cancel() BAPIs [Page 113]. For more information see Change Parameters [Page 125]. You can create a change parameter to identify the values to create the instance with and to tell differentiate these values from the initial values when the BAPI is called. For more information about this parameter see Return Parameters (Error Handling) [Page 130].BAPI Programming Programming Create() BAPIs SAP AG Programming Create() BAPIs Use The BAPI Create() creates one instance of an SAP business object type. you can also use a test run parameter to check the entry for an object instance before actually creating the instance in the database. For this you can either enter all object keys or else you must ensure that these can be derived. Extension parameters You can create extension parameters to enable customers to enhance the functionality of BAPIs without making modifications. Cancel() which cancels a business object instance.

to a document number. If the Customizing settings write-protect a field. must be documented. For every incidence of incompatibility an error message must be returned to the calling program. All the fields that are assigned default values by Customizing and are therefore writeprotected. Locking We recommend that you implement Create() BAPIs without the locking function and create your own BAPIs instead that lock the relevant data. Otherwise keys are created that cannot be used in dialog applications. for example. • • External Key Assignment For Create() BAPIs with an external key assignment the caller transfers the key (ID) to the object instance to be created. December 1999 103 . you should implement a Create() BAPI in the following way: • The BAPI should transfer all the fields and check them against the Customizing settings. These values cannot be overwritten by a Create() BAPI. Keep in mind that you have to convert the specified keys explicitly in upper case letters in the source code of this type of Create() BAPIs. This is because with dialog applications external keys are always converted implicitly in upper case letters. “Customizing settings do not allow the field 'MyAsset-AssetName' to be modified ”. the data in this field cannot be overwritten by data in the BAPI interface. To avoid any incompatibility with Customizing settings. For example.SAP AG BAPI Programming Programming Create() BAPIs Avoiding Incompatibilities with Customizing Settings It could be possible that certain values set by Customizing appear differently in the BAPI interface.

BAPI Programming Example of a Create() BAPI

SAP AG

Example of a Create() BAPI
The BAPI Create() of the business object type InternalOrder (BUS20745) is used here as an example. The graphic below shows this BAPI in the BAPI Browser.

104

December 1999

SAP AG

BAPI Programming Example of a Create() BAPI

December 1999

105

BAPI Programming Programming Change() BAPIs

SAP AG

Programming Change() BAPIs
Use
The BAPI Change() changes an existing instance of an SAP business object type, for example, a sales order. The BAPI Change() is an instance method, whereas the BAPI ChangeMultiple() is a class method (instance-independent).

Features
Import Parameters
The import parameters of the Change() BAPI must contain the key fields of the business object type. If required, you can create also create these parameters: • • A test run parameter for checking the entry for an object instance before actually creating/changing the instance in the database. A change parameter to identify parameter fields containing modified values and parameter fields that have not been modified.

For more information about these parameters see Standardized Parameters [Page 29].

Export Parameters
To make the object key available to the calling program, the entire key fields must be returned in the export parameters. To report messages from the method call back to the calling program, you should create the export parameter RETURN. For more information about this parameter see Return Parameters (Error Handling) [Page 130].

Extension parameters
You can create extension parameters to enable customers to enhance the functionality of BAPIs without making modifications. For information about extension parameters see Customer Enhancement Concept for BAPIs [Page 65].

Avoiding Incompatibilities with Customizing Settings
It could be possible that certain values set by Customizing appear differently in the BAPI interface. These values cannot be overwritten by a Change() BAPI. To avoid incompatibility with Customizing settings, you should implement a Change() BAPI in the following way: • The BAPI should transfer all the fields and check them against the Customizing settings. If the Customizing settings write-protect a field, the data in this field cannot be overwritten by data in the BAPI interface. For every incidence of incompatibility an error message must be returned in the return parameter to the calling program. For example, “Customizing settings do not allow the field 'MyAsset-AssetName' to be modified ”.

106

December 1999

SAP AG BAPI Programming Programming Change() BAPIs • All the fields that are assigned default values by Customizing and are therefore writeprotected. Locking We recommend that you implement Change() BAPIs without the locking function and create your own BAPIs instead that lock the relevant data. must be documented. December 1999 107 .

108 December 1999 .BAPI Programming Example of a Change () BAPI SAP AG Example of a Change () BAPI The BAPI Change of the business object type PurchaseRequisition (BUS2105) is used here as an example. The graphic below shows this BAPI in the BAPI Browser.

SAP AG BAPI Programming Example of a Change () BAPI December 1999 109 .

Implement the interface of a Delete() BAPI so that it is not possible to delete all the instances simply by parameterizing the interface. Features The interfaces of the Delete() and Undelete() BAPIs should be identical. that is the instance to be cancelled remains in the database and an additional instance is created that is canceled. 110 December 1999 . Import Parameters The BAPI's import parameters have to identify the business object instances to be deleted. Likewise. • • If an instance is to be deleted. If required. A delete() BAPI can delete immediately or at a later time by setting the deletion flag. When the BAPI DeleteMultiple() is used. you have to create a parameter for each key field in the business object type. The type of deletion you use in your BAPI is irrelevant to the caller.BAPI Programming Programming Delete() BAPIs SAP AG Programming Delete() BAPIs Use The BAPI Delete() deletes an instance of an SAP business object type from the database. so you do not have to include these details in the BAPI interface. Delete() BAPIs must always delete entire instances. For more information see Programming Cancel() BAPIs [Page 113]). To do this you can create selection parameters. for example. The BAPI Undelete() is used to reset a deletion flag that has been set for a specific object. A test run parameter for checking the entry for an object instance before actually deleting the instance from the database. If several instances are to be deleted. You can do this using a range table. a whole material master. For more information about this parameter see Return Parameters (Error Handling) [Page 130]. you must create a table for the key fields of the business object type. the BAPI DeleteMultiple() deletes several instances of a business object type. The BAPIs Delete() and Undelete() are instance methods. it must be possible to use the selection criteria to select the object instances to be deleted. for example by specifying default settings. Export Parameters To report messages from the method call back to the calling program. (Whereas the BAPI Cancel() cancels an instance of a business object. you should create only the export parameter Return . whereas the BAPIs DeleteMutliple() and UndeleteMutliple() are class methods (instance-independent). you can create also create these parameters: • • For more information about these parameters see Standardized Parameters [Page 29].

For information about extension parameters see Customer Enhancement Concept for BAPIs [Page 65]. December 1999 111 .SAP AG BAPI Programming Programming Delete() BAPIs Extension parameters You can create extension parameters to enable customers to enhance the functionality of BAPIs without making modifications. Locking We recommend that you implement Delete() BAPIs without the locking function and create your own BAPIs instead that lock the relevant data.

The graphic below shows this BAPI in the BAPI Browser.BAPI Programming Example of a Delete() BAPI SAP AG Example of a Delete() BAPI The BAPI Delete() of the business object type EmployeeTrip (BUS2089) is used here as an example. 112 December 1999 .

SAP AG BAPI Programming Programming Cancel() BAPIs Programming Cancel() BAPIs Use The Cancel() BAPI cancels one instance of a business object. which can check the details of the object instance before it is actually canceled. December 1999 113 . which deletes an object instance from the database. the name of the user performing the cancellation. with the BAPI Cancel(): • • The canceled instance of the business object is not deleted An additional instance is created with which the instance of the business object is deleted The Cancel() BAPI is used to cancel business processes such as goods movements or invoice receipts. Locking We recommend that you implement Cancel() BAPIs without the locking function and create your own BAPIs instead that lock the relevant data. Features Import Parameters The data of the instance to be created comes from the data of the business object instance to be cancelled. The Cancel() BAPI is an instance method. Unlike the BAPI Delete() [Page 110]. For more information about this parameter see Test Run Parameters [Page 135]. You can also create further parameters to specify information relevant for the actual cancellation process. For more information about this parameter see Return Parameters (Error Handling) [Page 130]. You have to put the key of the created instance in another export parameter. Export Parameters To report messages from the method call back to the calling program. you can also create a test run parameter. you should create the parameter Return. If required. for example.

BAPI Programming Example of a Cancel() BAPI SAP AG Example of a Cancel() BAPI The BAPI Cancel() of the business object type GoodsMovement (BUS2017) is used here as an example. The graphic below shows this BAPI in the BAPI Browser. 114 December 1999 .

SaveReplica() and SaveReplicaMultiple(). Loop via the receiver and call the relevant SaveReplica() BAPI. Both of the above replication methods can be implemented with the BAPIs Replicate(). For this reason replicate BAPIs must be implemented for each business object. The replicated instances are usually created under the same object key. for example. You can also restrict the number of receivers in the parameter Recipients of the Replicate() BAPI. Business objects instances can be replicated in two ways: • By request ("Pull") System "A" requests replicates from system "B". 2. Then system "B" replicates the requested business object instances on system "A". Features Replicate() The BAPI Replicate() is called in the system which contains the originals of the business object instances to be replicated. 3. if you want to exchange data between two distributed systems in the context of Application Link Enabling (ALE). The interface of these BAPIs depends on the characteristics and contents of the business object that is to be replicated. You must follow the steps below: 1. At regular intervals system "B" replicates the business object instances to all the systems in the list. This is done in the ALE distribution model using the function module ALE_SYNC_BAPI_GET_RECEIVER. For information on this function module see Distribution Using BAPIs [Ext. The actual replication is carried out when the server system calls one of the SaveReplica() BAPIs described below on the client system. December 1999 115 .SAP AG BAPI Programming Programming Replicate()/SaveReplica() BAPIs Programming Replicate()/SaveReplica() BAPIs Use To replicate an instance of a business object. The BAPI Replicate() is used for: • • Identifying the business object instances to be replicated and to organize the required data Calling the SaveReplica() methods in the receiving system The BAPI Replicate() can only request the replication of instances of a business object.] in the ALE Programming Guide. These BAPIs are both class methods (instanceindependent). Determine the receiver. • Using subscription lists ("Push") In this approach system "B" maintains a list of systems requiring replicates. you have to implement certain standardized BAPIs (see also Using BAPIs in Distributed Systems (ALE) [Page 164]. Select the data to be replicated. The objective of replicating business object types is to make specific instances of an object type available on one or more additional systems.

to specify the data range of the instances to be replicated (for example. material with or without plant data). • Other BAPI-specific import parameters. 116 December 1999 . the receiver is determined using the ALE distribution model. • Parameter Recipients This parameter identifies the logical systems in which the business object instances are to be replicated. if change management is accessed by the receiver.BAPI Programming Programming Replicate()/SaveReplica() BAPIs 4. using a range table for the key fields of the business object types or using selection parameters that enable you to select instances to be replicated. You could implement these. SAP AG Import Parameters The interface of the Replicate() BAPI must contain the following parameters: • Parameters which identify the business object instances to be replicated. Documentation on this parameter must refer explicitly to this connectivity. If this parameter is set to “initial”. The interface of the Replicate() BAPI may also contain the following import parameters: • Parameter RequestChanges This parameter enables modifications of object instances already replicated to be copied directly from engineering change management and forwarded to the receiving system. You should only use this parameter if the business object type in question provides engineering change management. For more information about this parameter see Return Parameters (Error Handling) [Page 130]. This can have the following values: − ' ' (no value) No value is the standard setting and means that engineering change management will not be accessed. for example. (See also Selection Parameters [Page 134]). • Extension parameters You can create extension parameters to enable customers to enhance the functionality of BAPIs without making modifications. For information about extension parameters see Customer Enhancement Concept for BAPIs [Page 65]. − 'X' This value means that the modified data is replicated directly from engineering change management. for example. This parameter must not be used together with the Recipients parameter. Enter a value in the return parameter and complete the Replicate() BAPI. Other receivers may then not be allowed access. A table with information on the object instances to be replicated. because the change pointers in change management are reset. Export Parameters The BAPI Replicate() should contain the following export parameters: • The Return parameter in which messages from the method call are returned to the calling program. This parameter is based on the data element BAPILOGSYS. Structure this parameter on the data element .

For technical reasons these objects may be created with different objects keys (object IDs). Locking We recommend that you implement SaveReplica() BAPIs without the locking function and create your own BAPIs instead that lock the relevant data. Export Parameters To return messages from the method call to the calling program. Extension parameters You can create extension parameters to enable customers to enhance the functionality of BAPIs without making modifications. they must. you should only create the parameter Return for these BAPIs. Import Parameters For the BAPI. If only parts of objects are to be replicated rather than whole objects.SAP AG BAPI Programming Programming Replicate()/SaveReplica() BAPIs Locking We recommend that you implement Replicate() BAPIs without the locking function and create your own BAPIs instead that lock the relevant data. If instances that have already been replicated are to be changed when a SaveReplica() or SaveReplicaMultiple() BAPI is called. receive new values) and the fields that are to remain the same must be identified. For the SaveReplicaMultiple() BAPI. as described in Change Parameters [Page 125]. The BAPI SaveReplica() is used by a system to replicate one business object instance on a target system or to modify one business object that has already been replicated. All the object keys may be provided. all the data required for replicating an individual business object instance must be provided in the import parameters. December 1999 117 . They are used to replicate objects in different systems that are semantically identical. For each business object type to be replicated you have to implement one or both of these methods. you can use other optional import parameters. For information about extension parameters see Customer Enhancement Concept for BAPIs [Page 65]. however be able to be derived. For more information about this parameter see Return Parameters (Error Handling) [Page 130]. the fields that are to be changed (that is. according to your requirements. Whilst the SaveReplicaMultiple() BAPI can replicate several business object instances on the target system or modify several instances that have already been replicated. You can do this by flagging the fields. SaveReplica() and SaveReplicaMultiple() The class method SaveReplica() and the method SaveReplicaMultiple() generate replicates of business object instances. all the relevant data for replicating several instances must be provided in the import parameters.

The graphic below shows this BAPI in the BAPI Browser.BAPI Programming Example of a SaveReplica() BAPI SAP AG Example of a SaveReplica() BAPI The BAPI SaveReplica() of the business object type InternalOrder (BUS2075) is used here as an example. 118 December 1999 .

SAP AG BAPI Programming Example of a SaveReplica() BAPI December 1999 119 .

To make the object key available to the calling program. If required. For more information about this parameter see Return Parameters (Error Handling) [Page 130]. purchase order. Export Parameters You should only create the export parameter RETURN in the BAPI Remove<Name of subobject> to return messages from the method call to the calling program. Features Import Parameters Both BAPIs’ import parameters must contain in the function module the data that uniquely identifies the sub-object as well as the key fields of the business object. you can implement the following standardized BAPIs to add or remove sub-objects: • • Add<name of sub-object> This method adds a sub-object to an object type. Remove<name of sub-object> This method removes a sub-object from an object. you can create also create these parameters: • • A test run parameter for checking the entry for an object instance before actually creating the instance in the database. the BAPIs AddItem() and RemoveItem() could be implemented for the object type. 120 December 1999 .BAPI Programming Programming Methods for Sub-Objects SAP AG Programming Methods for Sub-Objects Use If a business object type consists of sub-objects. A change parameter to identify parameter fields containing modified values and parameter fields that have not been modified. to add or remove the sub-object purchase order item to the business object type purchase order. Extension parameters You can create extension parameters to enable customers to enhance the functionality of BAPIs without making modifications. The BAPIs Add<Name of sub-object> and Remove<Name of sib-objects> are instance methods. For example. For information about extension parameters see Customer Enhancement Concept for BAPIs [Page 65]. the key fields of the object type must also be returned in the export parameters of the BAPI Add<Name of sub-object> as well as in the export parameter Return. For more information about these parameters see Standardized Parameters [Page 29].

SAP AG BAPI Programming Programming Methods for Sub-Objects Locking We recommend that you implement methods of sub-objects without the locking function and create your own BAPIs instead that lock the relevant data. December 1999 121 .

They should be implemented the same in all BAPIs.BAPI Programming Programming Standardized Parameters SAP AG Programming Standardized Parameters Purpose There are some parameters that can be created for various BAPIs because they contain the same or equivalent data in all BAPIs. 122 December 1999 . Process Flow If your BAPI is a standardized BAPI. you should implement it following the programming guidelines described in the following sections. Such parameters are known as “standardized” parameters.

Use one of the following structures as a copy reference for addresses in BAPIs: Reference Structure BAPIADDR1 BAPIADDR2 BAPIADDR3 BAPIADDR1X BAPIADDR2X BAPIADDR1X Use Addresses of companies and organizations Addresses of individuals Addresses of contact persons within an organization Change reference structures for addresses of companies and organizations Change reference structures for addresses of individuals Change reference structures for contact persons within an organization Keep in mind the following points when you use these reference structures: • All the fields of the reference structures refer to the central address management (CAM). If the CAM is already included. CHAR 20 or CHAR 39) are included as fields in these structures. • Function Module ADDR_CONVERT_FROM_BAPIADDR1 ADDR_CONVERT_TO_BAPIADDR1 ADDR_CONVERT_FROM_BAPIADDR2 Description Converts the fields in the structure from the external format into the internal format. for example. Only use fields that can also be processed in your application context. In these cases you can use the function modules below which enter values in these structures or accept changes made to the structures and then assign the correct keys internally. then all the fields are relevant. TITLE and FORMOFADDRESS) Academic title (fields TITLE_ACA1 and TITLE_ACA2) Name prefixes. for example "von". titles (field TITLE_SPPL) You cannot expect in these cases that a calling program converts the internal database keys into the external readable form and vice versa. for some coded name parts the text formats (for example. Converts the fields in the structure from the external format into the internal format. especially if the underlying object type uses the central address management (CAM).SAP AG BAPI Programming Address Parameters Address Parameters Use Specific reference structures are defined for address parameters in BAPIs. Converts the fields in the structure from the internal format into the external format. You should copy these structures to use in your BAPI. Contrary to the standard guidelines (compare with Internal and External Data Formats [Page 69]). These fields are: − − − − Address text (fields TITLE_P. rather than the internal database keys. "van der" (fields PREFIX1 and PREFIX2) Names affixes. December 1999 123 .

For the new field length a new field with a new name is added to the end of the structure. longer fields. 124 December 1999 . remember that read-only access is possible to all the fields in the company’s address (check table ADRC). Currently this affects the following fields: Existing Field FORMOFADDR BUILDING STREET Length Char 20 Char 10 Char 40 New Field TITLE BUILD_LONG STREET_LNG Length Char 30 Char 20 Char 60 In Structure BAPIADDR1 BAPIADDR1. Converts the fields in the structure from the internal format into the external format. • If fields are lengthened in the CAM. If you want to make changes to these fields you have to access the reference structure BAPIADDR1. The obsolete field is still taken into account in the conversion modules described above. Converts the fields in the structure from the external format into the internal format. • When using the reference structure BAPIADDR3. A new data element is assigned to this field that can be identified as obsolete in the description and/or short text.BAPI Programming Address Parameters ADDR_CONVERT_TO_BAPIADDR2 ADDR_CONVERT_FROM_BAPIADDR3 ADDR_CONVERT_TO_BAPIADDR3 SAP AG Converts the fields in the structure from the internal format into the external format. you should use the new. BAPIADDR2. BAPIADDR3 BAPIADDR1 Preferably. the associated field in the BAPI reference structure remains the same type and length.

Also. The additional change parameter must contain exactly the same number of fields and the same field names as the parameter. the fields in the additional change parameter whose counterparts in the corresponding parameter contain modifications. Change() and Create() BAPIs). the value “NULL” should not be assigned to a data type to indicate an empty field. must be marked with an update flag. you must be able to distinguish between parameter fields that are to be modified (change-relevant fields) and parameter fields that are to remain unmodified. the name of the additional change parameter is EquiSalesX.SAP AG BAPI Programming Change Parameters Change Parameters Use In BAPIs that cause database changes (for example. ' ' (no value) This means that the corresponding parameter field does not have to be updated. the additional change parameter must also be a table. If the parameter is a table. You can do this in two ways: • • Flagging Fields to Identify Fields Containing Modified Values Comparing Fields to Identify Fields Containing Modified Values Flagging Fields to Identify Fields Containing Modified Values In this approach parameter fields containing modified values are identified by including a flag in an additional "change parameter". The program objects in the R/3 System affected by this change are: December 1999 125 . Using an initial value is no solution because an initial value could also represent a valid new value. Standardized change parameters are used to identify fields with modified values in Change() and Create() BAPIs. The fields that have been changed should be identified by flagging them. 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". When the BAPI is called. This can have the following values: • • • 'X' This value means that the corresponding parameter field contains a modified value. This way the BAPI can identify both modified and unmodified fields in the parameter. For instance. • • 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. • A Change() BAPI is used to change the value of the existing distribution channel (Distr_Chan) to Distr_Chan="US". You must use the data element BAPIUPDATE (CHAR 1) as the data element for the update fields. if the parameter is called EquiSales. in the ABAP programming language as well as on other development platforms.

When the Change() BAPI is called. • Note the following when you are comparing fields containing modified data. but the parameter containing the modified data must also have the suffix ‘New’. the parameter fields of the Change() BAPI must be exactly the same as the fields in the GetDetail() BAPI of the same business object type. the relevant values must be transferred from the parameter with the new data. the current data in the database and the new. This way any database changes made between the time the data was read by the GetDetail() BAPI and the time the database is updated can be identified. If the data in two corresponding fields is different. modified data.BAPI Programming Change Parameters Program Object SAP business object type BAPI Parameter Fields in parameter EquiSales SAP AG Name PieceOfEquipment Change EquiSales SalesOrg=0001' Distr_Chan='US' Division=' Marketing' Change parameter that identifies modified fields Fields in parameter EquiSalesX EquiSalesX SalesOrg=' ' Distr_Chan='X' Division=' ' In the parameter EquiSalesX the value in the field Distr_Chan is 'X'. • • 126 December 1999 . The data in both the parameters can be compared field by field. The names of the parameters to be compared must be the same. The current data set can be transferred. for instance. A calling program must be able to provide data in all the parameter fields of the Change() BAPI. The Change() BAPI then overwrites the existing value in the field Distr_Chan with the current value in the field Distr_Chan in the parameter EquiSales. The following comparisons can be made: • The current data can first be checked against the database contents to ascertain whether it has changed in the meantime. one containing the current valid data and the other the new. Comparing Fields to Identify Fields Containing Modified Values In this approach fields containing modified values are identified by comparing two parameters. modified data must be entered in the corresponding parameters. from a GetDetail() BAPI that has been called. For this reason. This indicates that the field Distr_Chan of the parameter EquiSales contains a modified value (US).

Area Performance Comments Flagging fields: The flag table can be compressed. The fields containing modified should be identified by comparing them. as described above. Entering data from the relevant GetDetail() BAPI in the parameter EquiSales. Initializing the parameter EquiSalesNew with the values from the parameter EquiSales. for example: EquiSalesNew-Distr_Chan='EN'. A Change() BAPI is used to change the value of the existing distribution channel Distr_Chan="US" to Distr_Chan=“EN”. The program objects in the R/3 System affected by this change are: Program Object SAP business object type BAPI Parameter Fields in parameter EquiSales Name PieceOfEquipment Change EquiSales SalesOrg=' 0001' Distr_Chan='US' Division=' Marketing' Parameter for the new data Fields in parameter EquiSalesNew EquiSalesNew SalesOrg=' 0001' Distr_Chan='EN' Division=' Marketing' The fields are compared by: 1. 2. • Both parameters must have exactly the same fields and the same structure. Data does not have to be compared. the parameter with the modified data is called EquiSalesNew. 3. If using in a distributed environment (ALE) the amount of data to be transported by flagging fields is not significantly greater. if the parameter with the current valid data is called EquiSales. Which is the Best Way? The table below compares the two ways of identifying fields containing modified values in BAPIs. December 1999 127 . and should help you decide which way suits your requirements best. Modifying the required parameter values in the parameter EquiSalesNew.SAP AG BAPI Programming Change Parameters For example.

meaning less demands are placed on the caller. Comparing fields: Need to compare with the associated GetDetail() method of the business object type. Comparing fields: Better for dialog-orientated applications with critical data. Flagging fields: Better for performance critical applications. Comparing fields: Can check against current database to identify and prevent inconsistencies. because all the fields in the Change BAPI() must filled by the calling program. Application 128 December 1999 . Flagging fields: Fields containing modifications can be flagged.BAPI Programming Change Parameters Programming Check facilities Comprehension Comparison with related data SAP AG Flagging fields: BAPI programming is simpler.

SAP AG BAPI Programming Extension Parameters Extension Parameters Use The parameters ExtensionIn and ExtensionOut enable customers to enhance BAPI interfaces without modifications and to process customer-specific data automatically. December 1999 129 . For details see Customer Enhancement Concept for BAPIs [Page 65].

BAPI Programming Return Parameters (Error Handling) SAP AG Return Parameters (Error Handling) Use A BAPI should be able to record and classify all possible errors that may occur. You must describe this process in the documentation for the Return parameter. As a table. In particular they must not generate terminations or display dialog boxes. BapiService.0 you must not use exceptions in BAPI interfaces. Instead. a database rollback is executed in the standard programming model. As of Release 4. the calling program performs the error handling. BAPIs themselves must not trigger any messages (such as MESSAGE xnnn) in the coding. Application developers are provided with two service BAPIs to diagnose and process error messages from BAPI calls: • • BapiService. For messages of type E (error). we recommend that you also execute a database rollback in the return parameter for termination messages. whereby it must be defined in the function module as a table parameter. When a termination message (message type A) is triggered. All error messages or indeed any message that may be returned by the BAPI. must be defined in message table (Tools → ABAP Workbench →=Development →=Programming environment →=Messages) and described in the documentation for the return parameter. whereby it must be defined in the function module as an export parameter. Otherwise the BAPI will not be processed correctly and control may not be given back to the calling program. as well as in the method in the BOR.MessageGetDetail() which displays the short and long texts of BAPI error messages. with which information in application logs can be displayed. as well as in the method in the BOR as an export parameter. When you program BAPIs. Features The export parameter Return can be implemented as follows: • • As a structure. This also applies to the most important or most likely error messages generated by other programs that can be indirectly passed via the BAPI to the application program.ApplicationLogGetDetail(). 130 December 1999 . all messages must be intercepted internally and reported back to the calling program in the Return parameter. You have to create a parameter named Return for every BAPI. that is. This parameter returns exception messages or success messages to the calling program. Before filling the Return parameter you should either initialize the structure with CLEAR or the table with REFRESH and CLEAR. all tasks performed since the last COMMIT WORK are canceled.

Line number of the data record containing the invalid value FIELD CHAR 30 Field containing the invalid value. The Return parameter may be based on the following reference structures: • • BAPIRET2 We recommend that you use this reference structure as of Release 4. Application log number This is empty if no log used. ID CHAR 20 NUMBER MESSAGE NUMC 3 CHAR 220 LOG_NO CHAR 20 LOG_MSG_NO MESSAGE_V1 MESSAGE_V2 MESSAGE_V3 MESSAGE_V4 PARAMETER ROW NUMC 6 CHAR 50 Current message number in application log Fields for the variable texts of the message specified in fields ID and NUMBER.5A. use the message classes before Release 4. Reference Structure BAPIRET2 The structure BAPIRET2 is filled via the function module BALW_BAPIRETURN_GET2. as in this case there is no COMMIT WORK. Message number Full message text from the message table. If you want messages to be compatible with earlier R/3 Releases.0. All variables (in fields Message_V1 to Message_V4) have been replaced with text.0. an application log is not created. Note that for type A error messages (abort). CHAR 32 INT 4 Parameter containing the invalid value. December 1999 131 . BAPIRET1 Both structures must be filled in the logon language.SAP AG BAPI Programming Return Parameters (Error Handling) If the return parameter is not set or is set to an initial value this means that no error has occurred. It contains the following fields: Field TYPE Type CHAR 1 Description S = success message E = error message W = warning message I = information message A = termination message (abort) Message ID The structure BAPIRET2 takes into account the name space extension for the message class as of Release 4.

the calling application can define its own additional error tables. The fields LOG_NO and LOG_MSG_NO of the Return parameter return the application log numbers and their messages.Extended Function Library Applications [Ext. that is. Otherwise status 53 (application document posted) is written and a COMMIT WORK executed. log entries are and no longer directly written to the database. you must write these using the update task. The use of the application log and error tables enable error messages to be returned if they cannot be adequately returned in the return parameter. If the field type is filled with E (error) in at least one of the transferred return parameter entries.6A you can already maintain the log number when you create the application log. If this still does not provide enough information. If the field type is filled with E (error) or A (abort) in at least one of the transferred return parameter entries. ROW and FIELD.BAPI Programming Return Parameters (Error Handling) SYSTEM CHAR 10 SAP AG System (logical system) in which the message was generated. they are written via the update task. if there are error messages (type E) in the table. It consists of the fields in the BAPIRET2 structure excluding the fields PARAMETER. Several instances of an application object can be maintained at the same time and can be updated together. Return Parameters in the ALE Distributed Environment 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 (see also Using BAPIs in Distributed Systems (ALE) [Page 164]. Reference Structure BAPIRET1 This structure is filled via the function module BALW_BAPIRETURN_GET1. There are no set guidelines for these additional tables.]. application document has not been posted) is assigned to all the status records of the IDoc and a COMMIT WORK is executed anyway. Application Log and Application-Specific Error Tables If the information provided in the Return parameter is not sufficient. 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 logging should be done by the BAPI itself so that function modules called directly by this BAPI do not have to be modified. the status 51 (application document has not been posted) is assigned to all the status records of the IDoc and a ROLLBACK WORK is executed. The Return parameter in your BAPI could give details of the messages in the error tables.] in the document BC . you can log errors with the application log. the status 51 (error. For further information on application logs see Creating Applications Logs [Ext. 132 December 1999 . for example. As of Release 4. If you plan to use application logs in your BAPI. The update task can be also used for application logs.

as in this case there is no COMMIT WORK. an application log is not created. December 1999 133 .SAP AG BAPI Programming Return Parameters (Error Handling) Note that for type A error messages (abort).

for example. for example. for example. a-z and 0-9. Application servers might not support ASCII. 134 December 1999 . for example. Relational operator. Because of this a BAPI should always select a range between A-Z.BAPI Programming Selection Parameters SAP AG Selection Parameters Use The parameters in BAPIs used to search for specific instances of a business object type.g. Note that when you select a list of objects you have to limit the number of objects selected. For more information see Programming GetList() BAPIs [Page 91]. MATNR. application-specific. e. Relational operator. BAPI GetList(). You can use the parameter MaxRows to do this. In your BAPI create the required selection parameters as structures or tables with the following parameters: Fields for Value Ranges Field Name SIGN Description Selection operator that determines whether the range specified is to be included or excluded. CP (contains pattern) or NP (no pattern) Data Element BAPISIGN OPTION BAPIOPTION HIGH LOW Upper limit of value range Lower limit of value range application-specific. but use a different character set instead. have to enable the caller of the BAPIs to specify appropriate selection criteria. If this is the case a problem may arise when you select quantities or ranges or when these are sorted. MATNR. You can use the function module BALW_RANGES_CHECK to check the values entered in SIGN and OPTION.

to check the entries for the object instance in the database before actually creating the object instance. such as. The generation of the instance. 'X' This value means that the BAPI is being called only in simulation mode and updating will not take place. is only simulated and the data is not written to the database. Keep in mind the following as you are programming: • • • • Do not assign any internal numbers either for the object itself. or for any dependent objects (for example. This is the default setting. establishing the connection to the R/3 System). The parameter is based on the data element TESTRUN. This can have the following values: • • ' ' (no value) No value means that the data will be posted. For BAPIs used in an ALE distributed environment. Be careful when calling function modules in other applications as these could assign numbers or update the database. Create a message in the return parameter of the BAPI that informs users whether the BAPI has been implemented in simulation mode.SAP AG BAPI Programming TestRun Parameters TestRun Parameters Use The parameter TestRun is used in write BAPIs. creating master data. the BAPI should carry out all the necessary checks (excluding technical checks. December 1999 135 . for example.Ledger No. in the material master). Updating can be switched on or off using the TestRun parameter. Do not inadvertently write change documents. without actually updating the database. Create() or CreateFromData(). EAN numbers or Mat. To simulate the creation of the object instance and to supply the relevant return messages. this parameter must be available in the interface. for example.

Use the type BAPI_TFRMT for this parameter. You can see an example of using text transfer parameters in the BAPI BapiService.BAPI Programming Text Transfer Parameters SAP AG Text Transfer Parameters Use Text transfer parameters are used to pass information in a BAPI (e. This requires the following fixed values that must all be provided by the BAPI: • • • • • SCR for SAPscript ASC for ASCII RTF for rich text format HTM for hypertext markup language (HTML) The table parameter Text that carries the text to be transferred. documentation on a business object type) from the R/3 System to a calling program. Features To transfer documentation texts you have to create the standardized parameters below: • The import parameter TextFormat that identifies the data format of the text to be transferred. 136 December 1999 .g.FieldhelpGetDocu(). Use the reference structure BAPITGB for this parameter.

This program is described in Defining Methods in the BOR Using the BOR/BAPI Wizard [Page 138]. • A transaction to automatically generate function modules to convert between internal and external data formats. December 1999 137 . For further information see the section Specifying Development Objects in the ABAP Dictionary [Page 37] in the report documentation. This transaction is described in Converting Between Internal and External Data Formats [Page 140].SAP AG BAPI Programming Tools for Developing BAPIs Tools for Developing BAPIs Use You can use the following development tools to develop BAPIs in addition to the standard development tools in the ABAP Workbench: • The BOR/BAPI Wizard to define BAPIs in the Business Object Repository. • The report BBAPIFLD used to generate default values for English field names and parameter names.

In the next dialog box specify the following information for the method to be defined: • Method A default name for the method is provided. On the initial Business Object Builder screen you can directly access the SAP business object type or interface type if you know the technical name of the object (object type). in the next dialog box select Other settings and then Interface. 2. You have already identified the technical name in Defining a BAPI and Its Interface [Page 24] Otherwise select Business Object Repository. You use the BOR/BAPI-Wizard to do this. Creating BAPIs as Methods of Business Object Types or Interface Types To define your BAPI as a method of a business object type or interface type: 1. the suggested method name might be BapiSalesorderGetstatus. 2. • Texts Enter meaningful descriptions for your BAPI. Select Tools → Business Framework → BAPI Development →==Business Object Builder. Search for the required business object type or interface type in the application hierarchy and double click it to open it. Procedure First find the relevant SAP business object type in the BOR: 1. 3. To display SAP interface types. Then select Continue. Begin every new word of the method name with a capital letter and do not use underscores. In the next dialog box enter the name of the function module. The application hierarchy is displayed. select Change. so that only the method name is left. based on the name of the function module.BAPI Programming Defining Methods in the BOR Using BOR/BAPI Wizard SAP AG Defining Methods in the BOR Using BOR/BAPI Wizard Prerequisites If the function module which your BAPI is based on has been fully implemented or modified you can define it as a method of an SAP business object type or SAP interface type in the Business Object Repository (BOR). • • To display object types. Example: If the name of the function module is BAPI_SALESORDER_GETSTATUS. When the business object type or interface type is displayed. BAPI_COMPANYCODE_GETDETAIL and select Continue. You will have to modify the suggested name. for example. 138 December 1999 . You should edit this so that the resulting name is GetStatus. • Delete the prefix “BAPI” and the business object name. Select Utilities → API Methods → Add method. in the next dialog box indicate whether you want to display all object types or only business object types.

Modify the parameter names as follows: • • • Each new word in the parameter name must start with a capital letter. December 1999 139 . 4. Make sure that the parameter names of the method in the BOR are identical to the parameter names in the function module except for the upper/lower case letters. Result After the program has been generated and executed. It is not used to make changes to existing BAPIs. 5. You have to make these changes manually in the BOR. The BOR/BAPI Wizard is used only to create new BAPIs for the first time. for example. Synchronous. To do this look at the newly created method of the business object type or interface type. Select Next Step. If you make changes to the underlying function module after you have created the BAPI in the BOR. Select Next Step. such changes do not automatically take effect in the BOR.SAP AG BAPI Programming Defining Methods in the BOR Using BOR/BAPI Wizard • Radio buttons Dialog. check that all the definitions have been made correctly by the BOR/BAPI Wizard.]. BAPIs are usually implemented synchronously. CompanyCodeDetail. For information about creating and modifying business object types refer to the documentation on SAP Business Workflow [Ext. if you make compatible interface enhancements or modify short texts. Instance-independent Enter relevant details for your BAPI. A list of parameters and default names is displayed which you need to edit as required. Table parameters are marked with a tick in the column 'MLine' (multiple lines). Make sure that a BAPI is not dialog orientated. for example. To create the method select Yes in the next dialog box. Also specify whether the individual table parameters are used for data import or data export.

In the appropriate input fields enter the names of the external BAPI structure and the internal working structure you are making the conversion between. the relevant internal and external data formats must have been created in the ABAP Dictionary. the fixed point arithmetic for the selected function group must be switched on. 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. A table is displayed containing suggestions for the conversion of each field of the external BAPI structure. Select Continue. If the function module is being used to convert currency amounts. These function modules are used to: • • • • Map English and German field names onto each other Carry out ISO code conversions Convert currency amounts into the required external or internal format Convert internal and external keys.BAPI Programming Converting Internal and External Data Formats SAP AG Converting Internal and External Data Formats Prerequisites This section describes how you can generate function modules to convert between internal and external data formats. Specify the required direction for mapping. Procedure To generate the function module follow the steps below: 1. The input fields for the name of the function module and the short text contain suggested values which you can accept or change. The FORM routine contains the same parameters as the generated function module. To generate the function modules. i. In the field Function group enter the name of the function group to which the generated function module is to be added. Field in external structure 140 December 1999 .e. is the internal structure to be mapped onto the external structure or vice versa. A dialog box is displayed in which you can enter details of the function module to be generated. Select Tools → Business Framework → BAPI Development →==Generate module to map fields. 2. for use for example by WBS elements (work breakdown structure) Note that conversions between internal and external data formats should only be carried out in exceptional circumstances. The table contains the following columns: • • Status Indicates if the conversion is possible or if data is missing. These exceptions are described in Internal and External Data Formats [Page 69]. Select Function module →=Generate. 4. select Form to edit. 3. To do this.

select Save. type. It is not yet possible to use this transaction to regenerate an existing function module.SAP AG BAPI Programming Converting Internal and External Data Formats Contains the field names of the external BAPI structure. type Displays the conversion type. To regenerate an existing function module you must first manually delete the function module and then generate it afresh. • • • • To map the internal work structures to the external BAPI structures before calling the BAPI To map the result to the internal work structure after the BAPI has been called To map the inbound parameters to the internal structures (import parameter structures) when you are implementing the BAPI To map the result from the internal structure to the BAPI (export parameter structures) when you are implementing the BAPI The section Application Example [Page 142] illustrates how function modules are used. Field in internal structure Displays the fields of the internal structure to which/from which mapping is to be carried out. 5. You can incorporate the generated function modules into the source code of your BAPI as required. Result In a few cases it may be necessary to manually edit the source code of a function module that has been automatically generated. For further information select F1 help for columns Status and Conv. December 1999 141 . The function module is stored in the Function Builder in the function group you specified. To generate the function module. • • Conv.

The external structure bapi_material_price contains the following fields: Fields in External BAPI Structure Field currency_iso currency amount Description ISO currency code Currency code Amount Data Element isocd waers bapimatprice Domain isocd waers 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.BAPI Programming Application Example SAP AG Application Example The BAPI used in this fictitious example can read the standard price of a material: bapi_material_getprice importing material like mara-matnr exporting material_price like bapi_material_price. This structure consists of the following fields: Fields in 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. Using the function. After calling the BAPI. which converts the currency and amount fields. map2i_bapi_material_price_to_mat_preis. (see section Converting Between Internal and External Data Formats [Page 140]). the application developer can generate the function module. the application programmer must convert these fields into the internal format used in R/3 so that the fields can be processed. 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. Generate module to map fields. The application code could be as follows: 142 December 1999 .

. * Map and convert the result to internal format call function map2i_bapi_material_price_to_mat_preis exporting external = bapi_preis changing internal = preis.. price like mat_preis... December 1999 143 .SAP AG BAPI Programming Application Example .. ... * * * exceptions error_during_iso_convertion error_during_currency_amount_conversion preis-matnr = matnr. * Call BAPI Call function bapi_material_getprice exporting material = matnr changing material_price = bapi_preis. data: matnr like mara-matnr. bapi_price like bapi_material_preis.

when adding a new import parameter. they are saved and generated. For example. it must fulfill certain requirements regarding the stability of its interface. If you continue developing your BAPI after you have released it. • Incompatible changes to data elements. As a result of this. or changes to the type or length of a domain. you need to ensure that any syntax changes or changes to the contents or functionality of the BAPI are downward compatible.BAPI Programming SAP Enhancements to Released BAPIs SAP AG SAP Enhancements to Released 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. For further details see Compatible Enhancements [Page 146] and Incompatible Enhancements [Page 148]. you can make the enhancement to the interface compatible by adding an optional parameter. you can only differentiate between a compatible and an incompatible enhancement. domains or structures that are being used by a BAPI that has been released. each enhancement to a BAPI must be created in a project in the BAPI Explorer. consider whether the interface would function without the parameter. If this is the case. when you enhance a BAPI. Process Flow When you are enhancing a BAPI. if the downward compatibility of the BAPI can be verified. you should attempt to make compatible changes in order to limit the impact of your modifications on existing programs which use the BAPI. Modifications and Version Management in the BOR Changes made to a BAPI only take effect when the changes are defined in the Business Object Repository (BOR). once a BAPI is released. Checks in the ABAP Dictionary Changes to the syntax of BAPIs are automatically checked by the ABAP Dictionary. Version management of BAPIs is also carried out in the BOR. The ABAP Dictionary can automatically test whether syntax changes are compatible. only the developer can ensure that content changes are downward compatible. 144 December 1999 . are rejected by the ABAP Dictionary. Accordingly. Downward compatibility means that applications that were programmed with BAPIs from a specific R/3 Release will not be effected in later R/3 Releases if the syntax or the content of this BAPI changes. thereby preventing the BAPI data structure being changed by mistake. For SAP internal development. that is. Examples of syntax changes are changes to parameter names. However.

domains or structures of a BAPI that has not been released are accepted by the ABAP Dictionary. December 1999 145 .SAP AG BAPI Programming SAP Enhancements to Released BAPIs • Compatible changes or changes to data elements.

A new optional parameter can be added in any place in the interface. Adding new optional field to the table.BAPI Programming Compatible Enhancements SAP AG Compatible Enhancements Use Compatible enhancements are interface enhancements that change the BAPI without effecting the downward compatibility of the BAPI. Compatible Changes to Function Modules In interface New optional parameter as a field New optional parameter as a structure New optional parameter as a table Adding new optional field to the structure. Converting mandatory fields to optional fields In program code New additional coding. Applications which access the BAPI are not affected by compatible enhancements. that does not involve changes to the interpretation/processing logic. A new parameter is added to the BAPI SalesOrder. The table below lists the compatible changes that can be made to function modules.. Features Compatible enhancements are: • New optional parameters A parameter is considered to be optional if it does not have to be included in a BAPI call. • New optional fields in structures A field is considered to be optional if it can be left out completely in a BAPI call.GetList() which can be used as an additional selection criteria for selecting sales orders in the R/3 System. Compatible changes to field types (in ABAP Dictionary). It does not matter how the fields are arranged in a structure or table because the whole structure is always forwarded.CreateFromData(). It is not first broken up into fields. 146 December 1999 . The fields must be added to the end of a structure because the function module underlying the BAPI is called via RFC. An additional input field for the applicant's educational background is added to the BAPI Applicant. We cannot guarantee that this list is complete.

December 1999 147 .SAP AG BAPI Programming Compatible Enhancements Changes to the existing code. Using customer exits. which do not involve changing the interpretation or processing logic.

Changes to the existing code that involve changing to the interpretation/processing logic. The table below lists the incompatible changes to function modules. Adding new fields between existing fields in the table. 148 December 1999 . Such modifications are considered to be incompatible enhancements. because they no longer enable the BAPI to be downward compatible. Incompatible Changes to Function Modules In interface New mandatory parameter Adding new fields between existing fields in structure. involving changes to the interpretation/processing logic. Adding new mandatory field to the structure. this is not the case with fields. We cannot guarantee that this list is complete. Incompatible enhancements are: • • • • • • Changes to the field length Changes to the field type Renaming parameters in the function module or in the method Inserting a field within a structure Deleting parameters and fields Adding new mandatory parameters or fields Parameters can be flagged as mandatory parameters in the BOR However. Incompatible changes to field types (in ABAP Dictionary). Adding new mandatory field to the table. Fields can only be categorized as mandatory at a semantic level and not at a technical level. Often. Converting mandatory fields to optional fields Renaming a parameter In program code New additional coding. This is why the documentation for each parameter must specify which fields can be filled.BAPI Programming Incompatible Enhancements SAP AG Incompatible Enhancements Purpose 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. these changes also cause existing parameters to lose their original meaning. Adding or removing COMMIT WORK commands in the program.

if required. you must not make any incompatible changes to the existing BAPI. In the BOR. This suffix changes if further incompatible changes are made.0 (in the correction release in which the new BAPI was introduced) and in the next functional Release “F1”. Instead. To implement these changes. additional BAPIs to replace the existing one. The following tasks are required when a BAPI has expired (become obsolete): • Select the relevant SAP business object type in the Business Object Builder and open the node Methods.SAP AG BAPI Programming Incompatible Enhancements Process Flow If changes to BAPIs are incompatible. During this time the original BAPI must remain fully functional and executable. The replaced BAPI is supported in Release 4.Create1().R/3 Frontend. If further incompatible modifications must be made to the BAPI at a later date. is created.5A”. A numeric suffix is simply added to it. FixedAsset.Create(). Supporting and Labeling the Expiring BAPI After the BAPI has been superseded by a new BAPI. create one or several. “Collective Note for Obsolete BAPIs from Release 4.Create2(). in order to maintain the interface integrity of the BAPI FixedAsset. yet another BAPI. you should not remove the replaced BAPI from the Business Object Repository (BOR) . December 1999 149 . • • • The graphic below illustrates the expiry phase of a BAPI. In this example the new BAPI is introduced into Release 4. a new BAPI. in the SAPNet . The BAPI can then no longer be used in the following functional Release “F2”. proceed as follows: Creating an Additional BAPI To ensure that the interface stability of an existing BAPI is not effected. must be created. Record the BAPIs set to “obsolete” in a particular Release in the Note 0107644. you first label this BAPI as expired and continue its support in the release in which you have introduced the new BAPI as well as in the next functional release. FixedAsset. document which method(s) are to replace the expiring BAPI. Position the cursor on the BAPI and select Edit → Change status to → Obsolete. The new BAPI must retain the same name as the existing BAPI.0. Instead. Inform your users about the relevant successor BAPIs in Release Notes. A number of incompatible changes must be made to the BAPI FixedAsset.Create().

150 December 1999 . • Delete the function module that implements the BAPI. You should delete an obsolete BAPI as near to the beginning of a new release as possible. in the SAPNet . • Record the release in which the BAPI was deleted from the BOR in the Note 0107644.0 F1 F2 Business Object BAPI BAPI Supported at least until F2 Business Object Supported as of 4. “Collective Note for Obsolete BAPIs from Release 4.R/3 Frontend. you can remove the BAPI from the BOR. so that developers have time to adjust to its successor. To delete a BAPI: • Delete the method from the BOR.5A”. Expand the node Methods Place the cursor on the appropriate BAPI and choose Edit → Delete.0 Neu F = functional Release Deleting the Replaced BAPI If the expiry phase of a BAPI set to obsolete has come to an end. To do this display the relevant SAP business object type in the Business Object Builder.BAPI Programming Incompatible Enhancements SAP AG BAPI Expiry Phase Release BAPI BAPI 3. In the Function Builder enter the name of the function module in the Function module field and choose Function module → Other functions → Delete.1 4.

For further information see BAPI Development [Page 159]. • Modifications Use this way if you want to enhance the functions of an existing BAPI for a subtype. For general information about object types and subtype refer to the documentation for SAP Business Workflow [Ext. In this way the SAP standard delivered to customers is not changed and the modifications/own developments carried out are retained when the release is upgraded.] as well as “Guidelines for Modifying the SAP Standard in SAPnet. Then you can make the modifications/own developments to the derived subtype. • Customer developments Use this method to provide functionality for the subtype which is not covered by any of the existing BAPIs of the subtype nor by any of the BAPIs inherited by the subtype. Process Flow Modifications to existing BAPIs or the development of customers’ own BAPIs cannot be made for business object types delivered in the standard. for example. should follow the guidelines in the document Changing the SAP Standard [Ext. For further information see Namespaces [Page 161].SAP AG BAPI Programming Customer Modifications and Developments Customer Modifications and Developments Purpose If required. The following sections describe how subtypes are created and the two ways of enhancing the BAPIs available for this subtype.]. The original object type becomes the supertype. For more information see Modifying BAPIs [Page 152]. December 1999 151 . This procedure also enables BAPIs to be modified in steps because further subordinate sub-types of a business object type can be created. make sure that the relevant development objects are assigned a name from the customer namespace. Instead. you create a subtype of the business object type which inherits all the characteristics and methods of this object type. Also. create new parameters or parameter fields. customers can carry out modifications to existing BAPIs. Prerequisites Customers and partners who want to create new development objects required in the context of a modification or own development. or develop new BAPIs following this programming guide.

2. Follow these steps: 1. as illustrated in the example below: Object type OT has two BAPIs m1 and m2. The original functionality is retained and can be enhanced for customer needs. the original inherited BAPI can only be called from the supertype.BAPI Programming BAPI Modifications SAP AG BAPI Modifications Purpose This section describes the steps involved in modifying an existing BAPI. for example. Redefine the BAPI inherited by the subtype. as described in Creating Subtypes [Page 160]. There are several ways to do this. you can use the following implementation options: Creating a New Function Module for the Implementation Here a new function module (BAPI_OTsub_m2) is created to call the function module of the superior BAPI method (of the supertype). by adding further parameters or modifying the implementation of the BAPI. you have to create a subtype of the business object type and for this subtype you have to redefine the BAPI method inherited from the superior business object. for example. Create a subtype of the required business object type. Instead. if new parameters or parameter fields are to be added. Only the redefined BAPI is then available for the subtype. The graphic below illustrates the implementation: 152 December 1999 . which are implemented by the function modules BAPI_OT_m1 or BAPI_OT_m2: m1 OT m2 BAPI_OT_m2 BAPI_OT_m1 If enhancements to BAPI m2 are required. Process Flow BAPI modifications cannot be made to business object types delivered in the standard system.

remember that the modifications must be merged with the original BAPIs every time a release is upgraded. . if the encapsulation affects system performance negatively. is cleanly encapsulated. If you use this method. UPDATE operations are to be made in different fields of the same data record that the developer would like to implement in one single update record (that is with one UPDATE). if only new optional parameters have been added (see also SAP Enhancements to Existing BAPIs [Page 144]). The advantage of using this method is that the original superior BAPI (BAPI_OT_m2). if in both BAPI_OT_m2 and in BAPI_OTsub_m2. As of Release 4. when releases are upgraded. whose stability has been guaranteed. if the interface of the original BAPI BAPI_OT_m2 is enhanced. Compatible Modifications to the Superior Function Module In principle.5A you can use The Modification Assistant [Ext. For example. . the call in BAPI BAPI_OTsub_m2 must also be enhanced. are automatically copied to the new BAPI without requiring the subtype to be changed in any way. This method is not a good choice. the BAPI method of a subtype can be implemented by the same function module as the method of the suoertype (BAPI_OT_m2 in this example). This could be the case. December 1999 153 . The graphic below illustrates the implementation: m1 OT m2 BAPI_OT_m2 modifiziert BAPI_OT_m1 OTsub m2 With this implementation method. This is possible if the modifications of the interface are compatible.] to do this. if the enhanced functionality of the original BAPI is to be used. for example. corrections and optimizations). the system checks which interface enhancements have been carried out on the original BAPI. Any changes carried out in the future to the original superior BAPI which do not affect the interface or semantics (for example.SAP AG BAPI Programming BAPI Modifications m1 BAPI_OT_m1 BAPI_OT_m2 OT m2 OTsub m2 BAPI_OTsub_m2 call function .

Creating the Implementing Function Module as a Copy of the Superior Function Module Here a copy of the function module of the superior BAPI method is created (in this example. if the enhancement cannot be done by calling the function module of the superior BAPI method. 3. we recommend that you do not use this option. When you have made the modification. The main disadvantage is that the encapsulation achieved by separating the supertype and subtype for the BAPI definition actually has to be revoked. The graphic below illustrates the implementation: m1 OT m2 BAPI_OT_m2 kopiert BAPI_OT_m1 OTsub m2 BAPI_OTsub_m2 modifiziert You should only use this option. even though they have been created independently of each other. you must ensure that the function module continues to behave the same when the original method of the supertype OT is called. you still have to check. optimal performance of database UPDATE operations. you have to copy them to the modified copy. to achieve. As the origin of the copy is not always supported. For further information about the BOR/BAPI Wizard see Defining Methods in the BOR Using the BOR/BAPI Wizard [Page 138].BAPI Programming BAPI Modifications SAP AG The advantage of using this option is that the original code and enhancement can be easily compared with one another. as described in Redefining BAPIs [Page 157]. with every release upgrade. you have to redefine the modified BAPI of the subtype in the BOR. Although it is more flexible to modify a copy of the function module. If changes have been made. When changes have been made. If global data is defined or form routines are called in the function group associated with a BAPI function module. in the same development system or for several industry solutions in one system. Once you have made the required modification to the copy of the function module. assign it as a method to the relevant business object type in the Business Object Repository using the BOR/BAPI Wizard. you may have to also copy these data declarations and form routines to ensure the copy of the BAPI can be executed. for example. 154 December 1999 . BAPI_OT_m2). for example for different industry solutions. whether changes have been made to the implementation of the superior BAPI method. This option can cause problems. for example. if several subtypes of an object type exist in the same system.

GetList() for the business object type Material should contain additional parameters. (For all methods that are not implemented for the sub-type Ymaterial. the BAPI YMaterial. In the case of all other method calls. the interface is enhanced with new. the method call is executed from the superordinate business object type. a new function module must be created and assigned to the method YMaterial. for example. The function module associated with this BAPI is BAPI_MATERIAL_GETLIST. customers create the method GetList() for the sub-type YMaterial using the BOR/BAPI Wizard. This is described as delegation.]. mandatory parameters. where the new parameters are included as part of the method definition. Application Example The BAPI Material. and then edit this copy. A delegation relationship is only significant for object-oriented BAPI method calls and not if the implementing function module is called directly.GetList() is the one actually executed. December 1999 155 . Customers should first create a sub-type YMaterial of the existing object type Material in the BOR.GetList(). For information about delegation see the documentation on SAP Business Workflow [Ext. on the other hand. If redefined BAPIs of a subtype are also to be used when the BAPI is called. The method is linked to the function module BAPI_MATERIAL_GETLIST. They will also note that method calls of the business object type YMaterial for the original object type Material are to be processed. because these are not implemented for the subtype YMaterial. Material are executed. and makes changes to the interface by creating new. Next.SAP AG BAPI Programming BAPI Modifications 4. (Customers can also copy the module BAPI_MATERIAL_GETLIST. to Y_BAPI_MATERIAL_GETLIST. If. optional parameters. This procedure is described in Defining Delegation Relationships [Page 158].GetList(). Material. At runtime the following process takes place: – – When the BAPI Material. the methods of the superordinate business object type.) Customers make the necessary changes in the source code of the function module BAPI_MATERIAL_GETLIST. provided that the associated method is implemented there. you have to define the delegation relationship between the supertype and subtype.

enter the required details: – – In the field Supertype enter the name of the object type for which you want to create a subtype. 3. Choose Tools →=Business Framework → BAPI Development →=Business Object Builder or enter the transaction code SWO1. In the field Object type enter the name of the subtype you want to create and sleet Create. In the field Object type enter the name of the subtype you want to create.BAPI Programming Creating Subtypes SAP AG Creating Subtypes To create a subtype: 1. In the next dialog box. Enter appropriate values in the remaining fields. 2. 156 December 1999 .

4. 3.SAP AG BAPI Programming Redefining BAPIs Redefining BAPIs To redefine a BAPI of a subtype: 1. 5. Display the subtype just created in the change mode. In the Name field of the modified function module enter and save your information. Choose Tools →=Business Framework → BAPI Development →=Business Object Builder or enter the transaction code SWO1. Double-click on the BAPI and select the register ABAP. Place the cursor on the BAPI you want to modify and choose Process →=Redefine. 2. December 1999 157 .

3. Deactivate the check box GUI-specific.BAPI Programming Defining Delegation Relationships SAP AG Defining Delegation Relationships To define the delegation relationship between the supertype and subtype: 1. 4. 5. 158 December 1999 . 2. Choose Settings → Delegate →=System-wide. Switch to the change mode and select New entries. Enter the name of the original object type (supertype) in the field Object type and the name of the subtype in the field Delegation type. Choose Tools →=Business Framework → BAPI Development →=Business Object Builder or enter the transaction code SWO1. Save your entries.

Create a subtype of the required business object type. Use this method to provide new functionality for the subtype which is not covered by any of the existing BAPIs of the subtype nor by any of the BAPIs inherited by the subtype. Your own developments are carried out in the subtypes derived from business object types delivered in the standard and not from the business object types themselves. This method is associated with the function module Y_BAPI_MATERIAL_GETDETAIL.YGetDetail is called. December 1999 159 . an additional method YGetDetail should be created for the sub-type YMaterial of the business object type Material. All existing BAPIs derived from the supertype can continue to be used unmodified. At runtime. Application Example Following on from the example in BAPI Modifications [Page 152]. as described in Creating Subtypes [Page 160]. Process Flow Follow these steps: 1. 2. the BAPI YMaterial. when the BAPI Material. Customers should create the new method YGetDetail of the business object type YMaterial using the BOR/BAPI Wizard. The new BAPI can only be used for this subtype and not for the object type from which it was derived (supertype). Use the guidelines described in this document to create a new BAPI for the subtype and to implement it in its own function module.YGetDetail is actually implemented due to the delegation pointer in the business object type Material.SAP AG BAPI Programming BAPI Development BAPI Development Purpose Using the information in these BAPI Programming guidelines customers and partners can create new methods for business object types. The function module associated with this BAPI is Y_BAPI_MATERIAL_GETDETAIL.

3. 2. In the field Object type enter the name of the subtype you want to create and sleet Create. In the field Object type enter the name of the subtype you want to create. 160 December 1999 . Choose Tools →=Business Framework → BAPI Development →=Business Object Builder or enter the transaction code SWO1. In the next dialog box.BAPI Programming Creating Subtypes SAP AG Creating Subtypes To create a subtype: 1. Enter appropriate values in the remaining fields. enter the required details: – – In the field Supertype enter the name of the object type for which you want to create a subtype.

attributes and so on with the superordinate object type. Reserved Namespaces/Prefixes for Various Application Groups User Special SAP project Partners/software houses Prefix For example. for function modules matching "Y_" and "Z_".. The following prefixes are used: • J_y" (where "y” is a single digit allocated namespace) for partners/software houses whose namespaces were assigned before Release 4. Industrial Business Units (IBUs) do not have specific namespaces. • Customers "Y" and "Z". You must follow the naming conventions for the sub-objects too. ABAP Dictionary Naming Convention Standard in the respective R/3 Release December 1999 161 . therefore. Sub-object types split the namespace for methods. regardless of the names of the methods. The Business Object Repository (BOR) introduced before R/3 Release 4.SAP AG BAPI Programming Namespaces Namespaces Definition The namespace concept describes how customers and partners have to name their development objects to avoid overlapping when SAP software is upgraded. made it easier to assign names to objects developed by customers and partners. and the namespace J_<number> was reserved for partners.0 still uses the old namespace concept. For this reason the limitations of the old namespace concept still apply to the namespaces for BAPI development objects. SAP object types cannot overlap with each other. In R/3 Release 3. Naming Conventions for BAPI Development Objects Development Object Domain Created in. In principle. together with the longer development object names. For further information see Customer Modifications and Developments [Page 151].1 the namespaces Y* and Z* were provided for customers. attributes and so on. “JPN” for developments in the Japanese area. In R/3 Release 4.0. the naming convention for this object type applies to all the sub-objects. to implement a new BAPI or to modify an existing BAPI.0 a new namespace concept was introduced which. for example.0. for example. "JJ<Namespace>" (where "<Namespace>" is the registered namespace) for partners/software houses whose namespaces were assigned after Release 4. If a customer or partner creates a new object type that is not a sub-type of another object type.. JJABC. Customers and partners can create their own development objects.

the object type in the standard is assigned the object name without the suffix. The object type in the IBU is assigned the IBU code from the component hierarchy as a suffix. • Prefixes are reserved exclusively for partners and customers. For example. For example. the node of the component hierarchy is added on as a suffix.BAPI Programming Namespaces Data Element Structure Field in structures Append structure Function group Function Module Function module parameter Object name (name of object type) ABAP Dictionary ABAP Dictionary ABAP Dictionary ABAP Dictionary Function Builder Function Builder Function Builder BOR SAP AG Standard used in the respective R/3 Release <Prefix>BAPI* Standard used in the respective R/3 Release Standard used in the respective R/3 Release <Prefix>BAPI_<object type>_<method> <Prefix>*. • If object types from standard applications require the same object name. if a customer changes the object type BusinessProcessCO. except for parameters in customers’ function modules <Prefix>object name<Suffix> Suffixes are only used if there is/could be a name conflict within SAP. except for modifications using delegation. the business object type. BusinessProcess in Controlling (CO) would be named BusinessProcessCO If there is a name conflict between a standard application and an IBU. <Function module parameter> 162 December 1999 . a possible name for it could be YBusinessProcessCO. Object type (technical object name) Attribute name Method Method parameters BOR BOR BOR BOR <Prefix>* <Prefix>* <Prefix>*. otherwise delegation does not work.

SAP AG BAPI Programming Namespaces December 1999 163 .

that is.0 you can implement an asynchronous BAPI interface by generating an ALE IDoc interface for the BAPI and using it in an appropriate ALE distribution scenario. In this situation a synchronous interface cannot be used because performance would be too low. 164 December 1999 . the application in the sending system calls the generated ALE IDoc interface instead of the BAPI.0 ALE (Application Link Enabling) technology has enabled data to be exchanged between individual distributed SAP Systems and non-SAP systems. see ALE Programming Guide [Ext.].BAPI Programming Using BAPIs in Distributed Systems (ALE) SAP AG Using BAPIs in Distributed Systems (ALE) Purpose Since Release 3. • Performance The interface has a large volume of data or database operations to be carried on the server system will take a long time. The ALE IDoc interface performs the following tasks: • • • Creates an IDoc from the BAPI data Sends the IDoc to the target system Receives the IDoc in the target system. For these reasons messaging is used for data communication between the participating systems in ALE distribution scenarios. This transaction is described in detail in the ALE Programming Guide [Ext. BAPI Development Even if one of the systems fails. For further information on ALE technology and using BAPIs in the context of ALE.]. This section provides a general overview of points you should keep in mind when implementing a BAPI to exchange data asynchronously. you should implement your BAPI as an asynchronous interface: • • Consistent database changes in several systems Data must be updated consistently on both the local system and on the remote system. (with a time delay) with each other. Loose coupling With a synchronous interface the coupling between the client and the server system is too narrow. Loose coupling means that the individual systems for the most part communicate asynchronously. As of Release 4. the associated IDoc and the required function modules. or a communications link is interrupted. If at least one of the conditions below applies. make sure that a BAPI of this type is actually required for the task in hand. If the connection is interrupted the client system would not be able to function properly. the remaining systems must be able to continue to function. Process Flow When you use BAPIs for asynchronous messaging. creates the BAPI data from the IDoc and calls the BAPI You can use Transaction BDBG to create the additional objects required for the BAPI in this process. Prerequisites Before you can implement a BAPI used to transfer data asynchronously in ALE.

If the field type is filled with E (error) or A (abort) in at least one of the transferred return parameter entries. All BAPI export parameters with the exception of the return parameter are ignored and are not included in the IDoc that is generated. The BAPI return parameter must use the reference structure BAPIRET2. the status 51 (error.SAP AG BAPI Programming Using BAPIs in Distributed Systems (ALE) 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 general BAPI programming guidelines: • • • • The BAPI must not issue a COMMIT WORK command. December 1999 165 . the status 51 (application document has not been posted) is assigned to all the status records of the IDoc after a ROLLBACK WORK has been executed. application document has not been posted) is assigned to all the status records of the IDoc and a COMMIT WORK is executed. Otherwise status 53 (application document posted) is written and a COMMIT WORK executed. After the function module which converts the IDoc into the corresponding BAPI in the receiving system has been called. If the field type is filled with E (error) in at least one of the transferred return parameter entries. status records are written for the IDoc in which messages sent in the Return parameter are logged.

Scenario Person responsible: Developer BAPIs must be developed as part of an integration scenario.. [Name of business object type] [Name of person responsible] 2. [ ] [ ] 3. BAPI Quality Checklist This checklist helps you to develop BAPIs in accordance with the programming guidelines and enables you to implement the best quality BAPIs right from the start.BAPI Programming BAPI Quality Checklist SAP AG BAPI Quality Checklist Definition The check list below contains extracts from the BAPI Quality Checklist used internally in SAP to develop BAPIs. Name of the function module 1. [ ]. ---------------------------------------------------------------------- 166 December 1999 . You can refer to this check list during the entire development and implementation of a BAPI. and that access to the R/3 functionality is provided in a structured and practical way... [ ] [ ]. You should use this checklist to manage the development of all BAPIs in your integration scenario. [Name of business object type] [BAPI name] 2. [ ] [ ] 3. This will ensure that they complement each other. [ ] 3.. Scenario to be implemented [Name of the scenario] ----------------------------------------------------------------------- Quality of Object Modeling Person responsible: Developer [] Existing object model Business object types used in the scenario and person responsible 1... BOR methods to be implemented 1. [ ] [ ]. [Name of function module] 2.

SAP AG BAPI Programming BAPI Quality Checklist Specification Person responsible: Quality assurance/central development department [ ] BAPI concept or specification has been checked by the central development department and by the responsible quality manager. For example.. 10. December 1999 167 .12 and not as 1012. Security issues [ ] All BAPIs contain authorization checks [ ] All F4 possible entries have authorization checks Updates Database changes can only be made through updates. Commit Work BAPIs containing the COMMIT WORK command (exceptions only) [Name of business object type] [BAPI name] [][] [ ] [ ].. Data conversion [ ] Only internal data formats are used.12 is displayed as 10. [ ] All BAPI structures begin with the prefix “BAPI” and all foreign keys are defined.. [Name of the contact person in the central development department] [Name of the quality manager] You must mark the checkbox for all the BAPIs in this development request. ---------------------------------------------------------------------Quality of the Method Concept Person responsible: Developer You must mark the checkbox for all the BAPIs in this development request. Fields and Parameters [ ] All field and parameter names must be in English [ ] All the quantity fields must have units of measurement fields [ ] All currency amount fields must have currency indicator fields [ ] All key fields in GetDetail() and GetList() BAPIs must be displayed in a text field. with the following exceptions: (mark these exceptions): [ ] All the date fields must have the format JJJJMMTT [ ] All currency amounts are based on the domain BAPICURR [ ] PSP elements and similar fields use external keys [ ] Additional fields are provided for ISO codes [ ] Currency amounts with decimal places are displayed with decimal points in the interface.

BAPI Programming BAPI Quality Checklist SAP AG [ ] No COMMIT WORK in asynchronous BAPIs that are sued in the context of ALE/BAPI Integration ---------------------------------------------------------------------- Quality of the BOR Definition Person responsible: Developer [ ] Table parameters are marked in the BOR "Imp. Otherwise either the indicator Imp or Exp is used. Person responsible: Central development department [ ] Instance-dependency/instance-independency checked [ ] BAPI name(n) OK (agree name with person in development department) [Name of person] A cross in a checkbox applies to all the BAPIs in this development request. and Exp. Documentation [ ] BAPIs and all the associated parameters are fully documented [ ] Documentation on the parameter RETURN contains all the important return codes and messages [ ] The comprehensibility and user friendliness of the documentation has been checked [ ] Documentation describes the use of the COMMIT WORK command (if applicable) [ ] Documentation on the function module has been saved to the active version [ ] Business object type has been documented [ ] BAPI scenario (ALE Business Process) has been documented Tests [ ] Individual tests OK [ ] Integration tests OK [ ] Calling from external programs OK [Name of quality manager responsible] ------------------------------------------------------------------------ 168 December 1999 ." only if they have to be imported as well as exported. -----------------------------------------------------------------------Quality of Documentation and Functionality Person responsible: QM A cross in a checkbox applies to all the BAPIs in this development request.

December 1999 169 .SAP AG BAPI Programming BAPI Quality Checklist Authorization to Release Person responsible: Quality assurance/central development department [ ] Authorized by member of central development department [Name of person] [ ] Authorized by quality manager [Name of the quality manager] A cross in a checkbox applies to all the BAPIs in this development request. -----------------------------------------------------------------------If all the fields have been marked are filled. you can release your BAPI(s) and the development request. Thank you for your cooperation.

Master your semester with Scribd & The New York Times

Special offer for students: Only $4.99/month.

Master your semester with Scribd & The New York Times

Cancel anytime.