The SAP .Net Connector 3.0 (NCo 3.0) offers many improvements over SAP .NET Connector 2.0. Unfortunately, SAP no longer offers example .NET code.  This blog attempts to fill that gap by describing how to build a simple RFC Client using SAP .Net Connector (NCo) 3.0 with VB.NET.  Click here to request a .zip file containing a copy of the source code.

The sample program displays details about companies defined by SAP. There are two BAPI calls involved, BAPI_COMPANY_GETLIST and BAPI_COMPANY_GETDETAIL.
Along with the SAP .Net Connector 3.0, we are using Microsoft Visual Studio 2010 and the Microsoft .Net Framework 4.0 to build our sample.  Prior to starting, you will have to download and install NCo 3.0 (OSS login required).

Setting up the Project

Using Visual Studio 2010, create a new Windows Form project. In the project properties, be sure to set the Target Framework to .Net Framework 4.0.  To change the target .NET framework version on a VB.NET project, first open the project’s property page.  Click on the “Compile” tab in the property page.  Then click on the “Advanced Compile Options..” button.

In the ensuing dialog window, change the target framework version.

Next, add references to the SAP .Net Connector 3.0. There are two DLLs, sapnco.dll and sapnco_utils.dll.

Design the Form

Add two controls to the form. The first is a List Box, which will contain the list of available SAP companies. The second control to add is a Property Grid control, which is used to display the details of a particular SAP company when the user selects one from the List Box.

Using App.Config to define the SAP Connections

There are several methods you can use in your solutions to define a particular SAP host. For this example, we are using an app.config file to define our SAP host.
The SAP .Net Connector 3.0 includes sample app.config files. For the RFC client, be sure there is a sectionGroup definition for <ClientSettings>.
The SAP host is defined by the destinations section. Within the destination, the Name field identifies this app.config entry to our program code. Specify the appropriate user name, password, SAP host name, client and system number in the destination section.

The BAPIs

Use the SAP transaction SE37 to determine the parameters for functions BAPI_COMPANY_GETLIST and BAPI_COMPANY_GETDETAIL. This will tell us what parameters need to be passed in and where to find the results that are returned to our code.

The Code

During the form load event, we want to populate our List Box with the defined companies from SAP.

1. Acquire a valid RfcDestination to use. Use method RfcDestinationManager.GetDestination() to do this. GetDestination() requires a parameter to determine which SAP host to refer to. Pass in the Name of the SAP host you previously defined in the app.config file. (Line 39)
2. Now that we have a valid RfcDestination object, we need access to the SAP Repository. The repository contains information about the BAPI calls we are going to make. The RfcRepository is an attribute of an RfcDestination object. (Line 42)
3. Using the RfcRepository object, acquire a reference to the SAP BAPI by calling method RfcRepository.CreateFunction() method. Pass in the name of the desired function as a string parameter to CreateFunction(). This method returns an object we can use to setup parameters, invoke the function, and retrieve results.
4. Now we can make the RFC calls into SAP. Using the IRfcFunction object returned by CreateFunction(), call the Invoke() method, passing in our RfcDestination object as parameter. This will make the RFC call into SAP, and provides the results via our IRfcFunction object. (Line 48)
5. SAP function BAPI_GET_COMPANYLIST returns a table of company records. We use an instance of an IRfcTable object that we retrieve by calling the GetTable() method on the IRfcFunction object. To get a desired table, pass in the table name to the GetTable() method. (Line 50)
6. We now have an instance of an IRfcTable object that contains company information through which we can iterate. It is possible to iterate through the data by setting the CurrentIndex property on the returned table. For a particular row in the table, it is possible to access values using the GetString() method. (Lines 55-59)
7. For each company, get the CompanyNumber, and use that as a parameter to SAP function BAPI_COMPANY_GETDETAIL. BAPI_COMPANY_GETDETAIL returns detailed information about that particular SAP company. The techniques are the same as before, with the additional step of using the SetValue() method on the IRfcFunction object to pass in the company number as a parameter. (Lines 60-67)
8. BAPI_COMPANY_GETDETAIL returns data as an instance of the IRfcStructure interface. Access individual field data of the company record, using the GetString() method of the IRfcStructure object instance. (Lines 67-78)
9. Extract the company details as desired. Add them to some object you create and then add that object to the List Box control. (Line 80)

The rest of the code is regular Windows Forms programming. Your code will need to wire up the List Box changed events so that the Property Grid will display the details of the selected company.

Additional Information

Follow these links for more information about NCo 3.0 programming:

• Webinar: SAP NCo 3.0 – Best Practice Guide for Upgrade from .NET Connector 2.0
• Source Code: RFC Client with NCo 3.0 for VB.NET
• C# version of this example: Build an RFC Client with NCo 3.0 – A Step-By-Step Guide

When two software systems integrate, we also have to deal with the “dropped call” problem.  SAP NCo 3.0 offers a few different levels of  data recovery options depending on whether NCo is the client or the server.  But before any data recovery can happen, the first step is to call the other party back.  This blog post describes the general process to reconnect an NCo RfcServer to an SAP gateway host.

I have read in other blogs that SAP claims their RfcServer object will automatically reconnect if it detects a dropped connection.  While this may be true, I have not seen this automatic reconnection occur in all the testing that I have done.  So, left to my own devices, I set out to figure out the best way to reconnect an RfcServer.

The first thing I did was to map out the “dropped call” process diagram.

I know that some of you are thinking that after a call is dropped it is not necessary to hang up.  This is true.  But the connection needs to be cleaned up.  In the mobile phone analogy, the phone automatically detects the dropped call and hangs up for you.  What I found during my research is that NCo 3.0 doesn’t automatically clean up broken connections, nor does it automatically clean up failed connection attemps.

Armed with this flow chart, my new found understanding of NCo 3.0, some Diet Mountain Dew, and a bag of Skittles, I decided to tackle coding a similar solution in C# using NCo 3.0.

But first, I tweaked my flow chart:

The result was a RfcServer NCo 3.0 project that would automatically recover from connection errors.  The key concept is to call the Shutdown() method of the RfcServer object after each connection failure.  Add in an event handler for the RfcServerError Event and a timer, and the rest falls into place.

Download RfcServer Reconnection Sample NCo 3.0 Project

A full sample C# project is available for download here: SAP NCo 3.0 RFC Server Reconnection Sample

Additional SAP NCo 3.0 Information

Follow these links for more information about SAP NCo 3.0 programming:

• Webinar: SAP NCo 3.0 – Best Practice Guide for Upgrade from .NET Connector 2.
• Build an RFC Client with NCo 3.0 – A Step-By-Step Guide
• Build an RFC Server with NCo 3.0 – A Step-By-Step Guide

SAP .NET Connector 2.0 offered a couple of different sample projects that were instrumental in my learning process.  As I mentioned in my post detailing the steps to build an RFC client, SAP no longer supplies code samples with SAP .NET Connector (NCo) 3.0.  So, I decided to make available some code examples created by my colleague, Terry DeBruicker.

This blog describes how to build a simple RFC Server using the SAP NCo 3.0. The sample program implements RFC STFC_CONNECTION.  STFC_CONNECTION is a good example to use because it contains both importing and exporting parameters.

Click here to request a .zip file containing a copy of the source code.

Along with the SAP .Net Connector 3.0, we are using Microsoft Visual Studio 2010 and the Microsoft .Net Framework 4.0 to build our sample. Prior to starting, you will have to download and install NCo 3.0 (OSS login required).

Setting up the Project

Using Visual Studio 2010, create a new console project. In the project properties, be sure to set the Target Framework to .Net Framework 4.0.

Next, add references to the SAP .Net Connector 3.0. There are two DLLs, sapnco.dll and sapnco_utils.dll.

Using App.Config to define the SAP Connections

There are several methods you can use in your solutions to define a particular SAP host. For this simple example, we are using an app.config file to define our SAP host connection information.

One of the biggest differences between NCo 3.0 and NCo 2.0 is how function metadata is retrieved and stored.  With NCo 2.0 the function metadata was downloaded from an SAP system at design  time and persisted as proxy objects that were compiled with the rest of your solution.  NCo 3.0 needs to access this metadata at runtime.  There are two methods for providing this metadata.  One method is to create the metadata in your .NET code.  The other method is to rely on the metadata stored in the SAP system.  For this example, we will rely on the SAP system to provide RFC metadata.  This metadata is retrieved using special built-in RFCs.  Therefore, not only will our program act as an RFC server, it will also need to act as an RFC client.

For basic RFC server configuration, there are two configuration sections that are used, <ClientSettings> and <ServerSettings>.  Ensure that the app.config file has a <sectionGroup> tag for both client and server settings.

An RFC server configuration is linked to a RFC repository by use of the REPOSITORY_DESTINATION attribute.  To be able to access function metadata, this attribute must match the name of a destination configuration in the client settings section.

All SAP NCo 3.0 RFC servers communicate with SAP through a SAP service called the gateway.  The server settings configuration section  defines how the program connects to the SAP gateway.  In the servers section, the NAME field identifies this app.config entry to our  program. The SAP .Net Connector 3.0 will use the values in the GWHOST, GWSERV, and PROGRAM_ID fields to register our program on the SAP Application Gateway. The PROGRAM_ID specified here must match the Registered Server Program ID specified in the RFC destination.

The SAP RFC Function Interface

SAP transaction SE37 can be used to determine the parameters for the STFC_CONNECTION function. This describes what parameters will be passed to our function, and what results are expected.

In this example, we expect to receive parameter REQUTEXT, which will be returned to the caller in ECHOTEXT. We also return a text string to the caller in field RESPTEXT.

SAP transactoin SM59 is used to configure the SAP RFC Destination. In this example, the name of the RFC Destination (NIMBUS) is the name of the development computer that is running the RFC Server. The registered program ID (NCO3_RFC_SERVER) matches our app.config file.

The Code

As an Nco developer, one of my favorite changes brought about by Nco 3.0 is how RFC server functionality is implemented. Instead of overriding generated stub method, we need to implement one or more class methods that will process the incoming RFC calls. For this there are several possibilities:

• The first option is to create one static method corresponding to each SAP function module to be implemented.  Assigning a SAP function module to a method is done by decorating the method with the RfcServerFunction attribute.
• The second method is to create one static method for that handles all SAP function modules. This is called the “default” method. Use the same RfcServerFunction method decoration as the previous option, but denote that the method is the defualt RFC handler. The Name attribute is irrelevant in this case.  These two methods for RFC Function handling can be combined in the same project.

It is also possible to use either of the two previous options with instance methods instead of static methods.  For the purposes of this example, we will use a static method to implement our RFC Server.

We will create a class that exposes a method that can be called via SAP RFC.  In our example that class is named DxsRfcServer and it contains one method that will supply the STFC_CONNECTION functionality.  Now perform the following steps to implement class.

1. Provide the RFC callable code. This is done in our DxsRfcServer class, where we have a method defined. The RfcServerFunction code attribute on line 59 identifies this function to the SAP .Net Connector as the method that implements SAP function STFC_CONNECTION. On line 60 is where we are passed two parameters that contain all of the information we need to execute our function. The IRfcFunction interface provides access to parameter values. In this case we use the .GetString() method on line 69 to extract the value of the REQUTEXT parameter. We also can return values to the RFC caller using the IRfcFunction interface by using the .SetValue() method as seen in lines 69-70.
   
2.  Create an array of types, with just one element that refers to our DxsRfcServer class.
   
3. Register the array with an RfcServer object.  Notice that on line 22, the first parameter to the .GetServer() method is the NAME field of the servers section in app.config.
   
4. Start the RFC server.
   
5. At this time, the SAP system has visibility of our program running on the application gateway. (SAP transaction SMGW Goto menu->Logged On Clients)
   
6. Use the test function screen in transaction SE37 to test the new function. The RFC Target System is set to the name of the RFC destination created in the previous step (in this case it is our development system name).
   
   Here are the results:
   
7. The command console will also display some useful information:
   

The rest of the code is regular Windows Console programming and is very straight forward.

Additional Information

Follow these links for more information about NCo 3.0 programming:

• Webinar: SAP NCo 3.0 – Best Practice Guide for Upgrade from .NET Connector 2.0
• Source Code: RFC Server with NCo 3.0

The sample program displays details about companies defined by SAP. There are two BAPI calls involved, BAPI_COMPANY_GETLIST and BAPI_COMPANY_GETDETAIL.
Along with the SAP .Net Connector 3.0, we are using Microsoft Visual Studio 2010 and the Microsoft .Net Framework 4.0 to build our sample.  Prior to starting, you will have to download and install NCo 3.0 (OSS login required).

Setting up the Project

Using Visual Studio 2010, create a new Windows Form project. In the project properties, be sure to set the Target Framework to .Net Framework 4.0.

Add references to the SAP .Net Connector 3.0. There are two DLLs, sapnco.dll and sapnco_utils.dll.

Design the Form

Add two controls to the form. The first is a List Box, which will contain the list of available SAP companies. The second control to add is a Property Grid control, which is used to display the details of a particular SAP company when the user selects one from the List Box.

Using App.Config to define the SAP Connections

There are several methods you can use in your solutions to define a particular SAP host. For this example, we are using an app.config file to define our SAP host.
The SAP .Net Connector 3.0 includes sample app.config files. For the RFC client, be sure there is a sectionGroup definition for <ClientSettings>.
The SAP host is defined by the destinations section. Within the destination, the Name field identifies this app.config entry to our program code. Specify the appropriate user name, password, SAP host name, client and system number in the destination section.

The BAPIs

Use the SAP transaction SE37 to determine the parameters for functions BAPI_COMPANY_GETLIST and BAPI_COMPANY_GETDETAIL. This will tell us what parameters need to be passed in and where to find the results that are returned to our code.

The Code

During the form load event, we want to populate our List Box with the defined companies from SAP.

1. Acquire a valid RfcDestination to use. Use method RfcDestinationManager.GetDestination() to do this. GetDestination() requires a parameter to determine which SAP host to refer to. Pass in the Name of the SAP host you previously defined in the app.config file. (Line 60)
2. Now that we have a valid RfcDestination object, we need access to the SAP Repository. The repository contains information about the BAPI calls we are going to make. The RfcRepository is an attribute of an RfcDestination object. (Line 62)
3. Using the RfcRepository object, acquire a reference to the SAP BAPI by calling method RfcRepository.CreateFunction() method. Pass in the name of the desired function as a string parameter to CreateFunction(). This method returns an object we can use to setup parameters, invoke the function, and retrieve results.
4. Now we can make the RFC calls into SAP. Using the IRfcFunction object returned by CreateFunction(), call the Invoke() method, passing in our RfcDestination object as parameter. This will make the RFC call into SAP, and provides the results via our IRfcFunction object. (Line 68)
5. SAP function BAPI_GET_COMPANYLIST returns a table of company records. We use an instance of an IRfcTable object that we retrieve by calling the GetTable() method on the IRfcFunction object. To get a desired table, pass in the table name to the GetTable() method. (Line 70)
6. We now have an instance of an IRfcTable object that contains company information through which we can iterate. It is possible to iterate through the data by setting the CurrentIndex property on the returned table. For a particular row in the table, it is possible to access values using the GetString() method. (Lines 75-79)
7. For each company, get the CompanyNumber, and use that as a parameter to SAP function BAPI_COMPANY_GETDETAIL. BAPI_COMPANY_GETDETAIL returns detailed information about that particular SAP company. The techniques are the same as before, with the additional step of using the SetValue() method on the IRfcFunction object to pass in the company number as a parameter. (Lines 78-84)
8. BAPI_COMPANY_GETDETAIL returns data as an instance of the IRfcStructure interface. Access individual field data of the company record, using the GetString() method of the IRfcStructure object instance. (Lines 88-99)
9. Extract the company details as desired. Add them to some object you create and then add that object to the List Box control. (Line 101)

The rest of the code is regular Windows Forms programming. Your code will need to wire up the List Box changed events so that the Property Grid will display the details of the selected company.

Additional Information

Follow these links for more information about NCo 3.0 programming:

• Webinar: SAP NCo 3.0 – Best Practice Guide for Upgrade from .NET Connector 2.0
• Source Code: RFC Client with NCo 3.0

Duration: 1 hour

Speaker:  Craig Stasila, Principal, DataXstream

This one hour webinar will supply you with knowledge of features specific to the new upgrade, as well as an overview of the advantages that come with investing in NCo 3.0.

What Will Be Highlighted:

• Changes and new features brought upon by the NCo 3.0 update
• Demonstrations of best-practices for implementing new and existing NCo code
• Live demonstration of inbound and outbound function calls between a .NET solution and SAP ECC

Included in the downloads are documents that discuss the notable changes from .NET Connector 2.0 and a very comprehensive help file (in .chm format).  Noticeably absent are complete samples, although SAP claims that the included tutorial will be updated.

Additionally, I already have my first NCo 3.0 project under way, so check back soon for more information about NCo 3.0!

Happy Coding!

[UPDATED]

Additional Information

Follow these links for more information about NCo 3.0 programming:

• Webinar: SAP NCo 3.0 – Best Practice Guide for Upgrade from .NET Connector 2.0
• Build an RFC Client with NCo 3.0 – A Step-By-Step Guide
• Build an RFC Server with NCo 3.0 – A Step-By-Step Guide

Pure Fishing, Inc. – Integration with SAP .Net Connector Pure Fishing needed a new and standardized solution to allow seamless interaction between their SAP systems and third-party warehouse management software that was more reliable and flexible then custom integration approach used in the past.

View More Case Studies

EDITOR’S NOTE: NCo 3.0 has now been released.  Read more details here.

NCo 3.0 Logon

One of the new features implemented to combat the malevolent for RFC client attacks is the interface IDestinationConfiguration. This interface contains method IDestinationConfiguration.GetParameters(string destinationName) which allows .NET programmers to provide their own secure method for storing and retrieving logon information, be it encrypted database, encrypted file, or even LDAP.  There is also a corresponding interface and method to secure NCo 3.0 RFC servers.

Additionally, there is updated functionality to support single sign-on (SSO) and X.509 certificates.

Say Goodbye to Data Containers and Generated Code

In SAP Connector 2.0, working with RFCs required the generation of proxy code via the SAP .NET Connector design-time tool.  This tool would convert the IMPORTING, EXPORTING, CHANGING, and TABLES parameters from the RFC you were calling/serving to .NET representations of the same.  With NCo 3.0 there is no longer any kind of generated code.  Instead of one generated proxy method for each function module, there is one single RfcFunction class, whose Invoke() method dynamically executes every given ABAP function module. Additionally, all ABAP parameters will be represented by the class RfcStructure instead of a dedicated generated class for every structure; All tables will be represented by class RfcTable.  So, instead of hard-coding all of the data and variable bindings statically at design time, NCo 3.0 now handles everything dynamically at runtime.

NCo 3.0 uses SAP’s data dictionary to determine the function interface for the called RFCs.  While this data is cached locally for performance reasons, NCo 3.0 is robust enough to detect changes in RFC interface signatures so your code will still execute if you’ve added, deleted, or changed RFC parameters.  If there arises a situation where the dynamic lookup of RFC interface signature is not wanted, there is also an option to hard code the RFC parameter metadata.

The biggest benefit of NCo 3.0′s new dynamic function handling is that NCo 3.0 no longer has a design-time component.  This releases the Visual Studio version restriction that .NET 2.0 had.  Let me rephrase that, NCo 3.0 will work with any version of Visual Studio you like! The only requirement is that at runtime, a .NET Framework version is installed that is compatible with the NCo 3.0 libraries.

Anxiously Waiting

NCo 3.0 figures to be a much-needed update to a vital SAP integration technology.  I, for one, cannot wait for the new functionality to be generally released.  Once NCo 3.0 is released we’ll be posting blogs highlighting the new features.  We’ll also include helpful information regarding a .NET Connector 2.0 to NCo 3.0 upgrade.  In the meantime, if you have any leave any questions or comments you have regarding NCo 3.0 below.  You may also email me directly at csta...@dataxstream.com if you’d like to set up a detailed conversation.

The SAP .Net Connector simplifies creating C# programs that can interoperate with an SAP host. The SAP .Net Connector is available from the SAP Service Marketplace. You must have access to the SAP Service Marketplace to be able to download the SAP .Net Connector. The SAP .Net Connector must be installed on your development machine before we begin.

RFC is a Remote Function Call. In this case, the SAP process is a ‘client’ that is making an RFC call to our custom ‘server’ code. Our code uses the SAP .Net Connector to register on an SAP Application Gateway.

The TLA system we have been creating exists solely to demonstrate certain programming techniques involving the SAP .Net Connector and C#.  We will cover three separate parts of the solution: defining the function to SAP, creating a proxy object used to access SAP, and creating our C# code to perform the RFC function.

Defining the Function in SAP

Before we build our RFC server, we will define our RFC function in the SAP system. There are two parts we will need to create:  the Function Signature, and the RFC Destination.

Defining the RFC Function Signature

Open the SAP SE37 Function Builder screen. For the Function Module field, enter Z_RFC_TLA_HELLO_WORLD and click Create. For the Function group, press the browse button to the right of the field, then select an appropriate function Group. Enter a short text description and click Save to save the function signature.

On the Attributes tab, be sure to select the Remote-enabled module radio button.

Now we will be asked to define the parameters that are used. SAP refers to values passed to the RFC call as Import values. Values that are returned from the RFC call are called Export values.

In the Function Builder screen, on the Import tab, define a Parameter named Name. Fill in the appropriate Type and Associated Type values. Be sure to check the Pass Value check box.

On the Export tab, create a Parameter named Hello_World. This will end up storing the result of the RFC call. Define the field in the same way as the Name import field.

Save your RFC Function. Then you need to activate your RFC function. To do that, from the SE37 screen, enter the function module name. then click the Activate button.

Defining the RFC Destination

SAP can direct an RFC call to different destinations. We will create an RFC Destination using SAP function SM59. This RFC Destination is used by the SAP system to route an RFC call to our program, which previously registered itself on the SAP Application Gateway.

In the SM59 screen, click the Create button.  Enter RFC destination of TLARFCSERVER. The Connection type is T for TCP/IP. Enter a description.

On the Technical settings tab, select Activation Type of Registered Server Program.

For the Registered Server Program Program ID, enter TlaRfcSrv. The Program ID we use here must match the Program ID used when our server code connects to the SAP Application Gateway.

If you try the Test connection button, it will fail, since we have not yet registered our program on the Application Gateway. Later, we can come back to SM59 and test this and see that our RFC destination is available.

C# Code

We will create an application that can be called from an SAP host. The SAP host will pass in a name, as a string. Our application will return a hello greeting back to the calling program.

Our solution will consist of two parts.

1. The first part is the SAP .Net Connector Proxy project, named TlaRfcServerSapProxy. This will produce a Dynamic Link Library that encapsulates what we need to know to interoperate with the SAP host.
2. The second part is is our custom code project, named TlaRfcServer. This contains the code which will execute when called from the SAP host via RFC. Save the RFC destination.

Creating the SAP Proxy Project

We will use Visual Studio 2003 to create a DLL that manages the interactions with the SAP host. The SAP .Net Connector version 2.0 works with Visual Studio 2003 or 2005. To use the .Net Connector in our preferred environment of Visual Studio 2008, we will create the proxy DLL in 2003 and add that to our 2008 project. The techniques are described in our earlier post, Using the SAP .Net Connector in Visual Studio 2008.

In Visual Studio 2003, start a new Class Library project named TlaRfcServerSapProxy. Delete the default Class1.cs file that is created automatically.

From the Solution Explorer, Right-click on References and choose Add New References. Under the .Net tab, highlight SAP.Connector.dll and SAP.Connector.RFC. Click the Select button, then OK to add the SAP .Net Connector references.

Now add the SAP Connector Proxy to our project. Right click on the project and choose Add / Add New Item. Under the templates, highlight SAP Connector Proxy. In the Name field, give our proxy the name TlaRfcServerSapProxy.sapwsdl. The name we use here will become the object type name for our SAP Server Proxy object we use when we build our RFC server code.

The TlaRfcSerfverSapProxy.sapwsdl file will be displayed in Design mode. Right click on the Design surface and choose properties. This displays properties of our SAP Connector Proxy. Change the Proxy Type to Server.

Now we need to add in a reference to our SAP host so that we can pull in the signature and object model for our RFC function. Open the Server Explorer windows and expand SAP / Application Servers. Right-click on Application Servers and choose add New Server. Enter in the connection information for your SAP host. Click OK.

Expand the newly added SAP Server and right-click on Functions. Choose Add New Function Filter. In the Name Filter field, enter *HELLO* . The * is used as a wild card. Click OK to display our Z_TLA_RFC_HELLO_WORLD function in the Server Explorer.

Highlight the Z_TLA_RFC_HELLO_WORLD function in the Server Explorer, and drag it onto the TlaRfcServerSapProxy.sapwsdl design surface. This will add the necessary function signatures and object type definitions to the project.

Now attempt to build the project. It will fail, as we have not yet created the code to implement our remote function. But, when we ran the build, the SAP Connector generated an implementation stub for our server method. A new class was automatically added to our project, named TlaRfcServerSapProxyImpl.cs.

However, we desire to implement our RFC server using Visual Studio 2008.

So, we will modify this code so it will build, and later we will override the implementation from our Visual Studio 2008 project.

If you double-click on the build error, it will take you to the offending line of code. All we need to do is set the result of Hello_World to some value.  To prevent confusion with our Visual Studio 2008 code, we will just return foo.

Now build the TlaRfcSapServerProxy project and it will create TlaRfcServerSapProxy.dll, which we will use in our Visual Studio 2008 project.

Creating the RFC Server Project

Using Visual Studio 2008, create a C# console project named TlaRfcServer. In the Solution Explorer, right-click on References and choose Add New Reference. Using the Browse tab, select both SAP.Connector.dll and Sap.Connector.Rfc.dll, typically found in C:\Program Files\SAP\SAP .Net Connector 2.0.

Add a reference to the TlaRfcServerSapProxy.dll created earlier, also using the Browse tab. Add a reference to System.Web.Services using the .Net tab.

In our C# code, we need to provide the code to implement our RFC function, which we do by inheriting from TlaRfcServerSapProxyImpl and overriding the Hello World function.

On Line 3, with have our ‘using’ directive to include our custom proxy.

On line 8, we are creating a new class named SAPProxy, which is derived from our TlaRfcServerSapProxyImpl class that was created in our Visual Studio 2003 class.

On line 12 is the override of the Z_Tla_Rfc_Hello_World call. We provide our functionality and place the result in the Hello_World variable.

That concludes our class that will implement the RFC functionality.

Now we will finish off our console program so that we can establish our code on the SAP Application Gateway and execute it.

To do this,we will pass in command line arguments to our Main routine. These arguments are passed to the SAPProxy constructor, which uses them to connect to the correct SAP Application Gateway.

Each of our SAP Proxy objects are hosted by an SAPServerHost object, which is part of the SAP .Net Connector. The SAPServerHost object governs the connection to the SAP host.

Once we create the SAPProxy object and attach it to an SAPServerHost, we can start the host and that will cause our program to register and be available on the SAP Application Gateway.

Our program will continue to be available on the SAP Application Gateway as long as we have it running (until we press the enter key, in our example).

On lines 22-25, we instantiate our proxy and SAP host. Notice how we pass in the command line arguments to the SAPProxy constructor (line 25).

We start the proxy on line 29. After we have done that, we can go back to the SAP SM59 function and test our RFC destination. If things are working, that test will success.

Our code will continue to be available until we press enter at line 37, after which we stop the SAP host.

Command Line Arguments

The command line arguments consist of three parts, and are specified in the Visual Studio environment under the Debug tab of the Project Properties display.

The three parts are

-aProgram ID

-XPort

-GHost

The Program ID specified here must match the Program ID we used when creating the SAP RFC Destination. In our case this is specified as –aTlaRfcSrv.

The Port field tells SAP what TCP/IP port to use. This is specified by –XSAPGW00. The SAPGW part specifies port 3300, we add whatever the 00 is to get the actual port number. In our case we are using port number 3300, so we use –XSAPGW00. If we wanted port 3302, we would have used –XSAPGW02.

The Host field is the DNS name or IP address of the SAP server.

So, your parameters will be different but they will look something like –aTlaRfcSrv –XSAPGW00 –Ghostname

Now build and run TlaRfcServer. A console window will appear.

Go back to SAP and bring up the SM59 screen. Expand the TCP/IP connections and find TLARFCSERVER. Double click that to display the definition. When you click the Test Connection button, you should see something like :

which indicates a successful test of the RFC destination.

Now we need to test our actual RFC function. Bring up the SAP SE37 screen. In the Function Module name, enter Z_TLA_RFC_HELLO_WORLD, which matches the name of the function signature we created earlier.

Press the F8 key to test the function. The Test Function Module screen is displayed.

For the RFC Target sys, we use the RFC Function destination we created earlier, TLARFCSERVER.

For the name field, type WORLD. Press F8 to execute the RFC call.

This indicates a good test of our RFC function.

Troubleshooting

If things don’t work, check the following:

Program ID in RFC Destination matches –a parameter of TlaRfcServer command line.

Port number (SAPGW00) on TlaRfcSever comand line is set to correct port number.

Any firewalls in between the SAP host and the RFC Server program need to allow traffic in both directions over that port.

Summary

In this blog posting we have shown how you can call custom C# code from an SAP process.

This blog post describes how to receive an IDOC from an SAP system, using the SAP .Net Connector and Microsoft C#.

Introduction

The SAP .Net Connector simplifies creating C# programs that can interoperate with an SAP host. The SAP .Net Connector is available from the SAP Service Marketplace. You must have access to the SAP Service Marketplace to be able to download the SAP .Net Connector. The SAP .Net Connector must be installed on your development machine before we begin.

An IDOC is an Interface Document that is used to send or receive information to or from an SAP host.  An IDOC will consist of a header record and as many detail records as necessary. The header records follow the format of the EDI_DC40 table, and the detail records follow the format of the EDI_DD40 table. The exact format of the payload in the detail records depends on the type of IDOC being transmitted.

C# Code

We will create an application that displays the contents of IDOCs received from an SAP host. Use Visual Studio 2008 and create a new C# console application. Name the new application IdocReceive.

Add Reference to SAP .Net Connector.

In the Solution Explorer,  right-click on References and choose Add New Reference. Select both SAP.Connector.dll and SAP.Connector.Rfc.dll. Typically, these files will be found in C:\Program Files\SAP\SAP .Net Connector 2.0.

Our program will instantiate a custom class, IdocReceiver, that encapsulates the SAP transmit and receive logic.

IdocReceiver inherits from the SAP .Net Connector.  IdocReceiver overrides methods from the SAP .Net Connector to manage the flow of IDOCs from the SAP host. IdocReceiver also subscribes to two events exposed by the SAP .Net Connector that perform the actual transmission.

IDOC Receiver Main Method

Line 5 contains the reference to the SAP .Net Connector that we need.

The IdocReceiver object requires an SAPHost object that is used to configure the connection to the SAP Gateway. Line 9 instantiates the SAPHost object.

Line 14 calls the IdocReceiver constructor. The first parameter is the SAP Connection String, used to connect to the SAP host. There are three parts of an SAP Connection String:

-aProgramName is the program name as it is defined on the SAP Gateway. This value must match the Program ID configured on the SAP Gateway. Use SAP command SM59 to view the settings of the SAP Gateway.

-xSAPGWnn is the SAP Gateway number to which the IDOC receiver will register.  The SAP Gateway listens on a TCP/IP port number based on nn value. The actual port number is equal to 3300 plus the nn value. In this case nn is zero, so port 3300 is used.

-gHostName is the DNS host name of the SAP server. It is also possible to specify an IP address, like -g192.168.10.1.

Line 16 starts the SAP host, which makes it possible to begin receiving IDOCs. At this point, our program will now be visible to the SAP host, which you can verify using the Test Connection command via SAP transaction SM59. As long as the IdocReceiver object remains in scope, it will receive IDOCs.

IdocReceiver Class

To receive an IDOC, the IdocReceiver class inherits from the SAP .Net Connector SAPIdocReceiver class. To control the flow of IDOCs, the IdocReceiver class overrides certain methods of the SAPIdocReceiver class. To actually receive an IDOC, the IdocReceiver subscribes to two events exposed by the SAPIdocReceiver class.

Constructor

Here is the code for the IdocReceiver constructor.

IdocReceiver Constructor

On line 25 we declare our IdocReceiver and inherit from the appropriate SAP .Net Connector object. We use the StringWriter on Line 27 to store the contents of the actual IDOC received.

The constructor requires two parameters, the SAP Configuration string, and an SAPServerHost object that is a container for the IdocReceiver. Line 30 is where we call the base constructor.

The transfer of the IDOC raises an event at two times: when the transfer begins and when the transfer ends. On lines 32-33, we wire up our IdocReceiver methods to the BeginReceive and EndReceive events exposed by the SAPIdocReceiver class. Our IdocBeginReceive will be called at the start of the IDOC transmission, and our IdocEndReceive method will be called at the end of the IDOC transmission.

IDOC Flow Control

IDOCs flow out of an SAP system in a transactional way, in that an SAP host will send a particular IDOC once an only once. To accomplish this, the SAP host will put together one or more IDOCs into a transaction and send that off to the IdocReceiver that has registered on the SAP Gateway. The transaction is identified by a unique Transaction ID (TID) that is supplied by the SAP host. The SAP host will communicate with our IdocReceiver using the Transaction ID to control the flow of IDOCs from SAP to our program.

There are four methods of the base SAPIdocReceiver class that we need to override.

IDOC Flow Control Methods

In each case, the SAP host expects our code to return a zero if there are no difficulties. The TIDs passed as parameters can be used to verify the state of the transmission. This demonstration code leaves out any processing you may want to use to validate the state of the transaction.

The SAP host will first call the CheckTransaction method. If a zero is returned, the SAP host will call ConfrimTransaction. If a zero is then returned, the SAP host will begin transmitting IDOCs. When the transmission is complete, the SAP host will call CommitTransaction.

IDOC Reception

We use two methods to receive the actual IDOCs. At the start of the transmission, we assign a StringWriter to the EventArg, which tells the SAP .Net Connector where we want to place the payload of the transmission. When the transmission is complete, we can read from the StringWriter to extract the payload.

IDOC Reception

There can be one or more IDOCs transmitted at a time. Your code will need to parse the payload to determine what goes where.

If any of your code throws an exception, the SAP .Net Connector will detect that and alert the SAP side. The SAP side will then call your Rollback method.

Summary

Using the SAP .Net Connector makes it easy to receive an IDOC from an SAP host.

To learn more about IDOCs download the white paper: ALE & IDOC Leveraging