Introduction

This documentation describes a set of components that allow applications to communicate easily, both synchronously and asynchronously, with each other. You can extend this system to fit your own particular needs. The components consist of:

  • the Navision Named Pipe Bus Adapter.

  • the Navision MS-Message Queue Bus Adapter.

  • the Navision Socket Bus Adapter.

  • the Navision Communication Component version 2.0.

More information:

Microsoft's documentation on the Message Queuing technology.

The manual Application Designer's Guide provides information about the C/SIDE development system. C/SIDE also has an online Reference Guide. Here you can find reference information about programming issues.

For information about Microsoft Business Solutions–Navision Application Server, see the manual Installation & System Management: Microsoft Business Solutions–Navision Application Server.


Bus Adapters

You can use the Navision Communication Component with the Navision Named Pipe Bus Adapter, the Navision MS-Message Queue Bus Adapter and the Navision Socket Bus Adapter. These enable C/SIDE applications to exchange documents with external programs. When you change from one transportation service to another, this has a very small impact on your application code.

You only work directly with a bus adapter when you set up all the objects. Otherwise any interaction between the user and the bus adapter takes place through other components.

Navision Named Pipe Bus Adapter

Navision MS-Message Queue Bus Adapter

Navision Socket Bus Adapter

More information:

The Navision Communication Component

Scenarios

Interfaces

Message Objects

Code Examples


Initializing Communication

This scenario uses the Navision MS-Message Queue Bus Adapter as the message transportation service. However, the same scenario applies if you use the Navision Named Pipe Bus Adapter or the Navision Socket Bus Adapter.


Navision MS-Message Queue Bus Adapter

The Navision MS-Message Queue Bus Adapter provides flexible, heavyweight synchronous/asynchronous communication between two systems. It supports disconnected communication and prioritized messages. The bus adapter supports both version 1.0 and 2.0 of the Microsoft Message Queue Server (MSMQ).

Microsoft states that:

  • MSMQ 1.0 can be deployed on computers running Windows NT 4.0, Windows 95, and Windows 98.

  • MSMQ 2.0 can be deployed on computers running Windows 2000.

  • With the MSMQ-MQSeries Bridge available from Microsoft System Network Architecture (SNA), you can use Message Queuing to communicate with IBM MQSeries systems.

Definition of Message Queuing (MSMQ)

Microsoft provides the following definition of Message Queuing:

"Message Queuing (MSMQ) technology enables applications running at different times to communicate across heterogeneous networks and systems that may be temporarily off-line. Applications send messages to queues and read messages from queues. The following illustration shows how a queue can hold the messages used by both sending and receiving applications.

Illustration of MSMQ

Where Applicable

Message Queuing provides guaranteed message delivery, efficient routing, security, and priority-based messaging.

It can be used to implement solutions to both asynchronous and synchronous scenarios requiring high performance. An example of where Message Queuing can be used is electronic commerce."

More information:

Sending a Document - Code Example 1

Sending a Document - Code Example 2

Receiving a Document - Code Example 1

Receiving a Document - Code Example 2

Scenarios

Interface Information


Navision Named Pipe Bus Adapter

The Navision Named Pipe Bus Adapter provides simple and easy synchronous/asynchronous communication between two systems. It works on all Windows 9x and Windows NT operating systems. This bus adapter does not require additional software, which means that it can also be used on a client. The Named Pipe Server runs only on Windows NT.

The Navision Named Pipe Bus Adapter does not support disconnected communication or prioritized communication.

Definition of the Named Pipes Data Transfer Method

Microsoft provides the following definition of Named Pipes:

"A named pipe is a named, one-way or duplex pipe for communication between the pipe server and one or more pipe clients. All instances of a named pipe share the same pipe name, but each instance has its own buffers and handles, and provides a separate conduit for client-server communication. The use of instances enables multiple pipe clients to use the same named pipe simultaneously.

Any process can access named pipes, subject to security checks, making named pipes an easy form of communication between related or unrelated processes. Named pipes can be used to provide communication between processes on the same computer or between processes on different computers across a network.

Any process can act as both a server and a client, making peer-to-peer communication possible. As used here, the term pipe server refers to a process that creates a named pipe, and the term pipe client refers to a process that connects to an instance of a named pipe."

More information:

Client Side Code Example

Server Side Code Example

Scenarios

Interface Information


Receiving a Document

This scenario uses the Navision MS-Message Queue Bus Adapter as the message transportation service. However, the same scenario applies if you use the Navision Named Pipe Bus Adapter or the Navision Socket Bus Adapter.

Receiving a document


Scenarios

The following scenarios use the Navision MS-Message Queue Bus Adapter 1.0 as the transport mechanism. However, these scenarios also apply if you use other Navision bus adapters.

Initializing communication

Sending a document

Receiving a document

For more information about setting up Navision Socket Bus Adapters, see the Navision Socket Bus Adapter Scenario.


Navision Socket Bus Adapter

The Navision Socket Bus Adapter uses Microsoft Windows Sockets 2 to provide communication between two systems across networks, for example across the Internet, and independently of network protocols.

The Socket bus adapter is especially useful when your application transmits large documents that can be streamed efficiently.

Windows Sockets 2 can use any transport protocol, but the Navision Socket Bus Adapter uses TCP.

Windows Sockets 2

In Microsoft documentation, you can find the following description:

"Windows Sockets 2 follows the Windows Open System Architecture (WOSA) model; it defines a standard service provider interface (SPI) between the application programming interface (API), with its exported functions and the protocol stacks. It uses the sockets paradigm that was first popularized by Berkeley Software Distribution (BSD) UNIX."

Windows Sockets "... is an interface, not a protocol. As an interface, it is used to discover and utilize the communications capabilities of any number of underlying transport protocols. Because it is not a protocol, it does not in any way affect the bits on the wire, and does not need to be utilized on both ends of a communications link."

For more information about Windows Sockets 2, see the Microsoft documentation, for example in the Microsoft Developers' Network (MSDN) Library, or the Web site www.sockets.com.

DOM, Sockets and Protocols

Microsoft DOM (MSDOM) reads messages in a continuous loop rather than closing the read interface when it reaches the end tag of a well-formed XML document. That means that it relies on the protocols surrounding the transmitted message to tell it when to stop reading. This creates problems when you use Windows Sockets, as the Navision Socket Bus Adapter does, because the bus adapter uses TCP as its transport protocol, and the efficiency of its transmission depends on the size of the TCP windows, that is, the amount of received data (in bytes) that can be buffered at one time on a connection (Microsoft MSDN).

The combination of TCP, Windows Sockets and MSDOM means that when you send a message, or document, using the Navision Socket Bus Adapter, the bus adapter will open a connection and keep it open until it receives acknowledgement that the message has been received. At the same time, the recipient will not know when it has received all of the message packet because Windows Sockets does not automatically include that information in the message.

If the bus adapter had contained a protocol layer, the built-in protocol would have handled this in one of three ways:

By adding information about the length of the message (such as the content-length in HTTP 1.0).

By sending special characters that indicate the end of the message.

By causing the sending bus adapter to close the connection, which indicates the end of the sent message.

When you use the Navision Socket Bus Adapter, you cannot use protocols to handle this for you, so you must use the bus adapter interface properties and C/AL code instead.

More information:

Navision Socket Bus Adapter: Setting Up Interfaces

Scenarios

Code Example: Sending a Document

Code Example: Receiving a Document

The Navision Socket Bus Adapter Interface


Sending a Document

This scenario uses the Navision MS-Message Queue Bus Adapter as the message transportation service. However, the same scenario applies if you use the Navision Named Pipe Bus Adapter or the Navision Socket Bus Adapter.


Code Examples - An Overview

The following code examples demonstrate how you can send and receive documents using the Navision Communication Component and the three bus adapters. None of the examples include handling of error situations.

Examples using the Navision MS-Message Queue bus adapter:

Sending a Document - Code Example 1

Sending a Document - Code Example 2

Receiving a Document - Code Example 1

Receiving a Document - Code Example 2

Visual Basic Code Example

Examples using the Navision Named Pipe bus adapter:

Client Side

Server Side

Examples using the Navision Socket bus adapter:

Sending a Document

Receiving a Document


Receiving a Document - Code Example 1

In this example, we use a single instance codeunit to initialize the Navision Communication Component, establish contact to a Navision MS-Message Queue Bus Adapter, open the bus adapter's receive queue and, finally, read the message that is received.

For the purpose of this example, we have defined the following variables:

Variable Name | Data Type | Subtype | Length
MQBus | Automation | 'Navision MS-Message Queue Bus Adapter '.MSMQBusAdapter |
CC2 | Automation | 'Navision Communication Component version 2'.CommunicationComponent |
InMsg | Automation | 'Navision Communication Component version 2'.InMessage |
InS | InStream |  |
Txt | Text |  | 100

Note that in the following example, you can use .\MyQueue (instead of MyMessageQueueServer\MyQueue) if you have installed the Microsoft Message Queue Server on your local machine.

Example

OnRun()

CREATE(MQBus);

CREATE(CC2);

CC2.AddBusAdapter(MQBus,1);

MQBus.OpenReceiveQueue('MyMessageQueueServer\comcom2_queue',0,0);

CC2::MessageReceived(VAR InMessage : Automation)

InMsg := InMessage;

InS := InMsg.GetStream();

InS.READ(Txt);

MESSAGE(Txt);

InMsg.CommitMessage();


Receiving a Document - Code Example 2

In this example, we use a single instance codeunit to initialize the Navision Communication Component, establish contact to a Navision MS-Message Queue Bus Adapter, open the bus adapter's receive queue, read the message that is received and then send a reply.

For the purpose of this example, we have defined the following variables:

Variable Name | Data Type | Subtype | Length
MQBus | Automation | 'Navision MS-Message Queue Bus Adapter'.MSMQBusAdapter |
CC2 | Automation | 'Navision Communication Component version 2'.CommunicationComponent |
InMsg | Automation | 'Navision Communication Component version 2'.InMessage |
InS | InStream |  |
Txt | Text |  | 100
OutMsg | Automation | 'Navision Communication Component version 2'.OutMessage |
OutS | OutStream |  |

Note that in the following example, you can use .\MyQueue (instead of MyMessageQueueServer\MyQueue) if you have installed the Microsoft Message Queue Server on your local machine.

Example

OnRun()

CREATE(MQBus);

CREATE(CC2);

MQBus.OpenReceiveQueue('MyMessageQueueServer\comcom2_queue',0,0);

CC2.AddBusAdapter(MQBus,1);

CC2::MessageReceived(VAR InMessage : Automation)

InMsg:= InMessage;

IF (InMsg.ExpectReply) THEN

BEGIN

InS:= InMsg.GetStream();

InS.READ(Txt);

MESSAGE(Txt);

OutMsg:= InMsg.CreateReply();

OutS:= OutMsg.GetStream();

OutS.WRITE('Yes, hello world! OK.');

OutMsg.Send(0);

END;

InMsg.CommitMessage();


Sending a Document - Code Example 1

In this simple example, we use a codeunit to initialize the Navision Communication Component, establish contact to the Navision MS-Message Queue Bus Adapter and send a document. This example does not include error handling.

For the purpose of this example, we have defined the following variables:

Variable Name | Data Type | Subtype
MQBus | Automation | 'Navision MS-Message Queue Bus Adapter'.MSMQBusAdapter
CC2 | Automation | 'Navision Communication Component version 2'.CommunicationComponent
OutMsg | Automation | 'Navision Communication Component version 2'.OutMessage
OutS | OutStream |

Note that in the following example, you can use .\MyQueue (instead of MyMessageQueueServer\MyQueue) if you have installed the Microsoft Message Queue Server on your local machine.

Example

OnRun()

CREATE(CC2);

CREATE(MQBus);

CC2.AddBusAdapter(MQBus,1);

MQBus.OpenWriteQueue('MyMessageQueueServer\XML-requests',0,0);

MQBus.SenderAuthenticationLevel:= 2;

OutMsg := CC2.CreateoutMessage('Message queue://MyMessageQueueServer\XML-requests');

OutS := OutMsg.GetStream();

OutS.WRITE('Hello world!');

OutMsg.Send(0);


Sending a Document - Code Example 2

In this example, we use a codeunit to initialize the Navision Communication Component, establish contact to the Navision MS-Message Queue Bus Adapter, send a document and wait for a reply. This example does not include error handling.

For the purposes of this example, we have defined the following variables:

Variable Name | Data Type | Subtype | Length
MQBus | Automation | 'Navision MS-Message Queue Bus Adapter '.MSMQBusAdapter |
CC2 | Automation | 'Navision Communication Component version 2'.CommunicationComponent |
OutMsg | Automation | 'Navision Communication Component version 2'.OutMessage |
OutS | OutStream |  |
InMsg | Automation | 'Navision Communication Component version 2'.InMessage |
InS | InStream |  |
Txt | Text |  | 100

Note that in the following example, you can use .\MyQueue (instead of MyMessageQueueServer\MyQueue) if you have installed the Microsoft Message Queue Server on your local machine.

Example

OnRun()

CREATE(CC2);

CREATE(MQBus);

CC2.AddBusAdapter(MQBus,1);

MQBus.OpenWriteQueue('MyMessageQueueServer\comcom2_queue',0,0);

MQBus.OpenReplyQueue('MyMessageQueueServer\notify_queue',0,0);

MQBus.SenderAuthenticationLevel:= 3;

OutMsg := CC2.CreateoutMessage('Message queue://MyMessageQueueServer\XML-requests');

OutS:= OutMsg.GetStream();

OutS.WRITE('Hello world!');

InMsg:= OutMsg.SendWaitForReply(3000);

IF ISCLEAR(InMsg) THEN

MESSAGE('InMsg not received')

ELSE

BEGIN

InS:= InMsg.GetStream();

InS.READ(Txt);

MESSAGE(Txt);

END;


Visual Basic Code Example

The following Visual Basic code example demonstrates sending and receiving scenarios using the Navision Communication Component and the Navision MS-Message Queue bus adapter.

The code is as follows:

Option Explicit

Dim WithEvents CC2 As CommunicationComponent

Dim MQBA As MSMQBusAdapter

Dim OutMsg As OutMessage

Dim ReplyMsg As OutMessage

Dim InMsg As InMessage

Dim DOM As DOMDocument30

Private Sub CC2_MessageReceived(InMessage As Object)

Set InMsg = InMessage

DOM.Load InMsg.GetStream

If InMsg.ExpectReply Then

Set ReplyMsg = InMsg.CreateReply

If ReplyMsg Is Nothing Then

MsgBox "Reply message could not be created."

Else

DOM.Load FileToSend.Text

DOM.Save ReplyMsg.GetStream

ReplyMsg.Send 2000

End If

MsgBox "Message received from ComCom2. Reply sent."

Else

MsgBox "Message received from ComCom2"

End If

End Sub

Private Sub Form_Initialize()

Set CC2 = New CommunicationComponent

Set MQBA = New MSMQBusAdapter

Set DOM = New DOMDocument30

End Sub

Private Sub Form_Load()

On Error Resume Next

If MQBA Is Nothing Then

MsgBox "MQBA could not be created."

Resume

End If

If CC2 Is Nothing Then

MsgBox "ComCom2 could not be created."

Resume

End If

CC2.AddBusAdapter MQBA, 1

End Sub

Private Sub Open_Receive_Q_Click()

MsgBox "Opening: " + Txt_ReceiveQ.Text

MQBA.OpenReceiveQueue Txt_ReceiveQ.Text, 1, 0

End Sub

Private Sub Open_ReplyQ_Click()

MsgBox "Opening: " + Txt_ReplyQ.Text

MQBA.OpenReplyQueue Txt_ReplyQ.Text, 1, 0

End Sub

Private Sub Open_WriteQ_Click()

MsgBox "Opening: " + Txt_WriteQ.Text

MQBA.OpenWriteQueue Txt_WriteQ.Text, 1, 0

End Sub

Private Sub Simple_Send_Click()

Dim SentCorrectly As Integer

Set OutMsg = CC2.CreateoutMessage("Message queue://")

DOM.Load FileToSend.Text

DOM.Save OutMsg.GetStream

SentCorrectly = OutMsg.Send(2000)

End Sub

Private Sub Sync_Send_Click()

Dim SentCorrectly As Integer

Set OutMsg = CC2.CreateoutMessage("Message queue://")

DOM.Load FileToSend.Text

DOM.Save OutMsg.GetStream

Set InMsg = OutMsg.SendWaitForReply(2000)

If InMsg Is Nothing Then

MsgBox "InMessage is empty!"

Else

DOM.Load InMsg.GetStream

DOM.Save ReadFileSave.Text

InMsg.CommitMessage

End If

End Sub


The Navision Named Pipe Bus Adapter - Client Side Code Example

In this example, we use a single instance codeunit to:

  • initialize the Navision Communication Component.

  • establish contact with the Navision Named Pipe bus adapter.

  • create and send a document.

  • create and send a document and wait for a reply.

  • send an XML document using the Microsoft XML DOM.

This example does not include error handling.

For the purpose of this example, we have defined the following global variables:

Variable Name | Data Type | Subtype
CC | Automation | 'Navision Communication Component version 2'.CommunicationComponent
NPBA | Automation | 'Navision Named Pipe Bus Adapter'.NamedPipeBusAdapter
OutMsg | Automation | 'Navision Communication Component version 2'.OutMessage
InMsg | Automation | 'Navision Communication Component version 2'.InMessage
Outstrm | OutStream |
InStrm | InStream |
Msgfile | File |
FileOutStrm | OutStream |
retval | Integer |
Reply | Integer |
ReplyMsg | Automation | 'Navision Communication Component version 2'.InMessage
Ch | Char |
DOM | Automation | 'Microsoft XML, v3.0'.DOMDocument30

We have also defined the functions Send, SendWaitForReply and SendXML.

Example

OnRun()

IF ISCLEAR(CC) THEN

CREATE(CC);

IF ISCLEAR(NPBA) THEN

CREATE(NPBA);

CC.AddBusAdapter(NPBA, 0);

Send()

OutMsg := CC.CreateoutMessage('Named Pipe://\\.\pipe\Test');

Outstrm := OutMsg.GetStream;

Outstrm.WRITE('Hello world');

OutMsg.Send(0);

SendWaitForReply()

OutMsg := CC.CreateoutMessage('Named Pipe://\\.\pipe\Test');

Outstrm := OutMsg.GetStream;

Outstrm.WRITE('Send and wait for reply');

ReplyMsg := OutMsg.SendWaitForReply(0);

InStrm := ReplyMsg.GetStream;

Msgfile.CREATE('c:\xmlout\MsgReply.txt');

Msgfile.CREATEOUTSTREAM(FileOutStrm);

REPEAT

retval := InStrm.READ(Ch,1);

FileOutStrm.WRITE(Ch);

UNTIL retval = 0;

Msgfile.CLOSE;

ReplyMsg.CommitMessage;

SendXML()

MESSAGE('Create message.');

OutMsg := CC.CreateoutMessage('Named Pipe://\\.\pipe\Test');

MESSAGE('Message created.');

Outstrm := OutMsg.GetStream;

IF ISCLEAR(DOM) THEN

CREATE(DOM);

DOM.load('c:\xmlout\items.xml');

DOM.save('c:\xmlout\test.xml');

DOM.save(Outstrm);

OutMsg.Send(0);

CLEAR(DOM);

CC::MessageReceived(VAR InMessage : Automation)


The Navision Named Pipe Bus Adapter - Server Side Code Example

In this example, we use a single instance codeunit to

  • initialize the Navision Communication Component.

  • create the pipe server so that it is available to all clients.

  • open the pipe in bidirectional mode.

  • handle an incoming message.

  • send a reply if one is expected

For the purpose of this example, we have defined the following global variables:

Variable Name | Data Type | Subtype
ComCom | Automation | 'Navision Communication Component version 2'.CommunicationComponent
NPBA | Automation | 'Navision Named Pipe Bus Adapter'.NamePipeBusAdapter
InMsg | Automation | 'Navision Communication Component version 2'.InMessage
ReplyMsg | Automation | 'Navision Communication Component version 2'.OutMessage
DOM | Automation | 'Microsoft XML, v3.0'.DOMDocument30
InStrm | InStream |
MsgFile | File |
OutStrm | OutStream |
retval | Integer |
Reply | Integer |
FileOutStrm | OutStream |
Ch | Char |

Example

OnRun()

IF ISCLEAR(ComCom) THEN

CREATE(ComCom);

IF ISCLEAR(NPBA) THEN

CREATE(NPBA);

ComCom.AddBusAdapter(NPBA, 0);

NPBA.OpenNamedPipe('Test', 0, 0);

ComCom::MessageReceived(VAR InMessage : Automation)

MESSAGE('Message received.');

InMsg := InMessage;

InStrm := InMsg.GetStream;

CREATE(DOM);

DOM.load(InStrm);

MESSAGE('DOM loaded.');

MsgFile.CREATE('c:\xmlout\MsgFile.txt');

MsgFile.CREATEOUTSTREAM(FileOutStrm);

REPEAT

retval := InStrm.READ(Ch,1);

FileOutStrm.WRITE(Ch);

UNTIL retval = 0;

MsgFile.CLOSE;

Reply := InMsg.ExpectReply;

IF Reply <> 0 THEN

BEGIN

ReplyMsg := InMsg.CreateReply;

OutStrm := ReplyMsg.GetStream;

OutStrm.WRITE('Reply message');

ReplyMsg.Send(0);

END;

InMsg.CommitMessage;


The Navision Socket Bus Adapter - Receiving a Document

In this example, we use a single instance codeunit to initialize the Navision Communication Component, establish contact to a Navision Socket Bus Adapter, open the socket server to check for received messages, and read the message that is received.

For the purpose of this example, we have defined the following variables:

Variable Name | Data Type | Subtype | Length
CC2 | Automation | 'Navision Communication Component version 2'.CommunicationComponent |
SBA | Automation | 'Navision Socket Bus Adapter'.SocketBusAdapter |
InMsg | Automation | 'Navision Communication Component version 2'.InMessage |
InS | InStream |  |
txt | Text |  | 1000

The WithEvents property for the CC2 variable is set to Yes. The socket server uses port 8079 on the local machine.

Example

OnRun()

IF ISCLEAR(CC2) THEN
CREATE(CC2);
IF ISCLEAR(SBA) THEN
CREATE(SBA);

CC2.AddBusAdapter(SBA, 0);
SBA.OpenSocket(8079, '');

CC2::MessageReceived(VAR InMessage : Automation)

InMsg:= InMessage;

InS:= InMsg.GetStream();

WHILE NOT (InS.EOS) DO
BEGIN
InS.READ(txt);
MESSAGE(txt);
END;

InMsg.CommitMessage();

More information:

Navision Socket Bus Adapter

Navision Socket Bus Adapter: Setting Up Interfaces


The Navision Socket Bus Adapter - Sending a Document

In this example, we use a codeunit to initialize the Navision Communication Component, establish contact to the Navision Socket Bus Adapter, open a socket server for the bus adapter and send the message.

For the purpose of this example, we have defined the following variables:

Variable Name | Data Type | Subtype | Length
CC2 | Automation | 'Navision Communication Component version 2'.CommunicationComponent |
SBA | Automation | 'Navision Socket Bus Adapter'.SocketBusAdapter |
OutMsg | Automation | 'Navision Communication Component version 2'.OutMessage |
OutS | OutStream |  |

The socket server uses port 8079 on the local machine.

Example

OnRun()

IF ISCLEAR(CC2) THEN
CREATE(CC2);
IF ISCLEAR(SBA) THEN
CREATE(SBA);

CC2.AddBusAdapter(SBA, 0);
OutMsg:= CC2.CreateoutMessage('Sockets://localhost:8079');

OutS:= OutMsg.GetStream();
OutS.WRITE('First Text');
OutS.WRITE('Second Text');
OutS.WRITE('Third Text');

OutMsg.Send(0);

More information:

Navision Socket Bus Adapter

Navision Socket Bus Adapter: Setting Up Interfaces


The Navision Communication Component

Overview

The Navision Communication Component version 2.0 is the generic interface of Navision. It is an automation server that allows external services to stream data to, for example, Navision Application Server. It also enables Navision to stream data to external services. Function calls can occur synchronously or asynchronously.

The Navision Communication Component ensures that no matter which type of bus adapter you use, the data communication between Navision and the Navision Communication Component is always the same. Although the Named Pipe, Socket and Microsoft Message Queue adapters are supplied with the Navision Communication Component, you can add other transport mechanisms if necessary.

The following diagram provides an overview of how we enable Navision to communicate with the outside world.

When Navision wishes to send a message, it hands this message over to the Navision Communication Component. This in turn hands the message over to the specified bus adapter, which ensures that the message is transported correctly to its destination. Incoming messages are handled in the same way, only in reverse order.

Navision is responsible for processing the contents of the message. The Navision Communication Component controls the various bus adapters. This ensures that a consistent application programming interface (API) is used to access each of them. Each bus adapter implements a specific data transfer method, for example, Named Pipe.

More information:

Code Examples

Bus Adapters

Message Objects

Interfaces

Scenarios


Error Handling

This description of error handling is divided into two subject groups. One group concerns error messages between the application and the components, and between the components themselves. The other group concerns error messages between systems.

Error Messages from Components

All functions return a standard HRESULT that states whether or not the operation was a success. The standard COM ISupportErrorInfo interface provides additional information about errors.

HRESULT errors from the Navision MS-Message Queue Bus Adapter:

MQBA_E_INTERNALERROR | 0x80040200
MQBA_E_REPLYREQ_NO_REPLYQ | 0x80040201
MQBA_E_BADREPLYQ | 0x80040202
MQBA_E_INSUFFMEM | 0x80040203
MQBA_E_BADINTERNAL | 0x80040204
MQBA_E_OUTOFBOUNDS | 0x80040205
MQBA_E_OUTMSGNOTCREATED | 0x80040206
MQBA_E_WRITEQNOTVALID | 0x80040207
MQBA_E_NODATATOSEND | 0x80040208
MQBA_E_BADINTERNAL_CC_POINTER | 0x80040209

Note that the numbers are hexadecimal.

Error Messages between Systems

When a message is delivered successfully to the recipient, but an error occurs at the recipient's end when the message is processed, an error message must be sent to the sender of the message. The Navision Communication Component automatically generates this error message using the error information that is returned on the MessageReceived event. This error information can either be returned by the application in the ExceptInfo parameter of the invoke call, or in a separate ErrorInfo object provided by the ISupportErrorInfo interface.

The error information that is provided is used to make an XML document, which contains this information. Here is an example of such an XML document:

<?xml version="1.0" ?>

<NavisionErrorMsg xmlns="urn:www-Navision-com:NavisionErrorMsg.xml">

<ErrorNo> The error number.

<ErrorMessage> The error message text.

<ErrorSource> The application that caused the error.

<BusAdapterId> The ID of the bus adapter that returns the error.

</NavisionErrorMsg>

Note that all the nodes will not necessarily be filled.

When you use the Navision Communication Component with Navision, the ErrorMessage node returns the C/AL error message as text.


Overview of Interfaces

The system consists of the following interfaces:

The Navision Communication Component/application interface: ICommunicationComponent

The out message interface: IOutMessage

The in message interface: IInMessage

The Navision Named Pipe Bus Adapter version 1.0/application interface: INamedPipeBusAdapter

The MSMQ bus adapter/application interface: IMSMQBusAdapter

The Navision Socket bus adapter interface: ISocketBusAdapter

The following interaction diagram provides an overview of the Navision Communication Component version 2.0 and the bus adapters. Note that each bus adapter has its own interface, but the diagram has been simplified to show all bus adapters and their interfaces in one.


ICommunicationComponent Interface

The ICommunicationComponent interface controls the different bus adapters that you use in your system.

ICommunicationComponent Methods | Description
AddBusAdapter | Initializes the Navision Communication Component version 2.0 and establishes contact with the bus adapter, which is specified in the parameter.
CreateOutMessage | Returns the dispatch interface of an OutMessage object.
Event MessageReceived | The MessageReceived event is raised each time a new message arrives at the Navision Communication Component.


MessageReceived Event

The MessageReceived event is raised each time a new message arrives at the Navision Communication Component.

Parameter: The event has an interface to an InMessage object as the parameter.

More information:

ICommunicationComponent Interface


ICommunicationComponent::AddBusAdapter

Initializes the Navision Communication Component version 2.0 and establishes contact with the bus adapter, which is specified in the parameter.

A second call with another bus adapter establishes contact with this bus adapter and adds that bus adapter to the communication component's list of bus adapters.

Parameter:

pBusAdapter [In] | The dispatch interface of the bus adapter.
Priority[In] | Sets the priority of the bus adapter that is added to the list of adapters.

More information:

ICommunicationComponent Interface


ICommunicationComponent::CreateOutMessage

Returns the dispatch interface of an OutMessage object. If the OutMessage object could not be created, the return value is NULL.

Parameter:

Destination [In]

The syntax for the Destination parameter is:

Bus adapter type://destination

For example, Named pipe://myServer/myPipe

When using the MSMQ Bus Adapter, you set the destination queue either from the CreateOutMessage or from the OpenWriteQueue. It is faster to set the target queue in the OpenWriteQueue if you are going to send several messages. This is because the queue is only opened once. The following examples send a message to the same queue.

Example 1

MQBus.OpenWriteQueue('MyMessageQueueServer\MyQueue',0,0);

OutMsg := CC2.CreateoutMessage('Message queue://'); // Use Queue set in OpenWriteQueue

OutS:= OutMsg.GetStream();

OutS.WRITE('Hello world!');

OutMsg.Send(0);

Example 2

OutMsg := CC2.CreateoutMessage('Message queue://MyMessageQueueServer\MyQueue');

OutS:= OutMsg.GetStream();

OutS.WRITE('Hello world!');

OutMsg.Send(0);

If you have specified the queue in the CreateOutMessage, you set Mode and Protocol in the OutMessage properties. If you have not specified the queue in the CreateOutMessage, the Mode and Protocol used are the ones described in the parameters of OpenWriteQueue. You cannot override the values using the properties in OutMessage.

More information:

ICommunicationComponent Interface


IInMessage Interface

The InMessage is the incoming equivalent of OutMessage. The application receives the InMessage either through the MessageReceived event of ICommunicationComponent interface, or through the SendWaitForReply method of the OutMessage.

The InMessage object has a stream interface through which the application can read data from the object. When the application is finished reading data, the application should call CommitMessage to indicate that the message object is no longer needed.

Method Name | Description
GetStream | Gets the stream interface of the message object.
CommitMessage | Commits that the message has been read.
CreateReply | Creates an OutMessage object that is used to create a reply.

Property Name | Description
ExpectReply | When you set this property to True, you indicate that the sender of the message expects a reply.
Source | This property reveals the IP address of the sender of the message. You use this property to authenticate the sender. Note that the property only can be used for the Navision Socket Bus Adapter.


ExpectReply Property

When you set this property to True, you indicate that the sender expects a reply. This property is valid for synchronous communication.

The default value of this property is False.

More information:

IInMessage Interface


IInMessage::CommitMessage

Commits that the message has been read. After calling CommitMessage, the stream interface is no longer valid.

More information:

IInMessage Interface


IInMessage::CreateReply

Creates an OutMessage object that is used to create a reply.

More information:

IInMessage Interface


IInMessage::GetStream

Gets the stream interface of the message object.

More information:

IInMessage Interface


Source Property

This property reveals the IP address of the sender of the message. You use the property to authenticate the sender.
Note that the property only can be used for the Navision Socket Bus Adapter.

More information:

IInMessage Interface

Navision Socket Bus Adapter


IMSMQBusAdapter Interface

You use the IMSMQBusAdapter interface to set up the bus adapter and establish the message bus.

Method Name | Description
OpenWriteQueue | Opens a queue for sending messages.
GetWriteIMSMQQueue | Returns the MSMQQueue object that is used to write to allow direct manipulation.
OpenReceiveQueue | Opens a queue for receiving messages.
GetReceiveIMSMQQueue | Returns the MSMQQueue object that is used to receive to allow direct manipulation.
CreateQueue | Produces a queue that can send and receive messages.
OpenReplyQueue | Opens a queue to receive reply messages (when you use SendWaitForReply).
Property Name | Description
SenderCertificate | Provides an array of bytes that represent the security certificate.
AdministrationQueue | Provides the name of the AdministrationQueue in case this can be created or used.
SenderAuthenticationLevel | Provides an authentication level that is passed to each message, which is sent through this bus adapter.
ReceiverAuthenticationLevel | Requests an authentication level for each incoming message.
WriteTimeout | Provides a maximum time in seconds for an application to read the messages sent by this bus adapter.
ReceiveTimeout | [In, Out] Provides a maximum time in milliseconds for the bus adapter to receive a message.
RemoveWhenCommit | [In, Out] Sets the bus adapter to either remove or not to remove the message from the Journal Queue when an InMessage is committed.


AdministrationQueue Property

[In, Out] This property provides the name of the AdministrationQueue in case this can be created or used. By default, it is set on entry to ".\\NSAdminReceiveQueue." The administration queue is used for debugging purposes.

You must never use the name ".\\NSAdminReceiveQueue" for other purposes. When your environment has been set up correctly, you must always set this property to an empty string.

More information:

IMSMQBusAdapter Interface


IMSMQBusAdapter::CreateQueue

Creates a queue that can send and receive messages. You use the OS protocol to create the queue.

Parameter:

[In] PathName

The name of the queue in MachineName\QueueName format.

The pathname of the queue provides the information Message Queuing needs to create or open the queue. The pathname of the queue specifies the name of the computer where the messages in the queue will be stored, an optional PRIVATE$ keyword that indicates if the queue is a private queue, and the name of the queue. The application must provide a unique pathname when the queue is created.

Examples of the PathName Syntax

"myMachine\myPublicQueue"

"otherMachine\otherPublicQueue"

"myMachine\Private$\myPrivateQueue"

As a shortcut, you can use "." to indicate your local machine. Therefore, you could specify myPublicQueue and myPrivateQueue on your local machine as:

.\myPublicQueue

.\Private$\myPrivateQueue

Public/Private Queues

A public queue is a queue that is registered in the directory service that any Message Queuing application can locate. Public queues are persistent. You can make a backup of their registration information, which makes them suitable for long-term use.

A private queue is a queue that is registered on the local computer (not in the directory service) that other applications typically cannot locate. Private queues have the advantage of having no directory service overhead. This means that they are faster to create, there is no latency and no replication. Further, they can be created and deleted when the directory service is not working.

More information:

IMSMQBusAdapter Interface


IMSMQBusAdapter::GetReceiveIMSMQQueue

Returns the MSMQQueue object that is used to receive to allow direct manipulation.

More information:

IMSMQBusAdapter Interface


IMSMQBusAdapter::GetWriteIMSMQQueue

Returns the MSMQQueue object that is used to write to allow direct manipulation.

More information:

IMSMQBusAdapter Interface


IMSMQBusAdapter::OpenReceiveQueue

Opens a queue for receiving messages. If the queue does not exist and the protocol is set to OS, the method tries to create a queue and fails if this is not possible.

Parameter:

[In] Name

The name of the queue in one of the following:

  • MachineName\QueueName (OS or PathName)

  • IPAddress\QueueName (TCP)

  • SPXAddress\QueueName (SPX)

[In] Protocol

Refers to the network protocol you must use when you connect to the queue. The options are:

  • 0: OS (default value) - any machine name supported by the underlying operating system. For Microsoft Windows NT4, it is either UNC or DNS.

  • 1: TCP (TCP/IP) - Internet address notation (IP address).

  • 2: SPX - network number and host number (separated by the ":" character).

[In] Mode

Reflects the mode in which the queue will be opened. The mode options are:

  • 0: DIRECT (default value) - see the MSDN Platform SDK (Opening Queues with a Direct Format Name) for further information.

  • 1: PRIVATE

  • 2: PUBLIC

When the protocol contains a value that has no meaning, the default OS protocol is used. When you set Mode to DIRECT, a FormatName (see below) is used. Any other Mode uses a PathName.

FormatName

You use direct format names to reference public or private queues without accessing the directory. You can use direct format names when performing the following operations:

  • Sending a message directly to a computer.

  • Sending a message to computers on the Internet.

  • Sending messages in a workgroup environment.

  • Reading messages in a workgroup environment.

The general format of direct format names is shown below. Note that you can directly access public, private and (for MSMQ 2.0 clients and servers) computer system queues.

FormatName Syntax Examples

AddressSpecification\QueueName (for public queues)

AddressSpecification\PRIVATE\QueueName (for private queues)

AddressSpecification\SYSTEM$,computersystemqueue (introduced in MSMQ 2.0 for computer journal and dead-letter queues)

157.18.3.1\myQueue (Mode Direct, Protocol TCP)

elvisp.ms.com\myQueue (Mode Direct, Protocol OS)

00000012:00a0234f7500\myQueue (Mode Direct, Protocol SPX, supported only on Windows NT4 and Windows 2000)

More information:

IMSMQBusAdapter Interface


IMSMQBusAdapter::OpenReplyQueue

Opens a queue to receive reply messages (when you use SendWaitForReply). If the queue does not exist and the protocol is set to OS, the method tries to create a queue and fails if this is not possible.

Parameter:

[In] Name

The name of the queue in one of the following:

  • MachineName\QueueName (OS or PathName)

  • IPAddress\QueueName (TCP)

  • SPXAddress\QueueName (SPX)

[In] Protocol

Refers to the network protocol that you must use when you connect to the queue. The options are:

  • 0: OS (default value) - any machine name supported by the underlying operating system. For Microsoft Windows NT4, it is either UNC or DNS.

  • 1: TCP (TCP/IP) - Internet address notation (IP address).

  • 2: SPX - network number and host number (separated by the ":" character).

[In] Mode

Reflects the mode in which the queue will be opened. The mode options are:

  • 0: DIRECT (default value) - see the MSDN Platform SDK (Opening Queues with a Direct Format Name) for further information.

  • 1: PRIVATE

  • 2: PUBLIC

When the protocol contains a value that has no meaning, the default OS protocol is used. When you set Mode to DIRECT, a FormatName is used. Any other Mode uses a PathName.

More information:

IMSMQBusAdapter Interface


IMSMQBusAdapter::OpenWriteQueue

Opens a queue for sending messages.

Parameter:

[In] Name

This is the name of the queue in one of the following:

  • MachineName\QueueName (OS or PathName)

  • IPAddress\QueueName (TCP)

  • SPXAddress\QueueName (SPX)

[In] Protocol

Refers to the network protocol that you must use when you connect to the queue. The options are:

  • 0: OS (default value) - any machine name supported by the underlying operating system. For Microsoft Windows NT4, it is either UNC or DNS.

  • 1: TCP (TCP/IP) - Internet address notation (IP address).

  • 2: SPX - network number and host number (separated by the ":" character).

[In] Mode

Reflects the mode in which the queue is opened. The mode options are:

  • 0: DIRECT (default value) - see the MSDN Platform SDK (Opening Queues with a Direct Format Name) for further information.

  • 1: PRIVATE

  • 2: PUBLIC

When the protocol contains a value that has no meaning, the default OS protocol is used. When you set Mode to DIRECT, a FormatName is used. Any other Mode will use a PathName.

More information:

IMSMQBusAdapter Interface


ReceiveTimeout Property

[In, Out] This property provides a maximum time in milliseconds for the bus adapter to receive a message:

  • when an event is raised from the Message Queue to that bus adapter.

  • from the Journal Queue.

More information:

IMSMQBusAdapter Interface


ReceiverAuthenticationLevel Property

[In, Out] This property requests an authentication level for each incoming message. There are two levels:

  • 0: No authentication is used. This is the default value. The receiving queue accepts both authenticated and non-authenticated messages.

  • 1 (or any value different from 0): Authentication is required. The receiving queue only accepts authenticated messages.

You cannot change the authentication level when direct connections are used.

More information:

IMSMQBusAdapter Interface


RemoveWhenCommit Property

[In, Out] This property sets the bus adapter to either remove or not to remove the message from the Journal Queue when an InMessage is committed. The values can be:

  • 0: No receive is made. Messages are not removed from the Journal Queue.

  • 1 (or any value different from 0. This is the default value.): Messages are removed from the Journal Queue when InMessages are committed.

More information:

IMSMQBusAdapter Interface


SenderAuthenticationLevel Property

[In, Out] Provides an authentication level that is passed to each message, which is sent through this bus adapter. There are four authentication levels:

  • 0: No authentication is used. This is the default value.

  • 1: Always. Message Queuing at run-time signs the message based on the authentication registry key being sent. (See Microsoft's documentation on the Message Queuing technology.)

  • 2: MSMQ 1.0. The message is signed using an MSMQ 1.0 signature.

  • 3: MSMQ 2.0. The message is signed using an MSMQ 2.0 signature. Signing requires that MSMQ 2.0 is installed on all involved systems.

More information:

IMSMQBusAdapter Interface


IMSMQBusAdapter::SenderCertificate Property

[In, Out] This property provides an array of bytes that represents the security certificate. This security certificate is used to authenticate messages.

More information:

IMSMQBusAdapter Interface


WriteTimeout Property

[In, Out] This property provides a maximum time in seconds for an application to read the messages sent by this bus adapter. That is, it is not the time by which a message must reach the queue. If you set this property to 0, its default value, the message stays in the queue until it is picked up.

More information:

IMSMQBusAdapter Interface


Navision Named Pipe Bus Adapter Interface

The INamedPipeBusAdapter interface manages the bus adapter and establishes the message bus.

INamedPipeBusAdapter Methods | Description
OpenNamedPipe | Creates the pipe server so that clients can connect to it.
AddUserToPipe | Gives a user permission to connect to the named pipe server.
RemoveUserFromPipe | Removes a user from the pipe server.


INamedPipeBusAdapter::AddUserToPipe

Gives a user permission to connect to the named pipe server.

More information:

INamedPipeBusAdapter Interface


INamedPipeBusAdapter::OpenNamedPipe

Creates the named pipe server so that clients can connect to it.

Parameter:

NameOfPipe [In] |
ShareMode [In] | 0: The pipe is available to everyone. 1: The pipe is only available to selected users. See the AddUserToPipe method.
OpenMode [In] | 0: Duplex. Opens the pipe in bi-directional mode. 1: Inbound. Read mode. Data flows to the pipe server from the client. 2: Outbound. Write mode. Data flows from the pipe server to the client.

More information:

INamedPipeBusAdapter Interface


INamedPipeBusAdapter::RemoveUserFromPipe

Removes a user from the pipe server.

More information:

INamedPipeBusAdapter Interface


IOutMessage Interface

The OutMessage object is the object that is returned to the application when the latter calls CreateOutMessage on the ICommunicationComponent interface. The object allows the application to write data to the object's stream interface. When the application finishes writing data to the message, the message can be sent to the message bus using one of two methods. The Send method sends the message whereas SendWaitForReply sends the message and waits until it receives a reply from the recipient of the message.

IOutMessage Methods | Description
GetStream() | Gets the stream interface of the message contents.
Send(Timeout) | Sends the message to the message bus.
SendWaitForReply | Sends the OutMessage object and waits for an InMessage object containing a reply.

Property Name | Description
Priority | Sets the priority of the message.
Protocol | Denotes the network protocol that is used when you connect to the queue that will send your message.
Mode | Reflects the mode in which the queue is opened that will send the message.


IOutMessage::GetStream

Gets the stream interface of the message contents.

More information:

IOutMessage Interface


IOutMessage::Send

Sends the message to the message bus. If the message arrives correctly at the message bus, the function returns True.

After calling Send, any stream interface returned by GetStream is no longer valid.

Parameter:

Timeout

The time in milliseconds in which the function tries to deliver the message to the message bus.

When the function is set to zero, it will wait until the OutMessage is delivered to the message bus.

More information:

IOutMessage Interface


IOutMessage::SendWaitForReply

Sends the OutMessage object and waits for an InMessage object containing a reply.

Parameter:

Timeout

The time in milliseconds that the function will wait.

When the function is set to zero, it will wait until the InMessage is received.

More information:

IOutMessage Interface


Mode Property

Reflects the mode in which the queue is opened that will send the message. The mode options are:

0: DIRECT (default value)

1: PRIVATE

2: PUBLIC

Some bus adapters ignore this parameter. It is only used when the OutMessage was created as a reply to an InMessage.

More information:

IOutMessage Interface


Priority Property

Sets the priority of the OutMessage. If this value is zero, the parameter is ignored.

Some bus adapters ignore this parameter.

More information:

IOutMessage Interface


Protocol Property

Refers to the network protocol that is used when you connect to the queue that will send your message. The protocol options are:

0: OS (default value)

1: TCP (TCP/IP)

2: SPX

Some bus adapters ignore this parameter. It is only used when the OutMessage was created as a reply to an InMessage.

More information:

IOutMessage Interface


The Navision Socket Bus Adapter Interface

The ISocketBusAdapter interface manages the bus adapter and establishes the message bus.

ISocketBusAdapter Methods | Description
OpenSocket | Creates the socket server so that clients can connect to it.

ISocketBusAdapter Properties

Description

Port

Number that describes the port that the bus adapter interface will use.

Address

String that refers to the IP address or host name.

CloseSendWhenWaitForReply

If you set this property to Yes, the bus adapter interface will be able to send a single message. When one message has been sent, the interface will only be able to receive messages.

ReceivingTimeout

This property determines the maximum amount of time (in seconds) the bus adapter interface will wait between reading consecutive TCP packets.

Use a value bigger than 0 if you receive partial information. This depends on your network conditions.

Note that this property is different from the use of timeout in InMessage and OutMessage.

HTTPHeaderReceive

This property is normally used in connection with ReceivingTimeout. When it is set to Yes, the bus adapter will expect to receive HTTP headers and it will return a message when the HTTP headers have been received. This is useful when you write multi-bounce protocols that use the 100 Continue HTTP status, such as SOAP.

BytesToRead

Forces the bus adapter interface to finish reading when at least this number of bytes have been received. This does not override other timeout settings.

More information:

Navision Socket Bus Adapter: Setting Up Interfaces


Address Property

Use this property to refer to the IP address or host name of a socket bus adapter interface.

More information:

The Navision Socket Bus Adapter Interface


BytesToRead Property

Use this property to force the bus adapter interface to finish reading when at least this number of bytes have been received. This does not override other timeout settings.

More information:

The Navision Named Pipe Bus Adapter Interface


CloseSendWhenWaitForReply Property

If you set this property to Yes, the bus adapter interface will be able to send a single message. When one message has been sent, the interface will only be able to receive messages.

More information:

The Navision Socket Bus Adapter Interface


ISocketBusAdapter::OpenSocket

This method creates the socket server so that clients can connect to it.

More information:

The Navision Socket Bus Adapter Interface


HTTPHeaderReceive Property

This property is normally used in connection with the ReceiveTimeout Property property. When it is set to Yes, the bus adapter will expect to receive HTTP headers and it will return a message when the HTTP headers have been received. This is useful when you write multi-bounce protocols that use the 100 Continue HTTP status, such as SOAP.

More information:

The Navision Socket Bus Adapter Interface


Port Property

This property specifies the number of the port that the socket bus adapter interface will use.

More information:

The Navision Socket Bus Adapter Interface


ReceivingTimeout Property

This property determines the maximum amount of time (in seconds) the bus adapter interface will wait between reading consecutive TCP packets.

Use a value bigger than 0 if you receive partial information. This depends on your network conditions.

Note that this property is different from the use of timeout in InMessage and OutMessage.

More information:

The Navision Socket Bus Adapter Interface


Message Objects

InMessage and OutMessage are extendable COM objects.

InMessage

This is an incoming message. Whenever a bus adapter receives an incoming message, it transfers the message to the communication component. This fires a COM event with the message as the parameter.

OutMessage

This is an outgoing message. It is created using the CreateOutMessage function on the Navision Communication Component object, or by using the CreateReply method on the InMessage object. To add contents to the message, the save method on the Microsoft XML DOM (or any other object that can write to a COM IStream interface) can write data directly to the message.

When sending a message, you must choose either to wait for the message to be handed over to the message transportation service, or to wait for a response from the recipient of the message.

More information:

IInMessage Interface

IOutMessage Interface


Navision Socket Bus Adapter: Scenario

When you use the Navision Socket Bus Adapter, you have to adapt the interfaces to handle the reactions that protocols usually trigger.

In this scenario, you have designed a solution that uses Commerce Gateway, the Navision Communication Component and Navision Socket Bus Adapters to allow two products, Navision and Axapta clients, to exchange information through the Internet. You are now setting up a communication channel between the two bus adapters where the Navision client sends a document to the Axapta client.

When you test your product, you find that the receiving bus adapter doesn't close the IStream to start processing the information even though the message is in fact received in full. Since the recipient does not acknowledge the receipt, the sending bus adapter thinks that the message has not been properly received and resends the message. This loop continues almost indefinitely.

The solution is to set up the receiving interface to time out after a defined number of milliseconds and to return an acknowledgement of the receipt to the sending bus adapter. The sending bus adapter must have the CloseSendWhenWaitForReply property set to Yes, and you must ensure that the receiving bus adapter does indeed send a reply (acknowledgement).

Code Example

Your receiving bus adapter should be set up as described in the following lines of code.

First, you set up the system to receive on port 8080:

CREATE(CC2);
CREATE(SBA);
CC2.AddBusAdapter(SBA, 0);
//Wait up to 20 seconds between TCP packets
SBA.ReceivingTimeout:= 20000;
//Open port 8080 to receive data
SBA.OpenSocket(8080, '');

Your Receiving event should read the data as usual:

...
CREATE(DOM);
IF (DOM.load(InMsg.GetStream())) THEN
BEGIN
DOM.save(txtFileName);
IF (InMsg.ExpectReply) THEN
BEGIN
// Reply with the same XML as you received
OutMsg:= InMsg.CreateReply();
DOM.save(OutMsg.GetStream());
OutMsg.Send(0);
END;
END;
...

Your sending (and reply-receiving) part should be something like this:

CREATE(CC2);
CREATE(SBA);
CREATE(DOM);

CC2.AddBusAdapter(SBA, 0);
OutMsg:= CC2.CreateoutMessage('Sockets://localhost:8080');

If (DOM.load(txtFileName)) THEN
BEGIN
DOM.save(OutMsg.GetStream());

// Prevent waiting for the reply
SBA.CloseSendWhenWaitForReply:= TRUE;
InMsg:= OutMsg.SendWaitForReply(20000);
IF (ISCLEAR(InMsg)) THEN
ERROR(Text1000);

DOM.load(InMsg.GetStream());
DOM.save(txtFileName);
InMsg.CommitMessage();
END;

where Text1000 = The message was not received.

More information:

Navision Socket Bus Adapter

Navision Socket Bus Adapter: Setting Up Interfaces

Code Example: Sending a Document

Code Example: Receiving a Document


Navision Socket Bus Adapter: Setting Up Interfaces

The Navision Socket Bus Adapter comes with four interface properties that you can use to simplify the protocol implementation: CloseSendWhenWaitForReply, ReceivingTimeout, BytesToRead and HTTPHeaderReceive.

Note that you must set up properties in both your sending and your receiving bus adapter in order for the system to work properly. For an example of how to use the interface properties, see the Navision Socket Bus Adapter Scenario.

Receiving Interface

In the receiving bus adapter, in the RecevingTimeout property, you must set a large number, for example 20000. This tells the interface and MSDOM to wait no more than 20 seconds between TCP packets. For more information about TCP packets and windows, see Microsoft MSDN and third party documentation.

If there are more than 20 seconds between packets, the bus adapter will consider the transmission complete and start processing the information.

You must also check if the sending bus adapter expects a reply, and if so, then you must send an acknowledgement of receipt.

You can combine this with one of the following properties to force the interface to stop receiving and start processing:

  • In the BytesToRead property, set the number of bytes that will be received.

  • Set the HTTPHeaderReceive property to Yes, if you intend to receive HTTP headers only.

Sending Interface

In the sending bus adapter, in the The IOutMessage Interface, use the SendWaitForReply method to indicate the number of milliseconds that the bus adapter should wait for an acknowledgement of receipt before timing out, and then set the CloseSendWhenWaitForReply property to Yes. This means that when the sending bus adapter has sent its message, it will close the socket for sending and concentrate on waiting for an actual reply to the sent message.

When the sending bus adapter closes its sending channel, the receiving interface will know that it cannot expect more information in this message , it will stop listening and start processing the information, provided that you set it up as described in the previous section.

Note that if you use a Simple Send, the connection will be closed anyway, so the CloseSendWhenWaitForReply property is irrelevant.

Note also that the ExpectReply property in the IInMessage interface for the Navision Socket Bus Adapter will always return TRUE.

More information:

Navision Socket Bus Adapter

Navision Socket Bus Adapter: Scenario

Code Example: Sending a Document

Code Example: Receiving a Document