Tutorial: DCOM Clients in VB programmieren

Tutorial: Programming DCOM Clients in VB

Task

Create a simple DCOM client application as user interface for a flight booking system with R/3 data. Display details for a valid flight connection and book a flight for a given customer number. After successful booking, the system assigns a booking ID.
Execute these steps:

Use the DCOM Object Builder to generate DCOM proxies from the business objects FlightConnection, FlightBooking (and FlightCustomer) and to install them in the MTS.
Program the client application in Visual Basic:

Transfer the user and logon data for the connection to the R/3 system using a session object.
Read the flight details based on the carrier, the flight connection, and the flight date from the R/3 system. To do so, call BAPI method FlightConnection.GetDetail.
Enter additional information for a booking (for example, class).
Book a flight using BAPI method FlightBooking.CreateFromData.

Overview: Objectives

This unit shows you how to

generate DCOM proxies from R/3 business objects and a session object using the DCOM Object Builder and how to install them in the MTS.
create a simple user interface for BAPI calls in Visual Basic.
include the required controls and the generated type library into the project.
pass connection parameters to session object and logon to the R/3 system.
use a global session object and create instances for business objects.
create Recordsets using method DimAs.
call other standard methods of COM objects.
call BAPIs.

Prerequisites

Systems

R/3 system with available business objects.

Operating systems Windows NT (Service Pack 3) or Windows 95.

Installations

RFC SDK of R/3 4.5A (or higher) is available.

The MTS (Microsoft Transaction Server) is installed on the target machine (NT Option Pack).

Internet Explorer 4.01 (or higher) is installed on the target machine.

OLEDB SDK 1.5 is installed on the target machine (MS Setup).

Development environment for Visual Basic 5.0 (or higher) is installed on the client machine.

Knowledge and Authorizations

Authorization to log on to the R/3 system.

Administrator authorization on the target machine (MTS server).

Basic knowledge in Visual Basic.

Basic knowledge about object-oriented programming.

Interface definition of the BAPIs determined using, for example, the BAPI Explorer or SAP Assistant.

The respective R/3 system contains the right business data.

More Prerequisites

The client application shall be executed on the same machine as the MTS.

Note:

As an alternative, from the client machine you can access the components of the MTS remotely. Refer to the documentation for the DCOM Object Builder to find out how to configure the client machine in this case.

Exercise 1: Generate and Install DCOM Proxies

Prerequisites

The destination for the remote call was created within the DCOM Connector under Administration and Destination Management.

The system displays the initial screen of the R/3 DCOM Connector (default.htm).

Procedure

To generate and install DCOM proxies, execute the following steps:

Press Object Builder to start the user interface of the DCOM Object Builder.

Under R/3 System specify the connection parameters.

Click on Logon… to test the RFC connection.

Under COM/MTS enter the project directory and the name of the project file. Use the Browse key.

Under Namespace specify a name space identifier that deviates from the default, if required.

Assign the DLL to be generated to an MTS package. Under MTS Package select an existing package or enter a name for a new package.

Choose Session for generation of a session object and specify the name if deviates from the default.

Choose Bapi.

In the dialog window, click on R/3 Business Components.
The system displays all objects from the BOR for the selected system, for which BAPI methods are defined.

Select the components to be generated:

Choose Add ® .
The system copies the selected components into the selection screen for the generation and inserts them into the structure under COM Components.

Choose Build Component DLL to start the generation process.
The selected components are assigned to <Projectfile.DLL>.
The first generation step creates source files; the second step creates the DLL and the type library.

Note:
Before starting the generation, the system checks whether a version of the component is already registered in the MTS.
In addition, it checks whether a DLL of the same name already exists in the project directory.

Note:
If the generation fails, you can find possible causes in the LOG file Project.log or in the protocol information of the activated RFC Traces.

As soon as the generation is completed successfully, the system activates the pushbutton Install Component DLL in MTS.
Click on it to start the installation process.
The system calls the DCOM Object Builder to install the generated DLL in the specified MTS Package. As soon as the installation is completed successfully, the system displays the message Generated component(s) succesfully installed in MTS !.

Result

The installation includes entering the DCOM proxies and the session object into the Windows Registry.

Exercise 2: Include Controls and Type Library

Prerequisites

You started the IDE of Visual Basic and created a new project of type Standard EXE.

The standard controls appear in the toolbox.

The generation and installation of DCOM proxies in the MTS of a proxy server was completed successfully and the corresponding Type Library is available.

Procedure

To add new controls to your project, proceed as follows:

If no VB toolbox is displayed, choose View ® Toolbox.

To add new controls to the project, choose Project ® Components.

From the list of registered controls, select the components:
- Microsoft Windows Common Controls 5.0
- Microsoft ActiveX Data Objects Recordset 1.5 Library

If these controls are not displayed, choose Browse… to include them into the selection list.

To include the type library into your project

Choose Project ® References…
A selection list of all available references appears.

Select the appropriate type library and confirm with OK.

Result

The system automatically includes a reference to the selected control into the project file. It is included into the toolbox and can now be positioned on the form. The reference to the respective type library now provides your application with the generated proxy objects.

Exercise 3: Designing the Form

Prerequisites

An empty form sheet of the newly created project is displayed.

Procedure

Create a simple user interface for the application.

Name the form sheet frmMain and design it to correspond to the figure below. In the Properties window, assign the appropriate names to the elements on the form sheet.

Exercise 4: Define Global Declarations and Form_Load

Procedure

Under Option Explicit declare the global variables for the module level:

Option Explicit

'session object

Public oSession As Object

'connection parameters

Private sDestination As String

Private sUser As String

Private sClient As String

Private sPassword As String

Private sLanguage As String

'Define as variants

Private fldCarrID, fldConnID, fldFldate, fldClass

'Index for entries in the Combobox

Dim Index As Integer

Const APPID = "Flights Booking"

Define the initial settings in the procedure Form_Load( ) and call the procedure GetDestinations as follows:

Private Sub Form_Load()

'set initial state for "frmMain"

    frmMain.Caption = APPID

    cmdGetFlights.Enabled = False

    cmdBookFlight.Enabled = False

'call procedure "GetDestinations" for reading destinations

    GetDestinations

'creating instance for the session object

    Set oSession = CreateObject("SAP.FlightsSession.1")

End Sub

Exercise 5: Connection Parameters and Logon Procedure

Prerequisites

The destination for the remote call was created using the DCOM Connector under Administartion and Destination Management.

Procedure

Define the procedure GetDestinations, which you can use to read all destinations maintained in the DCOM Connector and to display them in the logon window:

To do this, use an instance of the object CCRegistry to access the corresponding entries in the Registry using method GetDestinations.
Select a destination as default destination to be displayed in the logon window.
Call the function InitLogonInfo, which is to be defined in the next step, with the two parameters oRegHelper, Index to display any previously maintained logon data in the logon window.

Write the following lines of coding:

Private Sub GetDestinations()

Dim oRegHelper As CCRegistry                           'reference to CCRegistry

Dim rsDestinations As Recordset

Dim rsOptions As Recordset

    Screen.MousePointer = vbHourglass                  'activate hour glass

   ' retrieve the list of available R/3 destinations

    On Error GoTo ErrHandle

    Set oRegHelper = New CCRegistry

    Set rsDestinations = oRegHelper.GetDestinations

    If Not rsDestinations Is Nothing Then

       While Not rsDestinations.EOF

         ' Add entries in the Listbox

          cbDestinations.AddItem (rsDestinations.Fields(0))

          rsDestinations.MoveNext

       Wend

      ' set the first element from List as default destination

       Index = 0

       ' call function for displaying initial Logon data

       InitLogonInfo oRegHelper, Index

    End If

    cmdGetFlights.Enabled = True                        'activate Button for next action

    Screen.MousePointer = vbDefault                    'deactivate hour glass

    Exit Sub

ErrHandle:

    Screen.MousePointer = vbDefault                    'deactivate hour glass

    MsgBox CStr(Err.Number) + vbCrLf + Err.Description

End Sub

Use function InitLogonInfo to read any preset logon data (language, client) from the Registry and display it in the logon window.

Create a local instance of object CCRegistry and call method GetOptionsAsRecord

The function to be defined has the two parameters oRegHelper of type Object and Index of type Integer.

Write the following lines of coding:

Function InitLogonInfo(oRegHelper As Object, Index As Integer)

Dim rsOptions As Recordset

    With cbDestinations

       .Text = .List(Index)

       If oRegHelper Is Nothing Then

          Set oRegHelper = New CCRegistry

       End If

       Set rsOptions = oRegHelper.GetOptionsAsRecord(.Text)

       If Not rsOptions Is Nothing Then

          rsOptions.MoveFirst

          txtClient.Text = rsOptions.Fields("Client")

          txtLanguage.Text = rsOptions.Fields("Lang")

       End If

    End With

End Function

Update the index as soon as an entry is selected from the list box.

Private Sub cbDestinations_Click()

Dim oRegHelper As CCRegistry

    Index = cbDestinations.ListIndex

   ' call function for displaying initial Logon data

    InitLogonInfo oRegHelper, Index

End Sub

Exercise 6: Call BAPI Method "GetDetail"

Prerequisites

The interface definition of method GetDetail of the business object FlightConnection is known.

Procedure

Define procedure cmdGetFlights_Click, in which you create an instance of the business object FlightConnection and call the BAPI method GetList.

Write the following lines of coding:

Private Sub cmdGetFlights_Click()

Dim oFlightConnection As SAPFlightConnection

Dim oTmp As Object

Dim rsConnDetailsOut As Recordset

Dim rsReturn As Recordset

Dim sError As String

'set the connection parameters

    sDestination = cbDestinations.Text

    sUser = txtUserID

    sLanguage = txtLanguage

    sPassword = txtPassword

    sClient = txtClient

    Screen.MousePointer = vbHourglass                       'activate hour glas

    On Error GoTo ErrHandle

'Casting

    Set oTmp = oSession

'transfer logon parameters in a single function call

    oTmp.PutSessionInfo sDestination, _

                             sUser, _

                             sPassword, _

                             sLanguage, _

                             sClient

'logon to R/3 system

    oSession.Logon (sError)

'fill key values

    fldCarrID = txtCarrID.Text

    fldConnID = txtConnID.Text

    fldFldate = txtFldate.Text

'create the instance for an object type from R/3

    Set oFlightConnection = oSession.CreateInstance("SAP.FlightConnection.1")

'call method "FlightConnection.InitKeys"

    oFlightConnection.InitKeys AirlineCarrier:=fldCarrID, _

                                    ConnectionNumber:=fldConnID, _

                                    DateOfFlight:=fldFldate

'call BAPI method "FlightConnection.GetDetail" with named parameters

    oFlightConnection.BapiGetDetail Flightdata:=rsConnDetailsOut, _

                                          Return:=rsReturn

'Output data

    txtFromCity.Text = rsConnDetailsOut.Fields("Cityfrom")

    txtToCity.Text = rsConnDetailsOut.Fields("Cityto")

    txtPlaneType.Text = rsConnDetailsOut.Fields("Planetype")

    Screen.MousePointer = vbDefault                         'deactivate hour glas

    cmdBookFlight.Enabled = True                            'activate Button for next action

    Exit Sub

ErrHandle:

    MsgBox CStr(Err.Number) + vbCrLf + Err.Description

    Screen.MousePointer = vbDefault                         'deactivate hour glas

End Sub

Exercise 7: Call BAPI Method "CreateFromData"

Prerequisites

The interface definition of method CreateFromData of the business object FlightBooking is known.

Procedure

Book a flight using button cmdBookFlight. To do so, create an instance of business object FlightBooking and call BAPI method CreateFromData.

Write the following lines of coding:

Private Sub cmdBookFlight_Click()

Dim oFlightConnection As SAPFlightConnection      ' reference to SAPFlightConnection

Dim oFlightBooking As SAPFlightBooking             ' reference to SAPFlightBooking

Dim rsBookingDataIn As Recordset

Dim rsBookingDataout As Recordset

Dim rsReturn As Recordset

    Screen.MousePointer = vbHourglass

    On Error GoTo ErrHandle

'create the instance for BO "FlightConnection"

    Set oFlightConnection = oSession.CreateInstance("SAP.FlightConnection.1")

'call method "FlightConnection.InitKeys" to set key values

    oFlightConnection.InitKeys AirlineCarrier:=fldCarrID, _

                                   ConnectionNumber:=fldConnID, _

                                   DateOfFlight:=fldFldate

'create instance for BO "FlightBooking"

    Set oFlightBooking = oSession.CreateInstance("SAP.FlightBooking.1")

'create an empty recordset of 'type' "rsBookingDataIn"

    oFlightBooking.DimAs "BapiCreateFromData", "BookingdataIn", rsBookingDataIn

'initialize structures and tables with data

    With rsBookingDataIn

       .AddNew                                                            'insert new data set

       .Fields("Carrid") = fldCarrID                               'Flight Carrier

       .Fields("Connid") = fldConnID                            'Connection ID

       .Fields("Fldate") = fldFldate                               'Flight date

       .Fields("Customid") = txtCustomerID.Text            'Customer ID

       .Fields("Smoker") = "X"                                       'Smoker (Values:"X" or "")

       .Fields("Luggweight") = 11.5                              'Luggage weight (default value)

       .Fields("Wunit") = "KG"                                      'Unit of weight

       .Fields("Class") = optClass(Index).Tag                 'Class

       .Fields("Counter") = "0"                                      'Counter (valid number)

       .Fields("Agencynum") = "20"                              'No. Agency (valid number)

       .Update                                                            'store in table

    End With

'call BAPI method "FlightBooking.CreateFromData" with named parameters

    oFlightBooking.BapiCreateFromData BookingdataIn:=rsBookingDataIn, _

                                              Bookingdata:=rsBookingDataout, _

                                              Return:=rsReturn

    Screen.MousePointer = vbDefault                          'deactivate hour glas

' display BookID

    txtBookID.Text = rsBookingDataout.Fields("BOOKID")

    Exit Sub

ErrHandle:

    MsgBox CStr(Err.Number) + vbCrLf + Err.Description

    Screen.MousePointer = vbDefault

End Sub

Define the procedure CheckInput for entering the class by writing the following lines of coding:

Private Sub optClass_Click(Index As Integer)

'define flight class

fldClass = optClass(Index).Tag

End Sub

Exercise 8: Exit the Application

Procedure

Click on cmdExit to exit the application as follows:

Private Sub cmdExit_Click()                                      'Menu "Exit"

    MsgBox "Program finished !", 16, "Exit"

   Unload Me                                                        'Unload frmMain and finish program

End Sub

Check Your Work

Test the program by choosing Start.

If the booking was successful, the system assigns a booking number and displays it in the field BookID.