![]() |
![]() |
|
|
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:
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:
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:
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.
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.
ABAP/4 Parameters
ABAP/4 functions use the following types of parameters:
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:
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:
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:
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:
For example, for the function signature specified in ABAP/4 Parameters, BAPI/RFC eLink to R/3 might return the following FML32 response buffer:
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:
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:
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:
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:
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:
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
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:
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:
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:
To invoke the TUXEDO action, the FML32 request buffer will contain the following fields:
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:
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:
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.
Infrastructure Error vs. Business Logic Error
Errors are classified into two categories: Infrastructure error and business error.
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.
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|