http://www.microsoft.com/TechNet/boes/bo/bosi/technote/bf208.htm (PC Press Internet CD, 03/1996)
| Updated: March 12, 1996 |  Go To TechNet Home Page |
David Shoemaker
300 Stevens Drive
Philadelphia, PA. 19113
Internet: david.shoemaker@sap-ag.de,
Portions of this document are excerpts from work by Dr. Martin Hofmann, of SAP AG, Walldorf, Germany, and Mr. Pong Ching, of SAP America, Foster City, CA.
Overview
Desktop Integration Dilemma
The Desktop Solution - OLE Enabled R/3
System Description
SAP and OLE 2.0
Components for Desktop Integration
Remote Function Call Interface
OLE Server Automation
OLE Client Automation
Future Directions
SAP America, a subsidiary of SAP AG, manufactures and distributes R/3, a client -server business information system. R/3 consists of three tiers, which are the database server, application server, and presentation server. The presentation server has been implemented on UNIX, OS/2, Microsoft® Windows®, Microsoft Windows NT™, and Microsoft Windows 95. SAP provides an environment where the presentation side of the system is open to integration with other desktop applications. This openness is accomplished using remote procedure calls, OLE 2.0 automation, and Open Database Connectivity ( ODBC ). This paper concentrates on the OLE and remote function call interfaces for R/3 in an attempt to demonstrate the open nature of the R/3 system.
Users of standard application packages such as R/3 want to make use of their favorite desktop tools to benefit from their full-functionality and easy-to-use data manipulation capabilities. Rather than processing text with special-purpose editors built into the standard package, customers want to use the word processor of their choice. Rather than calculating their data with less than sophisticated means, customers want to use their highly effective spreadsheet program that they would use for any other calculations.
This is the reason why standard application packages have introduced ways to transfer (resp. down- and upload) data between individual application modules and individual desktop applications on a case-by-case basis. The consequence of this approach is the introduction of a level of technological complexity that is more than difficult to master. This construction is even more complicated in client/server environments. Furthermore, down- and upload creates by nature two different data sets, one on the server and one on the client, which have to be kept synchronized to avoid consistency problems.
Therefore the current situation can best be described as a dilemma. Either you have to recode all the business rules of your standard applications, which are meant to preserve the integrity of your business data, into your desktop application, or you have to recode the comprehensive data manipulation functionality of your desktop application into your standard business application. Neither of these alternatives are achievable to a satisfactory degree.
With OLE - Object Linking and Embedding - Microsoft has introduced a common standard for application interoperability. OLE not only supports the transfer of data between applications in a consistent manner, it also enables the calling of the respective functions of the communicating applications in a well-defined way.
Using the example of telephony, OLE takes care of all the cabling, wiring, and switching between applications on the desktop. Anyone using OLE can fluently converse with any other OLE user. Additionally OLE allows the creation of new functionality by plugging together parts of existing applications at your will. For example the Unit Costing of R/3 has been combined with the calculation of Microsoft Excel spreadsheet to form a new quality business function.
A brief description of the R/3 architecture is provided here. A basic understanding of the system will help a great deal in successfully integrating with R/3.
One R/3 system always contains one database server. A typical database server for R/3 consists of an ORACLE database on an Hewlett-Packard (HP) platform. SAP software provides locking, queuing, rollback, querying, networking, and so forth. ( This is a highly simplified description of R/3. )
One or more application servers are connected to the database server. Application servers are the heart of the R/3 system. All business model programs run on application servers. The system is highly efficient because each application server caches a great deal of information from the database and manages caching intelligently. All application servers in the system have an identical copy of the system's data dictionary. This entity contains descriptions of every table, relationship, datatype, field, and so forth in the system.
All programs in the system are written in the SAP 4GL, ABAP/4. All programs reside centrally in the database. Therefore, all application servers have access to all system programs, in identical form.
One or more presentation servers attach to each application server. A presentation server is a program that resides on the client workstation. In the case of Microsoft Windows, a program called 'SAPGUI' is the presentation server. SAP maintains a 'lean' client. Presentation servers do not run ABAP/4 programs. No business logic runs in the client workstation. The presentation servers offload work from the application servers by managing screens, handling keyboard input, and providing desktop application communication. The SAP presentation server is compact enough to run well concurrently with other Win16 applications.
Business and system logic in R/3 can exist in several kinds of programs. Each has a special purpose. All of the following kinds of programs are written in ABAP/4.
A module pool is a grouping of several screen definitions, screen processing logic (DynPro), asynchronous update processing logic, global variables, and so forth whose purpose is to present one complete business model transaction to the user. If you are familiar with Structured Query Language (SQL), you probably think of transactions as groups of database updates that can be committed or rolled back. SAP uses the term transaction to encompass not just the database operations, but the entire business operation. The R/3 system is delivered with hundreds of transactions. An example of a transaction would be "Customer Down Payment Request". A workbench is provided to allow the creation of custom module pools.
Reports are programs that produce listed output. Writing reports is made easy by attaching each to a 'logical database' that contains prepackaged query logic and parameter screens. Reports can be created to be interactive.
A library of globally available functions exists in the R/3 system. Functions have the ability to activate other transactions, reports, or functions. Custom functions can always be added through the workbench. All functions have their prototypes stored within the central 'data dictionary'. This interface specification always takes the same form:
CALL FUNCTION <Function name>
EXPORTING parameter1 = ...
parameter2 = ...
IMPORTING parameter3 = ...
parameter4 = ...
TABLES table1 = ...
EXCEPTIONS...
The structure of each parameter and table needs to have a definition. This centrally located definition of the function's prototype enables the system to provide several useful services for the developer. See 'stub generation' in the Remotely Callable Function (RFC) section.
Functions and remotely callable functions appear similar in their internal structure. An RFC is essentially a function declared to be remotely callable. Externally, however, they differ considerably. An RFC can be called from another platform within a system, or another system. Most important for our discussion here is that an RFC can be called from external clients by a gateway built into each application server. The prototype of an RCF appears this way:
CALL FUNCTION <Function name>
DESTINATION <Target computer>
EXPORTING parameter1 = ...
parameter2 = ...
IMPORTING parameter3 = ...
parameter4 = ...
TABLES table1 = ...
EXCEPTIONS...
The target computer referenced above consists of the host name of another system. A table must exist on the calling platform containing routing and gateway information about the target. On an external client workstation, this table exists in a special 'SIDEINFO' file.
If another application is being integrated with R/3 by the Open Database Connectivity (ODBC) method, then SAP's software is essentially invisible. The ODBC driver for ORACLE or Informix is used to directly access database tables. However, SAP sets up the underlying database to prevent ODBC updates. This is done to secure the database. Therefore, ODBC is a read-only integration mechanism, mainly for report writing.
If OLE 2.0 or the RFC interface are to be used for integration, then the external application is going to use RCFs within the target system.
Keep in mind that a function can call any other program in the system. An RFC can be written to perform almost any conceivable task. Therefore, it is possible to define the API of the system by writing ABAP/4 functions, and then calling them. Hopefully, an existing RFC can be found beforehand that suffices for the task at hand.
External applications can make use of R/3 only if remotely callable functions exist in an R/3 system to provide the desired services. Integrators can take one of two approaches when solving a problem. They can either use existing functions provided by SAP or write their own functions.
SAP provides a robust, user-friendly workbench within R/3 that can be used to write remotely callable functions in ABAP/4. If the integrator has a working knowledge of the R/3 business model and the workbench, it is a fairly simple task to add R/3 functionality. However, SAP would like to do better in this area, and therefore the concept of the Business Application Programming Interface has been introduced.
The BAPI is an attempt to enhance the set of delivered RCF groups to the point where the entire business model is represented. In other words, an API will exist with as much functionality as is contained in the user transactions.
This is the true middleware approach. SAP's system already can exist on top of several different database engines, such as ORACLE, INFORMIX, and SYBASE. With the introduction and expansion of the BAPI, SAP will be accessible from many different front end applications. The desktop applications will not need to provide any business model logic, only presentation logic.
This paper is not intended to be a tutorial on the OLE 2.0 specification. However, a brief list of OLE 2 capabilities is listed below to show what parts of the specification SAP has implemented now and in the future.
OLE 2.0 calls for the following features:
SAP has taken advantage of the automation feature in the next release of R/3. An ABAP/4 program can manipulate the exposed objects of another desktop application, and R/3 exposes objects representing itself.
Development work is in progress to implement other features of the OLE 2 specification, in particular, structured storage. The automation feature alone provides a powerful and easy method for integrating with R/3.
Desktop integration with R/3 can be accomplished in several ways. The various components involved are summarized below.
The OLE Client function allows R/3 internal programs to manipulate objects belonging to desktop applications. R/3 programs are written in ABAP/4, SAP's fourth generation languages (4GLs). OLE Automation objects can be created and manipulated from within ABAP/4 programs.
The OLE Server function allows desktop applications to use R/3 remotely callable functions by way of an object-oriented interface. The R/3 system is represented by a set of hierarchical objects, such as 'Application' and 'Table'. This function allows Microsoft Excel 5 and WORD 6 macros to access R/3 for input and output operations.
R/3 contains a remote procedure call mechanism called RFC, or remote function call. This mechanism allows external systems to invoke R/3 internal functions. It also allows R/3 programs to remotely invoke properly written external RFC servers.
The RFC system encapsulates all of the logic necessary to perform Transmission Control Protocol/Internet Protocol (TCP/IP) communications between platforms, manages table and parameter transfer, and initiates processing. The external program is provided with a Microsoft Visual Basic® or 'C' language API.
Each of the above are described more fully in the following sections.
The basis of any integration with an R/3 system is the Remote Function Call layer. The OLE 2 Automation Objects described elsewhere in this document are really an organizing layer on top of the RFC interface. An integration consists of the desktop application calling one or more functions residing within the R/3 system.
When a desktop application uses the RFC interface, it makes calls to an API defined in a dynamic-link library (DLL) provided by SAP. The RFC functions eventually make use of another underlying layer that uses the CPI-C protocol to communicate with the SAP application server attached to the workstation. The CPI-C messages are communicated to the application server by TCP/IP. The SAP RFC interface DLL for Microsoft Windows always uses the WinSockets interface to use a TCP/IP stack in the desktop environment.
On the SAP application server side, an RFC Gateway process maintains the server side of the CPI-C connection. The gateway then uses internal mechanisms to activate the named remotely callable function.
CPI-C is the name of a standard protocol initiated by IBM that supports remote procedure calls.
It should be pointed out here that a desktop application can be constructed to act as a server to the R/3 system. Developing an RFC server requires a 'C' language implementation. A discussion of server application design is beyond the scope of this document.
The RFC interface provides several important services to the client. These services reduce considerably the effort needed to integrate with the system. They are described below.
To maintain a CPI-C conversation, several management operations are necessary, such as initiating the connection, closing the connection, and so forth. Programming against the CPI-C API can be complex, and the RFC interface layer encapsulates these details.
Frequently, the integration problem being addressed by the client involves transferring table data into or out of R/3. The system provides for efficient table transfer management as would be expected from a high-end client server system.
Upon connecting to the system, a client specifies the remotely callable function to be invoked. Part of the function's specification is the tables to be shared in the interface. The delta management function ensures that the client receives a copy of a table only once. Thereafter, only changes, or deltas, are communicated. In this way, network traffic is reduced. The system ensures that both sides of the connection always see the same table contents.
Any Microsoft Windows programmer is familiar with the 'callback function' used frequently in the Windows API. This mechanism allows a called system function to call-back to the client during execution, without terminating. The client is required to provide a callable function to service the request.
Callbacks can be used also in the RFC interface. A remotely callable function can use a system address "BACK" to gain access to the particular client platform and task location that invoked itself.
Callbacks have several uses. One example would be when the system function has no access to the user interface and needs to cause some sort of notification. The client provides a notification function for the system function to use. The system function invokes the client function during execution without returning and therefore terminating. The client retains full control of the user interface.
Another use for callbacks is to gain more information. The specified system function interface requires the usual and necessary information to execute. However, an unusual condition during the system function's execution may require more data from the client. The client can provide an exception function to be called at will from the system.
Callbacks take the following form:
Client Program ( 'C' ) RFC ( ABAP/4 )
RFCOpen
RFCCall -------------------------------------->
RFCReceive
<--------------------------------- CALL FUNCTION 'CPROG'
DESTINATION 'BACK'.
If ( RFC_RC == RFC_CALL )
{
RfcGetData
< process >
RfcSendData --------------------------------->
}
<-------------------------------------------------- ENDFUNCTION.
RfcReceive
RfcClose
The functions of the remote function call application programming interface are shown below. They are grouped into three categories. The first group contains the function API for the C language. The second group contains the extended functions for the Visual Basic language. These exist because Visual Basic does not pass structures in a way compatible with ANSI C functions. The third group consists of table handling functions.
This document is not intended as a complete programming reference for the RFC API. The functions listed below are shown in an attempt to give the reader an idea of the scope of the RFC interface. They are not described in detail.Function API:
RfcOpen RfcCall RfcInstallFunction
RfcClose RfcReceive RfcWinInstallFunction
RfcAbort RfcCallReceive RfcDispatch
RfcAccept RfcGetName RfcListen
RfcRaise
RfcConnArgv
RfcEnvironment
RfcLastError
Extended Function API:
RfcOpenExt RfcCallExt RfcAddExportParam
RfcReceiveExt RfcAddImportParam
RfcCallReceiveExt RfcAddTable
RfcGetDataExt RfcAllocParamSpace
RfcSendDataExt RfcFreeParamSpace
Table Handling Functions:
ItCreate ItGupLine ItDelete ItFree ItInsLine ItFill ItAppLine ItLeng ItDelLine
The R/3 system provides template Visual Basic and 'C' applications for any specified remotely callable function. A complete Visual Basic project can be downloaded into a workstation from the system. This project contains all of the logic necessary to logon to a system, form a connection, and call a function. A user interface containing all imports, exports, and tables named in the function's interface specification will automatically appear when the project is started. The developer then can add application-specific statements to the program.
The 'C' language is supported also. Headers are downloaded containing structure definitions for any datatypes or table rows involved in a particular function's interface. A source file containing a UNIX or DOS compatible harness program for the function is automatically provided. It can be run also in the 'QuickWin' mode. The developer is required to create a makefile, however.
In future versions of the R/3 system, a browser function will be provided to aid in searching for appropriate remotely callable functions.
The OLE Server Automation component of the SAP desktop integration system provides a way for external applications to use R/3 as a server, through OLE objects.
The R/3 system exposes a hierarchy of objects, methods, and properties for client programs to manipulate. The figure below shows the family of objects that represent R/3 to an OLE server automation client.
The SAP OLE Server consists of a server application and a communications DLL. The server automatically registers itself when any application first creates an application object. The server also starts and stops itself, as do all OLE compliant servers. The server encapsulates RFC and CPI-C management.
Certain objects created by a client can be stored for ease of use in later invocations. These persistent objects should not be confused with embedded objects. There is no data in the stored object, only connection information.
The OLE Server makes it possible for desktop applications to make use of R/3 remotely callable functions without using the RFC API. It is possible, for instance, to get a list of customers from R/3 into a Microsoft Excel 5 spreadsheet with a few Microsoft Visual Basic for Applications statements. However, as with direct RFC integration, a remotely callable function needs to exist in R/3 for the desktop application to use.
In this example, a Microsoft Excel Visual Basic, Applications Edition application is shown that will use almost all the R/3 objects and most of their properties and methods. This application retrieves employee information and budget information from the SAP System for a Sales department. It then increases every employee's bonus by 10 percent and matches department total bonus with the budget bonus. If the total bonus is less than the budget bonus, it will update this adjustment in the database. There are two ABAP/4 functions called in the application. These two ABAP/4 functions are listed as the following:
Get_Employees IMPORT Department (company-dept)
EXPORT DeptBudget (company-budget)
TABLES Employees (employees)
Update_Employees TABLES Employees (employees)
The Get_Employees function retrieves employee information and budget information for a given department. It takes an import parameter Department, an export parameter DeptBudget, and a Table parameter Employees. The Department specifies the name of a department, and its data type is defined by the company-dept. The DeptBudget specifies the department budget, and its data type is defined by the company-budget that contains three elements; bonus, equipment and travel. The Employees contains employee information about the department, and it is defined by the internal table employees as shown later in this section.
The Update_Employees function updates table(s) in the SAP System based on the updated employee information. It takes only a Table parameter Employee.
Employee Table Structure:
EmployeeID Name Title Bonus
Department Budget Structure
Bonus Equipment Travel
'Declare object variables.
Dim RFCServer as Object
Dim GetEmployees as Object
Dim UpdateEmployees as Object
Dim Employees as Object
Dim Budget as Object
Dim RFConnection as Object
Dim Functions as Object
'Create the RFC ServerObject.
set RFCServer = CreateObject("RFC.ServerObject")
'Indicate what SAP System you want to log on to.
RFCServer.Connection.Destination = "B20"
'Set the rest of Connection object values. Logon to the SAP
'System.
RFCServer.Connection.Logon
'Get the Functions collection object.
set Functions = RFCServer.Functions
'Request Function objects.The Connection object must be set up
'first before any 'Function object can be created.
set GetEmployees = Functions.Add("Get_Employees")
set UpdateEmployees = Functions.Add("Update_Employees")
'Set the export parameter.
GetEmployees.Exports("Department") = "SALES"
'Call the function
GetEmployees.call
'Get the Employee table from the GetEmployees 'Function object.
set Employees = GetEmployees.Tables("Employees")
'Get the Department Budget from the Function object. Again the
'import object still lives with the Function object.
set Budget = GetEmployees.Imports("DeptBudget")
'Get the Department Bonus Budget from Budget Structure object.
BonusBudget = Budget("Bonus")
'Set TotalBonus to be 0.
TotalBonus = 0
'Increase the bonus by 10% for each employee in the Employees
'Table object.
'Get value from the Bonus column.
'Calculate the new bonus.
'Calculate the total bonus.
For Each Person in Employees
Bonus = Employee("Bonus")
NewBonus = 1.10 * Bonus
TotalBonus = TotalBonus + NewBonus
Employee("Bonus") = NewBonus
Next Person
'Check the budgeted bonus.
'Set the Table parameter.
If TotalBonus <= BonusBudget Then
UpdateEmployees.SetTable("Employees", Employees)
UpdateEmployees.call
End If
'Quit the Application (FALSE disables the "Save?" prompt).
RFCServer.Close FALSE
The SAP Automation Server provides the SAP Automation Assistant as an online tool for external users. With the SAP Assistant, you can display remote function information, and make RFC calls online. The assistant becomes visible whenever the OLE server is not minimized.
To use the SAP Assistant, you must open a ServerObject window and add to it the functions you want to use. (The ServerObject window is a display window where you access functions and display related information.) Each time you add a function, the SAP Assistant calls up the SAP System for function information and displays it on the screen. As a development aid, the SAP Assistant lets you:
The following functions help you perform these tasks.
The OLE Automation Client function is provided in the next version of R/3. This function allows R/3 internal programs to manipulate objects in a desktop application. This capability will allow R/3 transactions ( R/3 user interface ) to seamlessly integrate other desktop applications into their logic. For example, Microsoft Excel could be brought up during a financial transaction for analysis purposes.
An ABAP/4 program in the R/3 system can manipulate objects exposed by any OLE 2 compliant desktop application. In providing this service, SAP has essentially created a distributed computing environment for OLE objects. Remember that ABAP/4 programs run on application servers. These programs are capable of using objects on any workstation platform attached to the server, that is, SAP can remotely manipulate OLE objects.
OLE Client Automation is accomplished by using SAP's presentation server as an intermediary. The application server's ABAP/4 processor transfers OLE operations to the target workstation's presentation server. The presentation server then behaves as an OLE 2 client to control the other application.
The application server that is processing the ABAP/4 OLE client program is required to communicate with a workstation's presentation server whenever an OLE operation is encountered. The SAP ABAP/4 processor has been enhanced to collect together contiguous OLE statements and send in one transmission. The transmission does not occur until the first non-OLE statement is encountered. This reduces network traffic.
The R/3 system contains a feature that allows the developer to browse the applications, objects, methods, and properties resident on a desktop. The browser database will be delivered with an initial set of the most popular applications. An automatic loading feature built into R/3 will, on demand, search a desktop environment and fill the browser database with additional application information.
Given the variations in OLE naming due to language differences, the R/3 system automatically converts object, method, and property references in an ABAP/4 program into numeric Ids before transmission to the presentation server. Therefore, the language used to code the OLE operations in the ABAP/4 program cannot effect operations in any location.
Presented below is an ABAP/4 program that performs a simple OLE 2 automation task. This program causes an instance of Microsoft Excel to become visible, and then kills it. The brevity of the program is necessary because most readers will not be familiar with ABAP/4 language syntax or structure.
REPORT NIOLETTT. INCLUDE OLE2INCL. DATA EXCEL TYPE OLE2_OBJECT. DATA BOOK TYPE OLE2_OBJECT. DATA RESULT(30). DATA FILE(50). CREATE OBJECT EXCEL 'Excel.APPLICATION'. SET PROPERTY OF EXCEL: 'Visible' = 1. CLEAR RESULT. GET PROPERTY OF EXCEL 'Visible' = RESULT. WRITE: 'Visible', RESULT. CALL METHOD OF EXCEL 'Quit'. FREE OBJECT BOOK. FREE OBJECT EXCEL.
SAP America is committed to the Microsoft Windows and Microsoft Windows NT operating systems for both presentation and as platforms for server products. Development work is proceeding on improvements in several areas to make the system more open.
Although OLE 2.0 automation has been integrated into the R/3 system, other features of OLE 2 have not. SAP would like to provide drag and drop and in-place activation capabilities in the near future.
Named arguments are not supported in Visual Basic 3.0 and they are not supported in R/3 either. The OLE Client component will be expanded to provide this capability.
Within the business information systems market, the ability to exchange mail between differing mail products is a desirable feature. SAP currently provides this capability with a configurable communications product, SAPComm. SAP would like to provide tighter integration with the MAPI API, by way of Microsoft Exchange.
Lastly, given the vast customer base of the R/3 system, and the ease of integration that will be achieved with the next version, SAP expects that many more 3rd party developers will create add-on desktop products. SAP is exploring the possibility of setting up a desktop center of expertise (DICE) in the U.S. This center would certify new 3rd party products and provide integration expertise where needed.
© 1995 Microsoft Corporation.
THESE MATERIALS ARE PROVIDED "AS-IS," FOR INFORMATIONAL
PURPOSES ONLY.
NEITHER MICROSOFT NOR ITS SUPPLIERS MAKES ANY WARRANTY, EXPRESS
OR IMPLIED WITH RESPECT TO THE CONTENT OF THESE MATERIALS OR THE
ACCURACY OF ANY INFORMATION CONTAINED HEREIN, INCLUDING, WITHOUT
LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE. BECAUSE SOME STATES/JURISDICTIONS DO
NOT ALLOW EXCLUSIONS OF IMPLIED WARRANTIES, THE ABOVE LIMITATION
MAY NOT APPLY TO YOU.
NEITHER MICROSOFT NOR ITS SUPPLIERS SHALL HAVE ANY LIABILITY FOR
ANY DAMAGES WHATSOEVER INCLUDING CONSEQUENTIAL INCIDENTAL, DIRECT,
INDIRECT, SPECIAL, AND LOSS PROFITS. BECAUSE SOME STATES/JURISDICTIONS
DO NOT ALLOW THE EXCLUSION OF CONSEQUENTIAL OR INCIDENTAL DAMAGES,
THE ABOVE LIMITATION MAY NOT APPLY TO YOU. IN ANY EVENT, MICROSOFT'S
AND ITS SUPPLIERS' ENTIRE LIABILITY IN ANY MANNER ARISING OUT
OF THESE MATERIALS, WHETHER BY TORT, CONTRACT, OR OTHERWISE SHALL
NOT EXCEED THE SUGGESTED RETAIL PRICE OF THESE MATERIALS.
 |
Click Here to Search TechNet Web Contents | TechNet CD Overview | |
Microsoft TechNet Credit Card Order Form At this time we can only support electronic orders in the US and Canada. International ordering information. |
| Go To TechNet Home Page |
©1996 Microsoft Corporation |  Go To Microsoft Home Page |