Background information

Business object development for the ABAP Extension Module consists of creating an application-specific business object definition and an associated ABAP handler for each verb that you want to support.

To develop an application-specific business object, you must create a business object definition that supports your business needs. The IBM WebSphere Business Integration Adapter for mySAP.com (SAP R/3 Version 3.x) includes tools that facilitate the process of developing business object definitions in the SAP application. Although you can use Business Object Designer or a text editor to create business object definitions for the ABAP Extension Module, we recommend that you initially use the adapter's business object development tools. These tools use the SAP application's native definitions as a template.

For each application-specific business object definition that you develop, you must support it by using an adapter-provided ABAP handler or by developing a custom ABAP handler. The ABAP handler is the mechanism that gets data into and out of the SAP application database.

Note:
The application-specific business object and the ABAP handler rely on each other's consistency to pass data into and out of the SAP application; therefore, if you change the business object definition, then you must change the ABAP handler to support it.

The adapter's ABAP handler is implemented as an ABAP function module. ABAP handlers are one or more function modules that work together to fulfill a business object retrieve or request from the business object router Y_XR_RFC_DO_VERB_NEXTGEN. ABAP handlers are responsible for passing business object data into and out of the SAP application.

Note:
SAP supports many verbs other than those (Create, Retrieve, Update, and Delete) supported by the WebSphere business integration system. You can develop an ABAP handler to support any verb.

To develop an ABAP handler, you must understand how the connector gets data into and out of the SAP application and what form that data takes during this process. For a high level description of business object processing, see Overview of the ABAP Extension Module. For a detailed description of business object processing, see Business object processing in the ABAP Extension Module.

Note:
When you develop business objects, you must make sure that the objects are added to the connector's YXROBJ table in the SAP R/3 application. If they are not, you will not be able to access the business objects for customization (for example, setting up the object for event distribution).

SAP native APIs

Adapter-provided ABAP handlers use SAP native APIs, which enable ABAP handlers to pass data into and out of the SAP application. The WebSphere business integration system has implemented the following native APIs:

ABAP SQL

ABAP SQL is SAP's proprietary version of SQL. It is database and platform independent, so that whatever SQL code you write, you can run it on any database and platform combination that SAP supports. ABAP SQL is similar in syntax to other versions of SQL and supports all of the basic database table commands such as update, insert, modify, select and delete. For a complete description of ABAP SQL, its use, syntax and functionality, see your SAP documentation.

Using ABAP SQL, an ABAP handler can modify SAP database tables with business object data for create, update and delete operations and similarly can use the business object data in the "where" clause of an ABAP select statement as the keys.

Note:
The WebSphere business integration system never uses ABAP SQL to modify SAP tables, because this may corrupt the integrity of the database. The connector uses ABAP SQL only to retrieve data and to modify adapter-delivered database tables.

Call transaction

Call transaction is SAP-provided functionality for entering data into an SAP system. Call Transaction guarantees that the data adheres to SAP's data model by using the same screens an online user sees in a transaction. This process is commonly referred to as screen scraping. To use Call Transaction, specify the following types of instructions:

Initiation is passed as a single value parameter in the Call Transaction call. Navigation and Mapping instructions are passed in together in a table with a specific format; this format is usable for invoking Call Transaction for any SAP transaction. In this format, these instructions are referred to as the BDC data, BDC table, or BDC session.

Batch data communication (BDC)

Batch data communication (BDC) is an instruction set that SAP can follow to execute a transaction without user intervention. The instructions dictate the sequence in which a transaction's screens are processed and which fields should be populated with data on which screens. All of the elements of an SAP transaction that are exposed to an online user have identifications that can be used in a BDC. The elements are as follows:

To get a screen's BDC identity, place the cursor in any field on the screen. Press F1 for help and then F9 for technical information. The program name and screen number are listed under Screen Data.

To get an input field's BDC identity, place the cursor in each field on the screen in which you want to input data. Press F1 for help and then F9 for technical information. If there is a box named Field Description for Batch Input, then use the information in the Screen Field field. If this box does not exist, from the Field Data box, concatenate the Table Name and Field Name together with a hyphen.

To get a command's BDC identity, highlight the command in the menu and press F1 for help. Use the value in the Function field.

IBM WebSphere function module interface

Every ABAP handler must implement the same function module interface. The function module interface guarantees that the business object router Y_XR_RFC_DO_VERB_NEXTGEN can pass business object data to and from ABAP handlers. The interface is:

*"*"Local interface: 
*"  IMPORTING 
*"      VALUE(PROC_FUNC_1) LIKE  RS38L-NAME OPTIONAL 
*"      VALUE(PROC_FUNC_2) LIKE  RS38L-NAME OPTIONAL 
*"      VALUE(OBJECT_NAME) LIKE  YXR_LOG_H-OBJ_NAME OPTIONAL 
*"      VALUE(OBJECT_VERB) LIKE  YXR_CHANGE-OBJ_VERB OPTIONAL 
*"      VALUE(ARCHIVE) OPTIONAL 
*"      VALUE(TEXT) LIKE  T100-TEXT OPTIONAL 
*"  EXPORTING 
*"      VALUE(RETURN_TEXT) LIKE  YXR_EVENT-OBJ_KEY 
*"      VALUE(RFCRC) LIKE  YXR_RFCRC-YXR_RFCRC 
*"  TABLES 
*"      RFC_STRUCTURE STRUCTURE  YXR_RFC_S 
*"  EXCEPTIONS 
*"      NOT_FOUND 
*"      ERROR_PROCESSING 

In the importing section of the interface, you can communicate values such as the ABAP handler name, business object name, and business object.

The exporting section of the interface is used to communicate the results of the ABAP handler processing. The return code RFCRC parameter is a single field used to determine the code a connector returns. The possible values are:

RC = 0 (success, VALCHANGE)

RC = 1 (failure, FAIL)

The RETURN_TEXT parameter is a 120-character free text field that is written to by the connector or logged as an error message in the return status descriptor. If the ABAP handler does not provide a value for this parameter, then Y_XR_RFC_DO_VERB_NEXTGEN supplies default text depending on the return code.

Note:
The exceptions section of the interface defines two exceptions. It is recommended that you use the exporting parameters instead.

IBM WebSphere ABAP handler APIs

The adapter includes several APIs that facilitate the development of ABAP handlers that support WebSphere business objects for SAP. These APIs were developed as "generic" ABAP handlers, because they only require metadata to support additional business objects of any type. The adapter includes the following ABAP handler APIs:

The adapter includes a set of tools that support these APIs. The tools can be found in IBM WebSphere InterChange Server Connector Tool (transaction YXR1). The following sections discuss the adapter-provided APIs and gives you steps on how to use the IBM WebSphere InterChange Server Connector Tool (transaction YXR1) to develop business objects for them.

Copyright IBM Corp. 1997, 2004