Bapi Programing

8/12/2019 Bapi Programing

1/57

1

BAPI PROGRAMMING..............................................................................................3 VERSION ...............................................................................................................................................................4

COPYRIGHT ..........................................................................................................................................................4

CONVENTIONS......................................................................................................................................................4

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

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

TRANSACTION MODEL FOR DEVELOPING BAPIS.............................................................................7

USING THE TRANSACTION MODEL IN RELEASE 3.1.............................................................8

TRANSACTION MODEL FOR RELEASE 3.1............................................................................................9

USING THE TRANSACTION MODEL IN RELEASE 4.0A .........................................................9

EXTENDED TRANSACTION MODEL ....................................................................................................10

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

FREQUENTLY USED BAPIS....................................................................................................11

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

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

DEFINING A BAPI AND ITS INTERFACE...............................................................................14

12

3 DETERMINING THE SAP BUSINESS OBJECT AND ITS KEY FIELDS.....................15

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

NAMING PARAMETERS IN THE FUNCTION MODULE .............................................17

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

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

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

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

CONVERSION BETWEEN INTERNAL AND EXTERNAL DATA FORMATS................22

12 3

CONVERTING BETWEEN INTERNAL AND EXTERNAL DATA FORMATS...23


2/57

2

APPLICATION EXAMPLE ...............................................................................................24

12 3

DEFINING METHODS IN THE BOR USING THE BOR/BAPI WIZARD ...................26

EXAMPLE OF A FUNCTION MODULE .........................................................................................27

TESTING THE BAPI..............................................................................................................................28

1

2 3 RELEASING AND FREEZING THE BAPI ..............................................................................................29

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

PROGRAMMING CHANGE BAPIS............................................................................................31

PROGRAMMING REPLICATE/CLONE BAPIS..........................................................................33

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

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

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

Provi ding I nput Help (F 4 Help).................................................................40

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

ENHANCEMENTS TO EXISTING BAPIS...............................................................................................43

CUSTOMER MODIFICATIONS OF BAPIS.............................................................................................46

IMPLEMENTING BAPIS IN ALE SCENARIOS .....................................................................................47

12 3

BAPI IMPLEMENTATION CHECKLIST .................................................................................................48


3/57

3

BAPI Programming

Purpose

This document describes the guidelines you should follow to implement BusinessApplication Programming Interfaces (BAPIs). It is targeted at developers who want to

implement BAPIs.

This document describes the guidelines valid at the time this document was published.These guidelines will be updated in subsequent R/3 Releases.

All developments should be done in the customer name space; all changes to existing

development objects are considered to be modifications.

Prerequisites

To program and implement a BAPI you need to have:

Basic knowledge of BAPIs, as described in BAPI - Introduction and Overview

Knowledge of the ABAP programming language and environment

Basic knowledge of the R/3 System

Process Flow

To implement a BAPI follow the processes described in the sections below as closely

as possible:

Transaction Model for Developing BAPIs

Defining and Implementing the BAPI

Creating Individual Programming Objects

Programming BAPIs

Testing the BAPI

Releasing and Freezing the BAPI

A BAPI Implementation Checklistis available to guide you through the implementation.

You should print it out and use it as a reference during the entire implementationprocess.

Other topics related to developing BAPIs are:

Enhancements to Existing BAPIs

Customer Modifications of BAPIs

Implementing BAPIs in ALE Scenarios

Select F1 to display help on the help function.

Version

Copyright

Conventions


4/57

4

Version

R/3 Release 4.0

December 1997

Copyright

Copyright 1997 SAP AG. All rights reserved.

No part of this documentation may be reproduced or transmitted in any form or for anypurpose without the express permission of SAP AG.

SAP AG further does not warrant the accuracy or completeness of the information, text,graphics, links or other items contained within these materials. SAP AG shall not beliable for any special, indirect, incidental, or consequential damages, including withoutlimitation, lost revenues or lost profits, which may result from the use of these materials.

The information in this documentation is subject to change without notice and does notrepresent a commitment on the part of SAP AG in the future.

Some software products marketed by SAP AG and its distributors contain proprietary

software components of other software vendors.

Microsoft, WINDOWS, NT and EXCEL and SQL-Server are registeredtrademarks of Microsoft Corporation.

IBM, OS/2, DB2/6000, AIX, OS/400 and AS/400 are a registered trademarkof IBM Corporation.

OSF/Motif is a registered trademark of Open Software Foundation.

ORACLE is a registered trademark of ORACLE Corporation, California, USA.

INFORMIX-OnLine for SAPis a registered trademark of Informix SoftwareIncorporated.

UNIX and X/Open are registered trademarks of SCO Santa Cruz Operation.

ADABAS is a registered trademark of Software AG.

SAP, R/2, R/3, RIVA, ABAP/4, SAPoffice, SAPmail, SAPaccess, SAP-EDI, SAP ArchiveLink, SAP EarlyWatch, SAP Business Workflow, R/3 Retail

are registered trademarks of SAP AG.

SAP AG assumes no responsibility for errors or omissions in these materials.

All rights reserved.

Conventions


5/57

5

Type style Description

Interface Text Words or characters that appear on the screen. Thisincludes field names, screen titles, pushbuttons, menunames, and menu options.

Document Title Cross-references to other documentation

User Entry Words and characters that you enter exactly as they appearin the documentation

Variable user entry. Pointed brackets indicate that youreplace these words and characters with appropriate entries.

NAME Names of elements in the R/3 System. These include

program names, transaction codes, table names, ABAPlanguage elements, file names, and directories.

Icon Description

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

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

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

Descriptions of R/3 System functions(such as reporting

functions)

12 3

Step-by-step proceduresfor completing a specific task

Overviewinformation

Conceptinformation

NoteImportant information like special considerations or

exceptions

ExampleExample

CautionHelps you avoid errors such as those that could lead to dataloss

BAPI

Definition

A Business Application Programming Interface (BAPI) is a precisely defined interface

providing access to processes and data in business application systems such as R/3.


6/57

6

BAPIs are defined as API methods of SAP Objects. These objects and their BAPIs are

described and stored in the BOR(BOR).

Use

BAPIs can be called within the R/3 System from external application systems and other

programs. A BAPI call can either be made as an object oriented method call or as aremote function call (RFC).

BAPIs are a global communication standard for business applications.

Examples of what BAPIs can be used for include:

R/3 satellite systems

Distributed R/3 scenarios using Application Link Enabling (ALE)

Connecting R/3 Systems to the Internet using Internet application components(IACs)

Visual Basic programs as frontends to R/3 Systems

Work flow applications that extend beyond system boundaries

Customers' and partners' own developments

Connections to non-SAP software

Connections to legacy systems

See also:

BAPI - Introduction and Overview.

BOR

Definition

The Business Object Repository (BOR) is the object oriented repository in the R/3System. It contains, among other objects, SAP Business Objects and their methods.

In the BOR a Business Application Programming Interface (BAPI) is defined as an API

method of an SAP Business Object. Thus defined, the BAPIs become standard with fullstability guarantees as regards their content and interface.

Use

With regard to SAP Business Objects and their BAPIs, the BOR has the followingfunctions:

Provides an object oriented view of R/3 System data and processes.

R/3 application functions are accessed using methods (BAPIs) of SAP BusinessObjects. Implementation information is encapsulated; only the interfacefunctionality of the method is visible to the user.

Arranges the various interfaces in accordance with the component hierarchy,enabling functions to be searched and retrieved quickly and simply.

Manages BAPIs in release updates.


7/57

7

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 theBOR. The same applies when any interface parameter is created.

The version control of the function module that a BAPI is based on is managed inthe Function Builder.

Ensures interface stability.

Any interface changes that are carried out in the BOR, are automatically checkedfor syntax compatibility against the associated development objects in the ABAPDictionary.

Integration

You should only define a BAPI as a SAP Business Object method in the BOR if the

function module that the BAPI is based on has been fully implemented.

Full access to the BOR is restricted to the persons responsible for the objects involvedand for quality control.

BOR-BAPI WizardThe BOR-BAPI Wizardassists with creating new BAPI methods in the BOR. It takesyou through the creation process step by step.

Transaction Model for Developing BAPIs

Purpose

The transaction model in which BAPIs are used determines how you have to program

BAPIs.The transaction model described here has been used to develop BAPIs for R/3

Releases 3.1 and 4.0A.

Logical Unit of Work (LUW) and Statelessness

Within the context of this transaction model a transaction represents one processing

step or one logical unit of work (LUW). When a transaction is called, databaseoperations are either fully executed or not at all. The whole transaction must beprogrammed to be stateless.

This transaction model requires that:

No data is imported that may indirectly affect the result. If a transaction is calledmore than once, each call must have the same result.

For BAPIs this means, for example, that Set or Get parameters cannot be used.However, you can keep Customizing data in a global memory as this data remainsunchanged even if transaction calls are repeated.

There must be no functional dependencies between two transactions.

Either allrelevant data has to be changed in the database or none at all.

The following sections describe how the transaction model effects BAPI development:

Using the Transaction Model in Release 3.1


8/57

8

Using the Transaction Model in Release 4.0A

Using the Transaction Model in Release

3.1

Purpose

The example below of an external program calling a BAPI to change data in an R/3

System, illustrates how the transaction model affects BAPI development in Release3.1. Assume the transaction was written in, for instance, Visual Basic and that data is tobe changed in the R/3 System only.

The RFC connectionis live the whole time the external program is logged on tothe R/3System to avoid having to connect and disconnect repeatedly. When the RFCconnection is already established, an RFC call does not essentially take up any more

CPU time than a direct call to the function module from within the R/3 System.

There is one BAPI call for each transaction in the transaction model supported in 3.1.BAPIs can only be called synchronously. A BAPI call is essentially the call of the

underlying RFC capable function module.

Process Flow

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

Log on

... .. (Visual Basic source code)

Call BAPI to read and/or change data




Log off

Prerequisites

What do the terms "LUW" and "statelessness" mean to BAPIs that are implemented inthe framework of this transaction model?

If a transaction represents one Logical Unit of Work and in addition is supposed to bestateless, 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 notaffected by the execution of the BAPI, for example, Customizing data, can bebuffered.

No functional dependency between two BAPIs

A BAPI call must not be negatively affected by an earlier call of another BAPI. Afollow up call must not presuppose an earlier call.

All or nothing principle

A database change, for example, creating a new sales order, must be carried out


9/57

9

completely or not at all (LUW).

This is why BAPIs to be implemented in 3.1 are created with integrated commitcontrol. The "Commit Work" command is always invoked at the end of the functionmodule of a BAPI that modifies data.

Transaction Model for Release 3.1

Using the Transaction Model in Release4.0A

Purpose

In Release 4.0A the Commit control must be taken out of write BAPIs, that is, thoseBAPIs that cause database changes. However, the existing transaction model used in

Release 3.1 should not be changed. This is achieved by using the RFC capablefunction module BAPI_TRANSACTION_COMMIT which executes the command"Commit Work".

This procedure is required because BAPIs are used for continued development of the

R/3 System, for example, for separating individual R/3 components. If this is the case,BAPIs must support the transaction model used in the R/3 System.

Features

A program based on this transaction model could consist of the following steps (see

graphic):

Log on




10/57

10

Call BAPI_TRANSACTION_COMMIT



Call BAPI_TRANSACTION_COMMIT


Log off

Extended Transaction Model

Defining and Implementing the BAPI

Purpose

A BAPI is an API method of a business object and is defined as such in the BusinessObject Repository (BOR). However, a BAPI is implemented as an RFC capable

function module which is maintained in the Function Builder.

For function modules that implement BAPIs certain standards and rules must be

adhered to over and above the standard programming rules for function modules. Thissection describes how to define a BAPI and which particular guidelines to comply with.

When implementing BAPIs follow the requirements below to ensure you achieveconsistent behavior and representation of BAPIs as object oriented methods of SAP

Business Objects.

There is a range of BAPIs that provide basic functions and these can be implementedfor most of the SAP Business Objects. For information on these BAPIs see the section

Frequently Used BAPIs. Check if the BAPI you want to implement is in one of thesegeneral categories.


11/57

11

Process Flow

The process of defining and implementing a BAPI consists of the following steps:

Describing the Scenario the BAPI is Used in

Reviewing the BAPI Concept and BAPI Scenario

Defining a BAPI and Its Interface


Testing the BAPI

Releasing and Freezing the BAPI

Frequently Used BAPIs

Definition

Some BAPIs and methods provide basic functions and can be used for most SAP

Business Objects. These BAPIs are:

BAPIs for Reading Data

The following BAPIs provide you with read-only access to data in the associated

Business Object:

GetList

With this BAPI you can select a range of object key values, for example, company

codes and material numbers. To specify appropriate selection requirements thecalling program must pass the relevant parameters to the interface.

The key values selected by the BAPI GetListare returned to the calling program in

a table, together with other useful information, for example, short texts. The keyvalues can then be passed on to another BAPI for further processing, for example,the BAPI GetDetail, as listed below.

For further information on programming GetList BAPIs see Programming ValueRanges.

GetDetail

The BAPI GetDetailuses a key to retrieve details about a specific instance of anobject and returns this data to the calling program.

GetStatus

The BAPI GetStatusis used to query the status of an SAP Business Object, for

example, to determine the processing status of a sales order. This BAPI is usedonly for displaying the status of an object and does not retrieve full details like the

BAPI GetDetail.

ExistenceCheck

The BAPI ExistenceCheckchecks whether an entry exists for an SAP Business

Object, for example, whether the customer master has been created. You shouldimplement this method as a workflow method and not as a BAPI (RFC capablefunction module).

The method CompanyCode.ExistenceCheck of the business object CompanyCode(BUS0002) is an example of this. This workflow method is indirectly invoked when


12/57

12

the calling program instantiates an object, for example, by using

GetSAPObject("CompanyCode") from within Visual Basic.

BAPIs for Creating or Changing Data

The following BAPIs can create, change or delete instances of a business object:

Create or CreateFromData

The BAPI Createor CreateFromData creates an instance of an object, for example,

a sales order.

Change

The BAPI Changechanges an existing instance of a SAP Business Object, forexample, a sales order.

For more information about the BAPI Changesee Programming Replicate/CloneBAPIs.

Delete

The BAPI Deletedeletes an instance of a SAP Business Object, for example, asales order.

BAPIs for Replicating Business Object Instances

The BAPIs below can be implemented as methods of business objects that can bereplicated. For further information about these BAPIs see ProgrammingReplicate/Clone BAPIs:

Replicate

The BAPI Replicateis used by a client system to request clones of businessobjects in a server system.

This method must be implemented for each business object to be cloned.

At least one of the following BAPIs must be implemented for each business object to becloned:

Clone

The BAPI Cloneis used by a system to replicate one business object on anothersystem or to modify one business object that has already been cloned.

CloneMultiple

The BAPI CloneMultiple is used by a system to replicate several business objects onanother system or to modify several business objects that have already been cloned.

Unlike the BAPI Clone, the BAPI CloneMultiplecan replicate or modify severalbusiness object instances at the same time.

Defining a BAPI Scenario

Purpose

Before you program a BAPI you should clearly define the processes and situations the

BAPI will be used for.

Process Flow

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


13/57

13

Which scenario is to be implemented?

Every BAPI should be based on a model of a scenario in which it can be usefullyemployed. You can describe the scenario in the form of a process model.

Which SAP Business Objects are involved?

From the scenario definition and with the help of the process model you can getinformation about the SAP Business Objects relevant to the BAPI scenario.

Example

In the scenario to be implemented, a BAPI is required to read data about a

creditor. First of all, a list of creditors is to be displayed from which a specificcreditor can be selected. Then, using another BAPI, specific details about thiscreditor are to be displayed.

The relevant SAP Business Object for this scenario is Creditor.

What functionality should the BAPI provide and how does it affect related BAPIs,especially the other BAPIs of the SAP Business Object in question?

In line with the scenario concept BAPIs must complement each other to create acomplete scenario. Their relationships with each other must be clearly defined.

Example

To read a creditor's details as described in the above scenario, two BAPIs arerequired:

- Display list of creditors

- Display details of a specific creditor

The interdependency between these two BAPIs is evident because first the

creditor list is displayed to obtain the ID of the specific creditor sought. From thisID, details of this creditor can then be displayed.

However, the two BAPIs remain functionally independent of each other,

because if the creditor ID is known, the BAPI "Display details of a specific

creditor" can be used without first calling the BAPI "Display list of creditors".

To what extent can the BAPI's functionality be implemented within the scope of the

business object?

A BAPI should be developed so that it provides functionality exclusively within thecontext of its associated SAP Business Object. If the data of a different SAP

Business Object is to be read or updated then the appropriate interface for thisobject must be used. The functions or methods of these other objects are usedimplicitly (delegation principle).

Example

The BAPIs required to read creditor details in the above scenario are only able

to access data in the SAP Business Object Creditor.Other object types are notinvolved.

Is the BAPI assigned to the SAP Business Object in a meaningful and semanticallycorrect way?

Result

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

Objects relevant to the BAPI scenario.


14/57

14

Review

Purpose

In the previous step you created a concept for a scenario a BAPI could be applied to.You also defined relevant SAP Business Objects.

Before you implement the scenario and begin defining and developing the BAPI, youshould carry out a review of the scenario concept.

Process Flow

You should carry out the review of the BAPI scenario in cooperation with all personsinvolved in the BAPI development and those responsible for quality control in your

development group.

Result

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

Defining a BAPI and Its Interface

Purpose

After you have carried out the review of the BAPI concept and it has been accepted,you can start defining the BAPI itself.

In this step, you will decide on the names, parameters, and characteristics of the BAPIand determine the structures the BAPI will be based on.

Only after you have planned and defined these required details can you start toimplement the BAPI, as described in Creating Individual Programming Objectsand

Programming BAPIs.

Process Flow

To define the scope and required components of the BAPI to be implemented, thefollowing steps must be completed:

Determining the SAP Business Object and Its Key Fields

Defining the Interface Structure of the BAPI

Identifying the name of the function group, or if a function group does not existalready, planning a name for one.

All BAPIs belonging to one SAP Business Object should be stored as functionmodules in one function group. Ascertain whether a function group has alreadybeen created for the BAPIs of the SAP Business Object in question. If a function

group does not already exist, then plan a name for the one to be created.

You can use the default technical name (object type) of the SAP Business Objectas the basis of the function group name. The technical name of a SAP Business

Object usually takes the form of BUSnnnn, where n is a number. Use the suffix"nnnn" as the name of the function group. For example, if the technical name of the


15/57

15

object is BUS1008 then the associated BAPI function group is called 1008.

To ascertain the technical name of the Business Object, open the Business Objectin the Business Object Repository (BOR), as described in Determining the SAPBusiness Object and Its Key Fields. To display further details, for example, the

object type, double click the name of the Business Object.

Assigning a name to the function module

Choose a name that gives an indication of what the BAPI is used for. The naming

convention is: BAPI__. For informationabout naming a method refer to Naming the Method in the BOR.

For example, in the case of a BAPI which reads details for the object type Creditor,

the name of the associated function module is BAPI_CREDITOR_GETDETAIL.

Naming Parameters in the Function Module

Defining the format for passing the values in the function module interface.

Parameters must not be converted before they are passed to and from the BAPIinterface. This is because BAPIs are programming interfaces and not end userinterfaces. Exceptions are currency codes, ISO codes and fields with an internal

key.

Specifying the Required Objects in ABAP Dictionary

Naming the Method in the BOR

Naming Parameters in the BOR

12

3 Determining the SAP Business Object andIts Key Fields

You have to identify the relevant SAP Business Object in the Business ObjectRepository (BOR) and determine whether the key fields of the Business Object arerelevant for your BAPI.

A key is defined in the BOR for most SAP Business Objects. This key can consist ofseveral key fields. The contents of these key fields uniquely identifies one individualinstance of an SAP Business Object.

You can differentiate between instance-dependent and instance-independent BAPImethods. Unlike instance-independent methods, instance-dependent methods relate toone instance (one specific occurrence) of an SAP Business Object type, for example to

one specific sales order.

In the case of instance-dependent BAPIs, the key fields of the corresponding SAP

Business Object must be used as parameters in the function module the BAPI is basedon so that the associated object instance can be identified. The names of the key fieldsin the SAP Business Object and the corresponding parameters in the BAPI functionmodule must be the same, because the name links the key fields to the parameters.

All the key fields defined in the BOR for the SAP Business Object in question must beused as the parameters in the function module. For further information see Defining theInterface Structure of the BAPI.

Example

SAP Business Object Creditorhas a key field named CreditorId.


16/57

16

This key field must be defined as a parameter with the name CREDITORIDin

the function modules of the instant-dependent BAPIs for this Business Object.

To display the Business Object and its key fields follow the steps below:

1. Select ToolsABAPWorkbenchOverview Business Object Browser.The

business objects are displayed in the order of the R/3 application hierarchy.

2. Select the required SAP Business Object in the application hierarchy and doubleclick it to open it.

3. To display the Business Object's key fields, expand the node Key fields.

Defining the Interface Structure of the BAPI

Purpose

In this step you are going to define the BAPI interface, that is, the individual import,

export and table parameters required for calling the BAPI.

Caution

You cannot use Changing and Exception parameters in a function module

which implements a BAPI.

Process Flow

To define the interface parameters, proceed as follows:

1. Check whether the key fields of the SAP Business Object are required in theinterface. The key fields of the SAP Business Object are some of the most importantBAPI 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. Thatway a specific instance of the Business Object is identified.

For example, this could be a customer number (CustomerNo) in the BAPIs

Customer.GetDetailand Customer.CheckPassword,or the number of a salesdocument in the BAPI SalesOrder.GetStatus.

- For BAPIs that generate instances, for example, the BAPIs Createor

CreateFromData, the key field of the Business Object should be set as anexport parameter in the BAPI function module.

These BAPIs return one key value, for example, an order number in the BAPI

SalesOrder.CreateFromData.

- For BAPIs that are class methods a key field is neither set as an import noras

an export parameter in the BAPI function module.

Class methods are instance-independent and are called without the use of keyvalues. Usually they return a table with a selection of key values. Exceptions

are write BAPIs, as described in the list item above.

2. Specify what other data is relevant as import, export or table parameters for theBAPI.

Every BAPI must have an Export parameter returnthat reports messages back tothe calling program.


17/57

17

Example

The BAPI to be developed is to read data from the SAP Business Object

Creditor. To read creditor details, the calling program has to pass the ID of thecreditor and the company code. The creditor data returned is to include generaldetails, specific details and bank details.

To map these requirements onto the BAPI interface, the following parametersmust be set in the function module which the BAPI is based on:

The key field CreditorIDof the SAP Business Object as an import

parameter

An import parameter for the company code

A Return parameter that reports messages back to the call ing program

A parameter for general details of the creditor

A parameter for specific details of the creditor

A parameter for bank details of the creditor

Naming Parameters in the Function Module

Purpose

In the previous step you identified the contents of the interface parameters. Now youcan specify the names of these parameters in the function module.

Prerequisites

You can only define export, import and table parameters in the function module

interface of the BAPI.

Give meaningful names to the parameters in the function module interface to give theBAPI an easy-to-use interface. This is because the names you choose for the functionmodule parameters are used in the Business Object Repository (BOR) as the names of

the corresponding method parameters.

When assigning parameter names follow the guidelines below:

The names must be in English

The names of parameters in the function module can generally be a maximum of30 alphanumeric characters. The names of parameters in a function module thatimplements a BAPI can only have a maxiumum of 20 alphanumeric characters,

because the names of parameters in the function module must be identical to the

parameter names in the BOR, and the latter are restricted to a maxiumum of 20characters.

The names of parameters in the function module must be written in capitals.

Choose meaningful names and do not use abbreviations.

Example

In the above example based on the creditor scenario, the following parameters

were identified:

An import parameter fo r the key field CreditorIdof the SAP Business


18/57

18

Object

An import parameter for the company code

A Return parameter

A parameter for general details of creditor

A parameter for specific details of creditor

A parameter for bank details of creditor

You could use the following names for these parameters in the function

module:

Parameters and their Names in the Function Module

Contents Name in Function Module Parameter

Type

Creditor number

Company code

General creditor details

Specific creditor details

Return parameter

Bank details

CREDITORID

COMPANYCODE

CREDITORGENERALDATA

CREDITORCOMPANYDATA

RETURN

CREDITORBANKDATA

IMPORTING

IMPORTING

EXPORTING

EXPORTING

EXPORTING

TABLES

Specifying the Required Objects in ABAPDictionary

Purpose

After you have specified the contents and names of the required interface parametersyou can identify and define the required data objects in the ABAP Dictionary.

Note the following:

You can use individual fields, structures and tables as parameters. Everyparameter must refer to a Dictionary object.

You have to create your own data structures for the BAPI interface that are

independent of the data structures generally used in the R/3 application. Thisenables changes to be made in R/3 applications without affecting BAPIs.

Give meaningful names to the data structures you create. Names should begin with

the prefix BAPI.

Chose meaningful names in English for the structure fields. Up until Release 4.0ten characters were available for naming structures; from Release 4.0 you can use

up to 30 characters. You can use alphanumeric characters and underscores.


19/57

19

You can use existing data elements and domains for the fields in the BAPI

structures. As of Release 4.0 it is possible to assign English names to the dataelements in the ABAP Dictionary. Whenever possible use these names for the fieldand parameter names.

Example

In the example in the previous steps the reference fields/tables shown belowwere 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 moremeaningfully in Release 4.0.

Parameters and their Reference Fields in Release 3.1

Parameter in the Function Module Reference Field/Table

CREDITORID

COMPANYCODE

CREDITORGENERALDATA

CREDITORCOMPANYDATA

RETURN

CREDITORBANKDATA

BAPI1008-VENDOR_NO

BAPI1008-COMP_CODE

BAPI1008_4

BAPI1008_5

BAPIRETURN2

BAPI1008_6

Parameters and their Reference Fields in Release 4.0

Parameter in the Function Module Reference Field/Table

CREDITORID

COMPANYCODE

CREDITORGENERALDATA

CREDITORCOMPANYDATA

RETURN

CREDITORBANKDATA

BAPI1008-VENDOR_NO

BAPI1008-COMP_CODE

BAPI1008_CREDITORGENERALDATA

BAPI1008_CREDITORCOMPANYDATA

BAPIRETURN2

BAPI1008_CREDITORBANKDATA


20/57

20

Naming the Method in the BOR

Purpose

You can now plan the name of the BAPI method in the Business Object Repository

(BOR).

Prerequisites

The individual components of BAPI names are identified by the use of upper and lowercase letters, for example, ChangePassword.

BAPI names must be meaningful and be in English, and can only have a maximum of

30 characters. For example:

ExistenceCheck

ChangePassword

GetDetail

If you are implementing one of the frequently used BAPIsuse the appropriate generic

name.To get an idea about naming BAPIs take a look at existing BAPIs of an SAP BusinessObject in the BOR. Select an SAP Business Object in the application hierarchy in theBusiness Object Browser and expand the node Methods.

BAPIs are identified by the API indicator (green circle) to the right of the method name.

Naming Parameters in the BOR

PurposeThe parameter names of the methods in the Business Object Repository (BOR) arebased on the parameter names in the function module. You have already named theparameters of the function module in Naming Parameters in the Function Module.

Caution

From Release 4.0 the names of the BAPI parameters in the BOR and the

names of the parameters in the corresponding function module must beidentical. This was not necessarily the case in earlier releases.

When naming parameters of a BAPI in the BOR take account of the following:

The parameters must be in English.

Unlike parameter names in the function module that must be written completely in

upper case, the components of parameter names in the BOR are separated byupper and lower case letters. Every new word in the parameter name begins with acapital letter, for example, ChangePassword.

A parameter name in the BOR cannot have more than 20 characters.

To get an idea about naming BAPI parameters, take a look at the parameters ofexisting BAPIs in the BOR. Select an object type in the application hierarchy in the

Business Object Browser. Expand the node for the object's methods, then select aBAPI, then finally selectParameter.


21/57

21

Example

In the example in the previous steps six parameters for a BAPI were identifiedand names given to these parameters in the function module.

The table below shows what the parameter names could look like in the function

module and in the BOR.

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

Contents Name in Function

Module

Name in the BOR

Creditor number

Company code

General creditordetails

Specific creditordetails

Return parameter

Bank details

CREDITORID

COMPANYCODE

CREDITORGENERALDATA

CREDITORCOMPANYDATA

RETURN

CREDITORBANKDATA

Defined as a key fieldof the Business Object

Creditor and NOT as aBAPI parameter.

CompanyCode

CreditorGeneralData

CreditorCompanyData

Return

CreditorBankData


Purpose

After you have identified the individual programming objects and given them names youshould create them in the R/3 System as required.

Process Flow

To create the required programming objects in R/3 the following steps are required:

Creating the Dictionary objects, for example, structures, fields and domains, in theABAP Dictionary.

Creating the function group in the Function Builder (if required).

Creating the function module in the Function Builder.

Writing documentation for the BAPI.


22/57

22

BAPI documentation is essential because it is very difficult to use a BAPI that has

not been well documented.

The BAPI documentation must be written in the Function Builder for the functionmodule that the BAPI is based on.

Make sure that the documentation is translated into the required languages.

Using the program to map the internal data format onto the external data format, asdescribed in Conversion Between Internal and External Data Formats.

Writing the program for the function module. Refer to Example of a FunctionModule.

Also, see Programming BAPIsfor more information.

Defining the function module as a method of the corresponding SAP BusinessObject in the BOR, as described in Defining Methods in the BOR Using theBOR/BAPI Wizard.

You should then verify that the parameters and parameter types of the method in theBOR match the parameters of the underlying function module in the Function Builder.

Conversion Between Internal and ExternalData Formats

Use

According to the guidelines BAPI interfaces should only have English field names.However, in the internal working structures of a BAPI German field names are often

used.

Moreover in one of the previous steps you created your own structures for your BAPI

which are different from the structures used in R/3 applications. This is necessary to beable to freeze the BAPI structure and to maintain a stable BAPI interface, yet at thesame time, to enable further development in the R/3 application. For more informationrefer to Internal and External Data Formats.

As a result of these discrepancies the fields of the internal working structure of theBAPI must be mapped onto the fields of the BAPI interface before the BAPI is called.You can generate function moduleswhich help to automatically convert and map the

data.

You can use the generated function modules in the source code of your BAPI for:

Mapping the internal working structures of the BAPI onto the external BAPI

structures before the BAPI is called

Mapping the result onto the internal structures after the BAPI call

When implementing the BAPI, mapping the inbound parameters onto the internal

structure (structuring import parameters)

When implementing the BAPI, mapping the result from the internal structure ontothe BAPI (structuring export parameters)

Features

The function modules generated have the following functions:

They map between German and English field names


23/57

23

They convert ISO codes

They convert currency amounts into the required internal or external format

They convert internal and external keys such as those used by the PSP Element(Project structure plan)

Any problems that could arise during data conversions are reported back using theRETURN parameter.

Limitations

Occasionally you may have to manually edit the source code of a function module afterit has been automatically generated.

Existing function modules can not yet be regenerated with this transaction. Toregenerate an existing function module you have to manually delete the functionmodule and then generate it anew.

Activities

To generate the required function modules see Converting Between Internal andExternal Data Formats.

TheApplication Example illustrates the use of these function modules.

12 3 Converting Between Internal and External

Data Formats

Prerequisites

Before you can generate the function modules to map between the internal working

structures and the external BAPI structures, you must make sure that the internal andexternal structures exist.

Step by Step Procedure

To generate the function module follow the steps below:

1. Select Tools BusinessFrameworkBAPI Development Generate moduleto 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 bemapped 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 shorttext contain suggested values which you can accept or change.

In the field Function group enterthe name of the function group to which thegenerated function module is to be added.

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


24/57

24

parameters as the generated function module.

4. Select Continue.

A table is displayed containing suggestions for the conversion of each field of the

external BAPI structure. The table contains the following columns:

-Status

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

-Field in external structure

Contains the field names of the external BAPI structure.

-Conv. type

Displays the conversion type.

-Field in internal structure

Displays the fields of the internal structure to which/from which mapping is tobe carried out.

For further information select F1 help for columns Status and Conv. type.

5. To generate the function module, select Save.

ResultThe function module is stored in the Function Builder in the function group you

specified. You can incorporate it into the source code of your BAPI as required.

Application Example

The BAPI used in this fictitious example can read the standard price of a material:

bapi_material_get_price

importing

material like mara-matnr

exporting

material_price like bapi_material_price.

The external structure bapi_material_pricecontains the fields:

Fields in the external BAPI structure

Field Description Data element Domain

currency_iso

currency

amount

ISO currency code

Currency code

Amount

isocd

waers

bapimatprice

isocd

waers

bapicurr

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

following fields:


25/57

25

Fields in the internal working structure

Field Description Data element Domain

matnr

waers

stprs

Material number

Currency code

Unit price

matnr

waers

stprs

matnr

waers

strps

The BAPI structure bapi_material_price contains an ISO currency code and a currency

amount. After invoking the BAPI the application programmer must convert these fieldsinto the internal format used in R/3 in order to be able to process the fields.

Using the function Generate module to map fields, the application developer can

generate the function module, map2i_bapi_material_price_to_mat_preis,whichconverts the currency and amount fields. This function module has the followinginterface:

function map2i_bapi_material_price_to_mat_preis

importing

external structure bapi_material_price

changing

internal structure mat_preis

exceptions

error_during_iso_convertion

error_converting_currency_amount.

The application code could be as follows:

...

data: matnr like mara-matnr,

preis like mat_preis,

bapi_preis like bapi_material_preis.

...

* Call BAPI

Call function bapi_material_get_price

exporting

material = matnr

changing

material_price = bapi_preis.

* Map and convert the result to internal format

call function map2i_bapi_material_price_to_mat_preis

exporting

external = bapi_preis

changing

internal = preis.

* exceptions


26/57

26

* error_during_iso_convertion

* error_during_currency_amount_conversion

preis-matnr = matnr.

12 3 Defining Methods in the BOR Using theBOR/BAPI Wizard

Prerequisites

If the function module which your BAPI is based on has been fully implemented youcan define it as a method of an SAP Business Object in the Business Object Repository

(BOR).

You use the BOR/BAPI-Wizard to do this.

Step by Step ProcedureFirst find the relevant SAP Business Object in the BOR:

1. Select ToolsBusiness FrameworkBAPIDevelopment Business ObjectBuilder.

On the initial Business Object Builder screen you can directly access the SAPBusiness Object if you know the technical name of the object (object type). Youhave already identified the technical name in Defining a BAPI and Its Interface.

Otherwise select Business Object Repository. In the next dialog box indicatewhether you want to display all object types or only business objects. Then selectContinue.

The application hierarchy is displayed. Select the required SAP Business Object inthe application hierarchy and open it.

2. When the relevant SAP Business Object is displayed, select Change.

To define your BAPI as a method of the Business Object:

1. Select UtilitiesAPI Methods Add method.

2. In the next dialog box enter the name of the function module, for example,

BAPI_CREDITOR_GETDETAILand select Continue.

3. In the next dialog box specify the following information for the method to bedefined:

- MethodA 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 BAPIand the business object name, so that only the method name is left. Beginevery new word of the method name with a capital letter and do not use

underscores.

Example: If the name of the function module isBAPI_SALESORDER_GETSTATUS, the suggested method name might be

BapiSalesorderGetstatus. You should edit this so that the resulting name isGetStatus.

- Texts


27/57

27

Enter meaningful descriptions for your BAPI.

- Radio buttons Dialog, Synchronous, Instance-independent

Enter relevant details for your BAPI. Make sure that a BAPI is not dialog

orientated. BAPIs are usually implemented synchronously.

4. Select Next Step.

A list of parameters and default names is displayed which you need to edit as

required. Make sure that the parameter names of the method in the BOR are

identical to the parameter names in the function module. Each new word in theparameter name must start with a capital letter.

Also specify whether the individual table parameters are used for data import or

data export. Table parameters are marked with a tick in the column 'MLine'(multiple lines).

5. Select Next Step.

To create the method select Yes in the next dialog box.

Result

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

BOR.

Example of a Function Module

This example function module implements the BAPI CompanyCode.GetDetail of the

SAP Business Object CompanyCode (BUS0002).

The BAPI CompanyCode.GetDetailreads details of a company code.

Note the following in the source code:

The name of the function module is in the format: BAPI_< Business Object

name>_.

Specific BAPI data structures are used, identified by the prefix BAPI.

The key field parameter "COMPANYCODEID" is defined as the import parameter.

The function module performs authorization checks.

The function module covers all exceptions.

Source Code

function bapi_companycode_getdetail.

*"------------------------------------------------------

*"*"Local interface:*" IMPORTING

*" VALUE(COMPANYCODEID) LIKE BAPI0002_2-COMP_CODE

*" EXPORTING

*" VALUE(COMPANYCODE_DETAIL) LIKE BAPI0002_2

*" STRUCTURE BAPI0002_2

*" VALUE(COMPANYCODE_ADDRESS) LIKE BAPI0002_3

*" STRUCTURE BAPI0002_3

*" VALUE(RETURN) LIKE BAPIRETURN


28/57

28

*" STRUCTURE BAPIRETURN

*"------------------------------------------------------

...

* authority check: S_TABU_DIS V_T001

perform check_authority_t001 changing return.

check return is initial.

* company code

call function 'FI_COMPANY_CODE_DATA'

exporting

i_bukrs = companycodeid

importing

e_t001 = t001

exceptions

error_message = 1

others = 0.

if sy-subrc ne 0.

perform set_return using '10' changing return.

endif.

check return-code is initial.

...

endfunction.

Testing the BAPI

Purpose

After you have implemented the function module your BAPI is based on and you havedefined the BAPI as an SAP Business Object method in the Business ObjectRepository (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 beencompletely implemented and that the BAPI has been correctly defined in the BOR as a

Business Object method.

Process Flow

You can test the BAPI in the following ways:

By calling the underlying function module

You can individually test the function module in the Function Builder. You can enter


29/57

29

the appropriate test values in the parameters of your function module and by

running the test you can verify that the source code in the function module isprocessed without errors.

Testing the BAPI in the BOR

You can test the BAPI by testing the individual method of the Business Object inthe Business Object Builder. You need to know the technical name of the BusinessObject (object type) that you have already specified in Defining a BAPI and Its

Interface.

Call the Business Object Builder by selecting ToolsBusiness Framework

BAPI Development Business Object Builder. Specify the appropriate object type

and then start running the test by selecting Test. To test the BAPI implementation,you need to specify appropriate test values in the parameters of the BAPI.

Note that for an instance-dependent BAPI you have to first specify an instance

before you can run the BAPI test. Select Create instance and specify the requiredinstance.

By calling the BAPI in a Visual Basic program

If possible write a program in Visual Basic to call the BAPI.

- Check that the BAPI can be called by BAPI ActiveX Control.

- Check that the BAPI can be called by making RFC calls to the underlying

function module.

Check the availability of documentation in the different logon languages.

Result

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

implementation.

12

3 Releasing and Freezing the BAPI

After you have completed the function module and BAPI tests and you are satisfied that

they function properly, the implementation is complete.

You can now release the function module the BAPI is based on and the method in theBusiness Object Repository (BOR), and freeze the BAPI as a method in the BOR.

Once the BAPI has been released and frozen, it becomes available as a fullyimplemented Business Object method.

Releasing and freezing also prevents anyone making incompatible changes to the

BAPI, because all changes made to a released and frozen BAPI are automaticallychecked for compatibility in the BOR and the ABAP Dictionary, and incompatiblechanges are rejected. For more information about what to look out for when making

changes to existing BAPIs see Enhancements to Existing BAPIs.

Releasing and freezing the BAPI should be done in cooperation with the personsresponsible for the development objects involved and those responsible for quality

control.

To release and freeze a BAPI follow the steps below:

First release the function module in the Function Builder. Select

Function moduleReleaseRelease.


30/57

30

Set the status of the method to 'released' in the Business Object Builder. Select the

relevant SAP Business Object in the Business Object Builder and expand the node

Methods . Place the cursor on your BAPI and select EditChange status Released.

Freeze the method. Place the cursor again on your BAPI in the Business Object

Builder and select UtilitiesAPI methods Freeze method.

Check the new status of the function module in the Function Builder and the method in

the BOR.

Programming BAPIs

Use

This section describes how to program the BAPI you defined in the previous sections.

It is not easy to formalize the functional scope of a BAPI. Every BAPI has a different

functional content, even those that perform similar functions, such as the frequentlyused BAPIs. The differences are mainly due to the different characteristics andcontents of SAP Business Objects.

Prerequisites

To ensure that BAPIs, as interfaces of SAP Business Objects, provide access to R/3

data and processes in a consistent way, you must follow certain rules whenprogramming BAPIs. These are:

Mandatory Rules

A BAPI must not contain any dialogs; in other words, the BAPI must not return anyR/3 screen dialogs to the calling application. This is true for the BAPI itself and for

any function module that may be indirectly called by the BAPI.

BAPIs must not produce any screen output, for example, display a list on thescreen.

Database changes can only be made through updates.

Set and Get parameters and the global memory must not be used to transfervalues.

If required every BAPI must be able to carry out its own authorization checks.

Recommendations

Minimize interface complexity. Use the object/method model when choosingparameters and combining them in structures. In other words, select the most

important parameters and combine them in structures in a meaningful way.

Application servers might not support ASCII, but use a different character setinstead. 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 arange between A-Z, a-z and 0-9.

Other Features

Also pay attention to the following when you program BAPIs:

Programming Change BAPIs


31/57

31

Programming Replicate/Clone BAPIs

Programming Value Ranges

Internal and External Data Formats

Reporting Errors

Providing Input Help (F4 Help)

Improving the Performance of your BAPI

Programming Change BAPIs

Use

The BAPI Changemodifies an existing instance of a SAP Business Object, forexample, one specific purchase order.

As the Change BAPI can carry out changes to existing data, a Change BAPI must beable to identify fields that have been modified and fields that have stayed the same.

Using an initial value is no solution because an initial value could also represent a valid

new value. Moreover, in the ABAP programming language or on other developmentplatforms you cannot assign the value "null" to all data types in order to mark fields andthus indicate that the remaining fields contain update values.

Features

Two different approaches can be used to identify fields containing values that have

been modified in a Change BAPI:

Flagging fields to identify those fields containing modified values

Comparing fields to identify those fields containing modified values

1. Flagging Fields to Identify Those Fields Containing Modified Values

In this approach parameter fields containing modified values are identified by a suitableflag in an additional "change parameter".

An additional change parameter must be created with the same number of fieldsand the same field names for every parameter in the BAPI containing modified fieldvalues.

When the BAPI is called, the fields in the additional change parameter whosecounterparts in the corresponding parameter contain modifications, must bemarked with an update flag.

That way the BAPI can identify both modified and unmodified fields in the parameter.

Follow the conventions below when you create change parameters to identify modifiedfields:

The name of the additional change parameter consists of the parameter name withthe suffix "X". For instance, if the parameter is called EquiSales, the name of theadditional change parameter is EquiSalesX.

The additional change parameter must contain exactly the same number of fieldsand the same field names as the parameter. You must use the data elementBAPIUPDATE as the data element for the update fields. This can have the

following values:

- 'X'


32/57

32

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

If the parameter is a table, the additional change parameter must also be a table.

Example

A Change BAPI is used to change the value of the existing distribution channel(Distr_Chan) to Distr_Chan="US". The program objects in the R/3 Systemaffected by this change are:

Program Object Name

SAP Business Object

BAPI

Parameter

Fields in parameterEquiSales

Change parameter that identifies modified fields

Fields in EquiSalesX

PieceOfEquipment

Change

EquiSales

SalesOrg='abcd'

Distr_Chan='US'

Division='efgh'

...

EquiSalesX

SalesOrg=' '

Distr_Chan='X'

Division=' '

In the parameter EquiSalesXthe value in the field Distr_Chan is 'X'. Thisindicates that the field Distr_Chanof the parameter EquiSales contains amodified value.

The BAPI Changethen overwrites the existing value in the field Distr_Chan with

the current value in the field Distr_Chanin the parameter EquiSales .

2. Comparing Fields to Identify Those Fields Containing Modified Values

In this approach parameter fields containing modified values are identified bycomparing them with the fields in an additional "compare parameter":

An additional compare parameter must be created with the same structure for each

BAPI parameter containing update values.

When the Change BAPI is called all relevant fields in the compare parameter mustbe filled with the data at the time the database is read. This data could be, for

example, the result of a previous GetDetail BAPI call.

The fields of the corresponding parameter may contain modified values.

The data in the compare parameter can first be checked against the current

database contents to ascertain whether it has changed in the meantime. This wayany database changes made between the time the data was read and the time thedatabase is updated can be identified.

Then, the data in the compare parameter can be compared field by field with the


33/57

33

data in the corresponding parameter. If data in any field is different then the field

contains data that must be changed.

When you create compare parameters follow these conventions:

The name of the additional compare parameter consists of the parameter name

with the suffix "X". For instance, if the parameter is called EquiSales, the name ofthe additional compare parameter is EquiSalesX.

The additional compare parameter must contain exactly the same fields and the

same structure as the parameter.

Advantages of Both Approaches

The advantages of each approach are shown in the table below:

Area Advantage

Performance

Programming

Check facilities

Comprehension

Application

Approach 1: Flag table can be compressed. Compare data doesnot have to be read.

Approach 2: BAPI programming is simpler.

Approach 2: Can carry out check against current database to

identify and prevent inconsistencies.

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

Approach 1: Better for performance critical applications.

Approach 2: Better for dialog-orientated applications with criticaldata.

Programming Replicate/Clone BAPIs

Use

To replicate a business object you can implement Replicate/Clone BAPIs. The interfaceof these BAPIs depends on the characteristics and contents of the business object thatis to be cloned. For this reason these BAPIs must be implemented for each business

object.

The objective of replication is to make specific instances of a business object availableon one or more additional systems. The cloned business objects are created under the

same object key.

Business objects can be cloned in two ways:

By request ("Pull")

System "A" requests clones from system "B". Then system "B" replicates therequested business objects on system "A".

Using subscription lists ("Push")

System "B" maintains a list of systems requiring clones. At regular intervals system"B" replicates the business objects on all the systems in the list.

Features


34/57

34

Both of the above cloning methods can be implemented with the following BAPIs:

Replicate

A client system uses the Replicate BAPI to request clones of business objects froma server system. This method must be implemented for each business object to be

cloned.

The BAPI's import parameters have to identify the business objects to be cloned.You can do this by using a range table for the key fields of the business object. You

can also add other import parameters, for example, to request all the materialsbelonging to a material group or to delimit the amount of data in the business objectto be cloned (for example, material with or without plant data).

Each Replicate BAPI must contain the parameter CloneReceivers which specifiesthe systems on which the business objects are to be replicated.

Only create the Parameter RETURNas an export parameter.

The BAPI Replicaterequests the replication of a business object. The actualreplication is carried out when the server system invokes one of the Clone BAPIsdescribed below on the client system. You can specify whether the replication is

carried out immediately or at a later time and in a separate step, depending onwhat is most practical for the business object.

Moreover, at least one of the BAPIs below must be implemented for each businessobject to be cloned. You should decide to implement one of these BAPIs, depending onthe specific requirements of your BAPI:

Clone

The BAPI Clone is used by a system to replicate one business object on anothersystem or to modify one business object that has already been cloned.

All the data required for cloning an individual business object must be provided in

the import parameters. Each Clone BAPI must contain the import parameterSenderwhich identifies the system that sends or owns the business object. If onlyparts of an object are to be cloned rather than the whole object, you can use other

optional import parameters.

Only create the Parameter RETURNas an export parameter.This BAPI should be used for more complex objects that will not be cloned in large

numbers.

CloneMultiple

The BAPI CloneMultiple is used by a system to replicate several business objects

on another system or to modify several business objects that have already beencloned. Unlike the BAPI Clone, the BAPI CloneMultiplecan clone or modify severalinstances of an object at the same time.

All the relevant data for cloning several business objects must be provided in theimport parameters. Each CloneMultiple BAPI must contain the import parameterSenderwhich identifies the system that sends or owns the business objects. If only

parts of objects are to be cloned rather than whole objects, you can use otheroptional import parameters.

Only create the Parameter RETURNas an export parameter.

This BAPI should be used for objects with small amounts of data. Although theBAPI CloneMultipleis more efficient than the BAPI Clone, it does require a farmore complex interface and error handling process.


35/57

35

Programming Value Ranges

Use

The parameters in BAPIs that can be used to search for specific instances of a

business object, for example, BAPI CustomerCode.GetList,have to enable BAPI usersto specify appropriate selection criteria.

Prerequisites

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

Fields for Value Ranges

Field Name Description Data element

SIGN

OPTION

LOW

HIGH

Selection operator that determines whether

the range specified is to be included orexcluded.

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

Lower limit of value range

Upper limit of value range

BAPISIGN

BAPIOPTION

Application specific, e.g.MATNR

Application specific, e.g.MATNR

You can use the function module BALW_RANGES_CHECK to check the values

entered in SIGN and OPTION.

Internal and External Data Formats

Use

BAPIs are programming interfaces used in the most diverse application areas, for

instance, to connect non-SAP systems or PC products to the R/3 System.

To meet the requirements of this diverse range of applications, a shared strategy forrepresenting data in the BAPI interface must be used. In particular, the use of values

that affect Customizing or are language dependent must be avoided.

BAPIs are programming interfaces, not application interfaces. Fields such as a datefield, should not be used in the BAPI interface in any other format than the format used

in the database, i.e. YYYYMMDD, where YYYYis the year, MMthe month and DDtheday.

Exceptions

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


36/57

36

in exceptional circumstances.

These exceptions are listed below. To convert data formats in these exceptionalcircumstances, you can use the transaction described in Converting Between Internaland External Data Formats.

These exceptions are:

Currency amount fields

In an R/3 System a currency amount field is only useful when a currency code

accompanies it, so that the decimal point in the amounts can be set correctly.Accordingly, a field for the currency code must be assigned to each currencyamount field. For example, if two Yen are stored in the field of data type CURR as

0.02, a non-SAP system cannot reasonably be expected to understand thesesemantics.

All R/3 currency data types have two digits after the decimal point, even though

currencies do exist with three digits after the decimal point.

For these reasons, the data type CURR cannot be used in the BAPI interface.Adhere to the following guidelines when using currency amount fields in BAPIs:

- You must not use parameters and fields of data type CURR in the interface

- All parameters and fields for currency amounts must use the domain

BAPICURR

- The position of the decimal point in currency amount fields must be converted

correctly

You can use two function modules for this conversion. The function moduleBAPI_CURRENCY_CONV_TO_EXTERNAL converts currency amounts from

R/3 internal data formats into external data formats. The function moduleBAPI_CURRENCY_CONV_TO_INTERNAL converts currency amounts fromexternal data formats into internal data formats.

Quantity fields

Like currency amount fields, the decimal point in quantity fields must be convertedcorrectly. A unit of measure field must be assigned to every quantity field. Quantity

fields have no general domain that can be used for BAPI structures.

Internal keys

In some situations an internal technical key is maintained in the database alongside

the external key. Examples are work breakdown structure plans or networks inproject systems.

You must always use the external key in the BAPI interface.

ISO codes

In R/3 Systems ISO codes are currently supported for language, country, currency,and unit of measure fields.

If you use one or more of these fields in your BAPI you have to make two fields

available for each of these fields in the BAPI interface: one field containing the SAPcode and another containing its corresponding ISO code. Use the namingconvention, 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, forinstance E. The corresponding field for the ISO code would then be namedLANGU_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.


37/57

37

- 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

Unit of measure

Language key

Country key

isocd

isocd_unit

laiso

intca

waers

meins

spras

land1

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

BAPIs for Converting Between Internal and External Data Formats (ConvertingDomains)

BAPIs are programming interfaces in which, with a few exceptions, only the internaldata format should be used. However, application programmers calling a BAPI from

within their program may sometimes require the external format, for example, to displaydata on the screen. In such cases the calling program must be able to convert betweenthe internal and external data formats.

The following conversion BAPIs exist for this purpose. The calling program uses them

to obtain the required data formats:

BapiService.DataConversionInt2Ext

This BAPI converts the internal data format into the required external data format.

BapiService.DataConversionExt2Int

This BAPI converts the external data format into the required internal data format.

Conversion routines are maintained in the ABAP Dictionary for the domains on which

the data to be converted are based. If this is not the case, no conversion takes placeand the values are returned unconverted.

Reporting Errors

Use

A BAPI should be able to record and classify all possible errors that may occur. You

have to create a parameter named RETURN for every BAPI. This parameter returnsexception messages or success messages to the calling program.

All error messages or indeed any message that may be returned by the BAPI must be

defined in table T100. A general error message has to be sent for those error situationsthat cannot sufficiently be identified and distinguished. This message can then beprocessed by the calling program in a different program branch.

The parameter RETURN can either be implemented as an export parameter and thusas a structure, or as a table parameter. Before filling the RETURN parameter youshould either initialize the structure with CLEAR or the table with REFRESH and

CLEAR.

If the RETURN parameter is not set or is set to an initial value this means that an errorhas occurred.


38/57

38

Caution

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

Features

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

Return parameter in Release 3.1

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

Structure of BAPIRETURN

Field Type Description

TYPE

CODE

MESSAGE

LOG_NO

LOG_MSG_NO

CHAR 1

CHAR 5

CHAR 220

CHAR 20

NUMC 6

S = success message

E = error messageW = warning messageI = information message

A = termination message (Abort)The first two characters are used for the messageclass and the remaining ones for the message

number (key fields from table T100).

Full message text from table T100. All variables

have been replaced with text.

Number of application log. This is empty if no log

used.

Current number of message in application log.

Return Parameter from Release 4.0 onwards

From Release 4.0 the return parameter must be based on one of the two referencestructures described below.

Both structures take into account the name space extension of the message ID made inRelease 4.0. However, if you want messages to be compatible with earlier R/3Releases, use only the first two characters of the message ID.

Both structures must be filled in the logon language.

The two structures are:

BAPIRETURN1This structure is filled via the function module BALW_BAPIRETURN_GET1. Itcontains the following fields:


TYPE CHAR 1 S = success messageE = error messageW = warning message

I = information messageA = termination message (abort)


39/57

39

ID

NUMBER

MESSAGE

LOG_NO

LOG_MSG_NO

CHAR 20

NUMC 3

CHAR 220

CHAR 20

NUMC 6

Message ID

Message number

Full message text from table T100. Allvariables have been replaced with text

Number of application log. This is empty if

no log is used

Current number of message in applicationlog

BAPIRET2

This reference structure contains the additional fields PARAMETER, ROW andFIELD in which error messages can be assigned to a specific field.

If a BAPI ascertains that an invalid value has been entered in a field, it can identify

the field containing this value in the returned error message using the additionalfields in the structure BAPIRET2.

Only use this structure if you need the functionality of the additional fields to

minimize the complexity of the parameter.

The structure BAPIRET2is filled via the function moduleBALW_BAPIRETURN_GET2. It contains the following fields:


TYPE

ID

NUMBER

MESSAGE

LOG_NO

LOG_MSG_NO

CHAR 1

CHAR 20

NUMC 3

CHAR 220

CHAR 20

NUMC 6

S = success messageE = error message

W = warning messageI = information messageA = termination message (abort)

Message ID

Message number

Full message text from table T100. Allvariables have been replaced with text

Number of application log. This is empty ifno log is used

Current number of message in application

log


40/57

40

PARAMETER

ROW

FIELD

CHAR 32

INT 4

CHAR 30

Identifies the parameter containing theinvalid value

Identifies the line number of the data recordcontaining the invalid value

Identifies the field containing the invalid

value

Application Log and Application Error Tables

If the information provided in the Return parameter is not sufficient, you can log errorswith the application log. The logging should be done by the BAPI itself so that functionmodules called directly by this BAPI do not have to be modified.

If this still does not provide enough information, the calling application can define its

own additional error tables. There are no set guidelines for these additional tables. TheReturn 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 thenhas immediate control over the contents of the error table and does not have to firstsearch for error messages.

The use of the application log and/or error tables is optional.

Providing Input Help (F4 Help)

UseUsers of an R/3 System can use the F4 key to obtain information about the possibleinput values for a certain field on the screen.

Information about the possible input values for a field should also be available to those

users who are working with the data in the R/3 System from an external program, viaBAPI calls. For example, the user of a Visual Basic program which incorporates a BAPIto display or modify data in R/3 should have transparent access to the functionality of

the F4 input help.

In order to provide input help for a field, a calling program can use the methodHelpValues.GetList. This method is based on the RFC-capable function module

BAPI_HELPVALUES_GET, which obtains the possible input values for a field that ispassed in a BAPI call.

Detailed information about the structure and use of the HelpValues.GetListmethod is

available in the documentation for the function module BAPI_HELPVALUES_GET.

Features

In order to enable the HelpValues.GetListmethod to obtain the valid input values for a

field in your BAPI and return them to the calling program, you must create or specifythe appropriate check table, matchcodes or domain fixed values for that field in thefield's reference structure. For information about check tables, matchcodes and domain

fixed values see the ABAP Dictionary .

This is necessary because the HelpValues.GetListmethod refers to the help view for


41/57

41

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

Dictionary.

Note

Whenever possible, you should therefore specify the appropriate check table,matchcodes or domain fixed values in the reference structure of a field in order

to enable a calling program to access the valid input values for the field.

Authorization Check

In some situations it will be necessary to only allow those persons with a particular user

profile to access to information in F4 possible entries. To do this you can carry outauthorization checks within your BAPI:

Table BAPIF4T is provided for this purpose. This table comprises the following fields

which you have to fill with the corresponding entries of your BAPI.

OBJTYPE (object type)

The technical name of the SAP Business Object, for example, BUS1065.

METHOD (verb)

The name of a BAPI for the Business Object named above, for example, GetList.

DTEL (data element)

The name of a data element for which a possible entry is specified. For example,an elementary input help could be specified for the data element PERNR_D and beprotected from unauthorized access.

FNAM (name of function module)

The name of the function module you have to create and that carries out theauthorization 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 moduleBF_BAPI_F4_AUTHORITY which provides exactly this interface. Copy this function

module and follow the documentation provided with it.

Documents

Bapi Programing