BAPI Programming ™ EF

HELP.CABFABAPIREF
BAPI Programming
Release 4.6B
™
BAPI Programming
SAP AG
Copyright
©
Copyright 2000 SAP AG. All rights reserved.
No part of this brochure may be reproduced or transmitted in any form or for any purpose without
the express permission of SAP AG. The information contained herein may be changed without
prior notice.
Some software products marketed by SAP AG and its distributors contain proprietary software
components of other software vendors.
®
®
®
®
®
®
Microsoft , WINDOWS , NT , EXCEL , Word and SQL Server are registered trademarks of
Microsoft Corporation.
®
®
®
®
®
®
®
®
®
IBM , DB2 , OS/2 , DB2/6000 , Parallel Sysplex , MVS/ESA , RS/6000 , AIX , S/390 ,
®
®
®
AS/400 , OS/390 , and OS/400 are registered trademarks of IBM Corporation.
®
ORACLE is a registered trademark of ORACLE Corporation, California, USA.
®
®
INFORMIX -OnLine for SAP and Informix Dynamic Server
Informix Software Incorporated.
®
®
®
TM
are registered trademarks of
®
UNIX , X/Open , OSF/1 , and Motif are registered trademarks of The Open Group.
®
HTML, DHTML, XML, XHTML are trademarks or registered trademarks of W3C , World Wide
Web Consortium, Laboratory for Computer Science NE43-358, Massachusetts Institute of
Technology, 545 Technology Square, Cambridge, MA 02139.
®
JAVA is a registered trademark of Sun Microsystems, Inc. , 901 San Antonio Road, Palo Alto,
CA 94303 USA.
®
JAVASCRIPT is a registered trademark of Sun Microsystems, Inc., used under license for
technology invented and implemented by Netscape.
SAP, SAP Logo, mySAP.com, mySAP.com Marketplace, mySAP.com Workplace, mySAP.com
Business Scenarios, mySAP.com Application Hosting, WebFlow, R/2, R/3, RIVA, ABAP, SAP
Business Workflow, SAP EarlyWatch, SAP ArchiveLink, BAPI, SAPPHIRE, Management
Cockpit, SEM, are trademarks or registered trademarks of SAP AG in Germany and in several
other countries all over the world. All other products mentioned are trademarks or registered
trademarks of their respective companies.
2
December 1999
SAP AG
BAPI Programming
Icons
Icon
Meaning
Caution
Example
Note
Recommendation
Syntax
Tip
December 1999
3
BAPI Programming
SAP AG
Contents
BAPI Programming .............................................................................................6
BAPI Programming Guide............................................................................................................. 7
BAPIs .............................................................................................................................................. 9
BOR ............................................................................................................................................... 11
Terminology ................................................................................................................................. 13
Further Documentation on BAPIs.............................................................................................. 14
Defining and Implementing the BAPI ........................................................................................ 15
BAPI Explorer............................................................................................................................... 17
Working with Display Functions ............................................................................................... 18
Working with Tools and Projects .............................................................................................. 20
Defining the Scenario.................................................................................................................. 21
Reviewing the Scenario Concept ............................................................................................... 23
Defining a BAPI and Its Interface ............................................................................................... 24
Standardized BAPIs ................................................................................................................. 26
Standardized Parameters......................................................................................................... 29
Determining the Object Type and Its Key Fields ...................................................................... 31
Defining the Interface Structure of the BAPI ............................................................................ 32
Naming Parameters in the Function Module ............................................................................ 34
Defining Data Formats.............................................................................................................. 36
Specifying Development Objects in ABAP Dictionary.............................................................. 37
Naming the Method in the BOR ............................................................................................... 40
Naming Parameters in the BOR............................................................................................... 41
Naming the Function Module and the Function Module Group................................................ 43
BAPIs Used for Outbound Processing ..................................................................................... 45
Creating Development Objects and Documentation ............................................................... 46
BAPI Interface and Function Module......................................................................................... 48
Testing the BAPI and Its Documentation .................................................................................. 52
Releasing the BAPI...................................................................................................................... 53
General Programming Guidelines for BAPIs ............................................................................ 54
Transaction Model for Developing BAPIs ................................................................................. 58
BAPI Transaction Model with Commit...................................................................................... 60
BAPI Transaction Model Without Commit ................................................................................ 63
Customer Enhancement Concept for BAPIs ............................................................................ 65
Internal and External Data Formats ........................................................................................... 69
Providing Input Help (F4 Help) ................................................................................................... 73
Providing Interface Descriptions ............................................................................................... 75
Buffering with Write BAPIs ......................................................................................................... 77
Example of Implementation and Process Flow ........................................................................ 83
Improving Performance .............................................................................................................. 86
Documentation Guidelines ......................................................................................................... 88
Programming Standardized BAPIs ............................................................................................ 90
Programming GetList() BAPIs .................................................................................................... 91
Example of a GetList() BAPI..................................................................................................... 92
Programming GetDetail() BAPIs ................................................................................................ 93
4
December 1999
SAP AG
BAPI Programming
Example of a GetDetail() BAPI................................................................................................. 94
Programming GetStatus() BAPIs ............................................................................................... 96
Example of a GetStatus() BAPI................................................................................................ 97
Programming ExistenceCheck() BAPIs..................................................................................... 98
Example of an ExistenceCheck() BAPI .................................................................................. 100
Programming Create() BAPIs ................................................................................................... 102
Example of a Create() BAPI ................................................................................................... 104
Programming Change() BAPIs ................................................................................................. 106
Example of a Change () BAPI ................................................................................................ 108
Programming Delete() BAPIs.................................................................................................... 110
Example of a Delete() BAPI.................................................................................................... 112
Programming Cancel() BAPIs................................................................................................... 113
Example of a Cancel() BAPI................................................................................................... 114
Programming Replicate()/SaveReplica() BAPIs...................................................................... 115
Example of a SaveReplica() BAPI.......................................................................................... 118
Programming Methods for Sub-Objects ................................................................................. 120
Programming Standardized Parameters ................................................................................. 122
Address Parameters.................................................................................................................. 123
Change Parameters ................................................................................................................... 125
Extension Parameters ............................................................................................................... 129
Return Parameters (Error Handling)........................................................................................ 130
Selection Parameters ................................................................................................................ 134
TestRun Parameters.................................................................................................................. 135
Text Transfer Parameters ......................................................................................................... 136
Tools for Developing BAPIs ..................................................................................................... 137
Defining Methods in the BOR Using BOR/BAPI Wizard ........................................................ 138
Converting Internal and External Data Formats ..................................................................... 140
Application Example ............................................................................................................... 142
SAP Enhancements to Released BAPIs.................................................................................. 144
Compatible Enhancements....................................................................................................... 146
Incompatible Enhancements .................................................................................................... 148
Customer Modifications and Developments........................................................................... 151
BAPI Modifications .................................................................................................................... 152
Creating Subtypes .................................................................................................................. 156
Redefining BAPIs ................................................................................................................... 157
Defining Delegation Relationships ......................................................................................... 158
BAPI Development..................................................................................................................... 159
Creating Subtypes .................................................................................................................. 160
Namespaces............................................................................................................................... 161
Using BAPIs in Distributed Systems (ALE) ............................................................................ 164
BAPI Quality Checklist .............................................................................................................. 166
December 1999
5
BAPI Programming
SAP AG
BAPI Programming
BAPI Programming
6
December 1999
SAP AG
BAPI Programming
BAPI Programming Guide
BAPI Programming Guide
Purpose
This document describes the SAP guidelines for developing and implementing Business
Application Programming Interfaces [Page 9] (BAPIs). It is targeted at SAP developers and SAP
partners who want to implement BAPIs.
Customers are also recommended to follow these guidelines when developing BAPIs. All
developments should be done in the customer name space; all changes to existing
developments objects of the SAP standard are considered to be modifications. (See
Namespaces [Page 161]).
As these guidelines are targeted for internal use at SAP, procedures or tools may be mentioned
that do not apply or are not available to customers. Information that applies internally to SAP is
indicated.
This document describes the guidelines valid at the time this document was published.
Prerequisites
To program and implement a BAPI with these guidelines you need to have:
•
Basic knowledge of BAPIs, as described in the BAPI User Guide [Ext.]
•
Knowledge of the ABAP programming language and ABAP Workbench
•
Basic knowledge of the R/3 System
Process Flow
To implement a BAPI follow the processes described in the sections below as closely as
possible:
Defining and Implementing the BAPI [Page 15]
Creating Development Objects and Documentation [Page 46]
General Programming Guidelines for BAPIs [Page 54]
Testing the BAPI and Its Documentation [Page 52]
Releasing the BAPI [Page 53]
Programming Standardized BAPIs [Page 90]
Programming Standardized Parameters [Page 122]
SAP Enhancements to Existing BAPIs [Page 144].
In Release 4.6A in the BAPI Explorer [Page 17] project forms are provided that take
you step by step through the implementation procedure for BAPIs and enable you to
December 1999
7
BAPI Programming
SAP AG
BAPI Programming 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
SAP AG
BAPI Programming
BAPIs
BAPIs
Definition
A Business Application Programming Interface (BAPI) is a precisely defined interface providing
access to processes and data in business application systems such as R/3.
BAPIs of SAP Business Object Types
BAPIs are defined as API methods of SAP business object types. These business object types
and their BAPIs are described and stored in the Business Object Repository [Page 11] (BOR). A
BAPI is implemented as a function module, that is stored and described in the Function Builder.
BAPIs of SAP Interface Types
As of Release 4.5A BAPIs can also describe interfaces, implemented outside the R/3 System
that can be called in external systems by R/3 Systems. These BAPIs are known as BAPIs used
for outbound processing. The target system is determined for the BAPI call in the distribution
model of Application Link Enabling (ALE).
BAPIs used for outbound processing are defined in the Business Object Repository (BOR) as
API methods of SAP Interface Types. Functions implemented outside the R/3 System can be
standardized and made available as BAPIs. For further information see BAPIs Used For
Outbound Processing [Page 45].
Integration
BAPIs can be called within the R/3 System from external application systems and other
programs. BAPIs are the communication standard for business applications. BAPI interface
technology forms the basis for the following developments:
•
Connecting:
•
New R/3 components, for example, Advanced Planner and Optimizer (APO) and Business
Information Warehouse (BW).
•
Non-SAP software
•
Legacy systems
•
Isolating components within the R/3 System in the context of Business Framework
•
Distributed R/3 scenarios with asynchronous connections using Application Link
Enabling (ALE)
•
Connecting R/3 Systems to the Internet using Internet Application Components (IACs)
•
PC programs as frontends to the R/3 System, for example, Visual Basic (Microsoft) or
Visual Age for Java (IBM).
•
Workflow applications that extend beyond system boundaries
•
Customers' and partners' own developments
The graphic below shows how BAPI interfaces enable different types of applications to be linked
together.
December 1999
9
BAPI Programming
SAP AG
BAPIs
BAPIs - Interfaces to the R/3 System
R/3 satellite systems /
distributed systems (ALE)
Business
Workflow
BAPI
BAPI
BAPI
Business
Object
Business
Object
BAPI
BAPI
Business
Object
Internet /
Intranet
VisualBasic/JAVA...
BAPI
BusinessObject
BAPI
Business
Object
Business
Component
BAPI
Isolating components in
the Business Framework
(R/3, R/2)
Business
B
Component
BusinessBAPI
Object
BAPI
BAPI
Customers and partners‘
own developments
Business
Component
For further background information on BAPIs refer to the document BAPI User Guide [Ext.].
10
December 1999
SAP AG
BAPI Programming
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 1999
11
BAPI Programming
SAP AG
BOR
12
December 1999
SAP AG
BAPI Programming
Terminology
Terminology
Definition
The table below contains definitions of the terms used in this document:
Term/Synonym
Definition
Object type
Generic definition of business objects. Describes the general
characteristics and common attributes of instances of SAP
business object types.
Business object type
SAP business object type
Business object
One instance of an SAP business object type
Business object instance
SAP business object
instance
BOR
Business Object Repository
BAPI
Business Application
Programming Interface
Central repository within the R/3 System containing all the
business object types and SAP interface types together with their
definitions and methods.
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.
Interface type
SAP interface type
December 1999
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.
13
BAPI Programming
SAP AG
Further Documentation on BAPIs
Further Documentation on BAPIs
In the Open BAPI Network under the URL www.sap.com/bapi 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.]
Information about using BAPIs in application programs.
BAPI Programming Guide
[Page 7]
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.
ALE Programming Guide [Ext.]
Information about ALE technology (Application Link Enabling),
including guidelines on using and programming BAPIs
implemented in ALE distributed environments.
Library of ALE Business
Processes [Ext.]
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.
BAPI ActiveX Control [Ext.]
Describes how external client applications can use SAP’s
BAPI ActiveX Control to access SAP business objects.
Calling BAPIs with BAPI
Control [Ext.] in the
Tutorial: Communication
Interfaces [Ext.]
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
SAP Automation RFC and
BAPI Interfaces [Ext.]
Describes how C++ and Java class libraries are used to
access BAPIs on C++ and Java platforms.
R/3 DCOM Component
Connector [Ext.]
Describes how the R/3 DCOM Component Connector
developed jointly by SAP and Microsoft is used to integrate
R/3 objects and COM objects seamlessly. 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
SAP AG
BAPI Programming
Defining and Implementing the BAPI
Defining and Implementing the BAPI
Purpose
Various components of the ABAP Workbench are used when you define and implement a BAPI.
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
Business Object BO:
Function module
BAPI_BO_M1
Method 1 = M1
Method 2 = M2
Function module
BAPI_BO_M2
ABAP
Dictionary
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 1999
15
BAPI Programming
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
For further information see:
1. Defining the scenario in which the BAPI
will be used
Defining the Scenario [Page 21]
2. Reviewing the BAPI scenario and how the
BAPIs interact with one another
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
SAP AG
BAPI Programming
BAPI Explorer
BAPI Explorer
Definition
The BAPI Explorer is the R/3 System working environment for developing BAPIs themselves and
for developing with BAPIs.
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 1999
17
BAPI Programming
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
SAP AG
BAPI Programming
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 1999
19
BAPI Programming
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
SAP AG
BAPI Programming
Defining the Scenario
Defining the Scenario
Purpose
Before you program a BAPI you should clearly define the processes and situations the BAPI will
be used for. 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 1999
21
BAPI Programming
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
SAP AG
BAPI Programming
Reviewing the Scenario Concept
Reviewing the Scenario Concept
Purpose
In the previous step you created a concept for a scenario a BAPI could be applied to. 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 1999
23
BAPI Programming
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)
Function Builder
Business object : CompanyCode
Function module
Interfaces
: ....
Parameter Importing : COMPANYCODEID
Key fields
: CompanyCodeId
: ....
Methods
: GetDetail
:
Exporting : COMPANYCODE_DETAIL
COMPANYCODE_ADDRESS
Attributes
Parameters
: BAPI_COMPANYCODE_GETDETAIL
RETURN
CompanyCodeDetail
CompanyCodeAddress
Return
Events
: ....
ABAP Dictionary
Structures
Fields
BAPI 0002_2
:
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
For further information see:
1. Check if the BAPI is in the Standardized BAPIs
category.
Standardized BAPIs [Page 26]
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.
24
December 1999
SAP AG
BAPI Programming
Defining a BAPI and Its Interface
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
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]
4. Give names to the required parameters in the
function module.
Naming Parameters in the Function
Module [Page 34]
5. Define the data formats in which the values must
be transferred in the function module interface.
Defining Data Formats [Page 36]
6. Specify the required data objects in the ABAP
Dictionary.
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.
Naming Parameters in the BOR
[Page 41]
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.
Naming the Function Module and the
Function Module Group [Page 43]
Result
Once you have completed these steps, you will have defined your BAPI.
December 1999
25
BAPI Programming
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
SAP AG
BAPI Programming
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 1999
27
BAPI Programming
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
SAP AG
BAPI Programming
Standardized Parameters
Standardized Parameters
Use
There are some parameters that can be created for various BAPIs because they contain the
same or equivalent data in all BAPIs. 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 1999
29
BAPI Programming
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
SAP AG
BAPI Programming
Determining the Object Type and Its Key Fields
Determining the Object Type and Its Key Fields
Purpose
Object type
You have to identify the SAP business object type required for your BAPI in the Business Object
Repository or if necessary, 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.
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.
Process Flow
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 1999
31
BAPI Programming
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]
You cannot use change and exception parameters in a function module which
implements a BAPI.
Process Flow
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
SAP AG
BAPI Programming
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 1999
33
BAPI Programming
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
Company code
Detailed data of company code
Address data of company code
Return Parameters
34
Name in Function Module
COMPANYCODEID
COMPANYCODEDETAIL
COMPANYCODEADDRESS
RETURN
Parameter Type
IMPORTING
EXPORTING
EXPORTING
EXPORTING
December 1999
SAP AG
BAPI Programming
Naming Parameters in the Function Module
December 1999
35
BAPI Programming
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
SAP AG
BAPI Programming
Specifying Development Objects in ABAP Dictionary
Specifying Development Objects in ABAP Dictionary
Purpose
After you have specified the contents and names of the required interface parameters, 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
F1
F2
Structure S2
F1
F2
Structure S2 includes structure S1
F3
Structures after adding field F3:
Structure S1
F1
F2
F3
Structure S2
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 1999
37
BAPI Programming
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
BAPI0002_2-COMP_CODE
COMPANYCODEDETAIL
BAPI0002_2
COMPANYCODEADDRESS
BAPI0002_2
RETURN
BAPIRETURN1
Parameters and their Reference Fields in Release 4.0
38
Parameter in the Function Module
Reference Field/Table
COMPANYCODE
BAPI0002_2-COMP_CODE
COMPANYCODEDETAIL
BAPI0002_COMPANYCODEDETAIL
COMPANYCODEADDRESS
BAPI0002_COMPANYCODEADDRESS
RETURN
BAPIRETURN1
December 1999
SAP AG
BAPI Programming
Specifying Development Objects in ABAP Dictionary
December 1999
39
BAPI Programming
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
SAP AG
BAPI Programming
Naming Parameters in the BOR
Naming Parameters in the BOR
Process Flow
You can now assign names to the individual method parameters in the Business Object
Repository (BOR).
These names are based on the names of the parameters in the function module that you
assigned in Naming Parameters in the Function Module [Page 34].
When naming BAPI parameters in the BOR follow the guidelines below:
•
The components of parameter names in the BOR are separated by upper and lower case
letters to make them easier to read. Each new word in the parameter name begins with a
capital letter, for example, CompanyCodeDetail.
•
From Release 4.0 the names of BAPI parameters in the BOR and the names of the
parameters in the associated function module must be identical except for the use of upper
and lower case letters. This was not necessarily the case for BAPIs developed before
Release 4.0.
•
Standardized parameters have specified names. For more information see Programming
Standardized Parameters [Page 122].
If you create your BAPI in the BOR using the BOR/BAPI Wizard, the Wizard uses the
parameter names in the function module as the default names of the method
parameters. For information about the BOR/BAPI Wizard see Defining Methods in the
BOR Using the BOR/BAPI Wizard [Page 138].
•
Parameter names in the BOR must be in English.
•
Parameter names in the BOR cannot be more than 30 characters.
In the example in the previous steps, four parameters for one BAPI were identified
and the names of these parameters specified in the function module.
The table below shows what the parameter names could look like in the function
module and in the BOR.
Parameters and their Names in the Function Module and in the BOR
Contents
Name in Function Module
Name in the BOR
Company code
COMPANYCODE
CompanyCode
Detailed data of company
code
COMPANYCODEDETAIL
CompanyCodeDetail
Address data of company
code
COMPANYCODEADDRESS
CompanyCodeAddress
Return Parameters
RETURN
Return
December 1999
41
BAPI Programming
SAP AG
Naming Parameters in the BOR
42
December 1999
SAP AG
BAPI Programming
Naming the Function Module and the Function Module Group
Naming the Function Module and the Function Module
Group
Purpose
Here you specify the name of the function module the BAPI is based on.
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 1008.
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 1999
43
BAPI Programming
SAP AG
Naming the Function Module and the Function Module Group
44
December 1999
SAP AG
BAPI Programming
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 1999
45
BAPI Programming
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
Tools / Further Information
1. If necessary, create the required SAP
business object type in the Business Object
Repository.
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.].
2. The data objects, for example, structures,
fields and domains are stored in the ABAP
Dictionary.
For further information see the ABAP
Dictionary [Ext.].
3. Create the function module in the Function
Builder and the function group, if required.
For further information see the BC ABAP Workbench: Tools [Ext.].
4. Create the documentation for the BAPI and
for each interface parameter and for each
parameter field.
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.
Documentation on the BAPI and its
parameters is essential because it is very
difficult to use a BAPI that has not been
well documented.
See the general Documentation
Guidelines [Page 88].
5. If required, generating the function modules
that can convert between the internal and
external data formats.
For details on how to do this see
Converting Between Internal and
External Data Formats [Page 140].
6. Writing the program for the function module
that the BAPI is based on.
For further information see General
Programming Guidelines for BAPIs
[Page 54]
and
Programming Standardized BAPIs
[Page 90]
Note that the COMMIT WORK command
must not be used in the function module.
For an example of a function module
that implements a BAPI see BAPI
Interface and Function Module [Page
48].
46
December 1999
SAP AG
BAPI Programming
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.
December 1999
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].
47
BAPI Programming
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:
•
48
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
December 1999
SAP AG
BAPI Programming
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
VALUE(PO_ADDRESS) LIKE BAPIADDRESS
STRUCTURE BAPIADDRESS
*"
*"
*"
*"
*"
*"
*"
*"
*"
*"
*"
*"
*"
*"
*"
TABLES
December 1999
BAPIEKKOL
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
49
BAPI Programming
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
SORT
SORT
SORT
SORT
SORT
SORT
SORT
SORT
PO_ITEMS BY PO_NUMBER PO_ITEM.
PO_ITEM_ACCOUNT_ASSIGNMENT BY PO_ITEM SERIAL_NO.
PO_ITEM_SCHEDULES BY PO_ITEM SERIAL_NO.
PO_ITEM_HISTORY BY PO_ITEM SERIAL_NO.
PO_ITEM_HISTORY_TOTALS BY PO_ITEM SERIAL_NO.
PO_ITEM_LIMITS BY PCKG_NO
PO_ITEM_CONTRACT_LIMITS BY PCKG_NO LINE_NO.
PO_ITEM_SERVICES BY PCKG_NO LINE_NO.
PO_ITEM_SRV_ACCASS_VALUES BY PCKG_NO LINE_NO SERNO_LINE.
ENDFUNCTION.
50
December 1999
SAP AG
BAPI Programming
BAPI Interface and Function Module
December 1999
51
BAPI Programming
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
SAP AG
BAPI Programming
Releasing the BAPI
Releasing the BAPI
After you have completed the function module and BAPI tests, the development of the BAPI is
complete.
You can now release the function module the BAPI is based on and the method in the Business
Object Repository (BOR).
Once the BAPI has been released, it becomes available as a fully implemented method of a
business object type. Releasing also prevents anyone making incompatible changes to the BAPI,
because all changes made to a released BAPI are automatically checked for compatibility in the
BOR and the ABAP Dictionary, and incompatible changes are rejected. For more information
about what to look out for when making changes to existing BAPIs see SAP Enhancements to
Existing BAPIs [Page 144].
The BAPI must be released in cooperation and agreement with the persons responsible for the
development objects involved and those responsible for quality control.
To release a BAPI follow the steps below:
1. First release the function module in the Function Builder. Select
Function module → Release → Release.
2. Set the status of the method to 'released' in the Business Object Builder.
3. Select the relevant SAP business object type in the Business Object Builder and open
the node Methods.
4. Place the cursor on your BAPI and select Edit → Change release status → Object type
component → In Released.
5. Verify the new status of the function module in the Function Builder and the method in
the BOR.
Releasing BAPIs in the Context of ALE
If you are implementing the BAPI in an asynchronous context of Application Link Enabling (ALE),
you have to also release the IDoc associated with the BAPI. For more information see the ALE
Programming Guide [Ext.].
December 1999
53
BAPI Programming
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
For Further Information See:
Minimize interface complexity.
Supply the BAPI with the minimum of data and group the
data from a business perspective.
Structure your BAPI in the most efficient way
Improving Performance [Page 86]
Mandatory Rules
You must follow these rules for all BAPIs:
General Mandatory Rules
For Further Information See:
BAPIs must not invoke COMMIT WORK
commands.
Transaction Model for Developing BAPIs
[Page 58]
BAPIs must not contain the following commands:
Transaction Model for Developing BAPIs
[Page 58]
•
CALL TRANSACTION
•
SUBMIT REPORT
•
SUBMIT REPORT AND RETURN
INCLUDE structures must not be used in BAPI
structures.
54
Specifying Development Objects in the
Dictionary [Page 37]
December 1999
SAP AG
BAPI Programming
General Programming Guidelines for BAPIs
Database changes can only be made through
updates.
Transaction Model for BAPIs Without
Commit [Page 63]
The global memory must not be used to transfer
values.
Transaction Model for Developing BAPIs
[Page 58]
Due to transparency it is strongly recommended
not to use Set and Get.
Transaction Model for Developing BAPIs
[Page 58]
If required every BAPI must be able to carry out
its own authorization checks.
Values relevant for Customizing are not allowed
to be changed.
Programming Create() BAPIs [Page 102]
and Programming Change() BAPIs [Page
106]
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.
Return Parameters (Reporting Errors) [Page
130]
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.
Fields and Parameters
You must follow these rules for BAPI fields and parameters:
Mandatory Rules for Fields and Parameters
Standardized parameters must be implemented
consistently.
For Further Information See:
Programming Standardized Parameters
[Page 122]
Each BAPI must have a return parameter for
returning messages to the calling application.
Return Parameters (Reporting Errors) [Page
130]
All field and parameter names must be in English
Naming Parameters in the Function Module
[Page 34]
Specifying Development Objects in the
Dictionary [Page 37]
All quantity and amount fields must be assigned
quantity unit fields.
All currency amount fields must be assigned
currency IDs.
Internal and External Data Formats [Page
69]
All key fields in GetDetail() and GetList() BAPIs
must be displayed as text fields.
December 1999
55
BAPI Programming
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
For Further Information See:
Only the internal data format can be used in
BAPIs
Internal and External Data Formats [Page
69]
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.
Internal and External Data Formats [Page
69]
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
For Further Information See:
The business object type must be documented
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
SAP AG
BAPI Programming
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 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]
The documentation must be checked for
completeness and comprehensibility.
December 1999
57
BAPI Programming
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
0131838, "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
SAP AG
BAPI Programming
Transaction Model for Developing BAPIs
December 1999
59
BAPI Programming
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
SAP AG
BAPI Programming
BAPI Transaction Model with Commit
BAPI Transaction Model with Commit
BAPI call
(RFC call of function module)
Visual Basic
...
...
...
...
R/3(ABAP)
Time
Log off
Log on
Logical
Unit of Work
Logical
Unit of Work
“Commit Work“ call
RFC session
What do the terms "LUW" and "stateless" mean to BAPIs that have been implemented in the
framework of this transaction model?
If a transaction represents one Logical Unit of Work and in addition is supposed to be stateless,
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 1999
61
BAPI Programming
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 0131838, "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
SAP AG
BAPI Programming
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 1999
63
BAPI Programming
SAP AG
BAPI Transaction Model Without Commit
BAPI Transaction Model Without Commit
BAPI
call
Visual Basic
...
BAPI
call
...
BAPIService
Transaction Commit call
...
R/3(ABAP)
...
...
Commit Work
Log on
Log off
Logical
Unit of Work
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
SAP AG
BAPI Programming
Customer Enhancement Concept for BAPIs
Customer Enhancement Concept for BAPIs
Use
The customer enhancement concept for BAPIs enables customers to enhance business object
types without modifications, 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 1999
65
BAPI Programming
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
BAPI Table Extension:
BAPI_TE_STRAVELAG
Parameter:
AgencyDataIn
Felder AGENCYNUM
.APPEND
CUSTOMER FIELD _1
CUSTOMER FIELD _2
CUSTOMER FIELD _3
AgencyNumber
Return
ExtensionIn
Fields from ExtensionIn:
Structure
BAPI_TE_
STRAVEL
AG
…
…
Valuepart1
Valuepart2
Valuepart3
Valuepart4
Values from 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
SAP AG
BAPI Programming
Customer Enhancement Concept for BAPIs
•
Create one BAPI table extension for each table to be extended.
•
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 1999
67
BAPI Programming
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
SAP AG
BAPI Programming
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.
BAPI Programming Interface
GUI
Application
program
GUI
BAPI
Application
program
External data format, for
example, on the screen (GUI)
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 1999
69
BAPI Programming
SAP AG
BAPI Programming 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
SAP AG
BAPI Programming
BAPI Programming 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 1999
71
BAPI Programming
SAP AG
BAPI Programming 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
SAP AG
BAPI Programming
Providing Input Help (F4 Help)
Providing Input Help (F4 Help)
Use
Users of R/3 Systems can use the F4 key to retrieve information about the possible input values
for screen fields.
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 1999
73
BAPI Programming
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
74
... ......the following fields in table BAPIF4T
must be filled.
OBJTYPE, FNAM
OBJTYPE, METHOD, FNAM
OBJTYPE, METHOD, DTEL, FNAM
December 1999
SAP AG
BAPI Programming
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 1999
75
BAPI Programming
SAP AG
Providing Interface Descriptions
76
December 1999
SAP AG
BAPI Programming
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.
BAPIs with buffering mean that there is no need to use or implement multiple BAPIs.
Integration
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 1999
77
BAPI Programming
SAP AG
Buffering with Write BAPIs
Transaction Model Without Buffering
Create i1
BapiService.TransactionCommit
Create i2
Change i1 BapiService.TransactionCommit
Client
(e.g. Visual
Basic)
Server (R/3)
i1 is passed
to pdate
78
LUW
i2 passed
to update
Update
performed:
i1 and i2 are
updated separately
LUW
i1 passed
to update
Update
performed:
i1 updated
December 1999
SAP AG
BAPI Programming
Buffering with Write BAPIs
This graphic shows the transaction model for BAPIs with buffering:
Transaction Model with Buffering
Create i1
Change i1
Create i2
BapiService.TransactionCommit
Client
(z.B. Visual
Basic)
Server (R/3)
LUW
Instances are
created and
processed
in the buffer
Buffer contents passed to
update. Update is
performed: i1 and i2
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 1999
79
BAPI Programming
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
SAP AG
BAPI Programming
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 1999
81
BAPI Programming
SAP AG
Documenting Read BAPIs
Each read BAPI that handles the buffering of corresponding write methods must be documented.
82
December 1999
SAP AG
BAPI Programming
Example of Implementation and Process Flow
Example of Implementation and Process Flow
The example below describes the implementation and process flow of BAPIs with buffering.
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 1999
83
BAPI Programming
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 4712. 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
Process Flow
1.
Call
meth
od
<obje
ct>.C
reate(
) for
insta
nce
4711
The delete module <object>_clearbuffer is subscribed by calling
buffer_subscribe_for_refresh for the BAPI BapiService.TransactionCommit().
2.
Call
meth
od
<obje
ct>.C
reate(
) for
insta
nce
4712
3.
Call
meth
od
<obje
ct.>
Chan
ge()
for
insta
nce
4711
84
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.
December 1999
SAP AG
BAPI Programming
Example of Implementation and Process Flow
The call of the update module is <object>_savebuffer is flagged using the form routine
<buffersave>. As this is already flagged, it is not flagged again.
4.
Call
meth
od
Bapi
Servi
ce.Tr
ansa
ction
Com
mit()
The form routine <buffersave> of the function group <object> is executed once only by
the COMMIT WORK command. This executes the update module and the contents of
the buffer is transferred to the update program.
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 1999
85
BAPI Programming
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 BAPI Programming
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
SAP AG
BAPI Programming
Improving Performance
•
The less specific the (partial) key of a modified data record is, the more likely it is that the
data record will be accessed by multiple BAPIs, causing the record to be locked. 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 1999
87
BAPI Programming
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
SAP AG
BAPI Programming
Documentation Guidelines
Documentation on Method Parameters
Documentation on the individual parameters is also written in the Function Builder in the
associated function module. 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 1999
89
BAPI Programming
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
SAP AG
BAPI Programming
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 1999
91
BAPI Programming
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
SAP AG
BAPI Programming
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 1999
93
BAPI Programming
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
SAP AG
BAPI Programming
Example of a GetDetail() BAPI
December 1999
95
BAPI Programming
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
SAP AG
BAPI Programming
Example of a GetStatus() BAPI
Example of a GetStatus() BAPI
The BAPI GetStatus() of the business object type DebtorCreditAccount (BUS1010) is used here
as an example.
The graphic below shows this BAPI in the BAPI Browser.
December 1999
97
BAPI Programming
SAP AG
Programming ExistenceCheck() BAPIs
Programming ExistenceCheck() BAPIs
Use
The BAPI ExistenceCheck() checks whether an entry exists in the database for an SAP business
object type, for example, whether the customer master has been created.
The ExistenceCheck() BAPI is an instance method.
Features
You can implement this method as a BAPI and/or as a method of SAP Business Workflow. If you
implement this method as a BAPI, it only has to be implemented once, because an
ExistenceCheck() BAPI can also be used by SAP Business Workflow.
To get the highest possible performance from the BAPI ExistenceCheck(), you should reduce the
number of columns to as few as possible before selecting the table rows.
select single bukrs from bkpf into lv_bukrs
where bukrs = bkpf-bukrs
and
belnr = bkpf-belnr
and
gjahr = bkpf-gjahr.
instead of
select single * from bkpf
where bukrs = bkpf-bukrs
and
belnr = bkpf-belnr
and
gjahr = bkpf-gjahr.
Import Parameters
The BAPI’s import parameters in the function module only contain the key fields of the business
object type.
Export Parameters
To report messages from the method call back to the calling program, you should create only the
export parameter Return . For more information about this parameter see Return Parameters
(Error Handling) [Page 130].
Activities
When a business object type is created, as the default, it inherits a definition of the method
ExistenceCheck() through the interface IFSAP. For this reason, you can create an
ExistenceCheck() BAPI using the BOR/BAPI Wizard, as the method name ExistenceCheck()
already exists for the business object type.
We recommend therefore, that you redefine the existing method ExistenceCheck() manually in
the BOR, via the menu path Edit → Redefine.
•
98
Enter the function module that implements the ExistenceCheck() BAPI.
December 1999
SAP AG
BAPI Programming
Programming ExistenceCheck() BAPIs
•
Create the method parameter RETURN (the key fields of the business object type are not
included in the method definition in the BOR).
December 1999
99
BAPI Programming
SAP AG
Example of an ExistenceCheck() BAPI
Example of an ExistenceCheck() BAPI
The BAPI ExistenceCheck() of the business object type CompanyCode (BUS0002) is used here
as an example.
The graphic below shows this BAPI in the BAPI Browser.
100
December 1999
SAP AG
BAPI Programming
Example of an ExistenceCheck() BAPI
December 1999
101
BAPI Programming
SAP AG
Programming Create() BAPIs
Programming Create() BAPIs
Use
The BAPI Create() creates one instance of an SAP business object type. Likewise, the BAPI
CreateMultiple() creates several instances of a business object type simultaneously.
If a workflow method called Create already exists for the business object type in question, you
can use the name CreateFromData() for your BAPI. Create() is the preferred name for this BAPI.
The BAPIs Create() and CreateMultiple() are class methods (instance-independent).
For each Create() BAPI a method must be provided with which the created business object
instance can be deleted or cancelled. To do this, depending on the business application practice,
you should implement one of the BAPIs below:
•
Delete(), which deletes a business object instance from the database. For more information
see Programming Delete() BAPIs [Page 110].
•
Cancel() which cancels a business object instance. For more information see Programming
Cancel() BAPIs [Page 113].
Features
Import Parameters
The BAPI’s import parameters in the function module contain the data required to uniquely
identify an instance. For this you can either enter all object keys or else you must ensure that
these can be derived.
If required, you can also use a test run parameter to check the entry for an object instance before
actually creating the instance in the database. For further information see Test Run Parameters
[Page 135].
You can create a change parameter to identify the values to create the instance with and to tell
differentiate these values from the initial values when the BAPI is called. We recommend that you
identify the change-relevant fields by flagging them. For more information see Change
Parameters [Page 125].
Export Parameters
To make the object key available to the calling program, the entire key fields must be returned in
the export parameters.
To report messages from the method call back to the calling program, you should create the
export parameter RETURN. For more information about this parameter see Return Parameters
(Error Handling) [Page 130].
Extension parameters
You can create extension parameters to enable customers to enhance the functionality of BAPIs
without making modifications. For information about extension parameters see Customer
Enhancement Concept for BAPIs [Page 65].
102
December 1999
SAP AG
BAPI Programming
Programming Create() BAPIs
Avoiding Incompatibilities with Customizing Settings
It could be possible that certain values set by Customizing appear differently in the BAPI
interface. These values cannot be overwritten by a Create() BAPI.
To avoid any incompatibility with Customizing settings, you should implement a Create() BAPI in
the following way:
•
The BAPI should transfer all the fields and check them against the Customizing settings. If
the Customizing settings write-protect a field, the data in this field cannot be overwritten by
data in the BAPI interface.
•
For every incidence of incompatibility an error message must be returned to the calling
program. For example, “Customizing settings do not allow the field 'MyAsset-AssetName' to
be modified ”.
•
All the fields that are assigned default values by Customizing and are therefore writeprotected, must be documented.
External Key Assignment
For Create() BAPIs with an external key assignment the caller transfers the key (ID) to the object
instance to be created, for example, to a document number.
Keep in mind that you have to convert the specified keys explicitly in upper case letters in the
source code of this type of Create() BAPIs. Otherwise keys are created that cannot be used in
dialog applications. This is because with dialog applications external keys are always converted
implicitly in upper case letters.
Locking
We recommend that you implement Create() BAPIs without the locking function and create your
own BAPIs instead that lock the relevant data.
December 1999
103
BAPI Programming
SAP AG
Example of a Create() BAPI
Example of a Create() BAPI
The BAPI Create() of the business object type InternalOrder (BUS20745) is used here as an
example.
The graphic below shows this BAPI in the BAPI Browser.
104
December 1999
SAP AG
BAPI Programming
Example of a Create() BAPI
December 1999
105
BAPI Programming
SAP AG
Programming Change() BAPIs
Programming Change() BAPIs
Use
The BAPI Change() changes an existing instance of an SAP business object type, for example, a
sales order.
The BAPI Change() is an instance method, whereas the BAPI ChangeMultiple() is a class
method (instance-independent).
Features
Import Parameters
The import parameters of the Change() BAPI must contain the key fields of the business object
type.
If required, you can create also create these parameters:
•
A test run parameter for checking the entry for an object instance before actually
creating/changing the instance in the database.
•
A change parameter to identify parameter fields containing modified values and parameter
fields that have not been modified.
For more information about these parameters see Standardized Parameters [Page 29].
Export Parameters
To make the object key available to the calling program, the entire key fields must be returned in
the export parameters.
To report messages from the method call back to the calling program, you should create the
export parameter RETURN. For more information about this parameter see Return Parameters
(Error Handling) [Page 130].
Extension parameters
You can create extension parameters to enable customers to enhance the functionality of BAPIs
without making modifications. For information about extension parameters see Customer
Enhancement Concept for BAPIs [Page 65].
Avoiding Incompatibilities with Customizing Settings
It could be possible that certain values set by Customizing appear differently in the BAPI
interface. These values cannot be overwritten by a Change() BAPI.
To avoid incompatibility with Customizing settings, you should implement a Change() BAPI in the
following way:
•
The BAPI should transfer all the fields and check them against the Customizing settings. If
the Customizing settings write-protect a field, the data in this field cannot be overwritten by
data in the BAPI interface.
•
For every incidence of incompatibility an error message must be returned in the return
parameter to the calling program. For example, “Customizing settings do not allow the field
'MyAsset-AssetName' to be modified ”.
106
December 1999
SAP AG
BAPI Programming
Programming Change() BAPIs
•
All the fields that are assigned default values by Customizing and are therefore writeprotected, must be documented.
Locking
We recommend that you implement Change() BAPIs without the locking function and create your
own BAPIs instead that lock the relevant data.
December 1999
107
BAPI Programming
SAP AG
Example of a Change () BAPI
Example of a Change () BAPI
The BAPI Change of the business object type PurchaseRequisition (BUS2105) is used here as
an example.
The graphic below shows this BAPI in the BAPI Browser.
108
December 1999
SAP AG
BAPI Programming
Example of a Change () BAPI
December 1999
109
BAPI Programming
SAP AG
Programming Delete() BAPIs
Programming Delete() BAPIs
Use
The BAPI Delete() deletes an instance of an SAP business object type from the database.
Likewise, the BAPI DeleteMultiple() deletes several instances of a business object type. Delete()
BAPIs must always delete entire instances, for example, a whole material master.
(Whereas 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. For
more information see Programming Cancel() BAPIs [Page 113]).
A delete() BAPI can delete immediately or at a later time by setting the deletion flag. The type of
deletion you use in your BAPI is irrelevant to the caller, so you do not have to include these
details in the BAPI interface.
The BAPI Undelete() is used to reset a deletion flag that has been set for a specific object.
The BAPIs Delete() and Undelete() are instance methods, whereas the BAPIs DeleteMutliple()
and UndeleteMutliple() are class methods (instance-independent).
Features
The interfaces of the Delete() and Undelete() BAPIs should be identical.
Import Parameters
The BAPI's import parameters have to identify the business object instances to be deleted.
•
If an instance is to be deleted, you have to create a parameter for each key field in the
business object type.
•
If several instances are to be deleted, you must create a table for the key fields of the
business object type. You can do this using a range table.
If required, you can create also create these parameters:
•
A test run parameter for checking the entry for an object instance before actually deleting the
instance from the database.
•
When the BAPI DeleteMultiple() is used, it must be possible to use the selection criteria to
select the object instances to be deleted. To do this you can create selection parameters.
For more information about these parameters see Standardized Parameters [Page 29].
Implement the interface of a Delete() BAPI so that it is not possible to delete all the
instances simply by parameterizing the interface, for example by specifying default
settings.
Export Parameters
To report messages from the method call back to the calling program, you should create only the
export parameter Return . For more information about this parameter see Return Parameters
(Error Handling) [Page 130].
110
December 1999
SAP AG
BAPI Programming
Programming Delete() BAPIs
Extension parameters
You can create extension parameters to enable customers to enhance the functionality of BAPIs
without making modifications. For information about extension parameters see Customer
Enhancement Concept for BAPIs [Page 65].
Locking
We recommend that you implement Delete() BAPIs without the locking function and create your
own BAPIs instead that lock the relevant data.
December 1999
111
BAPI Programming
SAP AG
Example of a Delete() BAPI
Example of a Delete() BAPI
The BAPI Delete() of the business object type EmployeeTrip (BUS2089) is used here as an
example.
The graphic below shows this BAPI in the BAPI Browser.
112
December 1999
SAP AG
BAPI Programming
Programming Cancel() BAPIs
Programming Cancel() BAPIs
Use
The Cancel() BAPI cancels one instance of a business object.
Unlike the BAPI Delete() [Page 110], which deletes an object instance from the database, with
the BAPI Cancel():
•
The canceled instance of the business object is not deleted
•
An additional instance is created with which the instance of the business object is deleted
The Cancel() BAPI is used to cancel business processes such as goods movements or invoice
receipts.
The Cancel() BAPI is an instance method.
Features
Import Parameters
The data of the instance to be created comes from the data of the business object instance to be
cancelled.
You can also create further parameters to specify information relevant for the actual cancellation
process, for example, the name of the user performing the cancellation.
If required, you can also create a test run parameter, which can check the details of the object
instance before it is actually canceled. For more information about this parameter see Test Run
Parameters [Page 135].
Export Parameters
To report messages from the method call back to the calling program, you should create the
parameter Return. For more information about this parameter see Return Parameters (Error
Handling) [Page 130].
You have to put the key of the created instance in another export parameter.
Locking
We recommend that you implement Cancel() BAPIs without the locking function and create your
own BAPIs instead that lock the relevant data.
December 1999
113
BAPI Programming
SAP AG
Example of a Cancel() BAPI
Example of a Cancel() BAPI
The BAPI Cancel() of the business object type GoodsMovement (BUS2017) is used here as an
example.
The graphic below shows this BAPI in the BAPI Browser.
114
December 1999
SAP AG
BAPI Programming
Programming Replicate()/SaveReplica() BAPIs
Programming Replicate()/SaveReplica() BAPIs
Use
To replicate an instance of a business object, for example, if you want to exchange data between
two distributed systems in the context of Application Link Enabling (ALE), you have to implement
certain standardized BAPIs (see also Using BAPIs in Distributed Systems (ALE) [Page 164].
The objective of replicating business object types is to make specific instances of an object type
available on one or more additional systems. The replicated instances are usually created under
the same object key.
The interface of these BAPIs depends on the characteristics and contents of the business object
that is to be replicated. For this reason replicate BAPIs must be implemented for each business
object.
Business objects instances can be replicated in two ways:
•
By request ("Pull")
System "A" requests replicates from system "B". Then system "B" replicates the
requested business object instances on system "A".
•
Using subscription lists ("Push")
In this approach system "B" maintains a list of systems requiring replicates. At regular
intervals system "B" replicates the business object instances to all the systems in the list.
Both of the above replication methods can be implemented with the BAPIs Replicate(),
SaveReplica() and SaveReplicaMultiple(). These BAPIs are both class methods (instanceindependent).
Features
Replicate()
The BAPI Replicate() is called in the system which contains the originals of the business object
instances to be replicated. The BAPI Replicate() is used for:
•
Identifying the business object instances to be replicated and to organize the required data
•
Calling the SaveReplica() methods in the receiving system
The BAPI Replicate() can only request the replication of instances of a business object. The
actual replication is carried out when the server system calls one of the SaveReplica() BAPIs
described below on the client system.
You must follow the steps below:
1. Select the data to be replicated.
2. Determine the receiver.
This is done in the ALE distribution model using the function module
ALE_SYNC_BAPI_GET_RECEIVER. For information on this function module see
Distribution Using BAPIs [Ext.] in the ALE Programming Guide. You can also restrict the
number of receivers in the parameter Recipients of the Replicate() BAPI.
3. Loop via the receiver and call the relevant SaveReplica() BAPI.
December 1999
115
BAPI Programming
SAP AG
Programming Replicate()/SaveReplica() BAPIs
4. Enter a value in the return parameter and complete the Replicate() BAPI.
Import Parameters
The interface of the Replicate() BAPI must contain the following parameters:
•
Parameters which identify the business object instances to be replicated.
You could implement these, for example, using a range table for the key fields of the
business object types or using selection parameters that enable you to select instances
to be replicated. (See also Selection Parameters [Page 134]).
•
Parameter Recipients
This parameter identifies the logical systems in which the business object instances are
to be replicated. This parameter is based on the data element BAPILOGSYS. If this
parameter is set to “initial”, the receiver is determined using the ALE distribution model.
The interface of the Replicate() BAPI may also contain the following import parameters:
•
Parameter RequestChanges
This parameter enables modifications of object instances already replicated to be copied
directly from engineering change management and forwarded to the receiving system.
You should only use this parameter if the business object type in question provides
engineering change management.
Structure this parameter on the data element . This can have the following values:
−
' ' (no value)
No value is the standard setting and means that engineering change management
will not be accessed.
−
'X'
This value means that the modified data is replicated directly from engineering
change management.
This parameter must not be used together with the Recipients parameter, because the
change pointers in change management are reset, if change management is accessed
by the receiver. Other receivers may then not be allowed access. Documentation on this
parameter must refer explicitly to this connectivity.
•
Other BAPI-specific import parameters, for example, to specify the data range of the
instances to be replicated (for example, material with or without plant data).
Export Parameters
The BAPI Replicate() should contain the following export parameters:
•
The Return parameter in which messages from the method call are returned to the calling
program. For more information about this parameter see Return Parameters (Error Handling)
[Page 130].
•
A table with information on the object instances to be replicated.
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].
116
December 1999
SAP AG
BAPI Programming
Programming Replicate()/SaveReplica() BAPIs
Locking
We recommend that you implement Replicate() BAPIs without the locking function and create
your own BAPIs instead that lock the relevant data.
SaveReplica() and SaveReplicaMultiple()
The class method SaveReplica() and the method SaveReplicaMultiple() generate replicates of
business object instances. They are used to replicate objects in different systems that are
semantically identical. For technical reasons these objects may be created with different objects
keys (object IDs).
The BAPI SaveReplica() is used by a system to replicate one business object instance on a
target system or to modify one business object that has already been replicated. Whilst the
SaveReplicaMultiple() BAPI can replicate several business object instances on the target system
or modify several instances that have already been replicated.
For each business object type to be replicated you have to implement one or both of these
methods, according to your requirements.
If instances that have already been replicated are to be changed when a SaveReplica() or
SaveReplicaMultiple() BAPI is called, the fields that are to be changed (that is, receive new
values) and the fields that are to remain the same must be identified. You can do this by flagging
the fields, as described in Change Parameters [Page 125].
Import Parameters
For the BAPI, all the data required for replicating an individual business object instance must be
provided in the import parameters. For the SaveReplicaMultiple() BAPI, all the relevant data for
replicating several instances must be provided in the import parameters. All the object keys may
be provided, they must, however be able to be derived.
If only parts of objects are to be replicated rather than whole objects, you can use other optional
import parameters.
Export Parameters
To return messages from the method call to the calling program, you should only create the
parameter Return for these BAPIs. 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].
Locking
We recommend that you implement SaveReplica() BAPIs without the locking function and create
your own BAPIs instead that lock the relevant data.
December 1999
117
BAPI Programming
SAP AG
Example of a SaveReplica() BAPI
Example of a SaveReplica() BAPI
The BAPI SaveReplica() of the business object type InternalOrder (BUS2075) is used here as an
example.
The graphic below shows this BAPI in the BAPI Browser.
118
December 1999
SAP AG
BAPI Programming
Example of a SaveReplica() BAPI
December 1999
119
BAPI Programming
SAP AG
Programming Methods for Sub-Objects
Programming Methods for Sub-Objects
Use
If a business object type consists of sub-objects, you can implement the following standardized
BAPIs to add or remove sub-objects:
•
Add<name of sub-object>
This method adds a sub-object to an object type.
•
Remove<name of sub-object>
This method removes a sub-object from an object.
For example, to add or remove the sub-object purchase order item to the business
object type purchase order, the BAPIs AddItem() and RemoveItem() could be
implemented for the object type, purchase order.
The BAPIs Add<Name of sub-object> and Remove<Name of sib-objects> are instance methods.
Features
Import Parameters
Both BAPIs’ import parameters must contain in the function module the data that uniquely
identifies the sub-object as well as the key fields of the business object.
If required, you can create also create these parameters:
•
A test run parameter for checking the entry for an object instance before actually creating the
instance in the database.
•
A change parameter to identify parameter fields containing modified values and parameter
fields that have not been modified.
For more information about these parameters see Standardized Parameters [Page 29].
Export Parameters
You should only create the export parameter RETURN in the BAPI Remove<Name of subobject> to return messages from the method call to the calling program. For more information
about this parameter see Return Parameters (Error Handling) [Page 130].
To make the object key available to the calling program, the key fields of the object type must
also be returned in the export parameters of the BAPI Add<Name of sub-object> as well as in the
export parameter Return.
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].
120
December 1999
SAP AG
BAPI Programming
Programming Methods for Sub-Objects
Locking
We recommend that you implement methods of sub-objects without the locking function and
create your own BAPIs instead that lock the relevant data.
December 1999
121
BAPI Programming
SAP AG
Programming Standardized Parameters
Programming Standardized Parameters
Purpose
There are some parameters that can be created for various BAPIs because they contain the
same or equivalent data in all BAPIs. Such parameters are known as “standardized” parameters.
They should be implemented the same in all BAPIs.
Process Flow
If your BAPI is a standardized BAPI, you should implement it following the programming
guidelines described in the following sections.
122
December 1999
SAP AG
BAPI Programming
Address Parameters
Address Parameters
Use
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).
Use one of the following structures as a copy reference for addresses in BAPIs:
Reference Structure
Use
BAPIADDR1
BAPIADDR2
BAPIADDR3
BAPIADDR1X
Addresses of companies and organizations
Addresses of individuals
Addresses of contact persons within an organization
Change reference structures for addresses of companies and
organizations
Change reference structures for addresses of individuals
Change reference structures for contact persons within an
organization
BAPIADDR2X
BAPIADDR1X
Keep in mind the following points when you use these reference structures:
•
All the fields of the reference structures refer to the central address management (CAM).
Only use fields that can also be processed in your application context. If the CAM is
already included, then all the fields are relevant.
•
Contrary to the standard guidelines (compare with Internal and External Data Formats
[Page 69]), for some coded name parts the text formats (for example, CHAR 20 or CHAR
39) are included as fields in these structures, rather than the internal database keys.
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)
You cannot expect in these cases that a calling program converts the internal database
keys into the external readable form and vice versa. In these cases you can use the
function modules below which enter values in these structures or accept changes made
to the structures and then assign the correct keys internally.
Function Module
Description
ADDR_CONVERT_FROM_BAPIADDR1
Converts the fields in the structure from the
external format into the internal format.
Converts the fields in the structure from the
internal format into the external format.
Converts the fields in the structure from the
external format into the internal format.
ADDR_CONVERT_TO_BAPIADDR1
ADDR_CONVERT_FROM_BAPIADDR2
December 1999
123
BAPI Programming
SAP AG
Address Parameters
ADDR_CONVERT_TO_BAPIADDR2
ADDR_CONVERT_FROM_BAPIADDR3
ADDR_CONVERT_TO_BAPIADDR3
•
Converts the fields in the structure from the
internal format into the external format.
Converts the fields in the structure from the
external format into the internal format.
Converts the fields in the structure from the
internal format into the external format.
If fields are lengthened in the CAM, the associated field in the BAPI reference structure
remains the same type and length. A new data element is assigned to this field that can
be identified as obsolete in the description and/or short text. The obsolete field is still
taken into account in the conversion modules described above.
For the new field length a new field with a new name is added to the end of the structure.
Currently this affects the following fields:
Existing Field
Length
New Field
Length
In Structure
FORMOFADDR
BUILDING
Char 20
Char 10
TITLE
BUILD_LONG
Char 30
Char 20
STREET
Char 40
STREET_LNG
Char 60
BAPIADDR1
BAPIADDR1, BAPIADDR2,
BAPIADDR3
BAPIADDR1
Preferably, you should use the new, longer fields.
•
124
When using the reference structure BAPIADDR3, remember that read-only access is
possible to all the fields in the company’s address (check table ADRC). If you want to
make changes to these fields you have to access the reference structure BAPIADDR1.
December 1999
SAP AG
BAPI Programming
Change Parameters
Change Parameters
Use
In BAPIs that cause database changes (for example, Change() and Create() BAPIs), you must
be able to distinguish between parameter fields that are to be modified (change-relevant fields)
and parameter fields that are to remain unmodified.
Using an initial value is no solution because an initial value could also represent a valid new
value. Also, in the ABAP programming language as well as on other development platforms, the
value “NULL” should not be assigned to a data type to indicate an empty field.
Standardized change parameters are used to identify fields with modified values in Change() and
Create() BAPIs. You can do this in two ways:
•
Flagging Fields to Identify Fields Containing Modified Values
•
Comparing Fields to Identify Fields Containing Modified Values
Flagging Fields to Identify Fields Containing Modified Values
In this approach parameter fields containing modified values are identified by including a flag in
an additional "change parameter".
•
An additional change parameter must be created with the same number of fields and the
same field names for every parameter in the BAPI containing modified field values.
•
When the BAPI is called, the fields in the additional change parameter whose counterparts in
the corresponding parameter contain modifications, must be marked with an update flag.
This way the BAPI can identify both modified and unmodified fields in the parameter.
Follow the conventions below when you create change parameters to identify modified fields:
•
The name of the additional change parameter consists of the parameter name with the suffix
"X". For instance, if the parameter is called EquiSales, the name of the additional change
parameter is EquiSalesX.
•
The additional change parameter must contain exactly the same number of fields and the
same field names as the parameter. You must use the data element BAPIUPDATE (CHAR
1) as the data element for the update fields. This can have the following values:
•
'X'
This value means that the corresponding parameter field contains a modified value.
•
' ' (no value)
This means that the corresponding parameter field does not have to be updated.
•
If the parameter is a table, the additional change parameter must also be a table.
A Change() BAPI is used to change the value of the existing distribution channel
(Distr_Chan) to Distr_Chan="US". The fields that have been changed should be
identified by flagging them.
The program objects in the R/3 System affected by this change are:
December 1999
125
BAPI Programming
SAP AG
Change Parameters
Program Object
Name
SAP business object type
PieceOfEquipment
BAPI
Change
Parameter
EquiSales
Fields in parameter
EquiSales
SalesOrg=0001'
Distr_Chan='US'
Division=' Marketing'
Change parameter that identifies modified fields
Fields in parameter
EquiSalesX
EquiSalesX
SalesOrg=' '
Distr_Chan='X'
Division=' '
In the parameter EquiSalesX the value in the field Distr_Chan is 'X'. This indicates
that the field Distr_Chan of the parameter EquiSales contains a modified value (US).
The Change() BAPI then overwrites the existing value in the field Distr_Chan with the
current value in the field Distr_Chan in the parameter EquiSales.
Comparing Fields to Identify Fields Containing Modified Values
In this approach fields containing modified values are identified by comparing two parameters,
one containing the current valid data and the other the new, modified data.
When the Change() BAPI is called, the current data in the database and the new, modified data
must be entered in the corresponding parameters. The current data set can be transferred, for
instance, from a GetDetail() BAPI that has been called.
The following comparisons can be made:
•
The current data can first be checked against the database contents to ascertain whether it
has changed in the meantime. This way any database changes made between the time the
data was read by the GetDetail() BAPI and the time the database is updated can be
identified.
•
The data in both the parameters can be compared field by field. If the data in two
corresponding fields is different, the relevant values must be transferred from the parameter
with the new data.
Note the following when you are comparing fields containing modified data.
•
A calling program must be able to provide data in all the parameter fields of the Change()
BAPI. For this reason, the parameter fields of the Change() BAPI must be exactly the same
as the fields in the GetDetail() BAPI of the same business object type.
•
The names of the parameters to be compared must be the same, but the parameter
containing the modified data must also have the suffix ‘New’.
126
December 1999
SAP AG
BAPI Programming
Change Parameters
For example, if the parameter with the current valid data is called EquiSales, the
parameter with the modified data is called EquiSalesNew.
•
Both parameters must have exactly the same fields and the same structure.
A Change() BAPI is used to change the value of the existing distribution channel
Distr_Chan="US" to Distr_Chan=“EN”. The fields containing modified should be
identified by comparing them.
The program objects in the R/3 System affected by this change are:
Program Object
Name
SAP business object type
PieceOfEquipment
BAPI
Change
Parameter
EquiSales
SalesOrg=' 0001'
Fields in parameter
EquiSales
Distr_Chan='US'
Division=' Marketing'
Parameter for the new data
EquiSalesNew
SalesOrg=' 0001'
Fields in parameter
EquiSalesNew
Distr_Chan='EN'
Division=' Marketing'
The fields are compared by:
1. Entering data from the relevant GetDetail() BAPI in the parameter EquiSales.
2. Initializing the parameter EquiSalesNew with the values from the parameter
EquiSales.
3. Modifying the required parameter values in the parameter EquiSalesNew, for
example: EquiSalesNew-Distr_Chan='EN'.
Which is the Best Way?
The table below compares the two ways of identifying fields containing modified values in BAPIs,
as described above, and should help you decide which way suits your requirements best.
Area
Comments
Performance
Flagging fields: The flag table can be compressed. Data
does not have to be compared.
If using in a distributed environment (ALE) the amount of
data to be transported by flagging fields is not
significantly greater.
December 1999
127
BAPI Programming
SAP AG
Change Parameters
Programming
Flagging fields: BAPI programming is simpler.
Check facilities
Comparing fields: Can check against current database
to identify and prevent inconsistencies.
Comprehension
Flagging fields: Fields containing modifications can be
flagged, meaning less demands are placed on the caller.
Comparison with related data
Comparing fields: Need to compare with the associated
GetDetail() method of the business object type, because
all the fields in the Change BAPI() must filled by the
calling program.
Application
Flagging fields: Better for performance critical
applications.
Comparing fields: Better for dialog-orientated
applications with critical data.
128
December 1999
SAP AG
BAPI Programming
Extension Parameters
Extension Parameters
Use
The parameters ExtensionIn and ExtensionOut enable customers to enhance BAPI interfaces
without modifications and to process customer-specific data automatically.
For details see Customer Enhancement Concept for BAPIs [Page 65].
December 1999
129
BAPI Programming
SAP AG
Return Parameters (Error Handling)
Return Parameters (Error Handling)
Use
A BAPI should be able to record and classify all possible errors that may occur.
You have to create a parameter named Return for every BAPI. This parameter returns exception
messages or success messages to the calling program.
BAPIs themselves must not trigger any messages (such as MESSAGE xnnn) in the coding. In
particular they must not generate terminations or display dialog boxes. Instead, all messages
must be intercepted internally and reported back to the calling program in the Return parameter.
Otherwise the BAPI will not be processed correctly and control may not be given back to the
calling program.
All error messages or indeed any message that may be returned by the BAPI, must be defined in
message table (Tools → ABAP Workbench →=Development →=Programming environment
→=Messages) and described in the documentation for the return parameter. This also applies to
the most important or most likely error messages generated by other programs that can be
indirectly passed via the BAPI to the application program.
As of Release 4.0 you must not use exceptions in BAPI interfaces.
When a termination message (message type A) is triggered, a database rollback is
executed in the standard programming model, that is, all tasks performed since the
last COMMIT WORK are canceled. When you program BAPIs, we recommend that
you also execute a database rollback in the return parameter for termination
messages. You must describe this process in the documentation for the Return
parameter. For messages of type E (error), the calling program performs the error
handling.
Application developers are provided with two service BAPIs to diagnose and process error
messages from BAPI calls:
•
BapiService.MessageGetDetail() which displays the short and long texts of BAPI error
messages.
•
BapiService.ApplicationLogGetDetail(), with which information in application logs can be
displayed.
Features
The export parameter Return can be implemented as follows:
•
As a structure, whereby it must be defined in the function module as an export parameter, as
well as in the method in the BOR.
•
As a table, whereby it must be defined in the function module as a table parameter, as well
as in the method in the BOR as an export parameter.
Before filling the Return parameter you should either initialize the structure with CLEAR or the
table with REFRESH and CLEAR.
130
December 1999
SAP AG
BAPI Programming
Return Parameters (Error Handling)
If the return parameter is not set or is set to an initial value this means that no error has occurred.
The Return parameter may be based on the following reference structures:
•
BAPIRET2
We recommend that you use this reference structure as of Release 4.5A.
•
BAPIRET1
Both structures must be filled in the logon language.
Reference Structure BAPIRET2
The structure BAPIRET2 is filled via the function module BALW_BAPIRETURN_GET2. It
contains the following fields:
Field
Type
Description
TYPE
CHAR 1
S = success message
E = error message
W = warning message
I = information message
A = termination message (abort)
ID
CHAR 20
Message ID The structure BAPIRET2 takes into account
the name space extension for the message class as of
Release 4.0. If you want messages to be compatible with
earlier R/3 Releases, use the message classes before
Release 4.0.
NUMBER
NUMC 3
Message number
MESSAGE
CHAR 220
Full message text from the message table. All variables
(in fields Message_V1 to Message_V4) have been
replaced with text.
LOG_NO
CHAR 20
Application log number This is empty if no log used.
Note that for type A error messages (abort), an
application log is not created, as in this case there is no
COMMIT WORK.
LOG_MSG_NO
NUMC 6
Current message number in application log
MESSAGE_V1
MESSAGE_V2
MESSAGE_V3
MESSAGE_V4
CHAR 50
Fields for the variable texts of the message specified in
fields ID and NUMBER.
PARAMETER
CHAR 32
Parameter containing the invalid value.
ROW
INT 4
Line number of the data record containing the invalid
value
FIELD
CHAR 30
Field containing the invalid value.
December 1999
131
BAPI Programming
SAP AG
Return Parameters (Error Handling)
SYSTEM
CHAR 10
System (logical system) in which the message was
generated.
Reference Structure BAPIRET1
This structure is filled via the function module BALW_BAPIRETURN_GET1. It consists of the
fields in the BAPIRET2 structure excluding the fields PARAMETER, ROW and FIELD.
Return Parameters in the ALE Distributed Environment
After the function module which converts the IDoc into the corresponding BAPI in the receiving
system has been called, status records are written for the IDoc in which messages sent in the
return parameter are logged (see also Using BAPIs in Distributed Systems (ALE) [Page 164].
If the field type is filled with E (error) or A (abort) in at least one of the transferred return
parameter entries, the status 51 (application document has not been posted) is assigned to all
the status records of the IDoc and a ROLLBACK WORK is executed. If the field type is filled with
E (error) in at least one of the transferred return parameter entries, the status 51 (error,
application document has not been posted) is assigned to all the status records of the IDoc and a
COMMIT WORK is executed anyway. Otherwise status 53 (application document posted) is
written and a COMMIT WORK executed.
Application Log and Application-Specific Error Tables
If the information provided in the Return parameter is not sufficient, you can log errors with the
application log. The logging should be done by the BAPI itself so that function modules called
directly by this BAPI do not have to be modified. The fields LOG_NO and LOG_MSG_NO of the
Return parameter return the application log numbers and their messages.
As of Release 4.6A you can already maintain the log number when you create the
application log. Several instances of an application object can be maintained at the
same time and can be updated together. The update task can be also used for
application logs, that is, log entries are and no longer directly written to the database,
they are written via the update task. If you plan to use application logs in your BAPI,
you must write these using the update task.
For further information on application logs see Creating Applications Logs [Ext.] in the document
BC - Extended Function Library Applications [Ext.].
If this still does not provide enough information, the calling application can define its own
additional error tables. There are no set guidelines for these additional tables. The Return
parameter in your BAPI could give details of the messages in the error tables, for example, if
there are error messages (type E) in the table. The calling program then has immediate control
over the contents of the error table and does not have to first search for error messages.
The use of the application log and error tables enable error messages to be returned if they
cannot be adequately returned in the return parameter.
132
December 1999
SAP AG
BAPI Programming
Return Parameters (Error Handling)
Note that for type A error messages (abort), an application log is not created, as in
this case there is no COMMIT WORK.
December 1999
133
BAPI Programming
SAP AG
Selection Parameters
Selection Parameters
Use
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.
In your BAPI create the required selection parameters as structures or tables with the following
parameters:
Fields for Value Ranges
Field Name
Description
Data Element
SIGN
Selection operator that determines
whether the range specified is to be
included or excluded.
BAPISIGN
OPTION
Relational operator, for example.
Relational operator, e.g. CP (contains
pattern) or NP (no pattern)
BAPIOPTION
HIGH
Upper limit of value range
application-specific, for
example, MATNR.
LOW
Lower limit of value range
application-specific, for
example, MATNR.
You can use the function module BALW_RANGES_CHECK to check the values entered in SIGN
and OPTION.
Note that when you select a list of objects you have to limit the number of objects selected. You
can use the parameter MaxRows to do this. For more information see Programming GetList()
BAPIs [Page 91].
Application servers might not support ASCII, but use a different character set instead.
If this is the case a problem may arise when you select quantities or ranges or when
these are sorted. Because of this a BAPI should always select a range between A-Z,
a-z and 0-9.
134
December 1999
SAP AG
BAPI Programming
TestRun Parameters
TestRun Parameters
Use
The parameter TestRun is used in write BAPIs, for example, Create() or CreateFromData(), to
check the entries for the object instance in the database before actually creating the object
instance. The generation of the instance, for example, creating master data, is only simulated
and the data is not written to the database.
To simulate the creation of the object instance and to supply the relevant return messages, the
BAPI should carry out all the necessary checks (excluding technical checks, such as,
establishing the connection to the R/3 System), without actually updating the database.
For BAPIs used in an ALE distributed environment, this parameter must be available
in the interface.
Updating can be switched on or off using the TestRun parameter. The parameter is based on the
data element TESTRUN. This can have the following values:
•
' ' (no value)
No value means that the data will be posted. This is the default setting.
•
'X'
This value means that the BAPI is being called only in simulation mode and updating will
not take place.
Keep in mind the following as you are programming:
•
Do not assign any internal numbers either for the object itself, or for any dependent
objects (for example, EAN numbers or Mat.Ledger No. in the material master).
•
Be careful when calling function modules in other applications as these could assign
numbers or update the database.
•
Do not inadvertently write change documents.
•
Create a message in the return parameter of the BAPI that informs users whether the
BAPI has been implemented in simulation mode.
December 1999
135
BAPI Programming
SAP AG
Text Transfer Parameters
Text Transfer Parameters
Use
Text transfer parameters are used to pass information in a BAPI (e.g. documentation on a
business object type) from the R/3 System to a calling program.
Features
To transfer documentation texts you have to create the standardized parameters below:
•
The import parameter TextFormat that identifies the data format of the text to be transferred.
Use the type BAPI_TFRMT for this parameter. This requires the following fixed values
that must all be provided by the BAPI:
•
SCR for SAPscript
•
ASC for ASCII
•
RTF for rich text format
•
HTM for hypertext markup language (HTML)
•
The table parameter Text that carries the text to be transferred.
Use the reference structure BAPITGB for this parameter.
You can see an example of using text transfer parameters in the BAPI
BapiService.FieldhelpGetDocu().
136
December 1999
SAP AG
BAPI Programming
Tools for Developing BAPIs
Tools for Developing BAPIs
Use
You can use the following development tools to develop BAPIs in addition to the standard
development tools in the ABAP Workbench:
•
The BOR/BAPI Wizard to define BAPIs in the Business Object Repository.
This program is described in Defining Methods in the BOR Using the BOR/BAPI Wizard
[Page 138].
•
A transaction to automatically generate function modules to convert between internal and
external data formats.
This transaction is described in Converting Between Internal and External Data Formats
[Page 140].
•
The report BBAPIFLD used to generate default values for English field names and parameter
names.
For further information see the section Specifying Development Objects in the ABAP
Dictionary [Page 37] in the report documentation.
December 1999
137
BAPI Programming
SAP AG
Defining Methods in the BOR Using BOR/BAPI Wizard
Defining Methods in the BOR Using BOR/BAPI Wizard
Prerequisites
If the function module which your BAPI is based on has been fully implemented or modified you
can define it as a method of an SAP business object type or SAP interface type in the Business
Object Repository (BOR). You use the BOR/BAPI-Wizard to do this.
Procedure
First find the relevant SAP business object type in the BOR:
1. Select Tools → Business Framework → BAPI Development →==Business Object Builder.
On the initial Business Object Builder screen you can directly access the SAP business
object type or interface type if you know the technical name of the object (object type).
You have already identified the technical name in Defining a BAPI and Its Interface
[Page 24]
Otherwise select Business Object Repository.
•
To display object types, in the next dialog box indicate whether you want to display all object
types or only business object types. Then select Continue.
•
To display SAP interface types, in the next dialog box select Other settings and then
Interface.
The application hierarchy is displayed. Search for the required business object type or
interface type in the application hierarchy and double click it to open it.
2. When the business object type or interface type is displayed, select Change.
Creating BAPIs as Methods of Business Object Types or Interface Types
To define your BAPI as a method of a business object type or interface type:
1. Select Utilities → API Methods → Add method.
2. In the next dialog box enter the name of the function module, for example,
BAPI_COMPANYCODE_GETDETAIL and select Continue.
3. In the next dialog box specify the following information for the method to be defined:
•
Method
A default name for the method is provided, based on the name of the function
module. You will have to modify the suggested name.
•
Delete the prefix “BAPI” and the business object name, so that only the method name is
left. Begin every new word of the method name with a capital letter and do not use
underscores.
Example: If the name of the function module is BAPI_SALESORDER_GETSTATUS,
the suggested method name might be BapiSalesorderGetstatus. You should edit this
so that the resulting name is GetStatus.
•
Texts
Enter meaningful descriptions for your BAPI.
138
December 1999
SAP AG
BAPI Programming
Defining Methods in the BOR Using BOR/BAPI Wizard
•
Radio buttons Dialog, Synchronous, Instance-independent
Enter relevant details for your BAPI. Make sure that a BAPI is not dialog orientated.
BAPIs are usually implemented synchronously.
4. Select Next Step.
A list of parameters and default names is displayed which you need to edit as required.
Modify the parameter names as follows:
•
Each new word in the parameter name must start with a capital letter, for example,
CompanyCodeDetail.
•
Make sure that the parameter names of the method in the BOR are identical to the
parameter names in the function module except for the upper/lower case letters.
•
Also specify whether the individual table parameters are used for data import or data
export. Table parameters are marked with a tick in the column 'MLine' (multiple lines).
5. Select Next Step.
To create the method select Yes in the next dialog box.
Result
After the program has been generated and executed, check that all the definitions have been
made correctly by the BOR/BAPI Wizard. To do this look at the newly created method of the
business object type or interface type.
The BOR/BAPI Wizard is used only to create new BAPIs for the first time. It is not
used to make changes to existing BAPIs.
If you make changes to the underlying function module after you have created the
BAPI in the BOR, for example, if you make compatible interface enhancements or
modify short texts, such changes do not automatically take effect in the BOR. You
have to make these changes manually in the BOR. For information about creating
and modifying business object types refer to the documentation on SAP Business
Workflow [Ext.].
December 1999
139
BAPI Programming
SAP AG
Converting Internal and External Data Formats
Converting Internal and External Data Formats
Prerequisites
This section describes how you can generate function modules to convert between internal and
external data formats. These function modules are used to:
•
Map English and German field names onto each other
•
Carry out ISO code conversions
•
Convert currency amounts into the required external or internal format
•
Convert internal and external keys, for use for example by WBS elements (work
breakdown structure)
Note that conversions between internal and external data formats should only be carried out in
exceptional circumstances. These exceptions are described in Internal and External Data
Formats [Page 69].
To generate the function modules, the relevant internal and external data formats must have
been created in the ABAP Dictionary.
Procedure
To generate the function module follow the steps below:
1. Select Tools → Business Framework → BAPI Development →==Generate module to map
fields.
2. In the appropriate input fields enter the names of the external BAPI structure and the internal
working structure you are making the conversion between. Specify the required direction for
mapping, i.e. is the internal structure to be mapped onto the external structure or vice versa.
3. Select Function module →=Generate.
A dialog box is displayed in which you can enter details of the function module to be
generated. The input fields for the name of the function module and the short text contain
suggested values which you can accept or change.
In the field Function group enter the name of the function group to which the generated
function module is to be added. If the function module is being used to convert currency
amounts, the fixed point arithmetic for the selected function group must be switched on.
In addition to the source text for the function module you can have a blank FORM routine
added for your own program code if you have to make manual modifications. To do this,
select Form to edit. The FORM routine contains the same parameters as the generated
function module.
4. Select Continue.
A table is displayed containing suggestions for the conversion of each field of the
external BAPI structure. The table contains the following columns:
•
Status
Indicates if the conversion is possible or if data is missing.
•
140
Field in external structure
December 1999
SAP AG
BAPI Programming
Converting Internal and External Data Formats
Contains the field names of the external BAPI structure.
•
Conv. type
Displays the conversion type.
•
Field in internal structure
Displays the fields of the internal structure to which/from which mapping is to be
carried out.
For further information select F1 help for columns Status and Conv. type.
5. To generate the function module, select Save.
The function module is stored in the Function Builder in the function group you specified.
Result
In a few cases it may be necessary to manually edit the source code of a function module that
has been automatically generated.
It is not yet possible to use this transaction to regenerate an existing function module. To
regenerate an existing function module you must first manually delete the function module and
then generate it afresh.
You can incorporate the generated function modules into the source code of your BAPI as
required.
•
To map the internal work structures to the external BAPI structures before calling the
BAPI
•
To map the result to the internal work structure after the BAPI has been called
•
To map the inbound parameters to the internal structures (import parameter structures)
when you are implementing the BAPI
•
To map the result from the internal structure to the BAPI (export parameter structures)
when you are implementing the BAPI
The section Application Example [Page 142] illustrates how function modules are used.
December 1999
141
BAPI Programming
SAP AG
Application Example
Application Example
The BAPI used in this fictitious example can read the standard price of a material:
bapi_material_getprice
importing
material like mara-matnr
exporting
material_price like bapi_material_price.
The external structure bapi_material_price contains the following fields:
Fields in External BAPI Structure
Field
currency_iso
currency
amount
Description
ISO currency code
Currency code
Amount
Data Element
isocd
waers
bapimatprice
Domain
isocd
waers
bapicurr
The application programmer in the R/3 System who intends to use this BAPI uses the internal
structure mat_preis in his or her own program. This structure consists of the following fields:
Fields in Internal Working Structure
Field
Description
Data Element
Domain
matnr
Material number
matnr
matnr
waers
Currency code
waers
waers
stprs
Unit price
stprs
strps
The BAPI structure bapi_material_price contains an ISO currency code and a currency
amount. After calling the BAPI, the application programmer must convert these fields into the
internal format used in R/3 so that the fields can be processed.
Using the function, Generate module to map fields, (see section Converting Between Internal and
External Data Formats [Page 140]), the application developer can generate the function module,
map2i_bapi_material_price_to_mat_preis, which converts the currency and amount fields. This
function module has the following interface:
function map2i_bapi_material_price_to_mat_preis
importing
external structure bapi_material_price
changing
internal structure mat_preis
exceptions
error_during_iso_convertion
error_converting_currency_amount.
The application code could be as follows:
142
December 1999
SAP AG
BAPI Programming
Application Example
...
data: matnr like mara-matnr,
price like mat_preis,
bapi_price like bapi_material_preis.
...
* Call BAPI
Call function bapi_material_getprice
exporting
material = matnr
changing
material_price = bapi_preis.
* Map and convert the result to internal format
call function map2i_bapi_material_price_to_mat_preis
exporting
external = bapi_preis
changing
internal = preis.
*
exceptions
*
error_during_iso_convertion
*
error_during_currency_amount_conversion
preis-matnr = matnr.
...
December 1999
143
BAPI Programming
SAP AG
SAP Enhancements to Released BAPIs
SAP Enhancements to Released BAPIs
Purpose
Application developers who are using BAPIs in their application programs must be able to rely on
the fact that the BAPI's interface is not going to change. As a result of this, once a BAPI is
released, it must fulfill certain requirements regarding the stability of its interface.
If you continue developing your BAPI after you have released it, you need to ensure that any
syntax changes or changes to the contents or functionality of the BAPI are downward compatible.
Downward compatibility means that applications that were programmed with BAPIs from a
specific R/3 Release will not be effected in later R/3 Releases if the syntax or the content of this
BAPI changes.
Examples of syntax changes are changes to parameter names, or changes to the type or length
of a domain. The ABAP Dictionary can automatically test whether syntax changes are
compatible.
However, only the developer can ensure that content changes are downward compatible.
Accordingly, when you enhance a BAPI, you can only differentiate between a compatible and an
incompatible enhancement, if the downward compatibility of the BAPI can be verified.
Process Flow
When you are enhancing a BAPI, you should attempt to make compatible changes in order to
limit the impact of your modifications on existing programs which use the BAPI.
For example, when adding a new import parameter, consider whether the interface would
function without the parameter. If this is the case, you can make the enhancement to the
interface compatible by adding an optional parameter.
For further details see Compatible Enhancements [Page 146] and Incompatible Enhancements
[Page 148].
For SAP internal development, each enhancement to a BAPI must be created in a
project in the BAPI Explorer.
Modifications and Version Management in the BOR
Changes made to a BAPI only take effect when the changes are defined in the Business Object
Repository (BOR), that is, they are saved and generated.
Version management of BAPIs is also carried out in the BOR.
Checks in the ABAP Dictionary
Changes to the syntax of BAPIs are automatically checked by the ABAP Dictionary, thereby
preventing the BAPI data structure being changed by mistake.
•
144
Incompatible changes to data elements, domains or structures that are being used by a BAPI
that has been released, are rejected by the ABAP Dictionary.
December 1999
SAP AG
BAPI Programming
SAP Enhancements to Released BAPIs
•
Compatible changes or changes to data elements, domains or structures of a BAPI that has
not been released are accepted by the ABAP Dictionary.
December 1999
145
BAPI Programming
SAP AG
Compatible Enhancements
Compatible Enhancements
Use
Compatible enhancements are interface enhancements that change the BAPI without effecting
the downward compatibility of the BAPI. Applications which access the BAPI are not affected by
compatible enhancements.
Features
Compatible enhancements are:
•
New optional parameters
A parameter is considered to be optional if it does not have to be included in a BAPI call.
A new optional parameter can be added in any place in the interface.
A new parameter is added to the BAPI SalesOrder.GetList() which can be used as
an additional selection criteria for selecting sales orders in the R/3 System.
•
New optional fields in structures
A field is considered to be optional if it can be left out completely in a BAPI call.
The fields must be added to the end of a structure because the function module
underlying the BAPI is called via RFC.. It does not matter how the fields are arranged in
a structure or table because the whole structure is always forwarded. It is not first broken
up into fields.
An additional input field for the applicant's educational background is added to the
BAPI Applicant.CreateFromData().
The table below lists the compatible changes that can be made to function modules. We cannot
guarantee that this list is complete.
Compatible Changes to Function
Modules
In interface
New optional parameter as a field
New optional parameter as a structure
New optional parameter as a table
Adding new optional field to the structure.
Adding new optional field to the table.
Compatible changes to field types (in ABAP Dictionary).
Converting mandatory fields to optional fields
In program code
146
New additional coding, that does not involve changes to
the interpretation/processing logic.
December 1999
SAP AG
BAPI Programming
Compatible Enhancements
Changes to the existing code, which do not involve
changing the interpretation or processing logic.
Using customer exits.
December 1999
147
BAPI Programming
SAP AG
Incompatible Enhancements
Incompatible Enhancements
Purpose
Changes to the contents or functionality of a BAPI often result in the introduction of new
parameters without which the interface can no longer function. Often, these changes also cause
existing parameters to lose their original meaning. Such modifications are considered to be
incompatible enhancements, because they no longer enable the BAPI to be downward
compatible.
Incompatible enhancements are:
•
Changes to the field length
•
Changes to the field type
•
Renaming parameters in the function module or in the method
•
Inserting a field within a structure
•
Deleting parameters and fields
•
Adding new mandatory parameters or fields
Parameters can be flagged as mandatory parameters in the BOR However, this is not
the case with fields. Fields can only be categorized as mandatory at a semantic level and
not at a technical level. This is why the documentation for each parameter must specify
which fields can be filled.
The table below lists the incompatible changes to function modules. We cannot guarantee that
this list is complete.
Incompatible Changes to
Function Modules
In interface
New mandatory parameter
Adding new fields between existing fields in structure.
Adding new fields between existing fields in the table.
Adding new mandatory field to the structure.
Adding new mandatory field to the table.
Incompatible changes to field types (in ABAP Dictionary).
Converting mandatory fields to optional fields
Renaming a parameter
In program code
New additional coding, involving changes to the
interpretation/processing logic.
Changes to the existing code that involve changing to the
interpretation/processing logic.
Adding or removing COMMIT WORK commands in the
program.
148
December 1999
SAP AG
BAPI Programming
Incompatible Enhancements
Process Flow
If changes to BAPIs are incompatible, proceed as follows:
Creating an Additional BAPI
To ensure that the interface stability of an existing BAPI is not effected, you must not make any
incompatible changes to the existing BAPI. Instead, create one or several, if required, additional
BAPIs to replace the existing one.
The new BAPI must retain the same name as the existing BAPI. A numeric suffix is simply added
to it. This suffix changes if further incompatible changes are made.
A number of incompatible changes must be made to the BAPI FixedAsset.Create().
To implement these changes, a new BAPI, FixedAsset.Create1(), is created, in order
to maintain the interface integrity of the BAPI FixedAsset.Create().
If further incompatible modifications must be made to the BAPI at a later date, yet
another BAPI, FixedAsset.Create2(), must be created.
Supporting and Labeling the Expiring BAPI
After the BAPI has been superseded by a new BAPI, you should not remove the replaced BAPI
from the Business Object Repository (BOR) . Instead, you first label this BAPI as expired and
continue its support in the release in which you have introduced the new BAPI as well as in the
next functional release. During this time the original BAPI must remain fully functional and
executable.
The following tasks are required when a BAPI has expired (become obsolete):
•
Select the relevant SAP business object type in the Business Object Builder and open the
node Methods. Position the cursor on the BAPI and select Edit → Change status to →
Obsolete.
•
In the BOR, document which method(s) are to replace the expiring BAPI.
•
Record the BAPIs set to “obsolete” in a particular Release in the Note 0107644, “Collective
Note for Obsolete BAPIs from Release 4.5A”, in the SAPNet - R/3 Frontend.
•
Inform your users about the relevant successor BAPIs in Release Notes.
The graphic below illustrates the expiry phase of a BAPI. In this example the new BAPI is
introduced into Release 4.0. The replaced BAPI is supported in Release 4.0 (in the correction
release in which the new BAPI was introduced) and in the next functional Release “F1”. The
BAPI can then no longer be used in the following functional Release “F2”.
December 1999
149
BAPI Programming
SAP AG
Incompatible Enhancements
BAPI Expiry Phase
Release
BAPI
BAPI
Business
Object
BAPI
BAPI
Business
Object
3.1
4.0
F1
F2
Supported at least until F2
Supported as of 4.0
Neu
F = functional Release
Deleting the Replaced BAPI
If the expiry phase of a BAPI set to obsolete has come to an end, you can remove the BAPI from
the BOR. You should delete an obsolete BAPI as near to the beginning of a new release as
possible, so that developers have time to adjust to its successor.
To delete a BAPI:
•
Delete the method from the BOR.
To do this display the relevant SAP business object type in the Business Object Builder.
Expand the node Methods Place the cursor on the appropriate BAPI and choose Edit →
Delete.
•
Delete the function module that implements the BAPI.
In the Function Builder enter the name of the function module in the Function module
field and choose Function module → Other functions → Delete.
•
150
Record the release in which the BAPI was deleted from the BOR in the Note 0107644,
“Collective Note for Obsolete BAPIs from Release 4.5A”, in the SAPNet - R/3 Frontend.
December 1999
SAP AG
BAPI Programming
Customer Modifications and Developments
Customer Modifications and Developments
Purpose
If required, customers can carry out modifications to existing BAPIs, for example, create new
parameters or parameter fields, or develop new BAPIs following this programming guide.
Prerequisites
Customers and partners who want to create new development objects required in the context of
a modification or own development, should follow the guidelines in the document Changing the
SAP Standard [Ext.] as well as “Guidelines for Modifying the SAP Standard in SAPnet.
Also, make sure that the relevant development objects are assigned a name from the customer
namespace. For further information see Namespaces [Page 161].
Process Flow
Modifications to existing BAPIs or the development of customers’ own BAPIs cannot be made for
business object types delivered in the standard.
Instead, you create a subtype of the business object type which inherits all the characteristics
and methods of this object type. The original object type becomes the supertype. Then you can
make the modifications/own developments to the derived subtype.
In this way the SAP standard delivered to customers is not changed and the modifications/own
developments carried out are retained when the release is upgraded. This procedure also
enables BAPIs to be modified in steps because further subordinate sub-types of a business
object type can be created.
For general information about object types and subtype refer to the documentation for SAP
Business Workflow [Ext.].
The following sections describe how subtypes are created and the two ways of enhancing the
BAPIs available for this subtype.
•
Modifications
Use this way if you want to enhance the functions of an existing BAPI for a subtype. For
more information see Modifying BAPIs [Page 152].
•
Customer developments
Use this method to provide functionality for the subtype which is not covered by any of
the existing BAPIs of the subtype nor by any of the BAPIs inherited by the subtype. For
further information see BAPI Development [Page 159].
December 1999
151
BAPI Programming
SAP AG
BAPI Modifications
BAPI Modifications
Purpose
This section describes the steps involved in modifying an existing BAPI, for example, if new
parameters or parameter fields are to be added.
Process Flow
BAPI modifications cannot be made to business object types delivered in the standard system.
Instead, you have to create a subtype of the business object type and for this subtype you have
to redefine the BAPI method inherited from the superior business object.
Only the redefined BAPI is then available for the subtype; the original inherited BAPI can only be
called from the supertype.
Follow these steps:
1. Create a subtype of the required business object type, as described in Creating Subtypes
[Page 160].
2. Redefine the BAPI inherited by the subtype, for example, by adding further parameters or
modifying the implementation of the BAPI. There are several ways to do this, as illustrated in
the example below:
Object type OT has two BAPIs m1 and m2, which are implemented by the function
modules BAPI_OT_m1 or BAPI_OT_m2:
m1
BAPI_OT_m1
m2
BAPI_OT_m2
OT
If enhancements to BAPI m2 are required, you can use the following implementation
options:
Creating a New Function Module for the Implementation
Here a new function module (BAPI_OTsub_m2) is created to call the function module of
the superior BAPI method (of the supertype). The original functionality is retained and
can be enhanced for customer needs.
The graphic below illustrates the implementation:
152
December 1999
SAP AG
BAPI Programming
BAPI Modifications
m1
BAPI_OT_m1
m2
BAPI_OT_m2
OT
OTsub
m2
BAPI_OTsub_m2
call function . . .
If you use this method, when releases are upgraded, the system checks which interface
enhancements have been carried out on the original BAPI. For example, if the interface
of the original BAPI BAPI_OT_m2 is enhanced, the call in BAPI BAPI_OTsub_m2 must
also be enhanced, if the enhanced functionality of the original BAPI is to be used.
The advantage of using this method is that the original superior BAPI (BAPI_OT_m2),
whose stability has been guaranteed, is cleanly encapsulated. Any changes carried out
in the future to the original superior BAPI which do not affect the interface or semantics
(for example, corrections and optimizations), are automatically copied to the new BAPI
without requiring the subtype to be changed in any way.
This method is not a good choice, if the encapsulation affects system performance
negatively. This could be the case, if in both BAPI_OT_m2 and in BAPI_OTsub_m2,
UPDATE operations are to be made in different fields of the same data record that the
developer would like to implement in one single update record (that is with one
UPDATE).
Compatible Modifications to the Superior Function Module
In principle, the BAPI method of a subtype can be implemented by the same function
module as the method of the suoertype (BAPI_OT_m2 in this example). This is possible
if the modifications of the interface are compatible, for example, if only new optional
parameters have been added (see also SAP Enhancements to Existing BAPIs [Page
144]).
The graphic below illustrates the implementation:
m1
BAPI_OT_m1
m2
BAPI_OT_m2
OT
modifiziert
OTsub
m2
With this implementation method, remember that the modifications must be merged with
the original BAPIs every time a release is upgraded. As of Release 4.5A you can use
The Modification Assistant [Ext.] to do this.
December 1999
153
BAPI Programming
SAP AG
BAPI Modifications
The advantage of using this option is that the original code and enhancement can be
easily compared with one another, to achieve, for example, optimal performance of
database UPDATE operations.
The main disadvantage is that the encapsulation achieved by separating the supertype
and subtype for the BAPI definition actually has to be revoked. When changes have
been made, you must ensure that the function module continues to behave the same
when the original method of the supertype OT is called. This option can cause problems,
if several subtypes of an object type exist in the same system, for example, in the same
development system or for several industry solutions in one system, even though they
have been created independently of each other, for example for different industry
solutions.
Creating the Implementing Function Module as a Copy of the Superior Function
Module
Here a copy of the function module of the superior BAPI method is created (in this
example, BAPI_OT_m2).
The graphic below illustrates the implementation:
m1
BAPI_OT_m1
m2
BAPI_OT_m2
OT
kopiert
OTsub
m2
BAPI_OTsub_m2
modifiziert
You should only use this option, if the enhancement cannot be done by calling the
function module of the superior BAPI method.
If global data is defined or form routines are called in the function group associated
with a BAPI function module, you may have to also copy these data declarations and
form routines to ensure the copy of the BAPI can be executed.
Although it is more flexible to modify a copy of the function module, you still have to
check, with every release upgrade, whether changes have been made to the
implementation of the superior BAPI method. If changes have been made, you have to
copy them to the modified copy. As the origin of the copy is not always supported, we
recommend that you do not use this option.
Once you have made the required modification to the copy of the function module,
assign it as a method to the relevant business object type in the Business Object
Repository using the BOR/BAPI Wizard. For further information about the BOR/BAPI
Wizard see Defining Methods in the BOR Using the BOR/BAPI Wizard [Page 138].
3. When you have made the modification, you have to redefine the modified BAPI of the
subtype in the BOR, as described in Redefining BAPIs [Page 157].
154
December 1999
SAP AG
BAPI Programming
BAPI Modifications
4. If redefined BAPIs of a subtype are also to be used when the BAPI is called, you have to
define the delegation relationship between the supertype and subtype. This procedure is
described in Defining Delegation Relationships [Page 158].
A delegation relationship is only significant for object-oriented BAPI method calls and
not if the implementing function module is called directly.
For information about delegation see the documentation on SAP Business Workflow [Ext.].
Application Example
The BAPI Material.GetList() for the business object type Material should contain
additional parameters. The function module associated with this BAPI is
BAPI_MATERIAL_GETLIST.
Customers should first create a sub-type YMaterial of the existing object type
Material in the BOR. They will also note that method calls of the business object type
YMaterial for the original object type Material are to be processed, provided that the
associated method is implemented there. This is described as delegation. (For all
methods that are not implemented for the sub-type Ymaterial, the method call is
executed from the superordinate business object type, Material.)
Customers make the necessary changes in the source code of the function module
BAPI_MATERIAL_GETLIST, and makes changes to the interface by creating new,
optional parameters.
Next, customers create the method GetList() for the sub-type YMaterial using the
BOR/BAPI Wizard. The method is linked to the function module
BAPI_MATERIAL_GETLIST, where the new parameters are included as part of the
method definition.
If, on the other hand, the interface is enhanced with new, mandatory parameters, a
new function module must be created and assigned to the method
YMaterial.GetList(). (Customers can also copy the module
BAPI_MATERIAL_GETLIST, for example, to Y_BAPI_MATERIAL_GETLIST, and
then edit this copy.
At runtime the following process takes place:
–
When the BAPI Material.GetList(), the BAPI YMaterial.GetList() is the one actually
executed.
–
In the case of all other method calls, the methods of the superordinate business
object type, Material are executed, because these are not implemented for the subtype YMaterial.
December 1999
155
BAPI Programming
SAP AG
Creating Subtypes
Creating Subtypes
To create a subtype:
1. Choose Tools →=Business Framework → BAPI Development →=Business Object Builder or
enter the transaction code SWO1.
2. In the field Object type enter the name of the subtype you want to create and sleet Create.
3. In the next dialog box, enter the required details:
–
In the field Supertype enter the name of the object type for which you want to create
a subtype.
–
In the field Object type enter the name of the subtype you want to create.
Enter appropriate values in the remaining fields.
156
December 1999
SAP AG
BAPI Programming
Redefining BAPIs
Redefining BAPIs
To redefine a BAPI of a subtype:
1. Choose Tools →=Business Framework → BAPI Development →=Business Object Builder or
enter the transaction code SWO1.
2. Display the subtype just created in the change mode.
3. Place the cursor on the BAPI you want to modify and choose Process →=Redefine.
4. Double-click on the BAPI and select the register ABAP.
5. In the Name field of the modified function module enter and save your information.
December 1999
157
BAPI Programming
SAP AG
Defining Delegation Relationships
Defining Delegation Relationships
To define the delegation relationship between the supertype and subtype:
1. Choose Tools →=Business Framework → BAPI Development →=Business Object Builder
or enter the transaction code SWO1.
2. Choose Settings → Delegate →=System-wide.
3. Switch to the change mode and select New entries.
4. Enter the name of the original object type (supertype) in the field Object type and the
name of the subtype in the field Delegation type.
Deactivate the check box GUI-specific.
5. Save your entries.
158
December 1999
SAP AG
BAPI Programming
BAPI Development
BAPI Development
Purpose
Using the information in these BAPI Programming guidelines customers and partners can create
new methods for business object types.
Your own developments are carried out in the subtypes derived from business object types
delivered in the standard and not from the business object types themselves. Use this method to
provide new functionality for the subtype which is not covered by any of the existing BAPIs of the
subtype nor by any of the BAPIs inherited by the subtype.
Process Flow
Follow these steps:
1. Create a subtype of the required business object type, as described in Creating
Subtypes [Page 160].
2. Use the guidelines described in this document to create a new BAPI for the subtype and
to implement it in its own function module.
The new BAPI can only be used for this subtype and not for the object type from which it was
derived (supertype). All existing BAPIs derived from the supertype can continue to be used
unmodified.
Application Example
Following on from the example in BAPI Modifications [Page 152], an additional
method YGetDetail should be created for the sub-type YMaterial of the business
object type Material. The function module associated with this BAPI is
Y_BAPI_MATERIAL_GETDETAIL.
Customers should create the new method YGetDetail of the business object type
YMaterial using the BOR/BAPI Wizard. This method is associated with the function
module Y_BAPI_MATERIAL_GETDETAIL.
At runtime, when the BAPI Material.YGetDetail is called, the BAPI
YMaterial.YGetDetail is actually implemented due to the delegation pointer in the
business object type Material.
December 1999
159
BAPI Programming
SAP AG
Creating Subtypes
Creating Subtypes
To create a subtype:
1. Choose Tools →=Business Framework → BAPI Development →=Business Object Builder or
enter the transaction code SWO1.
2. In the field Object type enter the name of the subtype you want to create and sleet Create.
3. In the next dialog box, enter the required details:
–
In the field Supertype enter the name of the object type for which you want to create
a subtype.
–
In the field Object type enter the name of the subtype you want to create.
Enter appropriate values in the remaining fields.
160
December 1999
SAP AG
BAPI Programming
Namespaces
Namespaces
Definition
The namespace concept describes how customers and partners have to name their development
objects to avoid overlapping when SAP software is upgraded.
Customers and partners can create their own development objects, for example, to implement a
new BAPI or to modify an existing BAPI. For further information see Customer Modifications and
Developments [Page 151].
In R/3 Release 3.1 the namespaces Y* and Z* were provided for customers, and the namespace
J_<number> was reserved for partners.
In R/3 Release 4.0 a new namespace concept was introduced which, together with the longer
development object names, made it easier to assign names to objects developed by customers
and partners.
The Business Object Repository (BOR) introduced before R/3 Release 4.0 still uses the old
namespace concept. For this reason the limitations of the old namespace concept still apply to
the namespaces for BAPI development objects.
Reserved Namespaces/Prefixes for Various Application Groups
User
Prefix
Special SAP project
For example, “JPN” for developments in the Japanese area.
Industrial Business Units (IBUs) do not have specific
namespaces.
Partners/software
houses
The following prefixes are used:
Customers
•
J_y" (where "y” is a single digit allocated namespace) for
partners/software houses whose namespaces were
assigned before Release 4.0.
•
"JJ<Namespace>" (where "<Namespace>" is the
registered namespace) for partners/software houses
whose namespaces were assigned after Release 4.0,
for example, JJABC.
"Y" and "Z", for function modules matching "Y_" and "Z_".
If a customer or partner creates a new object type that is not a sub-type of another object type,
the naming convention for this object type applies to all the sub-objects. In principle, therefore,
SAP object types cannot overlap with each other, regardless of the names of the methods,
attributes and so on.
Sub-object types split the namespace for methods, attributes and so on with the superordinate
object type. You must follow the naming conventions for the sub-objects too.
Naming Conventions for BAPI Development Objects
Development Object
Created in...
Naming Convention
Domain
ABAP
Dictionary
Standard in the respective R/3 Release
December 1999
161
BAPI Programming
SAP AG
Namespaces
Data Element
ABAP
Dictionary
Standard used in the respective R/3 Release
Structure
ABAP
Dictionary
ABAP
Dictionary
ABAP
Dictionary
Function
Builder
Function
Builder
Function
Builder
BOR
<Prefix>BAPI*
Field in structures
Append structure
Function group
Function Module
Function module
parameter
Object name (name of
object type)
Standard used in the respective R/3 Release
Standard used in the respective R/3 Release
<Prefix>BAPI_<object type>_<method>
<Prefix>*, except for parameters in
customers’ function modules
<Prefix>object name<Suffix>
Suffixes are only used if there is/could be a
name conflict within SAP.
•
If object types from standard
applications require the same object
name, the node of the component
hierarchy is added on as a suffix. For
example, the business object type,
BusinessProcess in Controlling (CO)
would be named BusinessProcessCO
•
If there is a name conflict between a
standard application and an IBU, the
object type in the standard is
assigned the object name without the
suffix. The object type in the IBU is
assigned the IBU code from the
component hierarchy as a suffix.
Prefixes are reserved exclusively for partners
and customers. For example, if a customer
changes the object type BusinessProcessCO,
a possible name for it could be
YBusinessProcessCO.
162
Object type (technical
object name)
Attribute name
Method
BOR
<Prefix>*
BOR
BOR
Method parameters
BOR
<Prefix>*
<Prefix>*, except for modifications using
delegation, otherwise delegation does not
work.
<Function module parameter>
December 1999
SAP AG
BAPI Programming
Namespaces
December 1999
163
BAPI Programming
SAP AG
Using BAPIs in Distributed Systems (ALE)
Using BAPIs in Distributed Systems (ALE)
Purpose
Since Release 3.0 ALE (Application Link Enabling) technology has enabled data to be
exchanged between individual distributed SAP Systems and non-SAP systems.
BAPI Development Even if one of the systems fails, or a communications link is interrupted, the
remaining systems must be able to continue to function. Loose coupling means that the individual
systems for the most part communicate asynchronously, (with a time delay) with each other.
For these reasons messaging is used for data communication between the participating systems
in ALE distribution scenarios.
As of Release 4.0 you can implement an asynchronous BAPI interface by generating an ALE
IDoc interface for the BAPI and using it in an appropriate ALE distribution scenario.
For further information on ALE technology and using BAPIs in the context of ALE, see ALE
Programming Guide [Ext.]. This section provides a general overview of points you should keep in
mind when implementing a BAPI to exchange data asynchronously.
Process Flow
When you use BAPIs for asynchronous messaging, the application in the sending system calls
the generated ALE IDoc interface instead of the BAPI. The ALE IDoc interface performs the
following tasks:
•
Creates an IDoc from the BAPI data
•
Sends the IDoc to the target system
•
Receives the IDoc in the target system, creates the BAPI data from the IDoc and calls the
BAPI
You can use Transaction BDBG to create the additional objects required for the BAPI in this
process, that is, the associated IDoc and the required function modules. This transaction is
described in detail in the ALE Programming Guide [Ext.].
Prerequisites
Before you can implement a BAPI used to transfer data asynchronously in ALE, make sure that a
BAPI of this type is actually required for the task in hand. If at least one of the conditions below
applies, you should implement your BAPI as an asynchronous interface:
•
Consistent database changes in several systems
Data must be updated consistently on both the local system and on the remote system.
•
Loose coupling
With a synchronous interface the coupling between the client and the server system is
too narrow. If the connection is interrupted the client system would not be able to function
properly.
•
Performance
The interface has a large volume of data or database operations to be carried on the
server system will take a long time. In this situation a synchronous interface cannot be
used because performance would be too low.
164
December 1999
SAP AG
BAPI Programming
Using BAPIs in Distributed Systems (ALE)
Additional Guidelines
If you are sure you want to implement your BAPI as an asynchronous interface you should keep
in mind the following points in addition to the general BAPI programming guidelines:
•
The BAPI must not issue a COMMIT WORK command.
•
The BAPI return parameter must use the reference structure BAPIRET2.
•
All BAPI export parameters with the exception of the return parameter are ignored and are
not included in the IDoc that is generated.
•
After the function module which converts the IDoc into the corresponding BAPI in the
receiving system has been called, status records are written for the IDoc in which messages
sent in the Return parameter are logged.
If the field type is filled with E (error) or A (abort) in at least one of the transferred return
parameter entries, the status 51 (application document has not been posted) is assigned
to all the status records of the IDoc after a ROLLBACK WORK has been executed. If the
field type is filled with E (error) in at least one of the transferred return parameter entries,
the status 51 (error, application document has not been posted) is assigned to all the
status records of the IDoc and a COMMIT WORK is executed. Otherwise status 53
(application document posted) is written and a COMMIT WORK executed.
December 1999
165
BAPI Programming
SAP AG
BAPI Quality Checklist
BAPI Quality Checklist
Definition
The check list below contains extracts from the BAPI Quality Checklist used internally in SAP to
develop BAPIs.
You can refer to this check list during the entire development and implementation of a BAPI.
BAPI Quality Checklist
This checklist helps you to develop BAPIs in accordance with the programming guidelines and
enables you to implement the best quality BAPIs right from the start. You should use this
checklist to manage the development of all BAPIs in your integration scenario.
Scenario
Person responsible: Developer
BAPIs must be developed as part of an integration scenario. This will ensure that they
complement each other, and that access to the R/3 functionality is provided in a structured and
practical way.
Scenario to be implemented
[Name of the scenario]
-----------------------------------------------------------------------
Quality of Object Modeling
Person responsible: Developer
[] Existing object model
Business object types used in the scenario and person responsible
1. [Name of business object type] [Name of person responsible]
2. [ ] [ ]
3. [ ] [ ]...
BOR methods to be implemented
1. [Name of business object type] [BAPI name]
2. [ ] [ ]
3. [ ] [ ]...
Name of the function module
1. [Name of function module]
2. [ ]
3. [ ]...
----------------------------------------------------------------------
166
December 1999
SAP AG
BAPI Programming
BAPI Quality Checklist
Specification
Person responsible: Quality assurance/central development department
[ ] BAPI concept or specification has been checked by the central development department
and by the responsible quality manager.
[Name of the contact person in the central development department]
[Name of the quality manager]
You must mark the checkbox for all the BAPIs in this development request.
---------------------------------------------------------------------Quality of the Method Concept
Person responsible: Developer
You must mark the checkbox for all the BAPIs in this development request.
Fields and Parameters
[ ] All field and parameter names must be in English
[ ] All the quantity fields must have units of measurement fields
[ ] All currency amount fields must have currency indicator fields
[ ] All key fields in GetDetail() and GetList() BAPIs must be displayed in a text field.
[ ] All BAPI structures begin with the prefix “BAPI” and all foreign keys are defined.
Data conversion
[ ] Only internal data formats are used, with the following exceptions: (mark these exceptions):
[ ] All the date fields must have the format JJJJMMTT
[ ] All currency amounts are based on the domain BAPICURR
[ ] PSP elements and similar fields use external keys
[ ] Additional fields are provided for ISO codes
[ ] Currency amounts with decimal places are displayed with decimal points in the interface,
For example, 10.12 is displayed as 10.12 and not as 1012.
Security issues
[ ] All BAPIs contain authorization checks
[ ] All F4 possible entries have authorization checks
Updates
Database changes can only be made through updates.
Commit Work
BAPIs containing the COMMIT WORK command (exceptions only)
[Name of business object type] [BAPI name]
[][]
[ ] [ ]....
December 1999
167
BAPI Programming
SAP AG
BAPI Quality Checklist
[ ] No COMMIT WORK in asynchronous BAPIs that are sued in the context of ALE/BAPI
Integration
----------------------------------------------------------------------
Quality of the BOR Definition
Person responsible: Developer
[ ] Table parameters are marked in the BOR "Imp. and Exp." only if they have to be imported as
well as exported. Otherwise either the indicator Imp or Exp is used.
Person responsible: Central development department
[ ] Instance-dependency/instance-independency checked
[ ] BAPI name(n) OK (agree name with person in development department)
[Name of person]
A cross in a checkbox applies to all the BAPIs in this development request.
-----------------------------------------------------------------------Quality of Documentation and Functionality
Person responsible: QM
A cross in a checkbox applies to all the BAPIs in this development request.
Documentation
[ ] BAPIs and all the associated parameters are fully documented
[ ] Documentation on the parameter RETURN contains all the important return codes and
messages
[ ] The comprehensibility and user friendliness of the documentation has been checked
[ ] Documentation describes the use of the COMMIT WORK command (if applicable)
[ ] Documentation on the function module has been saved to the active version
[ ] Business object type has been documented
[ ] BAPI scenario (ALE Business Process) has been documented
Tests
[ ] Individual tests OK
[ ] Integration tests OK
[ ] Calling from external programs OK
[Name of quality manager responsible]
------------------------------------------------------------------------
168
December 1999
SAP AG
BAPI Programming
BAPI Quality Checklist
Authorization to Release
Person responsible: Quality assurance/central development department
[ ] Authorized by member of central development department
[Name of person]
[ ] Authorized by quality manager
[Name of the quality manager]
A cross in a checkbox applies to all the BAPIs in this development request.
-----------------------------------------------------------------------If all the fields have been marked are filled, you can release your BAPI(s) and the development
request. Thank you for your cooperation.
December 1999
169