[Table of Contents] [Index] [Previous] [Next] Integrating with RFCs

# Integrating with RFCs

This chapter describes how to integrate with SAP Remote Function Calls (RFCs) in the BEA eLink Adapter for R/3 environment. It includes the following sections:

- About RFC Integration

- Invoking ABAP/4 Functions

For information about setting up RFC processing, see Configuring for RFC Integration in the BEA eLink Adapter for R/3 Installation and Configuration Guide.

## About RFC Integration

Figure 2-1 provides an overview of the information flow for RFC Inbound:

> Figure 2-1 Overview of Information Flow for RFC Processing

RFC Inbound is a TUXEDO server that allows TUXEDO applications to invoke any ABAP/4 functions that have been RFC-enabled in R/3. See Invoking ABAP/4 Functions for more information.

## Invoking ABAP/4 Functions

This section describes how to invoke RFC-enabled ABAP/4 functions in the TUXEDO environment using RFC Inbound, a TUXEDO server, via synchronous RFC. It includes the following topics:

- About the RFC Inbound Server

- Information Flow

- About ABAP/4 Parameters

- FML32 Field Definitions for RFC Inbound

- Configuring Export Parameters and Export Tables

- Handling Problems with RFCs

For information about setting up RFC processing, see the following chapters in the BEA eLink Adapter for R/3 Installation and Configuration Guide:

- Configuring RFC Integration

- Configuring R/3 Connections

### About the RFC Inbound Server

RFC Inbound is a component of the BEA eLink Adapter for R/3 product that allows TUXEDO applications and other non-R/3 applications to invoke any ABAP/4 functions that have been RFC-enabled. RFC Inbound 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. RFC Inbound advertises the ABAP/4 functions that it can invoke as TUXEDO services and aliases them to the CR3_RFC_IN service. Developers can configure which ABAP/4 functions can be invoked and the service names by which they are advertised.

### Information Flow

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

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

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

1. One or more instances of RFC Inbound (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 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 RFC, passing in the FML32 request buffer.

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

5. RFC Inbound 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 back to RFC Inbound.

7. RFC Inbound receives the results and, depending on the success of the RFC call, does one of the following:

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

   - If the RFC call failed, RFC Inbound populates the FML32 response buffer with information about the error:

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

     Adapter-level errors. RFC Inbound 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-specific error code and message. RFC Inbound 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, RFC Inbound 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.

### About 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. Listing 2-1 defines a generic ABAP/4 function:

> Listing 2-1 ABAP/4 Function Signature

>     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 RFC Inbound

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. RFC Inbound 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 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 consists of only one field.

- 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 formatting the row data correctly in the fixed-position format that the ABAP/4 function recognizes.

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

For example, for the function signature shown in Listing 2-1, "ABAP/4 Function Signature " 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 RFC Inbound allocates an FML32 response buffer. After executing the ABAP/4 function, RFC Inbound 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 Listing 2-1, "ABAP/4 Function Signature " RFC Inbound 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 RFC Inbound includes in the response buffer.

- CR3_EXPORT_TABLES specifies the list of export tables that RFC Inbound includes in the response buffer.

After the ABAP/4 function is executed, RFC Inbound populates the response buffer with these values. If an export parameter or export table is not specified in this list, RFC Inbound discards it even if it is returned from the ABAP/4 function. See Configuring RFC Integration in the BEA eLink Adapter for R/3 Installation and Configuration Guide.

### Handling Problems with RFCs

Two kinds of problems can arise when executing 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, RFC Inbound 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, RFC Inbound 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, RFC Inbound:

- 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 set to zero (0), it 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, RFC Inbound:

- 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 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 RFC Inbound 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 RFC Inbound encounters an adapter level error, it logs the following information to the TUXEDO userlog:

- The adapter error category. For example, if the RFC Inbound 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 (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.

[Table of Contents] [Index] [Previous] [Next]