.. highlightlang:: us

.. index:: DdeInitiate

.. _ddeinitiate:

DdeInitiate
===========

.. us.tag  DdeInitiate ENGLISH

:ref:`DdeInitiate` initiates a DDE conversation between UniPlot and another
application.

.. function::  hConv = DdeInitiate(ssService, ssTopic)

.. us.return

**Return Value**

*hConv* is the channel number (handle) which is used with other UniPlot DDE
functions. If an error occurred, the function returns 0.

.. us.params

**Parameters**

.. uparam:: ssService

   *ssService* is a service name. Normally, *ssService* is the name of an EXE 
   file without the extension. The service name for UniPlot is ``"UniPlotSL"``.

.. uparam:: ssTopic

   *ssTopic* is the topic of the conversation. For most applications the names of
   already open documents are allowed topics. Most applications support the
   topic "system".

.. us.comment

**Comment**

A list of all open DDE channels can be received by calling the function
:ref:`ObjShow`.

.. us.example

**Example**

The following DDE conversation starts Excel and inserts the
numbers 1,2,3,4 into an Excel spreadsheet.

At first the function :ref:`system` starts Excel. The value 0 of the third
parameter causes the function to return immediately.

::

   def FindApp(ssApp)
   {
       RegConnect("HKEY_LOCAL_MACHINE")
       b = RegOpen("Software\Classes\" + ssApp + "\CLSID");
       s = RegGetValue("");
       RegOpen("Software\Classes\CLSID\" + s + "\LocalServer32")
       return RegGetValue("");
   }
   s = FindApp("Excel.Application");
   if (s == "") {
       MessageBoxError("Excel not found");
       return;
   }
   system(s, SW_SHOW, 0);

The following function call opens a channel to the topic ``"System"``.

::

   hConv = DdeInitiate("Excel", "System");

DdeRequest requests the system topics.

::

   ssTopics = DdeRequest(hConv, "Topics");

The following function call opens a channel to the first topic
(the first Excel spread sheet).

::

   hConvTable = DdeInitiate("Excel", strtok(ssTopics, "\t")[1]);

The function DdePoke writes the numbers 1,2,3,4 into the first
Excel spread sheet. In the English Excel version, cell range is
specified as ``R1C1:R2C2`` (Row/Column) In the German Excel version,
cell range is specified as Z1S1:Z2S2 (Row/Column). The numbers in a
row are separated by tab characters (``"\t"``), rows are separated by the
character sequence ``"\r\n"``.

::

   DdePoke(hConvTable, "R1C1:R2C2", "1\t2\r\n3\t4")

When the conversation is finished, all channels should be closed.

::

   DdeTerminate(hConvTable);
   DdeTerminate(hConv);

.. us.example

**Example**

.. include:: ../include/test_DdeExecute.ic

.. seealso::
   :ref:`overview-dde`,
   :ref:`DdeTerminate`,
   :ref:`DdeTerminateAll`,
   :ref:`DdePoke`,
   :ref:`DdeExecute`,
   :ref:`DdeRequest`,
   :ref:`system`,
   :ref:`ObjShow`

:sub:`id-1361586`