About DDE support in Common Graphics

DDE stands for Dynamic Data Exchange. Quoting from the Windows API Bible (a standard reference for programming with Windows): "Dynamic Data Exchange is a message protocol that allows Windows applications to exchange data."

Here we briefly describe the functionality available in Lisp for DDE. Note that we do not describe DDE in much detail. We assume you are familiar with using DDE between Windows applications. If you are not, please refer to standard Windows programming manuals. Here are some principles of using DDE in Lisp:

• Creation and management of DDE "string handles" is done automatically. You simply pass in Lisp strings or keyword symbols that name applications, topics, and items without worrying about the string handles.
• Rather than deal with the DDE callback function directly, you can simply supply a few Lisp methods which are invoked automatically when callbacks occur.
• Conversations with other tasks are implemented as CLOS instances (called ports), so you don't need to deal with the conversation handles directly.
• Lisp can act as either a client or server, and handle cold, warm, and hot links. Currently the only clipboard data format supported is text.

Example

There is a simple example illustrating the DDE functionality in examples\cg\dde\examples.cl. Also in that directory is ddedoc.txt which contains most of the information in this entry.

Creating a port where Lisp is the DDE client

Create a client-port instance by calling make-instance on the client-port class. Available initargs are:

• name: an arbitrary object (typically a symbol) to name this port. Defaults to :client-n, where n is an integer that is auto-generated to make the name unique.
• application: the "service" name of the DDE server application that this port will connect to. This is often the filename of the executable image that is run, such as "progman" for the Program manager, but can be any arbitrary string that that server chooses to use. This value can be either the official DDE string or the keyword symbol whose print name is that string.
• topic: the particular topic of the application that this port will address. (To address multiple topics of the same application, you must create multiple port instances.) This value can be either a string or a keyword symbol.

These attributes can be changed after the instance is created using setf and the accessors port-name, port-application, and port-topic (all are setf'able). The new values will be used if the port is closed and re-opened.

Example of creating a port:

;; Create a port with the program manager acting as the DDE 
;; server
(setq port1 (make-instance 'client-port
              :application :progman
              :topic :progman))

DDE and Multithreading

Any single DDE port (either a client or server port) will work only within a single thread during the time that it is open, and so all of the application code that uses a particular DDE port should run only in one thread. (A port could be opened and closed in one thread and then later opened and closed in another, but it would likely be tricky to ensure that the threads do not have the port open at the same time.)

When a DDE port is opened in a thread, a dde-info instance is created for that thread. The function dde-info applied to the process associated with a thread returns that instance, which can be used as the argument to various generic functions which provide information about the port.

The generic function can be used to poll and set values in a dde-info instance.

Separate DDE ports work in separate threads. Allegro CL will continue to automatically initialize DDE as needed whenever a first port is opened, though now this is handled separately in each thread that begins to use DDE.

DDE Functionality

• active-client-ports
• active-server-ports
• answer-request
• case-sensitive-dde (which uses *case-sensitive-dde* for its default)
• close-port
• close-server
• convert-returned-dde-buffer
• convert-returned-dde-string
• dde-info (the class)
• dde-info (the function)
• execute-command
• list-to-tabbed-string
• open-port
• open-server
• port-open-p
• post-advice
• receive-advice
• receive-value
• send-command
• send-request
• send-value
• server-active-p
• service-name (which uses *service-name* for its default)
• service-topics (which uses *service-topics* for its default)
• sysitems (which uses *sysitems* for its default)
• tabbed-string-to-list
  

Copyright (c) 1998-2002, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 6.2. This page was not revised from the 6.1 page.
Created 2002.2.26.