The function of an ABAP handler is to get business object data into or out of the SAP application database. When processing business object data, ABAP handlers:
Every ABAP handler receives business object data in the same format (flat structure). However, each ABAP handler has specific requirements for business objects that are determined by the complexity of the WebSphere business object definition, the native API that SAP provides, and the level of functionality that the ABAP handler provides. For these reasons, ABAP handlers may interpret business object data by parsing it into a structure specific to the business object. This enables the ABAP handler to more easily manipulate the data.
The adapter provides several ABAP handlers, such as an IDoc handler. The IDoc handler leverages SAP's IDoc technology by providing an ABAP handler to interpret business object data by reformatting it into an IDoc-based structure for the ABAP handler to use.
Once the ABAP handler interprets the business object data, the ABAP handler must integrate it with the SAP application database. It must manipulate the business object data to use SAP native APIs such as Call Transaction or ABAP SQL to get data into or out of the application database.
The intent of a Create, Update, or Delete operation is to modify the SAP application database. While the SAP application database schema for a given business object defines the structure of the data, the transactions provided by SAP that modify that data have a much broader scope of influence. As a result, directly modifying the application database tables of an SAP application can have disastrous results to the application's data integrity.
Instead of directly modifying the database tables, SAP provides a flexible ABAP API (Call Transaction) for Create, Update, and Delete operations. Call Transaction is SAP-provided functionality for entering data into an SAP application. It guarantees that the data adheres to SAP's data model by using the same screens an online user would use in a transaction. This process is commonly referred to as screen scraping.
If the verb is Retrieve, then the connector uses ABAP SQL statements to retrieve data from the SAP application database. The business object data provides the keys for the where clause when pulling data. The difficulty in this methodology of retrieving data is that the retrieved data must be represented in a format that represents the business object structure. This is done in the ABAP Handler ABAP code.
The connector supports the Retrieve processing only with a primary key specified.
Regardless of the verb of the business object, the connector waits for two types of confirmations:
The ABAP Extension Module uses three different return codes to process business object data; return code 0, 21, and any non-zero code (other than 21). Set the return code in the function module interface. For more information on the function module interface, see IBM WebSphere function module interface.
Return code 0 indicates that the business object was successfully processed and returns VALCHANGE to the connector infrastructure. If ABAP handler processing is successful, then the connector expects new business object data that reflects the operation performed. For example, after a successful Create, the returned business object is an exact copy of the business object initially sent in, except that the keys are updated. Similarly, a successful Retrieve results in a fully formed instance of the business object. However, Create, Update, and Delete operations have different requirements for returned business objects than do Retrieve operations.
When the IBM WebSphere InterChange Server is the integration broker, the difference in requirements comes from how the WebSphere business integration system handles business objects, specifically dynamic cross-referencing of object IDs during mapping. When the connector returns a business object to IBM WebSphere InterChange Server after a Create or Update operation, the mapping infrastructure attempts to update the cross-reference tables with the newly acquired object ID. This is accomplished by looking up the value of the business object's ObjectEventId attribute that was set when the business object was originally sent to the connector.
To the ABAP handlers, this is significant because the ABAP handlers are responsible for "stitching" the object IDs into the business object that is returned to the connector. Typically, this is not an issue for Retrieve operations because there is no corresponding dynamic cross-referencing. Retrieve operations generate an entirely new business object that is returned to the connector. This business object does not have any direct relationship to the structure of the business object originally sent in.
The business object data returned by the ABAP handler must be in the same flat structure format as when it was initially passed in to function module /CWLD/RFC_DO_VERB_NEXTGEN. The ABAP handler needs to send out only simple type attributes with the following information for each:
The attribute name is not required at this point, because the connector uses only the application-specific information to create a business object from this data. Identifiers for the beginning and ending of business objects or object type attributes are not used and should not be added. For example, the BoName and BoVerb rows are not used in the business object returned from the ABAP handler. They are initially passed into the ABAP handler only to facilitate processing.
The ABAP handler must adhere to the following set of rules when populating a flat structure with business object response data representing an WebSphere business object:
Figure 14 illustrates a flat business object (no object type attributes).
Figure 14. Flat business object
SAP_Material
Table 11 represents the structure of a flat business object, SAP_Material, whose key value is ItemID. Notice that field ATTR_NAME is not required, APPTEXT is unique for each attribute, and because this business object is flat, the PEERS field can be left blank.
Table 11. Flat business object SAP_Material
ATTR_NAME | ATTR_VALUE | ISKEY | ISNEW | PEERS | OBJ_ NUMBER | APPTEXT |
---|---|---|---|---|---|---|
(blank) | 000000000000001179 | (blank) | (blank) | (blank) | (blank) | ItemId |
(blank) | Toaster 6000 | (blank) | (blank) | (blank) | (blank) | ShortDesc |
(blank) | SAP_124 | (blank) | (blank) | (blank) | (blank) | ObjectEventId |
Figure 15 illustrates a hierarchical business object (containing object types).
Figure 15. Hierarchical business object SAP sales
order (IDoc)
Table 12 shows a representation of a flat structure of a hierarchical business object based on an IDoc Sales Order. Notice that field ATTR_NAME is not required, APPTEXT is unique for each attribute, and because this business object is hierarchical, the PEERS field lists the appropriate relationship.
Table 12. Hierarchical business object based on an IDoc sales order
ATTR_NAME | ATTR_VALUE | ISKEY | ISNEW | PEERS | OBJ_ NUMBER | APPTEXT |
---|---|---|---|---|---|---|
(blank) | USD | 0 | 0 | 1 | (blank) | E1EDK01:CURCY |
(blank) | 0000000101 | 0 | 0 | 1 | (blank) | E1EDK01:BELNR |
(blank) | SAP_124 | 0 | 0 | 1 | (blank) | E1EDK01: ObjectEventId |
(blank) | User1 | 0 | 0 | 2 | (blank) | Z1XRV40:ERNAM |
(blank) | SAP_125 | 0 | 0 | 2 | (blank) | Z1XRV40: ObjectEventId |
(blank) | 001 | 0 | 0 | 1 | (blank) | Z1XRV40:QUALF |
(blank) | 1000 | 0 | 0 | 1 | (blank) | E1EDK14:ORGID |
(blank) | SAP_126 | 0 | 0 | 1 | (blank) | E1EDK14: ObjectEventId |
(blank) | User1 | 0 | 0 | 2 | (blank) | Z1XRV40:ERNAM |
(blank) | SAP_127 | 0 | 0 | 2 | (blank) | Z1XRV40: ObjectEventId |
Return code 21 indicates that the business object was successfully processed and returns SUCCESS to the connector infrastructure. This code returns only success and does not return any business object data back to the connector. The Object-specific IDoc handler that process the business object data returns a return code of 21 when the business object data is successfully entered into the SAP application. The return code is passed back to the /CWLD/RFC_DO_VERB_NEXTGEN function module, which returns success back to the connector. The connector never receives business object data.
This is useful when passing large objects (such as an IDoc with multiple line items) and all you want is to know that your business object data was passed to the SAP application successfully. Performance is greatly improved because you return only the code and not the business object.
When WebSphere InterChange Server is the integration broker, you should use return code 21 only when the business object does not require cross-referencing and when you are simply passing data into the SAP application. Do not use return code 21 for retrieve operations. Behavior of the SUCCESS return code means that no business object is returned to the WebSphere InterChange Server for cross-referencing or further processing.
A non-zero return code (other than 21) indicates that the object was not processed successfully and returns FAIL to the connector. If the ABAP handler returns a non-zero code (other than 21), then no business object is returned to the connector.