1  Introduction

It enables DDE connectivity from within PLT-Scheme to other applications to control them and/or exchange data. Although DDE is a very old and not state of the art protocol there is still software around which can only communicate with other software via DDE. The use of such software was the reason for developing this package.

This documentation does not introduce DDE but the use of the provided procedures. For using DDE with a certain program look at this program?s documentation. Because commands and examples how to communicate with it have to be provided there. The example program distributed with this package can be a good starting point to check out the commands and to see if you get what you want from the other application. There is a certain DDE terminology which might be unfamiliar to you. In that case have a look at the Glossary. For any questions, comments, suggestions and your user experience please contact me via email.

2  Realization

Ddeclient.ss relies on a C/C++ dynamic link library DDEClient.dll, which provides the DDE connectivity and exports the necessary C-functions and data. It's written for use with other programs as well, so if you are interested ask me for additional material like docs, header and examples. Ddeclient.ss imports the procedures of DDEClient.dll and provides easier to use procedures for scheme, that user's don't have to worry about freeing memory for example. A disadvantage over this approach is that data returned to the client is converted to scheme values by copying thus using additional memory.

3  Features

This package is beta release software.

4  Requirements

The package was developed and tested under Windows XP SP2 and PLT Scheme 350.4. Anything higher should work anything lower since the introduction of the Foreign Function Interface should also work, but as always there is no guarantee in both directions.

5  Files and Directories

This package contains the following main files and directories:

6  Getting Started

The package contains a sample file ddeclientsample.ss. It's a commented module file which shows examples of the DDE procedures provided by ddeclient.ss. It uses Microsoft Word as service application, since most Windows users will have it on their machines.

Load ddeclientsample.ss in DrScheme with,

(require (planet "ddeclientsample.ss" 
                 ("mato" "ddeclient.plt" 1 0)))

Open Microsoft Word, make sure you have write access to your C:\ drive and there is no file named test.doc. If you don't have write access to C:\ search for the file name C:\test.doc in ddeclientsample.ss and replace it with what ever suits you. The easiest way to open ddeclientsample.ss is to run the require expression above without having opened Word. This causes an error in the interaction window and you can click on its page icon to open the file. Read through the file. It provides a procedure (run). Type (run) in the interaction window and look at the output. After that experiment with it, copy blocks and change them in your own programs.

To load ddeclient.ss into your own programs require it as follows:

(require (planet "ddeclient.ss" ("mato" "ddeclient.plt" 1 0)))

7  Structure of a DDE process

To implement a DDE conversation you need to set up a number of steps which are described below. As structure of DDE process in this document is regarded the set of commands which is needed for a successful DDE conversation. The procedures provides by ddeclient.ss have to be used as follows.

8  Procedures

8.1  List of procedure arguments

Most of the procedure arguments are the same ones for different procedures. They are described here together.

8.2  List of procedures

9  Supported Clipboard Formats

The following formats can be used to determine how the DDE data will be formatted between service and client. Microsoft uses clipboard formats to format data which is exchanged via DDE. Such it is possible not only to transfer text but also other data, for example pictures. If you use anything else than the CF_TEXT format your access argument must be set to "byte" and you have to handle the resulting byte string on your own to get the desired data, which may be a lot of work. The formats themselves are described in the Windows SDK. There are a lot more formats but only the following are available through the DLL. Write the format strings in capitals exactly as they are given here.

10  Thanks

Eli Barzilay and collegues thanks for the foreign function interface. Without it the project wouldn't be possible.

I owe a lot concerning the C/C++, DDE part of this project to the following people, companies through their books or presence of their work on the internet:

for their info on DDE and their example archive xlddec.zip
Jürgen Wolf
and Galileo Computing for his very instructive book on C programming ``C von A bis Z'', at www.galileo-press.de/openbook/c_von_a_bis_z/
Steven Randy Davis
for his book ``C++ for Dummies''
who ever are behind it, for their perfect tutorial on creating dlls at www.functionx.com/visualc/libraries/win32dll.htm, I wouldn't have started without it.
Faweb, Takebishi
for their DDE example at
Graeme S. Roy
for his library mpatrol to check this dll for memory leaks at www.cbmamiga.demon.co.uk/mpatrol/
Robert Schmitt
for his article and binaries to get mpatrol started so quickly at www.codeguru.com/cpp/w-p/win32/tutorials/article.php/c12231/.
Microsoft Knowledgebase
for some articles like KB279721, but the DDE documentation is mostly quiet unreadable in my opinion.

11  Glossary

Application that asks for the conversation, here the scheme program.

In earlier times called server, the application which is to be controlled or serves the client with data. It is normally the name of the application's exe-file, example: "winword".

The interaction between client and server, which is of a certain type like "request", "execute", "poke".

The connection and what happens between client and service. Since a client can have more than one conversation at the same time with different services each conversation is indexed by a distinct number.

Synchronous transaction
In a synchronous transaction the client sends a transaction to the service and waits a certain time for the service to finish. It returns the control to program only if the service finishes the transaction or if the timeout reached.

Asynchronous transaction
In an asynchronous transaction the client does not wait for the service to answer, but returns the control to the program after sending the transaction. To get the data the program has explicitly to ask if the service has returned data. This kind of transaction is preferable if the duration of a transaction is not known. The dde-... commands handle asynchronous transactions in a way that they seem to be synchronous transactions without a timeout. This is very convenient for a lot of applications.