Integrating with BAPI/RFC

 

This topic describes how to integrate SAP R/3 SAP remote function calls (RFCs) and business application programming interfaces (BAPIs) in the BEA eLink Adapter for R/3 BAPI/RFC environment. It includes the following main sections:

• BAPI/RFC Integration

• BAPI/RFC eLink to R/3 Server

• RFC R/3 to eLink Server

For information about setting up RFC processing, see Configuring BAPI/RFC Integration in this guide.

BAPI/RFC Integration

BAPI/RFC eLink to R/3 is a component of the BEA eLink Adapter for R/3 BAPI/RFC product that allows TUXEDO applications to invoke any ABAP/4 functions that have been RFC-enabled. The RFC function may be the underlying RFC for any BAPI. The adapter will return the response from R/3 back to the TUXEDO application.

RFC R/3 to eLink is a TUXEDO server that allows R/3 to send request messages to TUXEDO applications and receive the response message. The request message specifies the data and functionality of the TUXEDO application to which R/3 requires access. The TUXEDO application returns the result of the access in the response message.

BAPI/RFC eLink to R/3 Server

BAPI/RFC eLink to R/3 is a component of the BEA eLink Adapter for R/3 BAPI/RFC product that allows TUXEDO applications and other non-R/3 applications to invoke any ABAP/4 functions that have been BAPI/RFC-enabled. BAPI/RFC eLink to R/3 is a TUXEDO server that has a generic service, CR3_RFC_IN, which invokes any ABAP/4 function. The CR3_RFC_IN service is aliased to unique services corresponding to ABAP/4 functions.

Developers configure the ABAP/4 functions they want to invoke and the service names that are advertised. The RFC R/3 to eLink server then advertises these service names. The RFC can then be invoked by the service name just as any other TUXEDO service.

This section describes how to invoke BAPI/RFC-enabled ABAP/4 functions in the TUXEDO environment using RFC eLink to R/3, a TUXEDO server, via synchronous BAPI/RFC. The following topics are covered:

• BAPI/RFC eLink to R/3 Information Flow

• ABAP/4 Parameters

• FML32 Field Definitions for BAPI/RFC eLink to R/3

• Configuring Export Parameters and Export Tables

• Handling Problems with BAPIs/RFCs

For information about setting up BAPI/RFC processing, see Configuring BAPI/RFC Integration, and Configuring R/3 Connections.

BAPI/RFC eLink to R/3 Information Flow

BAPI/RFC eLink to R/3 allows a TUXEDO application to act as a client to R/3. Figure 2-1 shows the information flow for invoking BAPI/RFC-enabled ABAP/4 functions:

Figure 2-1 Information Flow for Invoking ABAP/4 Functions

The information flow for invoking ABAP/4 functions is as follows:

1. One or more instances of BAPI/RFC eLink to R/3 (a TUXEDO server) start up and advertise each ABAP/4 function that can be invoked as a TUXEDO service.

2. The calling application prepares an FML32 request buffer that contains the applicable import parameters and import tables for the BAPI/RFC.

   It is the developer's responsibility to ensure that the names of import parameters and import tables are spelled exactly as they appear in the ABAP/4 function signature.

3. The calling application makes a service call to the TUXEDO service associated with the BAPI/RFC, passing in the FML32 request buffer parameter to TUXEDO.

4. The BAPI/RFC eLink to R/3 service (CR3_RFC_IN) determines the service name used to invoke it and therefore knows the associated ABAP/4 function.

5. BAPI/RFC eLink to R/3 processes the FML32 request buffer and then makes the remote function call on R/3 using the synchronous RFC API, passing the import parameters to R/3.

6. The executed ABAP/4 function processes the input parameters and returns the results to BAPI/RFC eLink to R/3.

7. BAPI/RFC eLink to R/3 receives the results, and, depending on the success of the RFC call, does one of the following:

   • If the RFC call succeeded, BAPI/RFC eLink to R/3 populates the FML32 response buffer with the returned data. BAPI/RFC eLink to R/3 includes only data for the export parameters and export tables that are listed in the CR3_EXPORT_PARAMS and CR3_EXPORT_TABLES environment variables. BAPI/RFC eLink to R/3 returns the FML32 response buffer to the calling application, as well as TPSUCCESS with the tpurcode error code set to zero (0).

   • If the RFC call failed, BAPI/RFC eLink to R/3 populates the FML32 response buffer with information about the error:

     R/3-level errors. BAPI/RFC eLink to R/3 populates the ELINK_APP_ERR field with the message text returned from R/3. BAPI/RFC eLink to R/3 returns the FML32 response buffer to the calling application, as well as TPFAIL with the tpurcode set to 0.

     Adapter-level errors. BAPI/RFC eLink to R/3 populates the ELINK_ADAPTER_ERR_CODE and ELINK_ADAPTER_ERR fields with the appropriate adapter-level error code and BEA eLink Adapter for R/3 RFC-specific error code and message. BAPI/RFC eLink to R/3 returns the FML32 response buffer to the calling application, as well as TPFAIL with the tpurcode set to -1. Alternatively, for uncorrectable errors such as a memory corruption problem, BAPI/RFC eLink to R/3 returns TPEXIT (which causes the service to shut down) with the tpurcode set to -1.

8. The calling application processes the response buffer as appropriate.

ABAP/4 Parameters

ABAP/4 functions use the following types of parameters:

• Import parameters are passed into an ABAP/4 function.

• Export parameters are passed out of an ABAP/4 function.

• Tables are passed into, out of, or both into and out of an ABAP/4 function. Tables are similar to arrays, consisting of 1+ rows, where each row is a specific type (such as a string) or a structure. Tables are passed by reference.

• Exceptions are defined error messages that are passed out of an ABAP/4 function if R/3 raises an exception (a business-level error).

The exact parameters vary with each ABAP/4 function and are defined in the function's ABAP/4 function signature. The following defines a generic ABAP/4 function:

FUNCTION FUNCTION_NAME
IMPORT
          IMPORT_PARAM_1
          IMPORT_PARAM_2
EXPORT
          EXPORT_PARAM_1
          EXPORT_PARAM_2
TABLE
          TABLE_IN
          TABLE_OUT
          TABLE_IN_OUT
EXCEPTION
          EXCEPTION_1
         EXCEPTION_2

This function signature includes two import parameters and one import table that it reads as input, two export parameters and one export table that it writes as output, one table (TABLE_IN_OUT) that it reads on input and writes as output, and two exceptions that it can raise if an R/3 error occurs.

FML32 Field Definitions for BAPI/RFC eLink to R/3

In TUXEDO messages, import parameters, export parameters, table, and exceptions are represented as named fields in FML32 buffers. A calling application uses two kinds of buffers:

• Request Buffers contain import parameters and import tables.

• Response Buffers contain export parameters and export tables as well as success/failure information (R/3-level errors or adapter errors).

The calling application constructs a request buffer containing import parameters and import tables. BAPI/RFC eLink to R/3 allocates a response buffer and populates it with data returned from the ABAP/4 function according to the settings of the CR3_EXPORT_PARAMS and CR3_EXPORT_TABLES environment variables in the configuration file.

Request Buffers

Before invoking a service associated with an BAPI/RFC call, a calling application prepares an FML32 request buffer that contains the following information:

• Import parameters. The Field Name is the import parameter name as specified in the ABAP/4 function signature, and the Field Value is the parameter value to pass into the ABAP/4 function. Each import parameter can consist of a single field or multiple fields.

• Import tables. Tables consist of one or more rows of data. Each row is an occurrence of an FML32 field. The Field Name is the table name as specified in the ABAP/4 function signature, and the Field Value is a string containing the row data to pass into the ABAP/4 function. The calling application is responsible for passing each field of a table row in a single FML buffer field.

The calling application passes this request buffer when it invokes the service associated with the BAPI/RFC.

For example, for the function signature shown in the section ABAP/4 Parameters, a calling application might construct the following FML32 request buffer:

Table 2-1 Request Buffer for a Sample ABAP/4 Function

FML32 Field Name	Field Value	Data Type
IMPORT_PARAM_1	ParameterValue	String
IMPORT_PARAM_2	ParameterValue	String
TABLE_IN	TableRowValue	String
TABLE_IN	TableRowValue	String
TABLE_IN	TableRowValue	String
..	..	String
TABLE_IN_OUT	TableRowValue	String
TABLE_IN_OUT	TableRowValue	String
TABLE_IN_OUT	TableRowValue	String
..	..	String

In this example, the TABLE_IN_OUT table is both an import and export table. Therefore, the request buffer contains table rows to be passed into the ABAP/4 function. In addition, TABLE_IN_OUT is specified in the CR3_EXPORT_TABLES environment variable in the configuration file so that data from this table is returned in the response buffer.

Note: It is the responsibility of the calling application to ensure that the names of import parameters and import tables are spelled exactly as they appear in the ABAP/4 function signature.

Response Buffers

The BAPI/RFC eLink to R/3 allocates an FML32 response buffer. After executing the ABAP/4 function, BAPI/RFC eLink to R/3 populates the response buffer with the results, which include:

• Export parameters. The Field Name is the export parameter name as specified in the ABAP/4 function signature and the Field Value is the parameter value returned from the ABAP/4 function. Each export parameter consists of only one field.

• Export tables. Tables consist of one or more rows of data. Each row is an occurrence of an FML32 field. The Field Name is the table name as specified in the ABAP/4 function signature and the Field Value is a string containing the row data returned from the ABAP/4 function. The calling application is responsible for anticipating the fixed-position format of the row data returned from R/3 and for retrieving and processing the row data accordingly.

• R/3 error information. The ELINK_APP_ERR field contains the text of an R/3 error, if any, that was raised by the ABAP/4 function.

• Adapter error information. Two FML32 fields, ELINK_ADAPTER_ERR_CODE and ELINK_ADAPTER_ERR, contain information about adapter errors.

For example, for the function signature specified in ABAP/4 Parameters, BAPI/RFC eLink to R/3 might return the following FML32 response buffer:

Table 2-2 Response Buffer for Sample ABAP/4 Function

FML32 Field Name	Field Value	Data Type
EXPORT_PARAM_1	ParameterValue	String
EXPORT_PARAM_2	ParameterValue	String
TABLE_OUT	TableRowValue	String
TABLE_OUT	TableRowValue	String
TABLE_OUT	TableRowValue	String
..	..	String
TABLE_IN_OUT	TableRowValue	String
TABLE_IN_OUT	TableRowValue	String
TABLE_IN_OUT	TableRowValue	String
..	..	String

Note: Error fields (ELINK_APP_ERR, ELINK_ADAPTER_ERR_CODE, and ELINK_ADAPTER_ERR) appear in the response buffer only if an R/3 error or adapter error occurs.

Configuring Export Parameters and Export Tables

Two environment variables control which export parameters and export tables are included in the response buffer:

• CR3_EXPORT_PARAMS specifies the list of export parameters that BAPI/RFC eLink to R/3 includes in the response buffer.

• CR3_EXPORT_TABLES specifies the list of export tables that BAPI/RFC eLink to R/3 includes in the response buffer.

After the ABAP/4 function is executed, BAPI/RFC eLink to R/3 populates the response buffer with these values. If an export parameter or export table is not specified in this list, BAPI/RFC eLink to R/3 discards it even if it is returned from the ABAP/4 function. See Configuring the BAPI/RFC eLink to R/3 Server.

Handling Problems with BAPIs/RFCs

Two kinds of problems can arise when executing BAPI/RFCs:

• R/3 errors indicate business-level errors that are raised by the ABAP/4 function, such as invalid import data. If an R/3 error occurs, BAPI/RFC eLink to R/3 returns a response buffer containing only the ELINK_APP_ERR field.

• Adapter errors, which indicate any other infrastructure-level problems, such as an R/3 connection error. If an adapter error occurs, BAPI/RFC eLink to R/3 returns a response buffer containing only the ELINK_ADAPTER_ERR_CODE and ELINK_ADAPTER_ERR fields.

It is the responsibility of the calling application to retrieve and process exception and error information accordingly.

Handling R/3 Errors

If an exception is raised when executing the ABAP/4 function on R/3, BAPI/RFC eLink to R/3 behaves as follows:

• Populates the ELINK_APP_ERR field in the response buffer with the text of the R/3 error

• Returns TPFAIL with the tpurcode set to zero (0)

After making the service call, the calling application should check the return value and tpurcode. If TPFAIL is returned with tpurcode error code set to zero (0), the application should parse the text in the ELINK_APP_ERR field in the response buffer and respond appropriately.

Handling Adapter Errors

If an adapter error occurs when executing an ABAP/4 function, BAPI/RFC eLink to R/3 behaves as follows:

• Populates the ELINK_ADAPTER_ERR_CODE field in the response buffer with the adapter error category

• Populates the ELINK_ADAPTER_ERR field in the response buffer with the BEA eLink Adapter for R/3 BAPI/RFC error code and message

• Returns TPFAIL with the tpurcode set to -1 or, if the error is an uncorrectable one (such as a memory allocation failure), then BAPI/RFC eLink to R/3 returns TPEXIT with the tpurcode set to -1

• Writes a message to the error log

After making the service call, the calling application should check the return value and tpurcode. If TPFAIL or TPEXIT is returned and tpurcode is -1, it should parse the text in the ELINK_APP_ERR field in the response buffer and respond appropriately.

Checking the Error Log

If BAPI/RFC eLink to R/3 encounters an adapter level error, it logs the following information to the TUXEDO userlog:

• The adapter error category. For example, if the BAPI/RFC eLink to R/3 server cannot start up, the adapter error category in the log entry is ELINK_ECONFIG.

• An error code and text that is specific to BEA eLink Adapter for R/3 BAPI/RFC (the same text that is returned in the ELINK_ADAPTER_ERROR field).

• A unique code identifying where in the code the error was encountered.

Refer to your TUXEDO documentation for more information about the TUXEDO userlog.

RFC R/3 to eLink Server

This section describes how R/3 applications access TUXEDO services by using the RFC/BAPI R/3 to eLink connection.

• RFC R/3 to eLink Server Application

• Information Flow of the RFC R/3 to eLink

• Calling a TUXEDO Service from an ABAP/4 Function

• Error Handling

• Error Return Codes

RFC R/3 to eLink Server Application

Some integration requirements may require R/3 to access the data and functionality of a TUXEDO application. When R/3 needs access to the data and functionality of the TUXEDO application during its business logic flow, R/3 will initiate the communication. The TUXEDO applications must be ready to service the requests from R/3.

RFC R/3 to eLink takes calls coming out of SAP, builds the FML32 message, and then generates the service call. After the service call, a response is initiated from the target application. (Usually eLink Server or some other TUXEDO server, which processes the FML32 message and returns a response - tpcall(), receives an FML32 message.)

RFC R/3 to eLink is the component of BEA eLink Adapter for R/3 BAPI/RFC that allows R/3 to act as a client application to a TUXEDO service. RFC R/3 to eLink is a TUXEDO server that allows R/3 to send request messages to TUXEDO applications and receive the response message. The request message specifies the data and functionality of the TUXEDO application to which R/3 requires access. The TUXEDO application returns the result of the access in the response message.

The TUXEDO applications must be able to receive the request messages, process the request, and send the response message.

RFC R/3 to eLink handles remote function calls from R/3. Therefore, R/3 communicates with TUXEDO applications in the same manner that R/3 invokes an ABAP/4 function or communicates with other R/3 systems using BAPI/RFC. This significantly reduces the effort required to implement the integration.

RFC R/3 to eLink can be called from any ABAP/4 program or DynPro flow. The most likely place for such calls would be in the user exits of transactions and ABAP/4 reporting programs that need access to non-R/3 programs.

Structure of RFC R/3 to eLink

The RFC R/3 to eLink structure consists of two main components:

• cr3rfcout is the program that handles messages exchanged between R/3 and the TUXEDO application.

• Any ABAP/4 function invokes the external cr3rfcout program to send and receive messages over TUXEDO.

The communication is synchronous. For synchronous communication, cr3rfcout will immediately return to the calling ABAP/4 program after sending the request message.

Because the contents of the import parameters, export parameters, and tables determine the message to be sent, the ABAP/4 program only needs to process the data in the request and response messages by using a standard ABAP/4 data structure.

ABAP/4 Function Interface

ABAP/4 functions have a function signature that defines the interface:

FUNCTION function_name

IMPORTING

	Import_parameter_1

	Import_parameter_2

	..

EXPORTING

	Export_parameter_1

	Export_parameter_2

	..

TABLES

	Table_1

	Table_2

	Table_3

	..

EXCEPTIONS

	Exception_1

	Exception_2

	..	

About Parameters and Tables

Parameters that are passed into the function are termed import parameters, and parameters that are returned are export parameters. Exceptions are defined error messages that the function can return to signal an error condition. A table is similar to an array. It consists of one or more rows, where each row is a specific type (for example, a string) or a structure. Tables are passed by reference and can be imported, exported, or both.

In the above function signature, the function takes the two import parameters as input and returns the two export parameters as output. In this example, the function reads input data from Table_1 and Table_2 and returns output data in Table_2 and Table_3. Therefore, Table_1 may be bi-directional. The functions can raise two exceptions, if an error occurs.

Information Flow of the RFC R/3 to eLink

RFC R/3 to eLink may allow R/3 to act as a client to a TUXEDO server application.

The information flow for using the RFC R/3 to eLink is as follows:

1. One or more instances of RFC R/3 to eLink (a TUXEDO server) start up and register a program ID with the R/3 Gateway. RFC R/3 to eLink runs in register mode and listens for messages associated with that program ID on the registered port.

2. RFC R/3 to eLink also registers the R/3 BAPI/RFC calls, which are specified in the configuration file.

3. The ABAP/4 function calls an R/3 BAPI/RFC call, which is registered in an instance of the RFC R/3 to eLink server on the port specified by the destination, passing the function parameters.

4. RFC R/3 to eLink builds an FML32 request buffer, specifying the name of the TUXEDO application/function to invoke and the parameters to pass to the function.

5. RFC R/3 to eLink makes a service call to the named TUXEDO application, passing the FML32 request buffer containing the parameter information.

6. The TUXEDO application reads the FML32 request buffer, processes the request, sets the tpurcode, and returns the result in an FML32 response buffer to the RFC R/3 to eLink.

7. The RFC R/3 to eLink returns the result to the ABAP/4 function.

8. The ABAP/4 function returns the result to the ABAP/4 program.

9. The ABAP/4 program processes the results as appropriate.

Figure 2-2 illustrates the information flow of the RFC R/3 to eLink:

Figure 2-2 Information Flow of the RFC R/3 to eLink

Calling a TUXEDO Service from an ABAP/4 Function

This section contains TUXEDO action invocation requirements.

Mapping of R/3 Import Parameters and Tables to FML32 Request Buffer

The FML32 request buffer will be used to pass data to the TUXEDO action by defining the following:

• What import parameters are to be passed into the input buffer and the values of those input parameters

• What import tables are to be passed into the input buffer and the values of those import tables.

To invoke the TUXEDO action, the FML32 request buffer will contain the following fields:

Table 2-3 Mapping R/3 Import Parameters and Tables to FML32 Request Buffer

FML32 Field Name	Field Value	Value Type
Import_parameter_1	ParameterValue	Parameter_type
Import_parameter_2	ParameterValue	Parameter_type
Table_1	Table_row_value	String
Table_1	Table_row_value	String
Table_1	Table_row_value	String
..	..	..
Table_2	Table_row_value	String
Table_2	Table_row_value	String
Table_2	Table_row_value	String
..	..	..

The Parameter_type of each BAPI/RFC function might not be the same type as the type of the corresponding FML field. FML conversion functions are used to perform data conversion upon reading or writing a fielded buffer. A table row can be a structure with a specific format, but the data type of each field of the structure should be defined as string.

Mapping of FML32 Response Buffer to R/3 Export Parameters and Tables

The response from the TUXEDO action will be encoded in the FML32 response buffer using the following fields:

Table 2-4 Mapping of FML32 Response Buffer to R/3 Export Parameters and Tables

FML32 Field Name	Field Value	Value Type
Export_parameter_1	Parameter_value	Parameter_type
Export_parameter_2	Parameter_value	Parameter_type
Table_2	Table_row_value	String
Table_2	Table_row_value	String
Table_2	Table_row_value	String
..	..	..
Table_3	Table_row_value	String
Table_3	Table_row_value	String
Table_3	Table_row_value	String
..	..	..

The Parameter_type of each BAPI/RFC function might not be the same type as the type of the corresponding FML field. FML conversion functions are used to perform data conversion upon reading or writing a fielded buffer. A table row can be a structure with a specific format, but the data type of each field of the structure should be defined as string.

Error Handling

This section describes how the RFC R/3 to eLink handles both adapter (non-TUXEDO) level errors and TUXEDO action invocation errors.

Error Logging

When the RFC R/3 to eLink encounters an infrastructure error, it may log the following to the TUXEDO userlog:

• The eLink error category

• An eLink Adapter for R/3 specific error code and text

• A unique code identifying where in the code the error was encountered

Adapter Error at Startup

All adapter level errors encountered during startup prevent RFC R/3 to eLink from starting and will be logged.

TUXEDO Action Invocation Error Handling

TUXEDO action TPCALL returns -1 on error and sets tperrno to indicate the error condition. The RFC R/3 to eLink connection raises exceptions to the calling ABAP application.

• RFC R/3 to eLink Infrastructure Error - If the error returned from TUXEDO action is an RFC R/3 to eLink infrastructure error, the exception defined in the environment variable CR3_RFC_INFRASTRUCTURE_EXCEPT is raised. If this environment variable is not specified, the application aborts.

• Business Logic Error - If the error returned from TUXEDO action is a business logic error, the exception defined in the environment variable CR3_RFC_BUSINESS_EXCEPT is raised. If this environment variable is not specified, the application aborts.

Infrastructure Error vs. Business Logic Error

Errors are classified into two categories: Infrastructure error and business error.

• Business logic error refers to the error that occurs at the application business logic level.

• Infrastructure error refers to the error that occurs at the adapter level or system level.

According to the error handling specified in the eLink Adapter Architecture Specification, when the business error occurs during TPCALL, the return value is set to -1, tperror is set to TPESVCFAIL, and the application defined value tpurcode is set to 0.