DDE-Dynamic Data Exchange

For BBj-specific information, see DDE-Dynamic Data Exchange - BBj.

Introduction

DDE is a protocol built into Microsoft Windows that allows users to share data between applications, either on a local machine or across a Windows Network connection. Visual PRO/5 offers a low-level interface to this protocol. Visual PRO/5 programmers can write code that takes advantage of DDE as a client accessing non-Visual PRO/5 applications. Visual PRO/5 only supports the CF_TEXT data format.

As the name suggests, DDE is a method for Windows applications to communicate with one another and share information in a dynamic fashion. It can be thought of as a conversation between two programs. The first program will initiate the conversation by asking a question and the second will oblige by sending the answer. The conversation continues until one of the applications closes the connection.

Uses of DDE

DDE is usually used to share data between two applications, but can also be used to send commands to another application. For example, you could use DDE to allow Visual PRO/5 to get the year-to-date sales from an Excel spreadsheet. Another use would be the manipulation of the Windows Program Manager groups. DDE will allow Visual PRO/5 to create and delete groups, as well as add, delete, and modify programs within the group. Another possible use would involve a Visual PRO/5 application starting up Microsoft Word, running a macro, and then retrieving the pertinent information for use in the application. A Visual PRO/5 program can be written to act as a DDE client to any DDE server application running on any machine on the network. A few of the applications that support DDE under Windows are Microsoft's Word, Excel, Visual Basic, and Program Manager, as well as other programs such as JSB's Multiview.

Windows, Client, and Server

When an application initiates the DDE process, the application is said to be the client because it requests information from another application. The other application is called the server because it provides its services to a DDE client. Despite what the name implies, a client and server communicating through DDE never talk directly to each other. Rather, they send messages to Windows, which passes the information on to the correct destination. Because of this, the world of DDE encompasses entire networks and is not limited to a single workstation. With DDE it is possible for a Windows application on one machine to send data to an application that is running on another workstation, provided that they are on the same network. Additionally, it is possible for a single application to participate in multiple DDE conversations simultaneously. This flexibility allows a Visual PRO/5 program to communicate with many other programs - both as a DDE server and as a DDE client.

Protocol

As with most communications, a set of rules applies to determine how and when data is sent. These rules determine the protocol that is used to govern the exchange of data. DDE requires its own protocol to oversee the communication between applications. This protocol outlines the procedures used to start and end a DDE session, send data to another application, receive data from another application, and instruct another application to execute a macro or command. There are relatively few parameters that constitute this protocol, making DDE communications fairly elementary.

Conversation Elements

Before attempting to perform a DDE conversation between Visual PRO/5 and another application, there are a few essential communication elements that must be determined. These components specify the application you want to converse with as well as the subject, or data, that you are interested in sharing.

Application

This is the program with which Visual PRO/5 wants to converse. In order to initiate a conversation with another application, you have to know the name of the other program. This is the name of the other executable, minus the .exe extension. As an example, if you were opening a DDE link with the Windows Program Manager, the application name would be PROGMAN. If the other application is not running, you will not be able to connect to it and will most likely get an !ERROR=70. It is the programmer's responsibility to ensure that the other application is running. If it is not, you should invoke it using the SCALL() function.

Topic

This is the data topic that is designated for DDE access from the DDE Server application. This field is predetermined by the server application as an object that it would like to share. For example, if you were going to communicate with an Excel spreadsheet via DDE, the topic of the conversation would be the name of the spreadsheet file with which you wish to exchange data.

Item

This is the specific piece of information that you are trying to read. Using the Excel example, the item would be the specific cell on the worksheet. If you wanted to find out what programs were defined in the Accessories group in the Windows Program Manager, you would use the group name "accessories" for the item.

In order to use DDE successfully, the programmer must have all the information pertaining to the remote application in advance. In other words, you cannot carry out a DDE conversation unless you know the topics that are shared and the nature of the items. This can limit the usefulness and capabilities that DDE provides. For example, you may want to get information from your Excel spreadsheet, but without knowing what Excel expects for DDE topics and items you cannot communicate with it at all.

DDE Basics

OPEN

Visual PRO/5 supports two forms of DDE:

  • Local DDE, which allows conversations between applications on a single workstation

  • Network DDE, which allows conversations with local or remote applications on a Microsoft Windows Network.

These two protocols behave in the same way; only the syntax used to open a channel differs. Either form of the OPEN call has the same result: a DDE conversation is established with another application.

Under local DDE (MODE="DDECLIENT"), the target to OPEN is passed as a topic name and an optional service name. The service name typically specifies a DDE-aware application with which the program wants to converse. If the service name is wildcarded (passed as an asterisk "*") or omitted, a DDE connection will be opened with the first available service that offers information on the specified topic. The following is an example of the syntax for a local OPEN:

OPEN (CHAN,MODE="DDECLIENT")"[service:]topic"

Under network DDE (MODE="NDDECLIENT"), the target to OPEN is passed as a DDE share name and (optionally) the name of a server where that share is active. If it is explicitly specified, the machine should be on your local Microsoft Windows Network; if it is wildcarded (passed as an asterisk "*"), a connection will be established with the first available machine offering the specified share name. If no server name is specified, Visual PRO/5 will only look for the share on your local workstation. It is also possible to pass the name of your local workstation as the server name. The following is an example of the syntax for a network OPEN:

OPEN (CHAN,MODE="NDDECLIENT")"[servername:]sharename"

Underneath this connection protocol, network DDE is still connecting to a service:topic pair, just like local DDE. When a conversation is successfully established with a DDE share, the network DDE handler on the machine where that share resides looks up the appropriate service:topic information in a table that is created when the DDE share is established.

NOTE: NETWORK DDE WARNING: A successful OPEN call does NOT guarantee that you have a connection to the application you requested. It only means that you successfully connected to the DDE handler on the machine you specified. To confirm that the connection to the application was successful, you must successfully perform a DDE operation with that application. (Unfortunately, this problem seems to be inherent to Network DDE.)

READ/WRITE

Once a connection is established, it is possible to read and write data across that connection. Visual PRO/5 offers a very limited interface; it simply passes the data back and forth. The programmer is responsible for interpreting the data. The "key=" option is used to specify the DDE Item for which data will be exchanged on each given read or write. It is only necessary to specify an item key on the first read or write after a channel is opened, or when you want to change items; Visual PRO/5 remembers the current item key for a channel. DDE WRITE statements must be terminated by null strings.

READ RECORD (chan{,key="item"}){strvar}
WRITE RECORD (chan{,key="dde_execute"}){strvar}+$00$

CLOSE

The CLOSE verb ends a DDE connection.

CLOSE (chan)

Local DDE Examples

DDE conversations with Visual PRO/5 are conducted in a manner similar to file operations. Visual PRO/5 attempts to contact the other application by opening a channel with a special mode. After that, the transfer of information between applications is conducted via regular reads and writes to the channel.

In the following example, the application, item, and topic components for the Program Manager are all the same:

0010 REM This program reads the groups defined in Program Manager
0020 PRINT 'CS'
0030 OPEN (1,MODE="DDECLIENT")"Progman:Progman"
0040 READ RECORD(1,KEY="Progman")TEXT$
0050 PRINT "Current Program Manager Groups:",$0D0A$,TEXT$
0060 CLOSE (1)

Line 30 initiates the DDE conversation by opening a channel with the DDE mode. Line 40 reads the information desired: a listing of groups defined in the Program Manager. Note that in order to query the Program Manager's groups, we had to know the Program Manager's executable name, shared topic, and shared items.

The following example makes use of the fact that the Program Manager responds to the command "[CreateGroup(groupname)]" in order to create a group:

0010 REM This program shows how to create and delete Program Manager Groups
0020 OPEN (1,MODE="DDECLIENT")"Progman:Progman"
0030 LET CMD$="[CreateGroup(DDE Test)]"+$00$
0040 WRITE RECORD(1,KEY="DDE_EXECUTE")CMD$
0050 INPUT "Hit <CR> to delete the DDE Test group",*
0060 LET CMD$="[DeleteGroup(DDE Test)]"+$00$
0070 WRITE RECORD(1,KEY="DDE_EXECUTE")CMD$
0080 CLOSE (1)

It also demonstrates the ease with which Visual PRO/5 can be used to send commands to and manipulate other programs.

Network DDE Example

Current versions of Microsoft Windows that ship with MS Windows Network capability (Windows for Workgroups, Windows NT, and Windows 95) are packaged with the DDE-capable "ClipBook Viewer" application. What follows is an example using network DDE to read data from a ClipBook share. On workstation "Steve" you will capture some text onto the Clipboard. Then you will establish a remote DDE connection from the workstation "Phil" to the Clipboard viewer on "Steve" and read the captured text into a Visual PRO/5 variable.

  1. From the Program Manager, open the ClipBook Viewer application. This application can be on your local machine or on a remote machine that is accessible via the Microsoft Windows Network. This example assumes you are accessing a remote machine. You can keep the operations local by omitting the server name when making the Visual PRO/5 OPEN call.

  2. Capture some text into the Clipboard on the machine who's Clipboard is to be read, then choose Paste... from the Edit menu in the Clipbook Viewer.

  3. The ClipBook Viewer will then ask for a share name for your page. (Call it DDETEST.) Be sure the Share Item Now box is checked before clicking OK.

  4. The ClipBook Viewer will then bring up the Share ClipBook Page box. Check the Start Application On Connect box and click OK.

  5. The DDETEST ClipBook page should now contain the text you captured into the Clipboard, and make that text available to other machines on the network.

  6. From Visual PRO/5, open a conversation with the ClipBook Viewer. Assume the machine you established the ClipBook share on is called "Steve". The syntax for the OPEN call would then be:

    OPEN (1,mode="NDDECLIENT")"Steve:CLPBK$"

    "Steve" is the name of the remote machine where you make the DDE connection. CLPBK$ is the name of the DDE Share for the ClipBook Viewer itself.

    Note that CLPBK$ does not refer to a Visual PRO/5 string variable. The literal text, complete with the dollar sign, is being passed to the DDE system.

  7. On "Phil" read a list of topics offered by the remote share. The ClipBook Viewer offers several data items that are accessible via DDE. To retrieve a list of objects being shared from the Viewer, pass the "Topics" item name in the "key=" option:

    READ RECORD (1,key="Topics")A$

    If you print A$, you will notice that the text $DDETEST appears in the returned string. (Visual PRO/5 does not massage the data returned over the DDE link in any way. It is the programmer's responsibility to understand and interpret the format in which the remote application returns data.) $DDETEST is the name of the remote share to which you will next connect.

  8. On "Phil" close the connection to the ClipBook Viewer and open a connection to your test page.

    CLOSE(1)
    OPEN(1,mode="NDDECLIENT")"Steve:$DDETEST"

  9. Read the data from the page.

    Now that you are connected to the page, you must again specify an item key to retrieve its contents. In this case you will use the "&Text" key, which tells the application to return any data it can in the Visual PRO/5-supported CF_TEXT format.

    READ RECORD(1,key="&Text")A$

  10. Print the value of A$. It is the data you originally pasted onto the clipboard.

DDE TCB(10) Errors

Some possible TCB(10) values for DDE-related errors are:

TCB(10)

Meaning

16386

Application Returned Busy

16390

Invalid Parameter

16391

Low Memory

16392

Memory Error

16393

Transaction Not Processed

16394

No Conversation Established

16398

Server Died

16399

System Error