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.

• 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.

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:

• /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

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.

• dde-init
  Initializes DDEML.dll, which provides the DDE features of the operating system

  • dde-connect
    Establishes DDE connection to a service

    • One or more of the following procedures do the actual DDE transaction:

    • dde-cmd
      universal command for execute, poke and request transactions

    • dde-request
      request for data

    • dde-request-string
      request for data as string

    • dde-execute
      execute a command in the service application, i.e. menu command to open a certain file

    • dde-poke
      send data to the service application

  • dde-disconnect
    Closes down the DDE connection to a service of a server, frees memory

• dde-uninit
  Uninitializes DDEML.dll

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.

• conv
  [number] conversation number, returned by dde-connect, index number to refer to a certain dde conversation.

• type
  [string] type of DDE transaction can be "execute", "poke" or "request".

• item
  [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 item must not exceed 255 characters. If it is longer there will be an error.

• data
  [string] data you send by a poke command to the service.

• format
  [string] format of DDE data. It determines in which format the data between the applications is sent. See 9 below.

• timeout
  [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.

• access
  [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 "byte" or "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 bytes->string/utf-8.

8.2  List of procedures

• (dde-init)
  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-uninit)
  End usage of DDEML.dll. To be called after the last dde procedure of a program.

• (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''.

• (dde-disconnect conv)
  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 and access. Only 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-cmd request transaction, which returns DDE data as string; meaning of arguments see 8.1.

• (dde-execute conv item timeout)
  Abbreviation of a dde-cmd execute transaction, format is CF_TEXT; meaning of arguments see 8.1.

• (dde-poke conv item data timeout)
  Abbreviation of a dde-cmd poke transaction, format is CF_TEXT; meaning of arguments see 8.1.

• (dc-dde-version) -> string
  returns a string with information about the version of DDEClient.dll.

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.

• CF_TEXT
  Null-terminated, plain ANSI text in a global memory block.

• CF_BITMAP
  A bitmap compatible with Windows 2.x.

• CF_METAFILEPICT
  A Windows metafile with some additional information about how the metafile should be displayed.

• CF_SYLK
  An ASCII text format used by some older Microsoft products.

• CF_DIF
  Software Art's data interchange format (DIF). Also an ASCII text format.

• CF_TIFF
  Tag image file format (TIFF) data in a global memory block.

• CF_OEMTEXT
  Similar to CF_TEXT but using the OEM character set.

• CF_DIB
  A global memory block containing a Windows device-independent bitmap (DIB) as a BITMAPINFO structure followed by the bitmap bits.

• CF_PALETTE
  A color-palette handle. (Used in conjunction with CF_DIB.)

• CF_PENDATA
  Data is for the pen extensions to Windows.

• CF_RIFF
  Resource interchange file format (RIFF) data as a global memory block.

• CF_WAVE
  A specific case of RIFF in which the contained data is a waveform (sampled sound).

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:

www.angelfire.com/biz/rhaminisys/ddeinfo.html

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''

www.functionx.com

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
http://www.faweb.net/us/ioserver/sample_vc.html

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

Client

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

Service

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".

Transaction

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

Conversation

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.