ABAP BAPI IV

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

This method adds a sub-object to an object type.

Remove

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 and Remove 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.
Export Parameters

You should only create the export parameter RETURN in the BAPI Remove to return messages from the method call to the calling program. For more information about this parameter see Return Parameters (Error Handling).
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 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.

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.

If you are implementing BAPIs that create or change data you should consider using buffering. For further information see Buffering for Write BAPIs.
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.

We strongly recommend that you create instance-dependent BAPIs with buffering instead of Multiple() BAPIs. For further information see Buffering with Write BAPIs.
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.


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 were 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 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().


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.
The naming convention for these function modules is:
_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.

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:

_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 ON COMMIT
call a form routine which then calls the update module(s).
The update modules must be called using the command
CALL _SAVEBUFFER IN UPDATE TASK
to flag the execution in the update program.

By adding 'ON COMMIT' to the command PERFORM 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 module once only. For this reason error handling cannot be performed in this form routine or 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 necessary information, BAPIs with buffering must subscribe their delete module for the BAPI BapiService.TransactionCommit() bow. 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 out-of-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 existence of an instance in the buffer also.
Documenting Read BAPIs
Each read BAPI that handles the buffering of corresponding write methods must be documented.

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.
The naming convention for these function modules is:
_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:

_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 ON COMMIT
call a form routine which then calls the update module(s).
The update modules must be called using the command
CALL _SAVEBUFFER IN UPDATE TASK
to flag the execution in the update program.

By adding 'ON COMMIT' to the command PERFORM 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 module once only. For this reason error handling cannot be performed in this form routine or 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 necessary information, BAPIs with buffering must subscribe their 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 out-of-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 existence of an instance in the buffer also.
Documenting Read BAPIs

Each read BAPI that handles the buffering of corresponding write methods must be documented.