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.
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.
This package is beta release software.
Enables DDE connections between one client up to 20 services/server applications.
Request, execute and poke transactions can be performed synchronously and asynchronously. Advise transactions are not implemented since I don't have any idea how they work and no examples to test.
Errors occurring during a conversation are reported and the the program is terminated. They are displayed in the interactions windows, if DrScheme is used.
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.
This package contains the following main files and directories:
/docs Directory of documentation files
/compiled Directory for compiled module files
/dll Directory for source and additional files of DDEClient.dll
/dll/DDEClient.dll C/C++ dynamic link library for DDE connectivity
ddeclient.ss Interface module between DDEClient.dll and PLT-Scheme
ddeclientsample.ss Sample program
info.ss Package specific file for installation
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.
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
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) in the interaction window and look at the output. After that experiment with it, copy blocks and change them in your own programs.
ddeclient.ss into your own programs require it as follows:
(require (planet "ddeclient.ss" ("mato" "ddeclient.plt" 1 0)))
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.
Initializes DDEML.dll, which provides the DDE features of the operating system
Establishes DDE connection to a service
One or more of the following procedures do the actual DDE transaction:
universal command for execute, poke and request transactions
request for data
request for data as string
execute a command in the service application, i.e. menu command to open a certain file
send data to the service application
Closes down the DDE connection to a service of a server, frees memory
Most of the procedure arguments are the same ones for different procedures. They are described here together.
[number] conversation number, returned by dde-connect, index number to refer to a certain dde conversation.
[string] type of DDE transaction can be "execute", "poke" or "request".
[string] the command you want to send to the service. I.e. to see what topics are available you can set it to ``topics'' in a request transaction, after connecting the service with the topic ``system'', but not all programs support this topic. The available commands are dependent on the service and topic. Look up the documentation of the service for information about them. Note: A major drawback of using DDEML.dll is that
itemmust not exceed 255 characters. If it is longer there will be an error.
[string] data you send by a poke command to the service.
[string] format of DDE data. It determines in which format the data between the applications is sent. See 9 below.
[number] indicates the waiting time in milliseconds until the transaction waits to be finished before returning to the program. If the number is greater 0 and the service doesn't return in time the transaction is terminated. 0 indicates an asynchronous transaction, which means the transaction is waiting for the service's answer as long as it takes.
[string] flag in which format DDE data is copied to DDEClient.dll variables. It is meant for convenience since a lot of conversations only use ascii strings. It can be
"string". Has to be
"byte"in case strings other than ascii format should be read. In that case the returned byte-string has to be converted accordingly, i.e. by
Initialize DDEML.dll the basic dll for DDE. DDEML.dll is installed with the operating system, so normally there is nothing to do to access it. To be called once in a program before any other DDE procedure.
(dde-connect service topic) -> number
Establish a connection to a service for a conversation. Returns a number which distinguishes the conversation from others. Service is a string containing the name of a DDE server application, i.e. ``winword'', usually the service name is the name of the programs exe-file. Topic is a string of the topic the service is connected for. There are different themes over which you can communicate with the service. Often a topic is a file name which is currently open in the service application. Most servers support also a topic ``system''.
Cancel a conversation and stop the connection to a service; meaning of argument see 8.1.
(dde-cmd conv type item data format timeout access) -> multiple
General procedure for execute, poke and request transactions, the communication with the service; meaning of arguments see 8.1. The return value depends on
type = "request"will have a return value.
access = "byte"returns data as byte-string.
access = "string"returns data as string.
(dde-request conv item format timeout) -> byte-string
Abbreviation of a dde-cmd request transaction, which returns DDE data as byte-string; meaning of arguments see 8.1. The byte-string leave the flexibility how the data are further analyzed to the programmer.
(dde-request-string conv item timeout) -> string
Abbreviation of a
dde-cmdrequest transaction, which returns DDE data as string; meaning of arguments see 8.1.
(dde-execute conv item timeout)
Abbreviation of a
dde-cmdexecute transaction, format is
CF_TEXT; meaning of arguments see 8.1.
(dde-poke conv item data timeout)
Abbreviation of a
dde-cmdpoke transaction, format is
CF_TEXT; meaning of arguments see 8.1.
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.
Null-terminated, plain ANSI text in a global memory block.
A bitmap compatible with Windows 2.x.
A Windows metafile with some additional information about how the metafile should be displayed.
An ASCII text format used by some older Microsoft products.
Software Art's data interchange format (DIF). Also an ASCII text format.
Tag image file format (TIFF) data in a global memory block.
CF_TEXTbut using the OEM character set.
A global memory block containing a Windows device-independent bitmap (DIB) as a BITMAPINFO structure followed by the bitmap bits.
A color-palette handle. (Used in conjunction with
Data is for the pen extensions to Windows.
Resource interchange file format (RIFF) data as a global memory block.
A specific case of RIFF in which the contained data is a waveform (sampled sound).
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.
- 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:
- The interaction between client and server, which is of a certain type like
- 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.