Tools Guide

Chapter 19   The SAP Data Connector

The SilverStream SAP Enterprise Data Connector (EDC) enables you to bind SilverStream forms and pages to an SAP RFC. It supplies a wizard interface that generates all of the server-side objects necessary to retrieve and update SAP RFC data. You can then write SilverStream forms or pages that let the user manipulate the RFC data. The SAP EDC automates the work of writing Java code to coordinate changes to forms and page controls related to RFC parameters.

This document provides the following information about using SilverStream to access data from an RFC:

SilverStream uses its Data Source object technology to access SAP R/3 data. A Data Source object (DSO) is a triggered business object that lets you access relational and non-relational data sources.

    For information on writing your own DSO, see the chapter on data source business objects in the Programmer's Guide.

How SilverStream integrates with SAP   Top of page

SilverStream Data Source objects interface to SAP R/3 via the RFC classes provided by SAP. These RFC classes use SilverStream JNI Middleware and libRFC to communicate with the R/3 Application Server.

The SilverStream Application Server acts as the Java RFC client to the SAP Application Server as shown in this diagram:

At design time, you use the SilverStream SAP wizard to create the server-side DSO and related utility objects to manage the connection and transfer of data between SilverStream application objects (like pages, forms or business objects) and the R/3 servers.

The SAP RFC Data source wizard presents a list of RFCs (by name). You simply select the RFC that you want to access using SilverStream. The wizard then constructs a single non-triggered utility object and one or more SilverStream DSOs as needed.

About the connection   Top of page

SilverStream connects to SAP on a per user basis. This connection is shared across the multiple DSOs (that make up a single RFC). The connection is opened on the first SAP access and held for the session. You pass the SAP connection and login information programmatically via a Hashtable on the AgxData.invokeQuery().

Running the SAP DSO wizard   Top of page

Once you have configured the server and client machines and are sure these machines can successfully run RFCPING, you can build your SAP DSO.

To build your SAP DSO:

  1. Start the SilverStream Server and Designer.

  2. From the SilverStream Explorer, choose Objects, then choose the New icon.

    SilverStream displays the New Objects menu shown here:

  3. Choose SAP Data Source Objects.

    SilverStream launches the SAP Data Connector Wizard shown here:

  4. Enter data in all of the text fields to log in to the SAP system, then press Next>.

    This information is used by the SilverStream Server to log the design time session into the SAP R/3 Application Server.

    The first time that you use the SAP EDC DSO, SilverStream asks if you want to save the log in information. If you respond yes, SilverStream writes the entries for all of these fields, except the password, to the sap_edc.props file in the SilverStream\Resources subdirectory. On subsequent uses of the DSO, SilverStream will only prompt for the password. During subsequent uses, if you change any of the values, SilverStream will then ask if you want to update the values in the props file with the new entries.

    SilverStream displays the RFC Search panel shown here.

  5. If you do not know the name of the RFC that you want to access, enter a search string in the Search String text box and press Search. If you know the name of the RFC, type it in the Search String text box and press Search. SilverStream returns the names of the RFCs that match the value you entered. To choose an RFC, highlight it and press Next>.

    SilverStream constructs a utility object (referred to as the RFCObject) and a number of DSO triggered business objects; one for all the import/export parameters plus one for each Table. The objects that are created for the RFC_CUSTOMER_GET are shown here.

    SilverStream constructs unique names for the RFCObject and the DSOs that it creates. The names are derived from the RFC parameter that they represent. You can change the default names by selecting the item and typing the desired name.

  6. Press Finish.

    SilverStream updates the Main Designer to display the names of the business objects that the wizard creates.

    For information about the objects that are created by the wizard see Building an example or What the wizard-generated objects do.

Building an example   Top of page

This section describes how SilverStream accesses data from RFC_CUST_GET which is a search function. You must supply a KUNNR or NAME and the RFC returns the associated data.

When you run the SAP wizard for the RFC_CUST_GET, SilverStream creates these objects:

Once you have run the wizard, you can then build a form or page that can access the data from the RFC parameters represented by the objects. This example accesses them from a form called SAP_cust_get_Form. The form prompts the user for the KUNNR and NAME fields as search criteria. Any data that matches the search criteria is returned and populates multiple JTextField controls on the form. The user can navigate the dataset using the First, Last, Next and Previous buttons.

Building the form   Top of page

To build the SAP_Cust_get_Form Form:

  1. Access the SilverStream Form Designer and start the Form Wizard.

  2. Choose dso_TBL_RFC_CUSTOMER_GET_CUSTOMER_T as the primary data source for your form, then choose Next.

  3. Continue with the wizard choosing the appropriate form style and name.

    The wizard generates the form and adds a single AgcData control named dso_TBL_RFC_CUSTOMER_GET_CUSTOMER_T which is bound to the dso_TBL_RFC_CUSTOMER_GET_CUSTOMER_T object.

  4. Rename the AgcData control to dso_TBL_CUSTOMER_GetData.

To complete the page, you must:

  1. Add another AgcData control named dso_IE_CUSTOMER_GETData and bind it to the dso_IE_CUSTOMER_GET data source object.

  2. Add two AgcTextField controls named Field1 and Field2.

  3. Bind Field1 to the KUNNR parameter of the dso_IE_CUSTOMER_GETData object (for example, dso_IE_CUSTOMER_GETData.KUNNR).

  4. Bind Field2 to the NAME1 parameter of the dso_IE_CUSTOMER_GETData object (for example, dso_IE_CUSTOMER_GETData.NAME1).

  5. Add a JButtonText control to the form. Name it btnSearch and change its label to Search.

The complete form looks like this:

The Form Wizard creates a subset of the code that is required for the form to communicate with the data source objects. By default, it supplies the following code in the FormActivate event:

  catch(Exception ex) 

This code is not enough. You need to create a Hashtable that includes the SAP connection information. Depending on your application, you might want to prompt the user for some of this information.

  Hashtable hConnect = new Hashtable(); 
  hConnect.put("SAP_SERVER", "sapservername"); 
  hConnect.put("SYSTEM_NUMBER", "sysnumber"); 
  hConnect.put("LANGUAGE", "language"); 
  hConnect.put("CLIENT_NUMBER", "clntnumber"); 
  hConnect.put("USER_NAME", "userid"); 
  hConnect.put("PASSWORD", "password"); 

You then need to call the invokeQuery() method on each AgcData on the form. This will invoke each business object associated with the RFC you are using. The Data Source Objects, as generated by the SAP DSO Wizard, expect the connect information in the parameter passed on the invokeQuery() call. You then need to call insertAfter() to create an empty row in the AgcData where the user can enter the input parameters

  try { 
  catch(Exception e)	 { 

At startup, the AgcData controls call the invokeQuery() method to initialize the DSOs to which they are bound. The dso_IE_RFC_CUSTOMER_GETData control also calls insertAfter() to put it in the appropriate state for users to enter the KUNNR and NAME search values.

Once the user has entered KUNNR and NAME values, they can press the JButton control to submit the request. The button's actionPerformed event must include calls to the updateRows(), query("EXECUTE") and query(null) methods as shown below.

  try { 
  catch (Exception e) { 

The updateRows() methods sends the input parameters to the DSO. The call to query("EXECUTE") tells the business object to actually call the RFC. You should only call query("EXECUTE") once. When the RFC is called all the associated DSOs on the server will get their data. The call to query(null) on any other AgcDatas causes their data, which is already on the SilverStream Server, to be passed to the client.

About the example's utility object(or RFCObject)   Top of page

The code for the utility is automatically generated by the SAP wizard. Do not modify it. Like all RFCObjects, the RFCObject created for RFC_CUSTOMER_GET includes two methods: its constructor called obj_RFC_CUSTOMER_GET() and createParameters(). The constructor, obj_RFC_CUSTOMER_GET(), includes the rfcname, an AgiSession object and the SAP server connection information. The connection information can be passed to the RFCObject on the form or page's invokeQuery() call. The createParameters() method instantiates whatever objects are necessary to pass parameters to SAP and to hold the data returned by it (before it is downloaded to the form or page). The RFCObject obtains metadata about the RFC and its data types through calls to the RFC methods. The wizard generates the RFC calls necessary to access the RFC metadata information.

About the example's DSOs   Top of page

For this example, the SAP wizard created two DSOs; one for the import/export parameter, the other for the table parameter. The SAP wizard automatically generates this code. Do not modify it. The wizard generates the code in the invokeQuery event and it is similar for both DSOs. You can view the code yourself, but as a quick summary:

What the wizard-generated objects do   Top of page

The SAP DSO wizard creates the objects that SilverStream needs to convert SAP Remote Function Calls (RFCs), with complex parameters, to data that looks relational (rows and columns). Once the data looks relational, a SilverStream form, page, or control can display and manipulate the data obtained by the SAP RFC.

For each RFC, SilverStream creates:

For example, when you create a DSO for the RFC_CUSTOMER_GET, which includes two import parameters, the wizard creates two DSOs: one that maps to the table parameter and the other import parameters.

The DSO provides the data to the SilverStream form or page control. You can bind the control to it at design time. When the wizard creates this object, SilverStream asks the SAP system (using the RFC method calls) for information that describes the particular parameter. It uses this information to format the data in the row and column format expected by the SilverStream object.

Do not change the wizard-generated code. If the code is changed, SilverStream cannot guarantee that the DSO will work as expected.

Using forms and pages to access the DSO   Top of page

Once you have used the wizard to construct the DSO, you can use the SilverStream Form or Page Designer to bind forms and pages to RFC parameters which are presented as columns.

If you use the form or page wizard, SilverStream constructs the form or page with the fields that you specified, the standard set of navigation buttons, and adds a single AgxData control. However, since most RFCs result in more than one DSO, you probably have to add one or more additional AgxData controls to your form or page. The form or page wizard also generates the following method calls to invoke the DSO. (It adds the code in the FormActivate events (for forms) or the PageLoaded event (for pages).)

  1. Calls invokeQuery(null) for the AgxData control(s) bound to an SAP DSO.

    You will call this once for each DSO that provides data for the form, page, or business object. The invokeQuery(null) call initializes the DSO.

  2. Calls insertAfter() for the AgxData control(s) bound to an SAP DSO.

    This creates the data for the RFC parameters by letting the user enter values, or programmatically inserting values to the AgxData control.

    An SAP RFC, like a stored procedure, needs parameters to run. SilverStream is, in effect, binding to (or passing) these parameters to a stored procedure, not to a column in a table. In order for SilverStream to pass values, the form or page needs to be in a state where a call to the updateRows() is meaningful. To force this state, you can call insertAfter() on the pageLoaded or formActivated events, then you can call updateRows(). The updateRows() passes the local data (the form or page data) to the DSO.

  3. If you provide a way for the user to enter values for the RFC parameters, you can then call updateRows() for the AgxData bound to the DSO.

    This passes the parameter values added by insertAfter() from the AgxData control to the DSO. You must call updateRows() before executing the RFC to move the modified data from the AgxData control to the RFCObject.

  4. Once the parameter values are available to the DSO, you can ask the RFCObject to execute the RFC by calling the query() method with the keyword constant "EXECUTE" like this:


    This executes the RFC and refreshes the data in the AgcData object.

    You would do this for ALL client DSOs where you need to bind data prior to the execution of an RFC. Still, no action will be taken until you issue the query("EXECUTE") function. It does not matter which client DSO issues this call, but it should be the first in the list, for example:

      agcData1.query ("EXECUTE"); // Executes the RFC 
    agcData2.query (null); // Refreshes the rows for this DSO
    agcData3.query (null); // Refreshes the rows for this DSO

    If you have multiple AgxDatas bound to the same RFC, you just need to call query("EXECUTE") once. All the other AgcData controls may then refresh their rows by simply issuing a query(null).

    Note that you should issue only one query("EXECUTE") or the RFC will be executed again.

Deploying an SAP DSO   Top of page

To deploy an SAP DSO:

  1. Install the SAP RFC components on the target server (if not already installed).

  2. Install the SAP DataConnector on the target server (if not already installed).

  3. Publish RFCObjects.

  4. Publish DSO Objects.

  5. Publish any calling forms or pages.

Be aware that the published objects will reference the SAPSrv.jar that exists in the SilverMaster database. If SilverMaster is named differently where you publish to, then each of the RFCObjects and dependent DSOs will need to be modified to reference the correct SilverMaster; otherwise they will not compile.

SilverJRunner, Web pages, and applets require no software installation.

Copyright © 2000, SilverStream Software, Inc. All rights reserved.