Configuring BAPI/RFC Integration

 

This topic describes how to configure your BEA eLink Adapter for R/3 BAPI/RFC installation for integration with SAP's Remote Function Call (RFC) / Business Application Programming Interface (BAPI) technology. It includes the following main sections:

• Configuring the BAPI/RFC eLink to R/3 Server

• Configuring the RFC R/3 to eLink Server

Using BEA eLink Adapter for R/3 BAPI/RFC, TUXEDO applications can invoke BAPI/RFC-enabled ABAP/4 functions on R/3 systems, and R/3 can act as a TUXEDO server and invoke TUXEDO services. For more information about BAPI/RFC integration, see Chapter 2, "Integrating with BAPIs/RFCs," in this guide.

Note: You need to complete the tasks in this section only if you require application integration with BAPI/RFC technology.

Configuring the BAPI/RFC eLink to R/3 Server

This topic describes how to configure the BAPI/RFC eLink to R/3 server. It includes the following main sections:

• Configuring the eLink to R/3 Connection for BAPI/RFC eLink to R/3

• Setting Environment Variables for BAPI/RFC eLink to R/3

BAPI/RFC eLink to R/3 is a standard TUXEDO server that is defined in the TUXEDO configuration file.

Configuring the eLink to R/3 Connection for BAPI/RFC eLink to R/3

You must configure the eLink to R/3 connection for BAPI/RFC eLink to R/3, including the sideinfo file and environment variables. For more information, see Configuring R/3 Connections.

BAPI Configuration Requirements

The BAPI/RFC servers interrogate the R/3 system to determine the version and then set internal configuration parameters accordingly.

The servers are configured via an environment file. A BAPI configuration is the identical to RFC configuration.

Configuring the UBB File for BAPI/RFC eLink to R/3

BAPI/RFC eLink to R/3 is a standard TUXEDO server that is defined in the UBB file. You must configure this file to specify the server group, server, environment file, and services associated with the BAPI/RFC eLink to R/3 server. See Sample cr3_bapi.ubb File, for a listing of the sample UBB file that comes with BEA eLink Adapter for R/3 BAPI/RFC.

Defining the Server Group

In the SERVERS section of your UBB file, you must first define the server group (such as CR3) to which BAPI/RFC eLink to R/3 belongs. See TUXEDO Initialization File, for instructions.

Defining the BAPI/RFC eLink to R/3 Server

In the SERVERS section of your UBB file, you must define the BAPI/RFC eLink to R/3 server, specifying its server group, server ID, and environment file using the following syntax:

SRVGRP=GroupId SRVID=ServerID
CLOPT = " -- -i unique_id -e env_filename"

where:

• GroupID is the unique ID of the server group to which the BAPI/RFC eLink to R/3 server belongs.

• ServerID is the unique ID of the BAPI/RFC eLink to R/3 server.

• -i unique_id is the unique ID that identifies the label section in the environment file containing the adapter's environment variables. You would use this value when you run multiple eLink adapters (for example, BAPI/RFC eLink to R/3 and RFC R/3 to eLink) that share this configuration file. If it is not specified, then the unique ID defaults to the process name.

• -e env_filename is the environment file that specifies the detailed configuration information.

Listing 6-1 shows SERVERS settings for RFC eLink to R/3 in a sample UBB file for Windows NT:

Listing 6-1 Sample SERVERS Settings for BAPI/RFC eLink to R/3 Server

---

##############################################################
*SERVERS
##############################################################
cr3rfcin
          SRVGRP=CR3 SRVID=4
          CLOPT="-o cr3rfcin.log -- -i cr3rfcin -e cr3.env"

---

Defining the BAPI/RFC eLink to R/3 Service

In the SERVICES section of your UBB file, you must define the CR3_RFC_IN service. Listing 6-2 shows SERVICES settings for BAPI/RFC eLink to R/3 in a sample UBB file for Windows NT:

Listing 6-2 Sample SERVICES Settings for BAPI/RFC eLink to R/3 Server

---

##############################################################
*SERVICES
##############################################################
CR3_RFC_IN

---

Setting Environment Variables for BAPI/RFC eLink to R/3

The BAPI/RFC eLink to R/3 server requires particular environment variables that specify connection information to R/3 and the behavior of the server. These environment variables are defined in an environment file that is specified in the TUXEDO initialization file as the ENVFILE parameter for the server.

BEA eLink Adapter for R/3 BAPI/RFC provides a semi-configured TUXEDO environment file (cr3rfcin.env) for use with the BAPI/RFC eLink to R/3 server. There should a separate environment file specified in the cr3_bapi.ubb configuration for each BAPI/RFC eLink to R/3 server. See Sample cr3_bapi.ubb File, for more information.

Environment Variables

You can configure the following environment variables for the BAPI/RFC eLink to R/3 server:

Table 6-1 Environment Variables for the BAPI/RFC eLink to R/3 Server

Task / Variable	Value	Description
Adapter Label Section
[SERVER=AdapterID]	Adapter ID	Defines the label section containing the adapter environment variables. The unique AdapterID is the value of the -i flag on the CLOPT line in the UBB file. If not specified, then the default value is the process name. Required.
Connecting to R/3
CR3_DESTINATION	System Name	The destination switch in the sideinfo file that defines the R/3 application server for connection. Default is undefined. Required.
CR3_CLIENT	Client Number	R/3 login client number. Default is undefined. Required.
CR3_USER	User	R/3 login user. Default is undefined. The user must be of type CPIC. Required.
CR3_PASSWORD	Password	R/3 login user password. Default is undefined. Required.
CR3_LANGUAGE	Language	R/3 login language. Default is E for English. Required.
SIDE_INFO	Path and File	Full path to the sideinfo file, which defines the R/3 connection information that is used by the BAPI/RFC library. If not specified, then the sideinfo file must reside in the same directory as the BAPI/RFC eLink to R/3 executable. Optional.
CR3_EXIT_R3_CONNECT_LOSS	Y or N	If set to Y, BAPI/RFC eLink to R/3 exits when it detects that it has lost the BAPI/RFC connection to R/3. If set to N or unspecified, then BAPI/RFC eLink to R/3 does not exit but instead tries to restore the connection upon the next service call. Optional.
Response Buffer Size
CR3_RESPONSE_BUFFER_SIZE	Size (bytes)	Defines the starting size of the FML32 response buffer. If not specified, then the default starting size is 10,000 bytes. Optional.
Defining Callable BAPIs/RFCs
SERVICE_LIST	List of services to be advertised	Comma-delimited list containing the names of TUXEDO services that BAPI/RFC eLink to R/3 advertises. Required.
[SERVICE= Service Name]	Service name	Service name for each service in the SERVICES_LIST environment variable. Signifies the start of the service configuration definition. Required.
CR3_RFC_NAME	BAPI/RFC Name	Name of the ABAP/4 function to execute when the associated service is invoked. Required.
CR3_EXPORT_PARAMS	Export parameters to be returned	Comma-delimited list containing the names of the BAPI/RFC's export parameters to be returned in the FML32 response buffer. Optional.
CR3_EXPORT_TABLES	Export tables to be returned	Comma-delimited list containing the names of the BAPI/RFC's export tables to be returned in the FML32 response buffer. Optional.
Logging
CR3_TRACE	Y or N	If set to Y, then BAPI/RFC eLink to R/3 logs detailed tracing information during processing. If set to N or unspecified, BAPI/RFC eLink to R/3 does not log trace information. Optional.

Sample Environment File (cr3rfcin.env)

Listing 6-3 shows the settings for the sample cr3rfcin.env file:

Listing 6-3 Sample Environment File

---

CR3_DESTINATION=<R/3 System Name>
CR3_CLIENT=<R/3 Client ID>
CR3_USER=<R/3 User>
CR3_PASSWORD=<R/3 Password>
CR3_LANGUAGE=E
SIDE_INFO=<your eLink app directory>\sideinfo
CR3_EXIT_R3_CONNECT_LOSS=N
CR3_TRACE=Y
SERVICES_LIST=service_1,service_2,service_3
[SERVICE=service_1]
CR3_RFC_NAME=RFCName1
CR3_EXPORT_PARAMS=ExportParam1,ExportParam2
CR3_EXPORT_TABLES=ExportTable1
[SERVICE=service_2]
CR3_RFC_NAME=RFCName2
CR3_EXPORT_PARAMS=ExportParam1,ExportParam2
CR3_EXPORT_TABLES=ExportTable1
[SERVICE=service_3]
CR3_RFC_NAME=RFCName3
CR3_EXPORT_PARAMS=ExportParam1,ExportParam2
CR3_EXPORT_TABLES=ExportTable1

---

Specifying the Adapter Label

You can specify an optional adapter label in the environment file to define a label section containing the adapter's environment variables. You use this label when you run multiple eLink adapters (for example, BAPI/RFC eLink to R/3 and RFC R/3 to eLink) that share this configuration file. The unique AdapterID corresponds to the value of the -i flag on the CLOPT line in the UBB file. See "Defining the BAPI/RFC eLink to R/3 Server" earlier in this topic for more information.

Setting Up the eLink to R/3 Connection to R/3

To set up the eLink to R/3 connection to R/3, you must set environment variables and configure the sideinfo file. See Configuring R/3 Connections for more information.

Exiting if the Connection is Lost

You can configure BAPI/RFC eLink to R/3 to exit if it detects a lost connection to R/3 by setting the CR3_EXIT_R3_CONNECT_LOSS environment variable to Y, as shown in the following example:

CR3_EXIT_R3_CONNECT_LOSS=Y

If you do not specify this environment variable or if you set it to N, then BAPI/RFC eLink to R/3 will try to restore the connection to R/3 instead upon the next service call.

Specifying the Initial Size of the Response Buffer

You can configure the initial size, in bytes, of the response buffer that BAPI/RFC eLink to R/3 allocates for exported parameters by setting the CR3_RESPONSE_BUFFER_SIZE environment variable, as shown in the following example:

CR3_RESPONSE_BUFFER_SIZE=15000

If you do not specify this environment variable, BAPI/RFC eLink to R/3 sets the initial size of the response buffer to 10,000 bytes. You increase this buffer size to improve performance for BAPI/RFC calls that return very large volumes of data.

Configuring BAPI/RFC

To execute an ABAP/4 function on R/3, the calling application prepares an FML32 request buffer that contains the applicable RFC import parameters and import tables. The calling application invokes the TUXEDO service associated with the BAPI/RFC, passing in the request buffer. BAPI/RFC eLink to R/3 makes the remote function call on R/3, passing the import parameters to R/3. BAPI/RFC eLink to R/3 receives the results and returns them in an FML32 response buffer to the calling application. You configure environment variables to control this process.

For each ABAP/4 function that you want to execute remotely using BAPI/RFC eLink to R/3, you must specify a label in the environment file that identifies the name of the TUXEDO service associated with this BAPI/RFC ([SERVICE=ServiceName]). For each service, you must specify the following attributes (in environment variables):

• Name of the BAPI/RFC to execute when this service is invoked (CR3_RFC_NAME).

• Export parameters, if any, to return in the FML32 response buffer (CR3_EXPORT_PARAMS).

• Export tables, if any, to return in the FML32 response buffer (CR3_EXPORT_TABLES).

In addition, you must specify a list of all services to be advertised to calling applications (SERVICES_LIST). BAPI/RFC eLink to R/3 reads and processes this list, and then advertises the service names, aliasing them to the CR3_RFC_IN service.

Defining the List of Services to Advertise

You must specify the list of services (a comma-delimited series) that BAPI/RFC eLink to R/3 advertises in the SERVICES_LIST environment variable, as shown in the following example:

SERVICES_LIST=service_1,service_2,service_3

Defining Each Advertised Service

For each service specified in the SERVICES_LIST, you must specify a service label and define the name of the BAPI/RFC to execute as well as the contents of the FML32 response buffer (export parameters and export tables) that you want BAPI/RFC eLink to R/3 to return to the calling application, as shown in the following example:

[SERVICE=service_1]
CR3_RFC_NAME=RFCName1
CR3_EXPORT_PARAMS=ExportParam1,ExportParam2
CR3_EXPORT_TABLES=ExportTable1

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

Configuring Trace Output to the BAPI/RFC eLink to R/3 Log

You can configure BAPI/RFC eLink to R/3 to write detailed trace information to the log by setting the CR3_TRACE environment variable to Y, as shown in the following example:

CR3_TRACE=Y

If you set this to N or do not specify it, BAPI/RFC eLink to R/3 writes no trace information to the log.

You can redirect stdout by changing the value of the -o flag on the CLOPT line in the UBB file. See "Defining the BAPI/RFC eLink to R/3 Server" for more information.

Operational Requirements

At run-time, the BAPI/RFC servers use the appropriate RFC structures to interface with R/3. These structures are version specific.

Once configured for a specific version of R/3, the BAPI/RFC servers will use the appropriate structures and functions. No further interrogation of R/3 will be necessary.

BAPI/RFC Interface

Each BAPI/RFC name defined in R/3 must have a corresponding TUXEDO service name defined in the environment file.

Each BAPI/RFC in R/3 defines a set of import parameters, export parameters, and tables. Each of the defined import parameters, export parameters, and tables must be supplied to the eLink to R/3 server. These values must be provided in the FML32 buffer passed into the eLink to R/3 server. Each field name in the FML buffer must directly map to the R/3 interface parameters for a particular BAPI/RFC.

R/3 tables and fields are specifically defined by a named FML field. Each table field is mapped to an FML field occurrence as outlined in later sections.

Import Parameter

For import parameters, there is one to one mapping between an R/3 parameter and an FML field name. Each parameter is supplied by one FML field containing the data value.

Table 6-2

Export Parameter

For export parameters, there is a one to one mapping between an R/3 parameter and an FML field name. Each parameter is supplied by one FML field containing the data value.

Table 6-3

Import Table

For import tables, there is a one to one mapping between an R/3 table field and an FML field occurrence. Each table field is supplied by one FML field occurrence containing the data value.

The FML field name consists of the table name concatenated with the field name. You must provide a user-defined concatenation string. The default concatenation string is "_".

Table 6-4

Export Table

For export tables, there is a one to one mapping between an R/3 table field and an FML field occurrence. Each table field is supplied by one FML field occurrence containing the data value.

The FML field name consists of the table name concatenated with the field name. You must provide a user-defined concatenation string. The default concatenation string is "_".

Table 6-5

Datatype Conversion

Data coming from R/3 is converted into a corresponding FML datatype. Similarly, data coming from eLink is converted into a corresponding R/3 datatype.

Table 6-6

Licensing

The eLink adapter for R/3 BAPI/RFC requires the following licenses:

• eLink Platform 1.1

• eLink Adapter for R/3 BAPI/RFC 1.5

Configuring the RFC R/3 to eLink Server

The RFC R/3 to eLink is a TUXEDO server. Configuration is required in the TUXEDO UBB file to run the RFC R/3 to eLink server within the TUXEDO domain. An environment file will define detailed configuration information required by the RFC R/3 to eLink.

SAP R/3 Connection Requirements

The RFC R/3 to eLink will register with R/3 using the registration functionality of the BAPI/RFC API.

UBB File Configuration Requirements

At a minimum, the RFC R/3 to eLink will require the following configuration in the UBB file:

cr3rfcout

	SRVGRP=.. SRVID=..

	CLOPT = " -- -i unique_id -e env_filename"

where -i unique_id

is the unique ID identifying the label section in the environment file containing the adapter environment variables. This parameter is optional. If it is not specified, then the unique id will default to the process name.

	-e env_filename

is the environment file specifying the detailed configuration information.

Environment File Configuration Requirements

The detailed configuration information for the RFC R/3 to eLink is specified in an environment file. The configuration information is grouped into the following tables. Users must provide server connection variables, client connection variables, generic configuration variables, and some additional variables based on different TUXEDO actions.

The environment variables for an adapter can be specified in an environment file individually or as part of a combined environment file with environment variables for other adapters. See the "Description" for the [SERVER=..] adapter unique ID variable in Table 5-7 for more information.

Adapter Unique ID Variable

You can configure the following adapter unique ID variable for the RFC R/3 to eLink server:

Table 6-7 Adapter Unique ID Variable for the RFC R/3 to eLink Server

Task / Variable	Value	Description
[SERVER=..]	String The adapter unique ID will either be the value of the -i flag on the CLOPT line, or if not specified, then the default value of the process name.	Adapter unique id. The label section defines all the environment variables for this adapter with this adapter unique id. If the environment file specifies environment variables for more than one adapter, the [SERVER=..] environment variable must be presented to distinguish the environment variables for this adapter with this adapter unique id from the environment variables for other adapters.

Server Connection Variables

You can configure the following server connection variables for the RFC R/3 to eLink server:

Table 6-8 Server Connection Variables for the RFC R/3 to eLink Server

Task / Variable	Value	Description
CR3_HOST	String	Destination switch in the sideinfo file
CR3_SOCKET	String	R/3 socket
CR3_PROGRAM_ID	String	R/3 program ID

Client Connection Variables

You can configure the following client connection variables for the RFC R/3 to eLink server:

Table 6-9 Client Connection Variables for the RFC R/3 to eLink Server

Task / Variable	Value	Description
CR3_DESTINATION	String	Destination switch in the sideinfo file
CR3_CLIENT	String	R/3 client
CR3_USER	String	R/3 user
CR3_PASSWORD	String	R/3 password
CR3_LANGUAGE	String	R/3 logon language
SIDE_INFO	String	Path and file name of sideinfo file. This file defines the R/3 connection information that is used by the BAPI/RFC library. Note: The RFC R/3 to eLink will not read this environment variable; it is read by the BAPI/RFC library - it is documented here for completeness only.

Generic Configuration Variables

You can configure the following generic configuration variables for the RFC R/3 to eLink server:

Table 6-10 Generic Configuration Variables for the RFC R/3 to eLink Server

Task / Variable	Value	Description
CR3_EXIT_R3_CONNECT_LOSS	Y or N	Specifies whether the RFC R/3 to eLink is to exit when it detects that it has lost the BAPI/RFC connection to R/3. If not specified or defined as a value other than Y, then the RFC R/3 to eLink will not exit upon losing the BAPI/RFC connection and will try to restore it.
CR3_CONNECT_RETRY_ATTEMPTS	Number	Number of connection retry attempts. If the RFC R/3 to eLink is not to exit when it detects that it has lost the BAPI/RFC connection to R/3 but to try to re-open the connection, then specifies the number of re-try attempts for every connection loss. If after this number of connection re-try attempts, the connection is still not opened, the RFC R/3 to eLink exits.
CR3_REQUEST_BUFFER_SIZE	Number with minimum 1	Number of bytes for the starting size of the FML32 request buffer.
CR3_TRACE	Y or N	Defines if trace output will be produced. If not specified or defined as a value other than Y, then no trace output will be produced.
CR3_RFC_NAMES	String	List of BAPI/RFC functions to be installed. Defines BAPI/RFC functions that the RFC R/3 to eLink will install and support. The function names will be specified as a list, which is comma delimited: function1, function2, function3, ...
[CR3_RFC_NAME=..]	String	BAPI/RFC function name. For each BAPI/RFC function in the list defined by the CR3_RFC_NAMES environment variables, a label will exist where the label is the BAPI/RFC function name. For each BAPI/RFC function, the label section will contain the CR3_TUX_ACTION environment variable and some additional variables. For example: CR3_RFC_NAMES=f1, f2, f3 [CR3_RFC_NAME=f1] ..... [CR3_RFC_NAME=f2] ..... [CR3_RFC_NAME=f3] .....
CR3_RFC_INFRASTRUCTURE_EXCEPT	String	The name of the BAPI/RFC function exception, which is used to raise adapter infrastructure-related exception. If this environment variable is not specified when a infrastructure-related error occurs, the application will abort.
CR3_RFC_BUSINESS_EXCEPT	String	The name of the BAPI/RFC function exception, which is used to raise business logic-related exception. If this environment variable is not specified when a business logic-related error occurs, the application will abort.
CR3_TUX_ACTION	TPCALL	Defines the TUXEDO action that is to be performed when the BAPI/RFC function specified in the label is executed and the BAPI/RFC call received from SAP R/3. Note: Only the TUXEDO action should be specified.