Programming Methods for Sub-Objects

Use

If a business object type consists of sub-objects, you can implement the following standardized BAPIs to add or remove sub-objects:

Add <name of sub-object>()

This method adds a sub-object to an object type.
Remove <name of sub-object>()

This method removes a sub-object from an object.

For example, to add or remove the sub-object purchase order item to the business object type purchase order , the BAPIs AddItem() and RemoveItem() could be implemented for the object type, purchase order .

The BAPIs Add<Name of sub-object>() and Remove < Name of sub-object>() are instance methods.

Features

BAPI Interface

Import Parameter

You should keep the following points in mind when defining the import parameters:

You should keep the following points in mind when defining the import parameters: The names of the parameters must be identical to the names of the object keys in the BOR and must have the same data elements.
The import parameters in the function module of both BAPIs must contain the key fields of the corresponding business object type.
The BAPI must also have a TestRun parameter that enables it to execute test runs. If this parameter contains 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 can be evaluated, (such as the application log, for example), but the BAPI has not modified the database.

Note
For more 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 Add < name of sub-object >() or Remove < name of sub-object >() BAPI, see Customer Enhancements to BAPIs .
You can create a change parameter to identify the values to create the instance with and to differentiate these values from the initial values when the BAPI is called. We recommend that you identify the change-relevant fields by flagging them. For more information see Change Parameters .

Export Parameter

You should keep the following points in mind when defining the export parameters of a Remove < name of sub-object >() BAPI:

To report messages from the method call back to the calling program, you should create only the export parameter Return . To ensure the results of a Remove < name of sub-object >() BAPI, called either synchronously or asynchronously, are monitored extensively, the following conventions for filling the Return parameter must be observed:

If the BAPI executes successfully, in other words, the desired sub-object is deleted, the following standardized T100 message must be passed in the Return parameter:

RETURN	MESSAGE
TYPE	S
ID	BAPI
NUMBER	014
MESSAGE_V1	< objectname >
MESSAGE_V2	< reference_id >
MESSAGE_V3	< reference_id >
SYSTEM	< system >

You should keep the following points in mind:

The field MESSAGE_V1 contains the external name of the business object, such as SalesOrder .
he key under which the object, whose sub-object has been deleted, is accessed, is returned in 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.

Note
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 Remove < name of sub-object >() BAPI, in addition to the application-specific error messages the following standardized message must be transferred in the Return parameter:

RETURN	MESSAGE
TYPE	E
ID	BAPI
NUMBER	015
MESSAGE_V1	< objectname >
MESSAGE_V2	< reference_id >
MESSAGE_V3	< reference_id >
SYSTEM	< system >

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 .

Note
For more information about this parameter, see Return Parameters (Error Handling) .

You should keep the following points in mind when defining the export parameters of a Add < name of sub-object >() BAPI:

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 an Add < name of sub-object() BAPI, see Customer Enhancements to BAPIs .

To report messages from the method call back to the calling program, you should create the parameter Return . To ensure the results of a Add < name of sub-object >() BAPI, called either synchronously or asynchronously, are monitored extensively, the following conventions for filling the Return parameter must be observed:

If the BAPI executes successfully, in other words, the desired sub-object is created, the following standardized T100 message must be passed in the Return parameter:

RETURN	MESSAGE
TYPE	S
ID	BAPI
NUMBER	012
MESSAGE_V1	< objectname >
MESSAGE_V2	< reference_id >
MESSAGE_V3	< reference_id >
SYSTEM	< system >

The meaning of the various fields is the same as described in the programming model for the Remove< name of sub-object>() BAPI.

If an error occurs during the execution of the Add < name of sub-object >() BAPI, in addition to the application-specific error messages the following standardized message must be transferred in the Return parameter:

RETURN	MESSAGE
TYPE	E
ID	BAPI
NUMBER	013
MESSAGE_V1	< objectname >
MESSAGE_V2	< reference_id >
MESSAGE_V3	< reference_id >
SYSTEM	< system >

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 .

Note
For more information about this parameter, see Return Parameters (Error Handling) .