Release 10.1A: OpenEdge Development:
Progress 4GL Reference

> ## DDE INITIATE statement

> ##
> (Windows only)

> Opens a dynamic data exchange (DDE) client conversation for a specified DDE server application and topic, and associates the new conversation with a Progress frame. To identify the conversation, the statement returns an integer as a unique channel number for this conversation.

> Note: Does not apply to SpeedScript programming.

> #### Syntax

>     DDE INITIATE ddeid FRAME frame-handle
>       APPLICATION server-name TOPIC topic-name [ NO-ERROR ]

> ``ddeid-var``

> An integer variable or field that receives the channel number for the newly opened DDE conversation.

> `FRAME `frame-handle``

> Specifies the handle of the frame that owns the conversation, where `frame-handle` is a widget handle expression. A frame can own more than one conversation. Progress records the status of the most recent conversation exchange in a set of DDE frame attributes. These attributes record the status of every dynamic data exchange, including advise exchanges (exchanges triggered by DDE-NOTIFY events). The DDE frame attributes include:

> - DDE-ERROR — The DDE error code returned by the most recent exchange.
> - DDE-ID — The channel number of the conversation that had the most recent exchange.
> - DDE-ITEM — The name of the data item referenced by the most recent exchange.
> - DDE-NAME — The name of the server application in the most recent exchange.
> - DDE-TOPIC — The name of the topic of the most recent exchange.
> `APPLICATION `server-name``

> Specifies the name of the server application for the conversation, where `server-name` is a character expression. The value of `server-name` must be unique for each DDE server on your system. It is usually the filename of the server executable without the extension (for example, the name EXCEL in Microsoft Excel).

> `TOPIC `topic-name``

> Specifies the name of the topic of the conversation, where `topic-name` is a character expression. The value of `topic-name` identifies a category defined by the server application. This is usually the name of a file or other container that includes one or more data items (for example, the name of a worksheet, such as Sheet1 in Microsoft Excel). An OpenEdge client can only exchange data with server data items included in the topic of an open conversation.

> `NO-ERROR`

> By default, if the statement fails to open a conversation, it sets the Progress error condition and posts the error to the DDE frame DDE-ERROR attribute. If you specify NO-ERROR, the statement does not set the Progress error condition but does post the error to the DDE frame.

> Example

> The following fragment shows a typical use of the DDE INITIATE statement. It assumes that the Microsoft Excel application is running, and has created the default Excel worksheet, Sheet1. It then uses the DDE INITIATE statement to open a conversation with Sheet1 as the topic. This allows Progress to exchange data with the cells of the worksheet. In this example, the fragment assigns column headings to the top row of the first three columns in the worksheet:

>     DEFINE VARIABLE Sheet1 AS INTEGER.        /* DDE-ID to worksheet topic */
>     DEFINE VARIABLE DDEframe AS WIDGET-HANDLE. /* DDE frame handle         */

>     CREATE FRAME DDEframe.                     /* Create DDE frame.       */
>                            .
>                            .
>                            .
>     /* Open a DDE conversation with Sheet1 and assign column headings. */

>     DDE INITIATE Sheet1 FRAME DDEframe APPLICATION "Excel" TOPIC "Sheet1".
>     DDE SEND Sheet1 SOURCE "Name"      ITEM "R1C1".
>     DDE SEND Sheet1 SOURCE "YTD Sales" ITEM "R1C2".
>     DDE SEND Sheet1 SOURCE "State"     ITEM "R1C3".
>                            .
>                            .
>                            .

> #### Notes

> - The specified DDE server application must be running on the Windows desktop before you can invoke the DDE INITIATE statement.

> - You can close a DDE conversation in three ways: use the DDE TERMINATE statement, leave the scope of the frame that owns the conversation, or terminate the server application or topic associated with the application.

> - For more information on using the DDE protocol (including DDE frame attributes) to exchange data with non-OpenEdge applications, see OpenEdge Development: Programming Interfaces .

> #### See also

> DDE TERMINATE statement

Copyright © 2005 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095