22.2 Client interface

22.2.2 Automatically managed conversations

There is an alternative to manually establishing a conversation and then disconnecting it once all transactions between server and client are concluded: the automatically managed conversation. Client functions that end with a * conduct automatically managed conversations.

A function handling an automatically managed conversation takes a service designator and topic designator as two of its arguments, and either automatically establishes a conversation with a server responding to the service designator/topic designator pair, or uses an existing equivalent conversation. For the purpose of brevity, functions conducting automatically managed conversations are only briefly mentioned in this chapter. For the details see dde-advise-start*, dde-advise-stop*, dde-execute*, dde-execute-command*, dde-execute-string*, dde-item*, dde-poke* and dde-request*.

22.2.3 Advise loops

A LispWorks client can set up an advise loop across a conversation using dde-advise-start, which takes a conversation (or a service designator/topic designator pair in the case of an automatically managed conversation using dde-advise-start*), an item, and a key as its main arguments. The key argument defaults to the conversation name, and can be used to distinguish between multiple advise loops established on the same service/topic/item group.

Whenever the data monitored by the advise loop changes, a function is called to inform the client. By default this function is the generic function dde-client-advise-data. You can add methods to dde-client-advise-data specialized on the key or the client conversation class. Alternatively, you can supply a different function in the call to dde-advise-start.

Note: a DDE advise loop is not a loop in the program source code. In particular it should not be confused with the "event loop" which is a loop in source code that processes low level events.

22.2.3.1 Example advise loop

The example shows you how to set up an advise loop. The code assumes that win32 package symbols are visible.

The first step defines a client conversation class, called my-conv.

(defclass my-conv (dde-client-conversation)

())

The macro define-dde-client can now be used to define a specific instance of the my-conv class for referring to a server application that responds to the service name "FOO".


(define-dde-client :foo :service "FOO" :class my-conv)

The next step defines a method on dde-client-advise-data which returns a string stating that the item has changed.

(defmethod dde-client-advise-data ((self my-conv) item data &key

&allow-other-keys)

  (format t "~&Item ~s changed to ~s~%" item data))

Finally, the next command starts the advise loop on the server foo, with the topic name "file1", to monitor the item "slot1".


(dde-advise-start* :foo "file1" "slot1")

When the value of the item specified by "slot1"" changes, the server calls dde-client-advise-data which returns a string, as described above.

The function argument of dde-advise-start and dde-advise-start* specifies the function called by the advise loop when it notices a change to the item it is monitoring. The function is dde-client-advise-data by default. A different function can be provided, and should have a lambda list similar to the following:


key item data &key conversation &allow-other-keys

The arguments key and item identify the advise loop, or link. The argument data contains the new data for hot links; for warm links it is nil.

Advise loops are closed using dde-advise-stop or dde-advise-stop*.

22.2.4 Request and poke transactions

LispWorks clients can issue request and poke transactions across a conversation using dde-request and dde-poke, which take a conversation (or a service designator/topic designator pair in the case of an automatically managed conversation), and an item as their main arguments. In the case of a poke transaction, data to be poked into item must also be provided.

In the case of a successful request transaction with dde-request or dde-request*, the data contained in item is returned to the LispWorks client by the server.

In the case of a successful poke transaction with dde-poke or dde-poke*, the data provided is poked into item by the server.

The accessor dde-item (or dde-item* for automatically managed conversations) can perform request and poke transactions. It performs a request transaction when read, and a poke transaction when set.

22.2.5 Execute transactions

A client can issue an execute transaction across a conversation, or in the case of an automatically established conversation, to a recognized server. There is no need to specify a topic, as an execute transaction instructs the server application to execute a command.

The command and its arguments are issued to the server in the form of a string in a standard format (see Execute transactions). LispWorks provides two ways of issuing an execute transaction, namely dde-execute-string and dde-execute-command (and the corresponding * functions that automatically manage conversations).

The following example shows how dde-execute-string* can issue a command to a server designated by :excel on the topic :system, in order to open a file called foo.xls:


(dde-execute-string* :excel :system "[open(\"foo.xls\")]")

The function dde-execute-command takes the command to issue, and its arguments, and marshals these into an appropriate string for you. The following example shows how dde-execute-command* can issue the same command as in the previous example:


(dde-execute-command* :excel :system `open `("foo.xls"))