Overview

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

EDITOR’S NOTE: SAP .Net Connector 2.0 has been replaced by NCo 3.0.  SAP .Net Connector 2.0 is scheduled to go off maintenance March 31, 2013.

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 FilesSAPSAP .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.

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.

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.

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