Processing IDocs

Processing IDocs can be separated into four operations, Receiving, Parsing, Writing, and Sending. Each of the sections below provides detail on how the individual operations are performed.

Receiving an IDoc

The SapServer component allows you to easily receive an IDoc from a remote SAP system. In order to do this, you must do the following:

• Initiate the connection with the SAP system by calling AcceptConnections.
• Set the ReceiveIDoc property to true. This will tell the component to install the INBOUND_IDOC_PROCESS and IDOC_ASYNCHRONOUS_INBOUND functions, which respectively handle the synchronous and asynchronous IDoc processing.

Once the component is set to receive IDocs, you will need to begin listening for the IDoc functions, which you can do by setting the Listening property to true.

When the component begins receiving an IDoc, the IDocStart event will fire. Then the IDocControlRecord event will fire, containing the full control record for the IDoc. At which point, the IDocDataRecord event will fire once for each data record segment in the IDoc. Once the component has finished receiving the IDoc, the IDocEnd event will fire, indicating that the component is ready to receive another IDoc.

Below is an example of how to receive an IDoc and then parse it using the IDocReader component:

Private reader As Idocreader

Private Sub btnStartServer_Click(sender As System.Object, e As System.EventArgs) Handles btnStartServer.Click
  sapServer1.Config("UseClientConnection=True")
  sapServer1.SapConnection.ConnectionType = 0 'NetWeaver
  sapServer1.SapConnection.Client = "000"
  sapServer1.SapConnection.Destination = ""
  sapServer1.SapConnection.Host = "localhost"
  sapServer1.SapConnection.User = "BCUSER"
  sapServer1.SapConnection.Password = "minisap"
  sapServer1.SapConnection.SystemNumber = 0

  sapServer1.AcceptConnections(txtProgramID.Text, txtHost.Text, txtService.Text)
  sapServer1.ReceiveIDoc = True
  
  sapServer1.Listening = True
End Sub

Private Sub sapServer1_OnIDocStart(sender As System.Object, e As nsoftware.InERP.SapserverIDocStartEventArgs) Handles sapServer1.OnIDocStart
  reader.InputData = ""
End Sub

Private Sub sapServer1_OnIDocControlRecord(sender As System.Object, e As nsoftware.InERP.SapserverIDocControlRecordEventArgs) Handles sapServer1.OnIDocControlRecord
  reader.InputData = reader.InputData & e.data
End Sub

Private Sub sapServer1_OnIDocDataRecord(sender As System.Object, e As nsoftware.InERP.SapserverIDocDataRecordEventArgs) Handles sapServer1.OnIDocDataRecord
  reader.InputData = reader.InputData & e.data
End Sub

Private Sub sapServer1_OnIDocEnd(sender As System.Object, e As nsoftware.InERP.SapserverIDocEndEventArgs) Handles sapServer1.OnIDocEnd
  reader.Parse()
End Sub

Parsing an IDoc

The IDocReader component allows you to easily parse an IDoc from a file, a stream, or from memory. You can parse documents that are formatted in either plain text or XML. To do so, you need to follow the steps below:

1. Import schema, this can be done one of two ways:
   • Use the ImportSchemaFromSAP method to retrieve the schema directly from SAP
   • Use the ImportXMLSchema method to retrieve the XML schema directly from disk
2. Load the IDoc Data into the component using one of the following methods:
   • Specify the file to read in the InputFile property
   • Provide the data directly from memory using the InputData property
   • Set the input stream using the SetInputStream method
3. Call the Parse parse method

During parsing, the component performs basic validation of the incoming document. If validation fails, a warning is generated, and the Error event will fire, populating the ErrorOffset property with the offset in the document where the error occurred.

In order to navigate the document, you will need to use the XPath property, like so:

/segmentA[1]/childSegmentC[2]/grandChildSegmentA[1]

This example path means that the component will select the first grandChildSegmentA in the second childSegmentC in the first segmentA.

Writing an IDoc

The IDocWriter component allows you to create a document from scratch. The component allows you to create an IDoc document one segment at a time. Here's how a document would normally be created:

1. First, load a schema file into the component. You can use ImportSchemaFromSAP to retrieve the schema from SAP or ImportXMLSchema if you have the XML schema saved locally.
2. Specify where to write the document by setting the OutputFile property or calling the SetOutputStream method. If neither is set, the data will be written to the OutputData property.
3. Start a new document by calling StartIDoc.
4. Write the Control Record Data before writing any segments, call WriteControlRecord. Note that you will need to set the fields in the ControlRecordData property before calling this method.
5. Create a new record data segment by calling StartSegment.
6. Write all the data for the segment by creating new fields using the WriteFieldValue method. Note that each segment can contain one to many fields.
7. Once you are done with the segment, call EndSegment.
8. Repeat steps 5-7 until you are finished writing the document.
9. Once you are done with the document, call EndIDoc.

Example IDocWriter Code:

idocwriter1.StartIDoc()
idocwriter1.WriteControlRecord()
idocwriter1.StartSegment("Segment1")
idocwriter1.WriteFieldValue("Field1", "Value1")
idocwriter1.WriteFieldValue("Field2", "Value2")
...
idocwriter1.EndSegment()
idocwriter1.StartSegment("Segment2")
idocwriter1.WriteFieldValue("Field1", "Value1")
...
idocwriter1.EndSegment()
...
idocwriter1.EndIDoc()

Sending an IDoc

Both the IDocReader and IDocWriter allow you to send an IDoc to the remote SAPSystem. When using the IDocReader component, you must first parse the document before calling Send. Likewise, you must write a document before calling Send when using the IDocWriter component.

When sending, you can specify whether to send synchronously or asynchronously using the TransferMode property to either tmSync or tmAsync respectively. Note that when using SOAP, you must set TransferMode to tmSync.