DDEInitiate() function - MapBasic - 2023

Purpose

Initiates a new DDE conversation, and returns the associated channel number.

Syntax

DDEInitiate( appl_name, topic_name )

appl_name is a string representing an application name (for example, "MapInfo").

topic_name is a string representing a topic name (for example, "System").

Return Value

Integer

Description

The DDEInitiate() function initiates a DDE (Dynamic Data Exchange) conversation, and returns the number that identifies that conversation's channel.

A DDE conversation allows two Microsoft Windows applications to exchange information. Once a DDE conversation has been initiated, a MapBasic program can issue DDERequest$() function calls (to read information from the other application) and DDEPoke statements (to write information to the other application). Once a DDE conversation has served its purpose and is no longer needed, the MapBasic program should terminate the conversation through the DDETerminate statement or DDETerminate All statement.

The appl_name parameter identifies a Windows application. For example, to initiate a conversation with Microsoft Excel, you should specify the appl_name parameter "Excel." The application named by the appl_name parameter must already be running before you can initiate a DDE conversation; note that the MapBasic Run Program statement allows you to run another Windows application. Not all Windows applications support DDE conversations. To determine if an application supports DDE conversations, see the documentation for that application.

The topic_name parameter is a string that identifies the topic for the conversation. Each application has its own set of valid topic names; for a list of topics supported by a particular application, refer to the documentation for that application. With many applications, the name of a file that is in use is a valid topic name. Thus, if Excel is currently using the worksheet file "ORDERS.XLS", you could issue the following MapBasic statements:

Dim i_chan As Integer
i_chan = DDEInitiate("Excel", "C:\ORDERS.XLS")

to initiate a DDE conversation with that Excel worksheet.

Many applications support a special topic called "System". If you initiate a conversation using the "System" topic, you can then use the DDERequest$() function to obtain a list of the strings which the application accepts as valid topic names (for example, a list of the files that are currently in use). Knowing what topics are available, you can then initiate another DDE conversation with a specific document. See the example below.

The following table lists some sample application and topic names which you could use with the DDEInitiate() function.

DDEInitiate("Excel", "System")

DDEInitiate("Excel", wks)

DDEInitiate("MapInfo", "System")

DDEInitiate("MapInfo" mbx)

When a MapBasic program issues a DDEInitiate() function call, the MapBasic program is known as the "client" in the DDE conversation. The other Windows application is known as the "server." Within one particular conversation, the client is always the active party; the server merely responds to actions taken by the client. A MapBasic program can carry on multiple conversations at the same time, limited only by memory and system resources. A MapBasic application could act as the client in one conversation (by issuing statements such as DDEInitiate(), etc.) while acting as the server in another conversation (by defining a RemoteMsgHandler procedure).

Error Conditions

ERR_CMD_NOT_SUPPORTED (642) error generated if not running on Windows.

ERR_INVALID_CHANNEL (696) error generated if the specified channel number is invalid.

Example

The following example attempts to initiate a DDE conversation with Microsoft Excel, version 4 or later. The goal is to store a simple text message ("Hello from MapInfo!") in the first cell of a worksheet that Excel is currently using, but only if that cell is currently empty. If the first cell is not empty, we will not overwrite its current contents.

Dim chan_num, tab_marker As Integer
Dim topiclist, topicname, cell As String 

chan_num = DDEInitiate("EXCEL", "System")
If chan_num = 0 Then
	Note "Excel is not responding to DDE conversation." 
	End Program 
End If 

' Get a list of Excel's valid topics 
topiclist = DDERequest$(chan_num, "topics")

' If Excel 4 is running, topiclist might look like: 
'		": Sheet1 System" 
' (if spreadsheet is still "unnamed"),or like: 
'		": C:Orders.XLS Sheet1 System" 
' 
' If Excel 5 is running, topiclist might look like: 
'		"[Book1]Sheet1 [Book2]Sheet2 ..." 
'
' Next, extract just the first topic (for example,"Sheet1")
' by extracting the text between the 1st & 2nd tabs; 
' or, in the case of Excel 5, by extracting the text
' that appears before the first tab. 

If Left$(topiclist, 1) = ":" Then 
	' ...then it's Excel 4. 
	tab_marker = InStr(3, topiclist, Chr$(9) ) 
	If tab_marker = 0 Then
		Note "No Excel documents in use! Stopping."
		End Program
	End If
	topicname = Mid$(topiclist, 3, tab_marker - 3)
	Else 
		' ... assume it's Excel 5. 
		tab_marker = Instr(1, topiclist, Chr$(9) ) 
		topicname = Left$( topiclist, tab_marker - 1) 
	End If 

' open a channel to the specific document
' (e.g., "Sheet1")
DDETerminate chan_num 
chan_num = DDEInitiate("Excel", topicname) 
If chan_num = 0 Then 
	Note "Problem communicating with " + topicname End Program
End If

' Let's examine the 1st cell in Excel.
' If cell is blank, put a message in the cell.
' If cell isn't blank, don't alter it - 
' just display cell contents in a MapBasic NOTE.
' Note that a "Blank cell" gets returned as a 
' carriage-return line-feed sequence:
'		Chr$(13) + Chr$(10). 
cell = DDERequest$( chan_num, "R1C1" ) 
If cell <> Chr$(13) + Chr$(10) Then
	Note
		"Message not sent; cell already contains:" + cell
	Else 
		DDEPoke chan_num, "R1C1", "Hello from MapInfo!"
		Note "Message sent to Excel,"+topicname+ ",R1C1."
	End If 
DDETerminateAll 

See Also: