Programming Change() BAPIs 
Use
The BAPI Change() changes an existing instance of an SAP business object type, for example, a sales order.
The BAPI Change() is an instance method, whereas the BAPI ChangeMultiple() is a class method (instance-independent).
Features
BAPI interface
Import Parameters
You should keep the following points in mind when defining the import parameters:
- Since the Change() BAPI is an instance method, the key fields of the corresponding business object type must be created as import parameters in the function module. The names of these parameters must be identical to the names of the object keys in the BOR and must have the same data elements.
For the associated method definition in the BOR, the key fields must not also be specified as parameters. For this reason, the BOR/BAPI Wizard does not include the function module parameters for the key fields in the method definition, when it creates a BAPI.
- The BAPI must also have a TestRun parameter that enables it to execute test runs. If this parameter is filled with the value "X", the BAPI executes normally, but does not write the results to the update task. In this way, after the BAPI BapiService.TransactionCommit executes, all results, such as the application log, for example, can be evaluated, but the BAPI has not modified the database. For further information see,
Test Run Parameters.
- If customers are to be enabled to enhance the import parameters of the BAPI without modifications being necessary, you must create the parameter ExtensionIn. For information about extension parameters and recommendations on how the customer enhancement concept should be implemented in a Change() BAPI, see
Customer Enhancements to BAPIs.
- Implement the Change() method according to the "Change by flagging" concept. Here you must create a change parameter for every parameter that has fields containing modified values. These change parameters serve to distinguish parameter fields containing modified values from parameter fields that have not been modified.
By contrast, if the Change by comparison concept is implemented, you must create an additional equivalent parameter for every parameter with fields containing modified values. For more information, see
Change Parameters.
Export Parameters
You should keep the following points in mind when defining the export parameters:
- If customers are to be allowed to extend the export parameters of the BAPI without modifications being necessary, you must create the parameter ExtensionOut. For information about extension parameters and recommendations on how the customer enhancement concept should be implemented in a Change() BAPI, see
Customer Enhancements to BAPIs.
- To report messages from the method call back to the calling program, you should create the export parameter Return . To ensure the results of a Change() BAPI, called either synchronously or asynchronously, are monitored extensively, the following conventions for filling the Return parameter must be observed:
- If the Change() BAPI executes successfully, the following standardized T100 message must be passed in the Return parameter:
You should keep the following points in mind:
- The field MESSAGE_V1 contains the external name of the business object type, such as SalesOrder.
- The key under which the object to be changed can be accessed at subsequent calls is returned in the field MESSAGE_V2. This is the external key when external number assignment is used, or the internal key when internal number assignment is used. If the object has several key fields, the values of these key fields must be concatenated in MESSAGE_V2. The sequence in which the key fields are defined in the BOR must be adhered to for the concatenation. Moreover, the maximum length must be used for each key field. This may require the use of padding.
If the complete key exceeds the maximum capacity of MESSAGE_V2 (that is, 50 characters), it is divided up between the fields MESSAGE_V2 and MESSAGE_V3. The first 50 characters are stored in MESSAGE_V2 and the remaining characters in MESSAGE_V3.
- If an error occurs during the execution of the Change() BAPI, in addition to the application-specific error messages the following standardized T100 message must be passed in the Return parameter:
The meaning of the various fields is the same as for successful execution.
- In addition to the standardized message, further messages can be written in the Return parameter.
It is of particular importance when errors occur that messages describing the errors in detail are returned. You should, therefore, use all of the fields of the structure BAPIRET2. You should, in particular, fill the fields
Parameter, Row and Field. For more information about this parameter, see
Return Parameters (Error Handling).
BAPI Coding
Possible Strategies for Implementing a Change() BAPI
In BAPIs that cause database changes (for example, Change() and Create() BAPIs), you must be able to distinguish between parameter fields that are to be modified (change-relevant fields) and parameter fields that are to remain unmodified.
Using an initial value is no solution because an initial value could also represent a valid new value. Also, in the ABAP programming language as well as on other development platforms, the value "NULL" should not be assigned to a data type to indicate an empty field.
For this reason, the change-relevant fields must be identified using a "workaround". This can take two forms:
- Flagging Fields to Identify Fields Containing Modified Values
In this approach, parameter fields containing modified values are identified by including a flag in an additional "change parameter".
- An additional change parameter must be created with the same number of fields and the same field names for every parameter in the BAPI containing modified field values.
- When the BAPI is called, the fields in the additional change parameter whose counterparts in the corresponding parameter contain modifications, must be marked with an update flag.
This way the BAPI can identify both modified and unmodified fields in the parameter.
Follow the conventions below when you create change parameters to identify modified fields:
- The name of the additional change parameter consists of the parameter name with the suffix "X". For instance, if the parameter is called EquiSales, the name of the additional change parameter is EquiSalesX.
- The additional change parameter must contain exactly the same number of fields and the same field names as the parameter. You must use the data element BAPIUPDATE (CHAR 1) as the data element for the update fields. This can have the following values:
| |
|
‘X’:
This value means that the corresponding parameter field contains a modified value. |
| |
|
‘ ‘ (no value):
This means that the corresponding parameter field does not have to be updated. |
- If the parameter is a table, the additional change parameter must also be a table.
For more information about this concept, see
Change Parameters.
- Comparing Fields to Identify Fields Containing Modified Values
In this approach, fields containing modified values are identified by comparing two parameters, one containing the current valid data and the other the new, modified data.
When the Change() BAPI is called, the current data in the database and the new, modified data must be entered in the corresponding parameters. The current data set can be transferred, for instance, from a GetDetail() BAPI that has been called.
The following comparisons can be made:
- The current data can first be checked against the database contents to ascertain whether it has changed in the meantime. This way any database changes made between the time the data was read by the GetDetail() BAPI and the time the database is updated can be identified.
- The data in both the parameters can be compared field by field. If the data in two corresponding fields is different, the relevant values must be transferred from the parameter with the new data.
Note the following when you are comparing fields containing modified data.
- A calling program must be able to provide data in all the parameter fields of the Change() BAPI. For this reason, the parameter fields of the Change() BAPI must be exactly the same as the fields in the GetDetail() BAPI of the same business object type.
- The names of the parameters to be compared must be the same, but the parameter containing the modified data must also have the suffix ‘New’.
For example, if the parameter with the current valid data is called EquiSales, the parameter with the modified data is called EquiSalesNew.
- Both parameters must have exactly the same fields and the same structure.
Avoiding Incompatibilities with Customizing Settings
It could be possible that certain values set by Customizing appear differently in the BAPI interface. These values cannot be overwritten by a Change() BAPI.
To avoid incompatibility with Customizing settings, you should implement a Change() BAPI in the following way:
- The BAPI should transfer all the fields and check them against the Customizing settings. If the Customizing settings write-protect a field, the data in this field cannot be overwritten by data in the BAPI interface.
- For every incidence of incompatibility an error message must be returned in the Return parameter to the calling program. For example, "Customizing settings do not allow the field 'MyAsset-AssetName' to be modified ".
- All the fields that are assigned default values by Customizing and are therefore write-protected, must be documented.
See also:
Example of a Change () BAPI