DDEInitiate(), DDETerminate(), DDEAbortTrans(), DDEPoke(), DDERequest(), DDEExecute(), DDELastError(), DDESetOption(), DDEAdvise(), DDEEnabled(), DDESetService(), DDESetTopic()

Despite all the hoopla you’ve heard about the wonders of OLE, COM and ActiveX, Dynamic Data Exchange—one of COM’s forebears—is not yet dead. Getting on in years, yes. Dead, no, not just yet.

In most cases, we prefer to use the COM technologies when developing communications between applications. COM communications are more robust, support richer data types, and are more easily integrated into an OOP environment. But it takes two to tango. If the application on the other end of the phone speaks only DDE, then that is the language FoxPro must speak, too. Visual FoxPro supports the whole complement of DDE commands, providing capability as a client or a server.

In case you’re new to the DDE scene, let’s do a brief overview of the ways in which DDE can be used. DDE is often described as similar to a phone conversation. One party initiates the phone call, the two parties exchange information, and the parties terminate the call.

If VFP is the calling application—if we’re driving the conversation—we first DDEInitiate() the conversation with the other party. This other application is commonly referred to as the server, confusing the situation with client-server database technology (as well as with Web technology). The client in DDE is the one running the show, running the code, and the server is the application that responds. DDERequest() and DDEPoke() provide the verbs to get and set variable values. DDEExecute() passes a command to the server. DDETerminate() completes the conversation.

DDELastError() is the function used to get the details when things go wrong.

It may be that we don’t want to talk with the server as much as register an interest in the values it has in a particular document, and ask to be advised if these change. DDEAdvise() is the trick for this. Again, you DDEInitiate() and DDETerminate() a conversation, with the request for DDEAdvise() in the middle.

Finally, if your application must play the server and be called upon by other applications, DDESetService() defines the services available, DDESetTopic() sets (surprise!) the topics of the conversations, and DDEEnable() allows the server to toggle on and off DDE services while processing.

As we said before, DDE is never our first choice for interprocess communication mechanisms. But for those applications that support only DDE, or in situations of limited resources, Visual FoxPro is up to the task of communicating well using DDE. Visual FoxPro can carry on a variety of conversations, working as a client with cold, warm and hot links, as well as working as a DDE server.

If you’re really interested in the DDE server stuff, a trip down memory lane is required. The FoxPro development environment itself is not a DDE server, but rather the interface is in place for you to hook up your own application as a DDE server. Not much is documented in this version, but Mike Taylor of MicroMega wrote a cool application, FoxData, as a FoxPro DDE server. It was included with the sample code for FoxPro 2.x, and it demonstrated some neat little nooks and crannies in getting FoxPro to work. In addition, several excellent magazine articles and at least one book (listed in the references in the appendices) get into DDE in some depth.

Usage

nChannel = DDEInitiate( cAppDDEName, cTopic )
lReturn = DDETerminate( nChannel | cAppDDEName )

DDEInitiate() is used to start a conversation between two applications, and DDETerminate() to finish it. Negative or false returns from these functions (and the ones below) are indicative of errors that should be checked out with DDELastError().

DDEInitiate() attempts to start a conversation with another application by searching the list of DDE servers available in memory. By default, if the server isn’t running, FoxPro offers to start the server by popping a dialog up on the screen. Typically, this is an option you will not want to offer the end user. You probably want to start the application if it isn’t running. Use DDESetOption() and the RUN command to do this, as shown in the second example below.

Most of the tricks to using DDE involve finding out the names of the services and topics available, and the commands and syntax the application recognizes. Far too often these are poorly documented, if they’re documented at all.

Example

? DDEInitiate("WinWord","Document1")

= DDESetOption("Safety",.F.)  && Turn off dialogs
nChannel = -1
nTries = 0
DO WHILE nChannel = -1 and nTries < 3
  nChannel = DDEINITIATE("WinWord","System")
  IF nChannel = -1  && Command failed
    IF DDELASTERROR() = 16  && Connect failure
      nTries = nTries + 1
      * You'll need to fully qualify the path to
      * your server, below, or this will fail.
      RUN /N7 WINWORD.EXE
    ENDIF
  ENDIF
ENDDO
IF nTries = 3  && Three tries and you're out...
  WAIT WINDOW "Three strikes, you're out."
ELSE
  WAIT WINDOW "Good to go!"
ENDIF

Usage

lResult = DDEAbortTrans( nChannel )
uResult = DDEPoke( nChannel, cItemName, cData
                   [ , cFormat [ , cAsynchUDF ] ] )
uValue = DDERequest( nChannel, cItemName
                     [ , cFormat [ , cAsynchUDF ] ] )

DDERequest() and DDEPoke() are the read and write equivalents of transactions via DDE. DDERequest() requests a value from another application and DDEPoke() places a value in it.

In some cases, poking or requesting a value might cause the server application to have to go off and do some number crunching or other time-consuming processing. In this case, an “asynchronous” connection can be made, whereby the server app “calls back” Visual FoxPro when the deed is done, and passes back results by starting a User-Defined Function (UDF) within FoxPro and passing it several parameters. It is up to your application to monitor an asynchronous transaction, because the DDESetOption(“Timeout”) value does not apply. If an excessively long time has passed or other conditions make the transaction no longer necessary, the transaction can be halted with DDEAbortTrans().

Example

* get the value of cell 2,3
nValue = VAL(DDERequest(nExcel,"R2C3"))

Usage

lResult = DDEExecute( nChannel, cCommand )
nResult = DDEExecute( nChannel, cCommand, cAsynchUDF )

DDEExecute() allows Visual FoxPro to pass commands to the DDE Server, which the server then executes.

Example

* Send the command to WinWord to print the current document
=DDEExecute(nWord,"[FilePrint]")

Usage

nValue = DDELastError()

Use DDELastError() to detect problems that DDE is having. Rather than firing the global error handler set in ON ERROR, this function gives you the option of handling the error locally.

Example

IF DDELastError() = 0  && no error, continue processing

Usage

lValue = DDESetOption( "Safety" [, lSafetyOn ] )
lValue | nValue  = DDESetOption( "Timeout" [, nTimeout ] )

This function is the DDE equivalent of the SET command and matching SET() function. Without the second parameter, it returns the present setting; with the second parameter, it sets the specified setting to the passed values. With Safety set to .F., our recommended setting, you will need to do more error checking, but your users will not be presented with dialogs allowing them to mangle the DDE portion of your application. As for Timeout, we expect that you might need to raise it for slower systems or systems with a lot going on, but we’ve never had to mess with the settings ourselves.

Example

? DDESetOption("Timeout") && Display the current timeout

Usage

lValue = DDEAdvise( nChannel, cItemName, cUDFName, nTypeLink )

This function allows the creation of “warm” and “hot” links between Visual FoxPro and another application. Both cause a Visual FoxPro routine to run when a change occurs in their environment. The difference between the two link types is that the warm link only notifies Visual FoxPro of the change, while the hot link passes the changed data as well.

The routine you indicate receives six items, similar to the AsynchUDF in DDEPoke() and DDERequest() above. Your Visual FoxPro application can then determine what action to take based on this new data.

Example

* This command sets up a hot link between an open Excel DDE
* conversation and FoxPro. If the operator or a function
* changes the value of the contents of row 2, column 2, the
* FoxPro routine will run.
= DDEAdvise(nExcel, "R2C2", "MyUDF", 2)

Usage

lValue = DDEEnabled( [ nChannel ]  [ , lOnOff ] )