Expanding the Reach of Your SAP Business Processes

By Ulrich Homann, Dan Rogers, and Peter Russo

 

Company wide use of SAP business functionality might include employee self-service, such as employee expense management and internal procurement. Although the idea of applying one set of SAP business rules to each individual person and process – across a wide variety of tools and infrastructure - inside the enterprise as well as to the business relationships with customers and partners is appealing, it is a difficult goal to achieve in a cost-effective and reusable way.

 

SAP has recognized the need for a reusable and standardized way to extend and embrace the SAP business processes outside of the R/3 framework, and it has delivered the SAP Business Framework (see http://www.sap.com/bfw) as the way to achieve this goal.

 

A critical part of the business framework is its seamless integration into standard infrastructures that customers have already deployed. For native integration on the Microsoft Windows platform, SAP delivers the SAP DCOM Connector (DCOMCC) - an extension to the Remote Function Call Software Development Kit (RFC SDK). Through the exposure as COM components, the business framework integrates easily into the Microsoft Office, Development Tools, and BackOffice systems.

 

The SAP DCOM Connector

The SAP DCOM Connector (connector) is the bridge between the SAP Business Framework and the Windows platform, as shown in Figure 1.

 


 


Figure 1

 

The connector has the ability to:

* Enable a Windows programmer to view SAP Business Objects and Business APIs (BAPIs) as native COM components, which behave like any other COM component available on the market. This lets all development tools (such as Microsoft Visual Studio and Inprise Delphi), personal productivity suites (such as Microsoft Office and Lotus SmartSuite), and server environments (such as Microsoft Site Server, Microsoft Exchange, and Lotus Notes) view the SAP objects as an integrated part of their environment.

* Eliminate the need to deploy a variety of infrastructure technologies to satisfy multiple SAP usage scenarios by providing a single, secure extension to the Windows platform. This infrastructure is tightly integrated into standard components of Windows, enabling any trained administrator to deploy and maintain the integration into SAP R/3 or SAP R/2 (version 5.0D or up).

* Integrate RFC tables and structures with the standard Windows data access technology OLEDB/ADO.

* Integrate into the security on Windows and allow for advanced scenarios, such as two-phase commit or asynchronous COM integration with Windows 2000.

 

The combination of SAP business objects exposed as COM components and the resulting tight SAP integration into the Windows infrastructure lets Windows programmers integrate R/3 into every aspect of an enterprise. As a developer, you don’t have to use the predefined SAP user interfaces or communication styles in your solutions; you are free to use your preferred tools together with SAP business functionality. Likewise, you can create solutions that access multiple systems — R/3, R/2, CICS/IMS applications, or custom-developed components — without introducing new infrastructure or programming environments. COM lets you maintain your focus on solutions, rather than on technology or infrastructure.

 

Connector Installation and Components

The SAP DCOM Component Connector (DCOMCC) ships as part of the SAP RFC SDK on the R/3 4.5a presentation CD and is available for download via SAPNET. If you are installing from the presentation CD, the SAPSETUP for the SAPGUI provides an option that will install the entire RFC SDK and will create the \rfcsdk subdirectory locally. The ..\rfcsdk\ccwww subdirectory contains a set of HTML pages that provide for the installation, documentation, configuration, and monitoring of the DCOMCC. The DCOMCC home page (default.htm) is the reference point for all this functionality (see Figure 2). You may want to create a shortcut to this homepage for fast reference.

 


 


Figure 2

 

To install the connector, you can follow the installation link from the DCOMCC homepage or go directly to ..\rfcsdk\ccwww\ccwizard.htm. All the pieces required for administration, configuration, monitoring, and building the R/3 proxy business objects are installed by default. The installation page does not currently support installing a subset of the components or advanced component configurations such as specialized security settings. You must carry out these tasks manually, and we will discuss how later in this article.

 

Connector installation requirements include: 

* WinNT 4 (SP3 or greater), Win95 or Win98

* Microsoft Data Access Components (MDAC) 1.5 or greater, available in IE 4.01, or NT SP3/4.

* MTS 2.0, available via the NT Option Pack

* Windows Scripting Host, via the NT Option Pack.

* IE 4.01 (required for the execution of the connector administration and monitoring html pages)

* Internet Information Server (IIS) or  personal Web server (required for Connector Wizard to automatically install connector components).

* Visual C++ 5.0 (SP 2) or Visual C++ 6.0, if you are going to use the Connector Wizard (also referred to as the Object Builder) to automatically generate and install Connector Business Objects.

 

When you install the connector using the connector installation page, a DLL that implements the connector’s RFC functions (librfc32.dll) goes into the %windir%/system32 subdirectory, and two DCOM Connector packages (SAP R/3 DCOM Connector and SAP R/3 DCOM Connector Samples) go into the computer’s MTS instance. Let’s examine these packages.

 

Start by invoking the Transaction Server Explorer. (If you installed MTS from the NT Option Pack, select Start à Programs à Windows NT 4.0 Option Pack à Microsoft Transaction Server à Transaction Server Explorer.) Drill down through Computers à My Computer à Packages Installed. You should see the two connector packages (see Figure 3).

 


 


Figure 3

 

The SAP R/3 DCOM Connector package contains a suite of components used for administering and configuring the connector as well as the components the Object Builder uses to construct the proxy objects for the R/3 business objects and functions. Drill down into the package and inspect the installed components (see Figure 4).

 


 


 Figure 4

 

Right click on any of these components; select Properties and examine the information under each of the tabs (General, Transaction and Security). You will notice that the ship vehicle for all of these components is the CCAdmin DLL. This DLL can be found in the \rfcsdk\ccpak subdirectory. Note that none of the components requires a transaction, and they all have authorization checking enabled. This means that, before executing, each component will check the credentials of the caller. Defining MTS roles and assigning users to these roles configures this authentication. Roles can be defined at the package, component, or interface level, depending upon the granularity of security required.

 

With the initial installation of the connector, a default administrator role is created for the SAP R/3 DCOM Connector package and all its components. The connector wizard will map all the users from the computer’s administrator group into this user group (see Figure 5). This configuration is not recommended for deployment. It is, however, a configuration that will guarantee that all the connector components will install and function correctly when initially run. We will discuss at greater length suggested ways to modify this default configuration to allow more specific control during deployment.

 


 


Figure 5

 

The other installed package, the SAP R/3 DCOM Connector Samples, contains four Connector Business Object components that illustrate some of the functionality of the DCOMCC. RFCSample is a hand-coded component that presents a proxy interface to a BAPI and to a standard exported R/3 function. The roll your own component link on the DCOMCC homepage provides documentation on how to hand code a component. The other components in the sample were generated using the connector wizard (Object Builder). Sample client applications that are written against these components can be found in the ..\rfcsdk\ccsamp subdirectory. All these components will successfully execute against any R/3 instance running the IDES 800 client at release level 3.1H or greater. The ccsamp subdirectory provides scripting, Visual Basic, and C++ client samples. You can also invoke a scripting sample by following the samples link on the connector home page.

 

Connector Administration and Monitoring

After you install the connector, the first step is to create destinations, which define a set of parameters required to connect to an R/3 system. Whenever you wish to invoke a method on the Connector Business Object component that does some work on an R/3 system, you must supply the requisite destination information. This can be done  in a number of different ways:

* Each Connector Business Object inherits the ISAPConnector interface. This interface exposes a set of methods that let you manually set any or all destination parameters. Using this option, the client program creates the Connector Business Object and then explicitly sets each of the destination parameter values.

* The DCOMCC admin components provide a mechanism to define a destination by name and to associate the destination parameter values with this name. The destination name and values are stored in the local registry in an encrypted format. Using this option, the client program creates the Connector Business Object and sets the destination by simply supplying the destination name.

* You can store a default-named destination with a Connector Business Object when it is generated by the connector wizard. If the client program creates the object and does not specify a destination, then the default destination will be used.

 

To create or modify a local named destination, select the destination tab on the DCOMCC homepage, which lists all currently defined destinations (see Figure 6).

 


 


Figure 6

 

To edit or create a new destination, select the Edit link. You can then specify the type of system you are accessing (R/2 or R/3), the server group or specific application server, system number, client, and language. Depending on the use of the destination as well as the security requirements, you can also specify a user and password. If you don’t, you will have to specify these when invoking a component. On systems configured for single sign-on (specifically, where the SAP user ID has been mapped to the NT user SID), it is possible to configure the connector to use NT user credentials for accessing R/3. In this case no user or password information need be specified.

 

Additionally, there are three optional parameters that you can specify for the destination:

* You can set Pooling of R/3 context, which lets a 3.x system reuse RFC connections that share the same destination. When this is set, the resource dispenser for the RFC connections suppresses the call to delete the user context on the R/3 instance, which saves the time usually needed for deleting and initializing a new context. You should only set this if the R/3 BAPIs or functions called are stateless. It need not be set for 4.x systems.

* You can set the trace option for debugging, which generates a trace file for each RFC connection thread. If the Connector Business Objects are sending or retrieving large amounts of data, these trace files can grow very large. They also slow down the overall performance of the connector. To specify the directory for the trace file, choose Monitor à Parameters à Working Directory from the connector home page.

* You should set the debugging option to enable the ABAP debugger. This option only works if the SAPGUI is installed locally and if the client program calls the AdviseRFCGuiSink method on the Connector Business Object.

 

Once you have defined and saved destinations, the detail link provides information about the R/3 instance. Because it connects to the R/3 instance to retrieve the information, it is a good preliminary way to test the completeness and accuracy of the destination information (see Figure 7).


 


Figure 7

 

When you retrieve this information from the R/3 instance, you also exercise the base functionality of the DCOMCC. A connector object is created and a method invocation made. An RFC connection resource is requested from the connection pool for the specified destination. If no connection resources are available, a new connection resource is created and assigned to the requesting object. Information about connection resources, their state (whether they are active or in the pool), the host R/3 server, and so on can be seen via the monitor page. If you successfully retrieve the detail information for a destination and then immediately view the monitor page (see Figure 8), you will see detailed information about the connection used. You will also find that the connection has already been returned to the pool. The connection will stay in the pool until the maximum connection lifetime has been reached. The default is 200 seconds. You can change the default via Monitor à Parameters àMax time to keep resources in Pool. This connection information will correspond to the RFC connection information that is visible from within R/3 by executing transaction SMGW.

 


 


Figure 8

Programming with the SAP DCOM Connector

 

Connecting your Windows application to SAP business functionality is a three-step process. The first step is to generate a COM component that encapsulates the SAP business logic you would like to expose in a standard COM fashion and enables the communication with the SAP R/3 application system. Once you have generated and installed the component (see Generating and Installing DCOM Objects for details) or follow the Working with the DCOM Object Builder section later in this document, the next two steps involve the writing of application code that uses the COM component. Writing this code to act in the desired fashion requires knowledge about the underlying principles and dependencies of the SAP DCOM Connector (DCOMCC) and SAP R/3. Furthermore it is strongly advised to acquire knowledge about the building blocks intrinsically used by the DCOMCC. Specifically the sections within the Microsoft Developer Network or on the general Microsoft website about COM (which includes information about Windows Component Services [MTS in Windows NT 4.0 and Windows 9x, COM+ with Windows 2000]) and Microsoft Data Access (specifically ADO/OLEDB and RDS – remote data services) are essential to the understanding of the DCOMCC – out of scope however, for this article.

Programming considerations for the DCOMCC

 

Serving potentially hundreds or more users simultaneously within a well-defined set of resources – the computer, SAP components are running on - requires thought with respect to resource management (memory, RFC connections, etc.), life-cycle of components and the business processes involved. The goal of the DCOMCC is to minimize the impact of client requests on precious resources within both the COM system and the R/3. The longer a specific client holds on to resources within COM and within the R/3 system, the lower the number of users that can be served with the given resources. Therefore the DCOMCC – in concert with Windows component services – is exposing one key concept: state management (method invocations are either stateful or stateless).

 

State is knowledge of a service provider (in this case the COM component [and all involved Windows services like MTS and R/3) about a specific consumer – typically expressed through the execution of multiple method calls on data (variables, etc.) stored inside some system context prior to persisting changes. This requires the service provider to keep resources locked for the specific consumer – in R/3 this is handled via the user context, within MTS this is handled inside the package process – thus reducing the number of clients serviceable by this system. In an optimal world all processing would be “stateless”, allowing the service provider to “forget” about the consumer immediately after the request and thus freeing resources for other consumers. The best example for a stateless environment is a HTTP server serving static web pages – once the HTTP GET request for a specific page has been satisfied the HTTP server will close the connection and will not remember anything about the consumer requesting this page – even if the same user would return and perform another request.

 

In the real world, however, stateless programming is only achievable in rare scenarios. Therefore session management is introduced as a “hint” to the involved execution systems (Windows Component Services and SAP R/3) about the status of the execution. Session management on the SAP side is primarily focused at pooling of R/3 user contexts. Session management on the COM side involves pooling of RFC connections and the life cycle of the COM components and their associated resources.

 

State can be expressed in two places: the SAP COM component itself and in the usage (method call sequence forced by the business process) of the component(s). In both scenarios the DCOMCC provides facilities to express the status of execution – which with the R/3 system will result into committing or aborting a transaction, cleaning/pooling of user contexts and within the COM system will result into resource re-usage.

 

Designing the SAP COM Component (inside R/3):

 

If the SAP BAPI is stateless (all SAP R/3 3.x BAPIS are stateless), the DCOMCC can create and destroy the SAP user context (the session within R/3 along with allocated shared memory that kept information about the user and his/her user rights), trusting that all work done on behalf of the user has been persisted in the underlying R/3 database. In this case, the DCOMCC can also allow clients with identical destination configurations (see Maintaining Destinations for more details) to reuse the RFC connection (i.e., to share the same R/3 user context) a.k.a. RFC connection pooling.

 

NOTE: The default behavior of the connector is to assume that method invocation is stateful, which implies that no connection pooling takes place.

 

In the first version of the connector (before the new concept of KeepSAPContext property was exposed in the ISAPConnector interface) RFC connection pooling required a two-step process. First, if the R/3 system being accessed was < version 4.x, then the destination had to be set with an optional property enabled: Enable R/3Pooling, which resulted in a synchronous destroying/re-creating of the SAP user context with every method call. With R/3 4.x systems, an asynchronous thread is created that cleans up the user context in the background. It is not necessary to set the Enable R/3 Pooling property.

Secondly, the C++ object method implementation code that was generated by the object builder had to be augmented. This was accomplished by manually altering the C++ code by adding a MTS API call: SetComplete() to the end of each method that accessed R/3 resources. This reset the connection at the end of the method call and enabled resource pooling. However, the SetComplete() also destroyed the business object and its MTS state – specifically the destination and BAPI key initialization data. This was very confusing to the client programmer who saw his object disappear without him explicitly destroying it. In many pooling scenarios, the programmer wants the benefit of RFC connection pooling, without having the object and its properties (destination and BAPI initialization values) automatically destroyed.

 

Version 4.6A of the DCOMCC addresses this problem – while still enabling connection pooling with the KeepSAPContext property added to the ISAPConnector interface. The DCOM CC version 4.6A (release APR-1999) designates stateless method invocation via setting the KeepSAPContext property to FALSE on either the business object itself or on the (later described) session object. Setting the property on both objects is not possible.

 

Using the SAP COM Component (within your COM development environment:

 

Stateless usage is straightforward and (other than setting KeepSAP Context to False) no special work of the client programmer is required – see examples later. For stateful programming (i.e., the execution of multiple method calls on data stored in a user context prior to committing the data), the user of the component has to determine (a) which method invocations require a shared context and (b) when in the sequence of method invocations to explicitly call CommitWork().

 

The DCOMCC version 4.5A only provided for the explicit commit via the CommitWork() function implemented within the ISAPConnector interface. There was no possibility to explicitly indicate to the runtime systems the intent to build up state. All state management is was implicit and per business object.

 

The DCOMCC version 4.6A allows for explicit state management within one business object and across multiple object instances forming a joint execution context. The connector introduces the SAP Session Object, which inherits from the ISAPConnector interface. The session object works something like an MTS activity (see MSDN Library -> Platform SDK -> Component Services -> Microsoft Transaction Server 2.0 Service Pack 1 -> Microsoft Transaction Server Programmer’s Guide -> MTS Overview and concepts -> MTS programming concepts -> MTS Clients -> Activities for more details) in that it is used to ‘collect’ the work of multiple business objects. Properties that are set at the Session level (such as Destination and KeepSAPContext) automatically extend (MTS refers to this as the flow) to all the objects created within the session. Again, the programmer has to understand the design of the SAP business process and at component generation time request a session object (the session interface is compiled into the business object via an optional setting in the Object Builder). All business object instantiation has to be done through the newly created session object – new and CreateObject() directly on a business object will result in a new and separate RFC connection. The session object is only required for the “root” of the object tree – all other business objects do not require a session object.Examples:

 

1)     Single object, single stateless method invocation:

 

Dim foo as new SAPBusObj

foo.Destination = ”MYDEST” ‘or explicitly set login properties

foo.KeepSAPContext = FALSE ‘it defaults to TRUE

 

… some parameter work

 

foo.MyMethod1 ….                 ‘ connection is pooled

 

 

… post processing

 

set foo = Nothing

 

2)     Single object, multiple stateless method invocations

 

Dim foo as new SAPBusObj

foo.Destination = ”MYDEST”

foo.KeepSAPContext = FALSE

 

… some parameter work

 

foo.MyMethod1 ….           ‘get a connection

                     ‘pool the connection

 

… post processing

 

foo.MyMethod2        ‘get another connection that meets the destination requirements

                     ‘pool the connection

 

… post processing

set foo = Nothing

 

 

3)     Single object, stateful method invocations

 

Dim foo as new SAPBusObj

foo.Destination = ”MYDEST”

foo.KeepSAPContext = TRUE

 

… some parameter work

 

foo.MyMethod1 ….           ‘get a connection

                     ‘keep the connection with the client

 

… post processing

 

foo.MyMethod2        ‘get another connection that meets the destination requirements

                     ‘keep the connection with the client

 

foo.CommitWork       ‘Commit the user context

                     ‘Pool the connection

set foo = Nothing

 

4)     Multiple objects, stateful method invocations

 

Dim blip as new SessionObject

Dim foo as SAPBusObj

Set foo = blip.CreateInstance(”SAPBusObj1”)        ‘need the prog ID here

blip.Destination = ”MYDEST”

blip.KeepSAPContext = TRUE

 

… some parameter work

 

foo.MyMethod1 ….           ‘get a connection

                     ‘keep the connection with the client

 

… post processing

 

Set bar = blip.CreateInstance(“SAPBusObj2”)        ‘need the prog ID here

 

bar.MyMethod2        ‘re-use the same connection and keep the connection with the client

 

blip.CommitWork            ‘Commit the user context

                     ‘Pool the connection

set foo = Nothing

set bar = Nothing

set blip = Nothing

 

 

Working with the DCOM Object Builder

 

Let’s look at the steps a typical Microsoft Visual Basic programmer would go through to interact with SAP. There are two steps: generating the DCOM Connector component using the wizard and writing a Visual Basic program that manipulates that component.

 

Creating a Business Object with the Connector Wizard

Let’s start our programming lesson by creating a component that can add, view, or update sales orders. A sales order component manipulates sales order documents as defined by SAP. A sales order document component would be useful, for example, when a business wants to be able to take orders electronically via the Internet or send information about unfilled orders to a manufacturing execution system.

 

Using the configuration we described previously, the first step is to click on the wizard button on the navigator bar found at the top of the default.htm Web page. This brings the R/3 COM Connector Wizard (Object Builder) up in your Internet Explorer. Note that the wizard uses ActiveX controls and ActiveX scripting; if you are prompted to allow ActiveX controls or scripts to run, always answer “yes.”

 

To generate our sales order component, we need to fill in information about the connection, provide the component’s project and MTS package information, and then locate and add the sales order BAPI to the component. Once you have done this, the wizard will generate the Visual C++ source code for your component, compile it, and then install it in the MTS environment.

 

Connecting to the R/3 System. Specifying the connection information that your component will use is easy. Using the drop-down list the wizard provides, select the destination profile. In this section we will assume that you have created a destination named ‘Bizapps’ that defines all the parameters required to connect to client 800 in an R/3 IDES system. Select the Bizapps destination.. This populates the connection information with the stored values and lets you connect to SAP by clicking on the connect button. After you click this button, the wizard connects to the R/3 instance. The component you generate will use this destination profile as its default destination name.

 

The next step is to fill in parameters about the component project. The project information controls the C++ compiler. Specify a directory location and file name for the project “make file.” A browse button displays the standard file dialog. For simplicity, create a new directory and call the project “Article.”

 

Next, fill in the NameSpace field, which formalizes the naming of DLL files. It provides four positions (blanks not allowed) that are used as name prefixes for the generated component. The recommended approach to NameSpace is to assign a four-letter abbreviation for the company name (for example, Microsoft might use MSFT), enabling two different companies to ship similar COM components and letting the components coexist on the same server. The name space value for our sample is DEMO.

 

Finally, choose an MTS package in which to install the generated component. A simple drop-down list lets you choose from existing MTS packages. For simplicity, think of the MTS package as a concept that lets the application architect define an application region in which all related components will execute in a single process space. When we installed the RFC SDK, a package — SAP R/3 DCOM Connector Samples — was automatically created for us. Choose this one for now. Unlike the default connection information, the package you select for testing has no bearing on your deployment environment.

 

Selecting the Sales Order BAPI. Establishing a connection to the R/3 instance populates the list of available BAPI calls. This is categorized by SAP business area and displayed in a standard tree-view control. This control lets you expand and collapse related information so you can display more or less information on a given topic as desired. To generate our sales order component, we’ll scroll down in the business objects list until we see the SAP module named Sales and Distribution. When we expand that branch of the tree view, we see that one of the objects listed is Sales Order. To generate a component that exposes a DCOM Connector interface for Sales Order, highlight that choice in the list and click the button labeled add, which adds the Sales Order BAPI to our COM object. You can add as many or as few BAPI and RFC interfaces to your DCOM Connector component as you wish.

 

Compiling the component. With the Sales Order BAPI selected into the COM objects list for this wizard project, all you need to do to generate the compiled component is scroll down until the button Generate Component DLL is visible. Clicking this button throws the generator into action. This step completes with a fully compiled DCOM Connector component. The code generation and compilation step is complete when a button labeled Install Components in MTS appears. Clicking this button adds the new component to our MTS test package. We can then open the MTS explorer, navigate to the sample component package, and see our new ActiveX MTS component named DEMO.SalesOrder.1 in a DLL named Article.DLL

 

This component follows COM naming conventions for versioned components. The “1” at the end indicates version one. Had this component been generated previously — perhaps you were adding functionality to the component — the wizard would have asked you whether you wanted to generate a new version of the component. In that case, the number at the end would have been increased, and the previous version left untouched.

 

Using the Generated Component in Your Programs

Now that you’ve successfully generated a new DCOMCC Business Object for the R/3 Sales Order BAPI, let's first consider some general COM and MTS programming techniques as well as some specific techniques proper to the DCOMCC Business Objects.. Then we’ll look at the code a Visual Basic programmer would need to write to create and save a new sales order in SAP.

 

When programming with DCOM Connector components, it’s a good idea to be familiar with MTS programming conventions. MTS adds value to a programming model by taking care of such details as memory management, database connection pooling, thread pools, and two-phase commit transactions. With SAP RFC calls, MTS also provides RFC connection pooling. The calling programmer should be aware of several other conventions (such as argument passing) and understand the basic architectural assumptions imposed by the DCOM Connector model itself.

 

DCOM Connector component programming model assumptions. Every DCOM Connector component the wizard generates exposes a common set of object methods, including InitKeys, DimAs, PutSessionInfo, AdviceRfcGuiSink, and CommitWork. Standard key fields that represent a specific document are also exposed. The key fields let you get or set information about a specific business document. For our sales order example, you may decide to update or get the status of an existing order. To do this, you would use the component’s InitKeys method on your sales order component, passing a unique order ID as a named parameter.

 

Common COM Connector methods. The InitKeys method common to all DCOM Connector components lets you pull up a specific document. In our sales order example, we could use the InitKeys method to get details about an order. Although the InitKeys method is common to every SAP document component, the parameters required (such as the order ID field) are different. However, because every key field set is passed as an ADO RecordSet, the steps required to make the program work properly are identical across all DCOM Connector components.

 

The PutSessionInfo lets you pass connection information to the DCOM Connector component. Using this call, the calling program can override the default connection information preprogrammed into the component. This method call doesn’t use RecordSets — most likely because there are only a few parameters. Individual parameters are overridden by calling PutSessionInfo with named arguments. For instance, you can override any of the UserID, Password, Language, and Client parameters as well as specify a server-specific value for the Destination parameter. The latter lets you use the same component on multiple servers, whereas specific named destination profiles are server dependent.

 

The DimAs method, provided in each wizard-generated DCOMCC Business Object , simplifies the programming involved in creating the empty, disconnected ADO RecordSets required to pass or retrieve data from document-specific method calls. In general, creating disconnected RecordSets is beyond most programmers’ experience. The DimAs method serves as a kind of RecordSet factory that is guaranteed to always give back the RecordSet with the appropriate shape. RecordSets are tabular and provide a strongly typed data interface that includes field name, data type, and field length restrictions. Each DCOMCC Business Object method call that accepts or provides data requires a RecordSet with a specific shape. We’ll see an example of the DimAs method as we examine the code required for saving an order.

 

The CommitWork method does what the name implies: It orders R/3 to commit changes to its database and calls MTS’ SetComplete. Normally, 3.1x BAPI commits within the BAPI call itself.  Thus Supporting the MTS stateless programming model.  Some 4.xx BAPI however requires an extra BAPI_COMMIT_WORK call to commit the changes.  This stateful programming model allows more complex transaction but requires the extra round trip to R/3.  On 3.1x Systems, the main usage of the CommitWork method is to allow pooling of the RFC connection, increasing scalability. On 4.xx system, it additionally commits the R/3 transaction.  If CommitWork is not called, the changes are not committed and the resource acquired by the SAP user context are kept until the object is released. If you are familiar with MTS, you might wonder whether DCOMCC Business Object support MTS transactions. The answer is no, they do not. Although a compensating resource manager is planned, the RFC protocol isn’t currently adequate to support the two-phase commit protocol needed for the MTS transaction and rollback.

 

You use the AdviceRFCGuiSink method to debug calls to the underlying BAPI by invoking the SAPGUI as an ABAP-debugger. This method returns a callback reference that can then be “attached” to the SAPGUI; however, this approach is not normally needed and beyond the scope of this article.

 

Argument passing. Many SAP business documents consist of more than one section. The DCOMCC Business Object’s  RecordSet argument interface provides each section (for input as well as output). When the underlying document requires multiple RecordSets, you’ll find the methods that manipulate the document accept multiple named arguments of type RecordSet. These can be seen using any capable object browser, as well as via the Visual Basic development programming environment itself. The SAP documentation for Business Objects (available online at http://www.sap-ag.de/products/techno/ à  Open BAPI Network à BAPI Section) describes each method and argument, and indicates whether an argument is mandatory or optional.

 

Because so many DCOMCC Business Object method arguments are optional and subsequent versions of R/3 may define new method arguments for existing BAPI calls, a good rule of thumb is to pass arguments using named parameter syntax. Instead of assuming knowledge about the order in which parameters appear, write programs that pass arguments in the form parmName:=value.

 

Placing an order. Let’s look at some code. The first thing we need to do is declare an object reference that will be used to access our DCOMCC Business Object. Then we’ll need to declare and prepare the RecordSets that we’ll use to pass data. Finally, we’ll populate those RecordSets, pass the order to R/3, and examine the return code to see if the request succeeded (see Listing 1).

 

Dim Order As new DEMOSalesOrder

Dim HeaderIn As RecordSet

Dim ItemsIn As RecordSet

Dim Partners As RecordSet

Dim BapiReturn As RecordSet

 

Order.DimAs(“BapiCreateFromDat1”, “OrderPartners”, Partners)

Order.DimAs(“BapiCreateFromDat1”, “OrderHeaderIn”, HeaderIn)

Order.DimAs(“BapiCreateFromDat1”, “OrderItemsIn”, ItemsIn)

 

HeaderIn.AddNew

HeaderIn.Fields!DOC_TYPE = "TA"

HeaderIn.Fields!SALES_ORG = "1000"

HeaderIn.Fields!DISTR_CHAN = "10"

HeaderIn.Fields!DIVISION = "00"

HeaderIn.Fields!PURCH_NO = ”XYZ0000123”

HeaderIn.Fields!INCOTERMS1 = ”CPT”

HeaderIn.Fields!INCOTERMS2 = ”New York”

HeaderIn.Fields!PMNTTRMS = “ZB01”

HeaderIn.Update

 

ItemsIn.AddNew

ItemsIn.Fields!MATERIAL = ”R-1001”

ItemsIn.Fields!PLANT = ”1000”

ItemsIn.Fields!REQ_QTY = “1”

ItemsIn.Update

 

Partners.AddNew

Partners.Fields!PARTN_ROLE = "AG" ' means sold-to-party

Partners.Fields!PARTN_NUMB = “0000001177”

Partners.Update

 

Order.BapiCreateFromDat1(OrderHeaderIn:=HeaderIn, _

OrderItemsIn:=ItemsIn, _

OrderPartners:=Partners, _

Return:=BapiReturn)

 

BapiReturn.MoveFirst

If BapiReturn.Fields(“type) = “”

Or BapiReturn.Fields(“Type”) = “S” Then

OrderNumber = objSAPConnector.KeySalesDocument

Else

      Debug.Print "Bapi Returns: type " & BapiReturn.Fields("TYPE")

      Debug.Print " Code " & BapiReturn.Fields("CODE")

      Debug.Print "Message." & BapiReturn.Fields("MESSAGE")

      Debug.Print "LogNo..." & BapiReturn.Fields("LOG_NO")

      Debug.Print "LogMsgNo" & BapiReturn.Fields("LOG_MSG_NO")

End If

 

Listing 1. Programming DCOMCC Objects with Visual Basic

 

The DimAs method prepares the RecordSet variables for use with the specific BAPI parameter. To get back a specific RecordSet, you tell DimAs the name of the method you intend to call and the name of the parameter that you want the RecordSet for, and pass a pointer to the variable you want to populate with the RecordSet.

 

Next, we populate the values that these RecordSets hold. Because they are RecordSets, we use the methods that the ADO RecordSet libraries provide to add a new record and then populate the individual fields. We repeat these steps for the Order Header, the Order Line Items, and the Partners parameters. SAP defines the field names. The values being set in the example are sample data. Your program would most likely get many of these values from another program or a database as a result of a look-up operation before saving the order. Here we order one item product “R-1001” from plant “1000.”

 

We identify the R/3 customer number by using the OrderPartners record. You have to know how SAP sales order documents are structured in order to interface via the DCOM Connector component. In many order systems, customer information appears in the order header. However, this is not the case with SAP, which provides capabilities for attaching multiple customers to one order.

 

In the BapiCreateFromOrder line, we make the call that saves the order into SAP. Until this point, we’ve only used the DimAs function to create RecordSets for passing information back to the component. From an MTS perspective, that component is inactive, and has no state. The RecordSet objects that are holding our order data are still under the control of the calling program; no references are held on the server.

 

Error handling

Three kinds of errors can occur when you call a DCOM Connector component. First, RFC protocol errors can happen between the component and R/3. Second, errors occurring in programs that run in R/3 can cause exceptions to be thrown in the component. Third, errors can occur within the generated component, generally a result of passing bad arguments or invalid values.

 

You can detect the first two error types directly from within Visual Basic. When these types of errors occur, the component will raise an exception and the standard Visual Basic error information will be populated. For this reason, your code should exercise proper error handling.

 

The third kind of error causes the BapiReturn parameter to be populated with error information. In our sales order example, if you tried to save an order using a customer number unknown to R/3, the order would not be saved, and information about the reason for the failure would be returned in the BapiReturn variable. Handling these types of errors requires that you check the return information after each BAPI call.

 

In our example , we look at the first record in the BAPIReturn RecordSet and see if the field named type contains an empty string or the letter S. Either of these markers indicates success by the connector component. Upon successful return, the object property KeySalesDocument contains the order number for the new order. At this point, the object is preserving information about the order on the server. This information is maintained on the server until the calling program releases the reference to the object.

 

As you can see, the amount of code you need to write a program that connects to R/3 is quite small and requires no skills beyond those of professional Visual Basic programmers. Now let’s take a look at the deployment and support of the SAP DCOM Component Connector in a typical IT organization.

 

Connector Installation and Administration for a Typical Multi-Instance Environment

The default connector installation  might be appropriate for the lone developer playing with the DCOMCC against a sandbox R/3 instance. However, it would not be appropriate for a typical R/3 installation consisting of a development, test, and productive instance. In these situations, we need more explicit control over the creation and deployment of the connector business components and, more importantly, over the connector administration and monitoring components. IT organizations preparing to use the connector must first decide what the MTS/SAP Connector instances’ topology will look like; then they must define the processes for creating Connector Business Objects, installing them in packages on MTS/ SAP Connector instances, and monitoring their performance within this topology.

 

Let’s consider the following deployment scenario in a sample company: The IT organization for this company supports a 3.1I R/3 installation consisting of a development, test, and productive instance. It is starting to deploy the connector and has decided to build three NT 4 servers, which will host MTS and the SAP Connector for each of these instances

Each of these machines has a correct NT 4 (SP4), IE 4.01, MTS 2.0 (installed via the NT 4 Options pack), and MDAC 2.0 (installed via the NT SP4 Y2K setup) installation. The development machine has a full RFC SDK and connector (including the package exports) installation. The test and production machines have a partial installation of the RFC SDK accomplished by copying a select part of the RFCSDK directory tree from the development server, which you can accomplish as follows:

1. Copy ..\rfcsdk\ccwww\*.* to <server>\rfcsdk\ccwww\

2. Copy ..\rfcsdk\lib\librfc32.dll to <server>\winnt\system32\

3. At a command prompt on <server> execute: regsvr32 <server>\winnt\system32\librfc32.dll

4. Copy ..\rfcsdk\ccpak\*.* to <server>\rfcsdk\ccpak\

 

Before discussing the installation of the connector packages on the test and production servers, we need to say a few words about MTS security. There are two facets to MTS package security:

·         First, there is package identity security. A MTS package must run under a specific NT account or under the credentials of the logged-on user. This determines the privileges of the package itself. Identity security is set when the package is first created; you can change it via the Properties à Identity on the package within the MTS Explorer.

·         Second, there is package/component/interface authentication via roles and assigned users. If authentication has been enabled for the package, this mechanism controls which external users are able to access and execute the functionality of a specific package. You can set controls at the package, component, or interface level depending on the required granularity of control.

 

For identity-level security, the IT group in our example company has decided to create a local user account on each of the DCOMCC servers for the Connector Business Object packages and an NT domain user account for identity of the MTS System package and the DCOMCC admin package. The latter packages require domain-level access and more security rights than the Connector Business Object packages. For example, one of the functions of the MTS System package is to import and export MTS packages. The IT group defined a single external domain share for package distribution. Consequently, the identity account for the MTS System package must be a domain account, and this account must have access rights to these shares. Similarly, the DCOMCC admin package writes destination information into the local machine registry. To do so, it needs specific advanced user rights on the machine. The domain accounts must belong to their respective MTS connector server’s administrators group and must also have the following advanced user rights:

* Act as part of the operating system

* Logon as a batch job

* Logon as a service.

 

The local user accounts for the Connector Business Objects must have these following advanced user rights:

* Logon as a batch job

* Logon as a service.

 

For the package authentication security, the IT group decided on the following role classifications:

* Administrators: responsibilities include MTS configuration (including creation and maintenance of roles and users), package migration, package installation (test and production), and destination creation and maintenance

* Developers: responsibilities include component generation, package installation (development only) and package exports

* Monitors: responsibilities include executing DCOMCC monitoring functions

* Various Connector Business Object users.

 

To facilitate the assignment of users to these roles, the IT group decides to use NT domain groups, which lets them use these same group classifications for access to local shares. For example, they are able to grant the monitor group read access to the share holding the connector log files.

 

Let’s take a detailed look at the configuration of the roles for the MTS System package and the DCOMCC admin package. First, set up MTS permissions for the system package using the following steps:

1. Open transaction server explorer: Microsoft Transaction Server à My Computer à Packages Installed à System à Roles à Administrator à Users

2. Select the users folder, right-click: New à User

3. Add users to the system package administrator role based on Table 1. (Monitors and end users have read access via the MTS installed default Reader Role that grants access to everyone.)

 

Instance

System Package Administrator Role Members

Production

Administrators

Test

Administrators

Development

Administrators and Developers

 

4.        Select “.\administrators” and delete (to prevent domainwide administrators from administering the MTS server).

 

We can now walk through the steps to install and configure the DCOMCC admin package.

 

Import the DCOMCC admin package from <server>\rfcsdk\ccpak\ccpak.pak. Specify the NT domain account and password for the package identity. (The DCOMCC admin package runs under an administrative account because it modifies the registry.) Perform the following steps to import the package:

1. Open transaction server explorer: Microsoft Transaction Server à My Computer à Packages Installed.

2. Select the packages installed folder. Then right-click New à Package.

3. Select install prebuilt packages.

4. Add the DCOMCC admin package by pointing to the cc.pak file in the \rfcsdk\ccpak subdirectory.

5. Specify the appropriate NT account and password to be used as the identity for the connector package. (Do not use the interactive user default.)

6. Accept the default installation directory for the package.

 

We can now configure connector package permissions (roles and role membership) by creating the following roles and assigning the appropriate memberships (see Table 2):

 

Instance

Role

User Membership

Production

Administrator

Administrators

Production

Monitor

Monitors

Test

Administrator

Administrators

Test

Monitor

Monitors

Development

Administrator

Administrators, Developers

Development

Monitor

Monitors

 

1. Create the monitor role for the SAP R/3 DCOM Connector (DCOMCC) package: Open the Transaction Server Explorer My Computer à Packages Installed à SAP R/3 DCOM Connector à Roles à Right-Click à New à Role.

2. Assign role user membership for each role (administrator and monitor) according to the user categories in the above table. The command is: Open {Role Name} à Select Users à Right-Click à New à User.

3. Enable authorization checking for the system package. (Accept the default authentication level.) Note: This step may not be required for Connector Business Object packages that authenticate a user’s account on SAP; however, the connector admin package does require it due to destination configuration and registry change requirements. The command is: Right-click on the System Package à Properties à Security Tab à Enable Authorization Checking.

 

Configure component permissions (roles and role membership) within the DCOMCC admin package by creating the roles for each component in Table 3:

 

Instance

Component Roles

Production

Administrator, Monitor

Test

Administrator, Monitor

Development

Administrator, Monitor

 

1. Open each component and add both the administrator and the monitor to the role membership. The command is open transaction server explorer: Microsoft Transaction Server à My Computer à Packages Installed à SAP R/3 DCOM Connector à Components à {Component Name} à Select Role Membership à Right-Click à New Role.

2. For the SAP.CCREGISTRY.1 (SAP R/3 DCOM package) component only, drill down one more layer into the interfaces and add administrator to the role membership list, but do not add any other role for the interface. (This interface performs the destination configuration, which is an activity we want to restrict to administrators only.) The command is: Interfaces à ICCRegistry à Select Role Membership à Right-Click à New Role.

 

The last item we want to cover in this section deals with remotely administering and monitoring the connector. In order to facilitate the remote execution of all administration and monitoring functions via the DCOMCC homepage, you must take the following steps:

1. Install IE 4.01 to ensure that all appropriate data binding components are installed.

2. Run the client configuration executable for the connector admin package, found in the \rfcsdk\ccpak\clients subdirectory (CC.exe)

3. Copy the RFC SDK Web pages from \rfcsdk\ccwww

4. Create a link to the default.htm file (the connector homepage).

5. Launch the homepage and select Connect. Enter the name of the remote server to be administered or monitored.

 

Once you have completed this configuration, the application can perform all the DCOMCC administration and monitoring functions at one central location for all the connector instances. You are now ready to successfully deploy and administer your DCOMM Business Objects.