BAPI Programming HELP.CABFABAPIREF. Release 4.6B

Transcription

1 HELP.CABFABAPIREF Release 4.6B

2 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 TM are registered trademarks of Informix Software Incorporated. 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 JAVA is a registered trademark of Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, CA 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

3 SAP AG Icons Icon Meaning Caution Example Note Recommendation Syntax Tip December

4 SAP AG Contents...6 Guide... 7 BAPIs... 9 BOR Terminology Further Documentation on BAPIs Defining and Implementing the BAPI BAPI Explorer Working with Display Functions Working with Tools and Projects Defining the Scenario Reviewing the Scenario Concept Defining a BAPI and Its Interface...24 Standardized BAPIs Standardized Parameters...29 Determining the Object Type and Its Key Fields Defining the Interface Structure of the BAPI Naming Parameters in the Function Module Defining Data Formats Specifying Development Objects in ABAP Dictionary Naming the Method in the BOR Naming Parameters in the BOR Naming the Function Module and the Function Module Group BAPIs Used for Outbound Processing Creating Development Objects and Documentation BAPI Interface and Function Module Testing the BAPI and Its Documentation Releasing the BAPI General Programming Guidelines for BAPIs Transaction Model for Developing BAPIs BAPI Transaction Model with Commit BAPI Transaction Model Without Commit Customer Enhancement Concept for BAPIs Internal and External Data Formats Providing Input Help (F4 Help) Providing Interface Descriptions Buffering with Write BAPIs Example of Implementation and Process Flow Improving Performance Documentation Guidelines Programming Standardized BAPIs Programming GetList() BAPIs Example of a GetList() BAPI...92 Programming GetDetail() BAPIs December 1999

5 SAP AG Example of a GetDetail() BAPI Programming GetStatus() BAPIs Example of a GetStatus() BAPI Programming ExistenceCheck() BAPIs Example of an ExistenceCheck() BAPI Programming Create() BAPIs Example of a Create() BAPI Programming Change() BAPIs Example of a Change () BAPI Programming Delete() BAPIs Example of a Delete() BAPI Programming Cancel() BAPIs Example of a Cancel() BAPI Programming Replicate()/SaveReplica() BAPIs Example of a SaveReplica() BAPI Programming Methods for Sub-Objects Programming Standardized Parameters Address Parameters Change Parameters Extension Parameters Return Parameters (Error Handling) Selection Parameters TestRun Parameters Text Transfer Parameters Tools for Developing BAPIs Defining Methods in the BOR Using BOR/BAPI Wizard Converting Internal and External Data Formats Application Example SAP Enhancements to Released BAPIs Compatible Enhancements Incompatible Enhancements Customer Modifications and Developments BAPI Modifications Creating Subtypes Redefining BAPIs Defining Delegation Relationships BAPI Development Creating Subtypes Namespaces Using BAPIs in Distributed Systems (ALE) BAPI Quality Checklist December

6 SAP AG 6 December 1999

7 SAP AG Guide 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

8 SAP AG Guide 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

9 SAP AG 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

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

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

12 SAP AG BOR 12 December 1999

13 SAP AG 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 Interface type SAP interface type Definition Generic definition of business objects. Describes the general characteristics and common attributes of instances of SAP business object types. One instance of an SAP business object type Central repository within the R/3 System containing all the business object types and SAP interface types together with their definitions and methods. 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. BAPIs are implemented as RFC-enabled function modules and are created in the Function Builder of the ABAP Workbench. Definitions of attributes, methods and events grouped together in one context. An object type can support one or more interface types. The functional group of associated attributes, 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. December

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

15 SAP AG 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. These are shown in the graphic below. BAPIs are defined in the Business Object Repository (BOR) as API methods of SAP business object types. BAPIs are implemented in the Function Builder as RFC-enabled function modules. The definitions and descriptions of the data structures used by the BAPI are stored in the ABAP Dictionary. BOR, Function Builder and ABAP Dictionary ABAP Workbench Business Object Repository Function Builder ABAP Dictionary Business Object BO: Method 1 = M1 Method 2 = M2 Function module BAPI_BO_M1 Function module BAPI_BO_M2 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. The following sections guide you through the steps involved in developing a BAPI. The sections contain information about the guidelines and conventions that you should adhere to when defining and implementing a BAPI. 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. December

16 SAP AG Defining and Implementing the BAPI 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. Defining the scenario in which the BAPI will be used 2. Reviewing the BAPI scenario and how the BAPIs interact with one another For further information see: Defining the Scenario [Page 21] Reviewing the Scenario Concept [Page 23] 3. Defining a BAPI and Its Interface Defining the BAPI and Its Interface [Page 24] 4. Creating individual programming objects Creating Development Objects and Documentation [Page 46] 5. Programming BAPIs General Programming Guidelines for BAPIs [Page 54] 6. Testing the BAPI and its documentation Testing the BAPI and Its Documentation [Page 52] 7. Releasing the BAPI Releasing the BAPI [Page 53] 8. Enhancing existing BAPIs, if required SAP Enhancements to Existing BAPIs [Page 144] 16 December 1999

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

18 SAP AG Working with Display Functions 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. Using the tabs Alphabetical and Hierarchical in the hierarchy display, 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. By expanding the relevant nodes you can navigate up to the parameter level of individual BAPIs. Features The following display functions are also provided which enable you to directly access BAPIs and their details 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. 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. For example, in the detail display for a particular method, by double clicking on the name of the function module, it will be displayed in the Function Builder. Displaying and Printing Documentation In the Documentation view of the work area the documentation for the development object selected in the hierarchy is displayed. The data element documentation for each parameter field is contained in the documentation for structured BAPI parameters. If you have installed Microsoft Internet Explorer Version 4.0 on the front-end computer, you can print the documentation using the standard SAPgui print function. Changing the level of the hierarchy display The component hierarchy may have many hierarchy levels. To make it easier to find a business object type and its BAPIs, you can use the function Goto Change hierarchy level to limit the display to two hierarchy levels. Specifying the BAPIs to be displayed The default is to display only released BAPIs of business object types. By choosing Goto BAPIs to display, you can display all the BAPIs contained in the BOR, that is BAPIs of SAP interface types and BAPIs that have not yet been released. Business object types and interface types are identified by different symbols. To display these, choose Goto Display legend. 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

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

20 SAP AG Working with Tools and Projects Working with Tools and Projects Use The views Tools and Projects in the work area are mainly used for developing BAPIs. Features Depending on the development object selected in the hierarchy display, in the Tools view, the following tools and navigation options are provided: Direct access to the Business Object Builder, Function Builder and ABAP Dictionary. 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, 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. 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. If you have installed Microsoft Internet Explorer Version 4.0 on the front-end computer, you can print the project form using the standard SAPgui print function. 20 December 1999

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

22 SAP AG Defining the Scenario 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. From this ID details of the company code can be displayed. However, the two BAPIs remain functionally independent of each other, because if the company code ID is known, the BAPI "Display details of a specific company code" can be used without first calling the BAPI "Display list of all company codes". 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. 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. The functions or methods of these other object types are used implicitly. 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. 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).You will also have identified the SAP business object types relevant to the BAPI scenario. 22 December 1999

23 SAP AG 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. You also defined the relevant SAP business object types. Before you implement the scenario and begin defining and developing the BAPI, you should carry out a review of the scenario. 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. Confirm that the scenario as it stands is meaningful and that the BAPIs in the scenario can interoperate without any problems. Start developing the BAPI only after you have successfully completed the review. December

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

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

26 SAP AG Standardized BAPIs 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. Features With object methods and especially with BAPIs, you can differentiate between instance methods and class methods. Instance methods refer to precisely one instance (one specific occurrence) of an SAP Business Object type, for example, to one explicitly specified customer order. Whereas class methods are instance-independent. 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, company codes and material numbers. The BAPIs GetList() is a class method. For more information see Programming GetList() BAPIs [Page 91]. 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. Then this information is reported back to the calling program. The BAPI GetDetail() is an instance method. For more information see Programming GetDetail() BAPIs [Page 93]. GetStatus() The BAPI GetStatus() is used to query the status of an SAP business object instance, for example, the processing status of a sales order. This BAPI is used only for displaying the status of an object and does not retrieve full details like the BAPI GetDetail(). The BAPI GetStatus() is an instance method. For more information see Programming GetStatus() BAPIs [Page 96]. ExistenceCheck() The BAPI ExistenceCheck() checks whether an entry exists for a business object instance, for example, whether the customer master has been created. The ExistenceCheck() BAPI is an instance method. For more information see Programming ExistenceCheck() BAPIs [Page 98]. BAPIs for Creating or Changing Data The following BAPIs can create, change or delete instances of a business object type: 26 December 1999

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

28 SAP AG Standardized BAPIs 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]. 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(). They enable specific instances of an object type to be copied to one or more different systems. These BAPIs are used mainly to transfer data between distributed systems within the context of Application Link Enabling (ALE). These BAPIs are class methods. For more information see Programming Replicate()/SaveReplica() BAPIs [Page 115]. 28 December 1999

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

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

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

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

33 SAP AG Defining the Interface Structure of the BAPI of the company code. The returned information should include detailed data and address data. To map these requirements to the BAPI interface, 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. A parameter for the address data of the company code. December

34 SAP AG Naming Parameters in the Function Module Naming Parameters in the Function Module Purpose In the previous step you identified the scope and the required contents of the interface parameters. Now you have to specify the names of these parameters in three function module. Process Flow You are only allowed to define export, import and table parameters for the BAPI function module interface. Change and exception parameters are not allowed. 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. The names of BAPI parameters in the BOR and the names of the parameters in the associated function module must be identical. 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. When assigning parameter names follow the guidelines below: The names must be in English. As of Release 4.5A the names of method parameters in the BOR can be up to 30 characters long. Parameter names in function modules that implement the BAPIs can therefore also have up to 30 alphanumeric characters. (In earlier Releases names of parameters in the BOR could only be a maximum of 20 characters long. The associated parameter names in the function module could only be 20 characters long). Choose meaningful names and do not use abbreviations. In the above example based on the company code scenario, 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. An export parameter for the address data of the company code. 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 Name in Function Module Parameter Type Company code COMPANYCODEID IMPORTING Detailed data of company code COMPANYCODEDETAIL EXPORTING Address data of company code COMPANYCODEADDRESS EXPORTING Return Parameters RETURN EXPORTING 34 December 1999

35 SAP AG Naming Parameters in the Function Module December

36 SAP AG Defining Data Formats Defining Data Formats Purpose Here you specify the formats in which the data has to be transferred in the function module interface. BAPIs are not end user interfaces, they are programming interfaces that can be used in diverse application areas, for instance, to connect non-sap systems and PC products to the R/3 System. 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. Data must not be presented in a user-dependent or language-dependent format. For example, the date in a BAPI must be in the internally used format YYYYMMDD, where YYYY is the year, MM the month and DD the day. Standard codes, such as ISO codes must be used, whenever possible. Exceptions SAP-specific data formats must be converted into the data format required externally. This applies to, 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. For further information about these exceptions see Internal and External Data Formats [Page 69]. 36 December 1999

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

38 SAP AG Specifying Development Objects in ABAP Dictionary Before you use an existing data element or domain, you should consult the respective colleague responsible for the object. Choose meaningful names in English for the fields in the structures. Up until Release 4.0 ten characters were available for naming structures; from Release 4.0 you can use up to 30 characters. You can use alphanumeric characters and underscores. As of Release 4.0 default field names in English exist for data elements in the ABAP Dictionary. Whenever possible use these names for the field and parameter names. The report BBAPIFLD generates the English default names for the fields and parameters. To use this report refer to the report documentation. 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], to convert the German field names into English. In the example in the previous steps, the reference fields/tables shown below were identified for the parameters. The first example here uses structures created in Release 3.1. In this Release structure names had a maximum of 10 characters. The second example shows how you could name the structures more meaningfully in Release 4.0. Parameters and their Reference Fields in Release 3.1 Parameter in the Function Module Reference Field/Table COMPANYCODEID COMPANYCODEDETAIL COMPANYCODEADDRESS RETURN BAPI0002_2-COMP_CODE BAPI0002_2 BAPI0002_2 BAPIRETURN1 Parameters and their Reference Fields in Release 4.0 Parameter in the Function Module Reference Field/Table COMPANYCODE COMPANYCODEDETAIL COMPANYCODEADDRESS RETURN BAPI0002_2-COMP_CODE BAPI0002_COMPANYCODEDETAIL BAPI0002_COMPANYCODEADDRESS BAPIRETURN1 38 December 1999

39 SAP AG Specifying Development Objects in ABAP Dictionary December

40 SAP AG Naming the Method in the BOR 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

41 SAP AG 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 Name in Function Module Name in the BOR Company code COMPANYCODE CompanyCode Detailed data of company COMPANYCODEDETAIL CompanyCodeDetail code Address data of company code COMPANYCODEADDRESS Return Parameters RETURN Return CompanyCodeAddress December

42 SAP AG Naming Parameters in the BOR 42 December 1999

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

44 SAP AG Naming the Function Module and the Function Module Group 44 December 1999

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

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

47 SAP AG Creating Development Objects and Documentation 7. Using the BOR/BAPI Wizard, define the function module as a method of the associated SAP business object type in the BOR. Finally, 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]. December

48 SAP AG BAPI Interface and Function Module 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. This example shows the relationships between the method and the function module. The graphic below shows the SAP business object type PurchaseOrder (BUS2012) in the BAPI Browser view of the BOR. Note the following: The business object type has a key field PurchaseOrder. The method we are looking at, GetDetail(), displays details of a purchase order The method consists of several import, export, and import/export (table) parameters. 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. 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>. Standard abbreviations can be used for business 48 December 1999

49 SAP AG BAPI Interface and Function Module object types. It is, however, better to write the name of the object type in full, for example, BAPI_PURCHASEORDER_GETDETAIL and, if necessary, to shorten the method name. BAPI data structures are used. These are recognized by the prefix BAPI, for example, BAPIEKKOL. As of Release 4.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. Underscores in parameter names are no longer allowed. The key field PURCHASEORDER of the business object type is defined as an import parameter. The function module performs authorization checks. The function module picks up exceptions in the Return parameter. From Release 4.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 BAPIEKKOL *" 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 December

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

51 SAP AG BAPI Interface and Function Module December

52 SAP AG Testing the BAPI and Its Documentation 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. Prerequisites Carry out the test together with persons responsible for quality control in your development group. Before you start testing make sure that the underlying function module has been completely implemented and that the BAPI has been correctly defined in the BOR as method of a business object type. Process Flow Testing the Documentation Check that the documentation for each business object type, each BAPI and for each interface parameter is available and that you can understand it. 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. By testing the BAPI call from an external program. You should ensure that your BAPI can be called from within external programs, for example, from a Visual Basic program using SAP s BAPI ActiveX Control [Ext.]. Result If you find any errors in the BAPI implementation, correct them and repeat the tests until you and the quality control team in your group are fully satisfied with the BAPI implementation and with the documentation. 52 December 1999

53 SAP AG 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

54 SAP AG General Programming Guidelines for BAPIs 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. For Further Information See: Structure your BAPI in the most efficient way 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 INCLUDE structures must not be used in BAPI structures. For Further Information See: Transaction Model for Developing BAPIs [Page 58] Transaction Model for Developing BAPIs [Page 58] Specifying Development Objects in the Dictionary [Page 37] 54 December 1999

55 SAP AG 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 For Further Information See: 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 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. 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] Internal and External Data Formats [Page 69] December

56 SAP AG General Programming Guidelines for BAPIs Whenever possible, F4 input help for fields in BAPI parameters must be made available 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 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. For example, the value "10.12" must be formatted as "10.12" and not as "1012". Documentation You must follow these rules for the documentation: Mandatory Rules for Documentation The business object type must be documented For Further Information See: Internal and External Data Formats [Page 69] Internal and External Data Formats [Page 69] For Further Information See: Business object type documentation is stored in the Business Object Repository. SAP information developers must follow the latest business object type documentation guidelines. You can get these from your contact person in BAPI development. 56 December 1999

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

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

59 SAP AG Transaction Model for Developing BAPIs December

60 SAP AG BAPI Transaction Model with Commit BAPI Transaction Model with Commit Use The example below of an external program calling a BAPI to change data in an R/3 System, illustrates how the transaction model affects BAPI development using commit. For example, this could involve a transaction implemented with Visual Basic. Only data from the R/3 System is to be changed. The RFC connection is live the whole time the external program is logged on to the R/3 System to avoid having to connect and disconnect repeatedly. When the RFC connection is already established, an RFC call does not essentially take up any more CPU time than a direct call to the function module from within the R/3 System. There is one BAPI call for each transaction in this transaction model. BAPIs can only be called synchronously. A BAPI call is essentially the call of the underlying RFC capable function module. The process flow of the program consists of the following steps below (see graphic below): Log on... Source code Call BAPI to read and/or change data... Source code Call BAPI to read and/or change data... Source code Log off 60 December 1999

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

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

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

64 SAP AG BAPI Transaction Model Without Commit BAPI Transaction Model Without Commit BAPI call BAPI call BAPIService Transaction Commit call Visual Basic R/3(ABAP) Commit Work... Log on Logical Unit of Work Log off RFC Session The same rules apply in this model as in the BAPI Transaction Model With Commit [Page 60]. But also keep in mind: If a termination message is displayed (message type A) in the Return parameter, a database rollback can be executed by the BAPI. This causes all the activities carried out since the last COMMIT WORK command to be canceled. 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. 64 December 1999

65 SAP AG 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, for example, make table enhancements to master data, 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.5B. Customer exits implemented using the enhancement concept valid before do not have to be reprogrammed. 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. Customers must not program these extensions. Conventional customer exits that can be individually implemented. The customer enhancement concept is not intended for developing individual industry solutions within SAP; a special enhancement concept has been defined for industry solutions. For further information contact the BAPI Development. Features Extension Parameters in BAPI Interfaces First consider which tables used by the BAPI may be suitable for customer enhancements. Then, depending on the requirements of the BAPI, create, one extension parameter for the data import and/or one extension parameter for the data export. Note the following guidelines: The naming convention for the extension parameter is ExtensionIn for import parameter enhancements and ExtensionOut for export parameter enhancements. Define the extension parameter as a table parameter. Use the reference structure BAPIPAREX for extension parameters. With this structure the extension parameter can be used as a generic data container. Extension parameters can relate to BAPI table extensions and/or to customer exits already in the program (see below). We recommend you use BAPI table extensions, if possible, because customer enhancements can be automatically used by the BAPI and do not require customers to rewrite any programs. You should create customer exits to enable customers to enhance BAPI interfaces in situations where it was not anticipated enhancements may be needed. 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. Customer-defined data can then be read and processed by the BAPI automatically. December

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

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

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

69 SAP AG Internal and External Data Formats Internal and External Data Formats Use BAPIs are not end user interfaces, they are programming interfaces that can be used in diverse application areas, for instance, to connect non-sap systems and PC products to the R/3 System. To meet the requirements of this diverse range of applications, a common strategy for representing data in the BAPI interface must be used. 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. Because of the reasons above, BAPIs should not convert data between the internal and external data formats, except in the circumstances outlined below. For example, the date in a BAPI must be in the format used internally, YYYYMMDD, where YYYY is the year, MM the month and DD the day. The graphic below shows the BAPI programming interface where data is transferred at the source code level and not at the application interface level. Interface GUI GUI External data format, for example, 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. December

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

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

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

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

74 SAP AG Use FNAM (name of the function module) The name of the function module that you have to create and that carries out the authorization check for the data element. This function module must have the following predefined interface: *" *"*"Local interface: *" IMPORTING *" VALUE(OBJTYPE) LIKE BAPIF4F-OBJTYPE *" VALUE(METHOD) LIKE BAPIF4F-METHOD *" VALUE(DTEL) LIKE BAPIF4F-DTEL *" VALUE(SHLPNAME) LIKE BAPIF4F-SHLPNAME *" VALUE(TABNAME) LIKE BAPIF4F-TABNAME *" EXPORTING *" VALUE(RETURN) LIKE BAPIF4F-RETURN *" As the template for your function module you can use the function module BF_BAPI_F4_AUTHORITY which provides exactly this interface. Copy this function module and follow the documentation provided with it. The additional parameter SHLPNAME contained in the function module interface provides the name of the active input help for the table or for the data element. The parameter TABNAME contains the name of the value table. The return code of the parameter RETURN is: 'X' if the user of the BAPI is not authorized to call up the valid input values for a field. ' ' (no value), if the user of the BAPI is authorized to display the input values for a field. During runtime the function module is called dynamically by the BAPI HelpValues.GetList(). An authorization check can be carried out at business object type, method or data element level: To carry out authorization check at this level... Business object type BAPI Data Element......the following fields in table BAPIF4T must be filled. OBJTYPE, FNAM OBJTYPE, METHOD, FNAM OBJTYPE, METHOD, DTEL, FNAM 74 December 1999

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

76 SAP AG Providing Interface Descriptions 76 December 1999

77 SAP AG Buffering with Write BAPIs Buffering with Write BAPIs Use To save external systems each having to define their own data, predefined buffering mechanisms should be implemented in all write BAPIs (i.e. BAPIs that create and change data). For SAP internal use this is particularly relevant for BAPIs developed as of Release 4.6A. If you want to implement a buffer for BAPIs in an earlier release, you should first contact a colleague in the central BAPI development group. For BAPIs standard R/3 System mechanisms can be used to buffer application data. Data to be created or changed by a BAPI is not created in the update buffer, it is first collected in the global buffer of the BAPI function module group. Then the whole buffer is updated at a specified time. This has the following advantages: Improvement in performance of the whole system. The updating of individual operations is delayed and they can all be updated together. Techniques such as "array insert" improve system performance. If buffering is not used, each change must be updated separately. 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. With the next change, the system recognizes that the data already exists in the buffer and also makes the change in the buffer. If buffering is not used, the first change would have to be updated before a second change could be made. 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). The buffering mechanism enables application instances to be processed separately in the ALE layer, while still enabling the instances to be updated together. Unlike multiple BAPIs, such as, SaveReplicaMultiple(), this procedure allows error handling of individual instances. Integration BAPIs with buffering mean that there is no need to use or implement multiple BAPIs. The Transaction Model for BAPIs Without Commit [Page 63] in use since Release 4.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. All changes (to one or more instances) are updated together by the BAPI BapiService.TransactionCommit(). This graphic shows the transaction model for BAPIs without buffering: December

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

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

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

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

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

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

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

85 SAP AG Example of Implementation and Process Flow 4. Call meth od Bapi Servi ce.tr ansa ction Com mit() The call of the update module is <object>_savebuffer is flagged using the form routine <buffersave>. As this is already flagged, it is not flagged again. 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. After the COMMIT WORK command, the delete modules subscribed for the BAPI BapiService.TransactionCommit() are called, that is, the function module <object>_clearbuffer is executed and the buffer for the business object <object> is emptied. December

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

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

88 SAP AG Documentation Guidelines Documentation Guidelines Purpose To use a BAPI in an application program, application developers need to know: Which BAPI provides the required data, that is, they need to know what the BAPI can do. How the BAPI is called, that is what are the parameters and fields of the BAPI interface. Application developers access the technical meta data and documentation of BAPIs from the Business Object Repository. This section contains general guidelines for documenting BAPIs. For internal use, SAP provides detailed guidelines on writing BAPI documentation. You can get a copy of the guidelines from your contact person in the BAPI Development group. 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. Readers of BAPI documentation are often not R/3 experts or business application experts. Process Flow To give application developers a complete picture of the functionality of a BAPI, 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. The purpose of this documentation is to explain what the method does and how the communication with external programs works. 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, that is, functions that this BAPI cannot perform? What must you pay particular attention to with this BAPI? For example, is special authorization required to use this BAPI? Are there any Customizing dependencies? What dependencies are there between this BAPI and other BAPIs, and between individual method parameters? If the BAPI uses a COMMIT WORK command or works with buffering, you must include this in the documentation. 88 December 1999

89 SAP AG Documentation on Method Parameters Documentation Guidelines Documentation on the individual parameters is also written in the Function Builder in the associated function module. Parameter documentation should provide answers to the following questions: What is the parameter used for? Which fields must be filled, that is, 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, 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.FieldHelpGetDocu (see Providing Input Help [Page 73]). For this reason you have to write data element documentation for each field in BAPI parameters. Further Documentation To provide the complete context of a BAPI, the information below must also be available: Documentation on the business object type the BAPI is implemented for. Documentation on the key fields of the business object type. December

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

91 SAP AG Programming GetList() BAPIs Programming GetList() BAPIs Use With the BAPI GetList() you can select a range of object key values, for example, company codes and material numbers. The key values returned by this BAPI can be passed on to another BAPI for further processing, for example, the BAPI GetDetail(). The BAPIs GetList() is a class method (instance-independent). Features Provide all the relevant fields in the interface of the GetList() BAPI. How complex and extensive you structure the interface, depends on the requirements the BAPI is to fulfill. Import Parameters The interface of a GetList() BAPI must provide selection parameters, in which the required selection criteria can be passed on by the calling program. The structure of selection parameters is described in the section Selection Parameters [Page 134]. You must also create the parameter MaxRows that enabes you to limit the number of entries selected. This parameter prevents too large a value set from being selected, if the selection parameter specification is not very precise. Use the data element BAPIMAXROW as the reference type for the MaxRows parameter. Export Parameters The key values selected by the BAPI GetList() are returned to the calling program in a table, together with other useful information, for example, short texts. 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]. December

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

93 SAP AG Programming GetDetail() BAPIs Programming GetDetail() BAPIs Use The BAPI GetDetail() is used to read details of specific object instances. The BAPI GetDetail() is an instance method. Features Import Parameters The import parameters of the GetDetail() BAPI must contain the key fields of the business object type. For the associated method definition in the BOR, the key fields must not also be specified as method parameters. For this reason, the BOR/BAPI Wizard does not include the function module parameters for the key fields in the method definition, when it creates a BAPI. Export Parameters The export parameters of a BAPI contain details of the instance. According to the amount of information, this should be structured in several parameters with meaningful names. 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]. December

94 SAP AG Example of a GetDetail() BAPI 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. 94 December 1999

95 SAP AG Example of a GetDetail() BAPI December

96 SAP AG Programming GetStatus() BAPIs Programming GetStatus() BAPIs Use With the BAPI GetStatus() you can retrieve information about the status of a particular object instance. The BAPI GetStatus() is an instance method. Features Import Parameters The import parameters of the GetStatus() BAPI must contain the key fields of the business object type. For the associated method definition in the BOR, the key fields must not also be specified as parameters. For this reason, the BOR/BAPI Wizard does not include the function module parameters for the key fields in the method definition, when it creates a BAPI. Export Parameters The export parameters of the BAPI contain information about the status of an object instance. 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]. 96 December 1999

97 SAP AG 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. The graphic below shows this BAPI in the BAPI Browser. December