CICA 1992 November/CICA_MS_Windows_CD-ROM_Walnut_Creek_November_1992.iso/win3/programr/ddeapp/ww0117t.txt

Text File | 1991-08-09 | 43KB | 1,109 lines

======================================================================
             WW0117: WINDOWS DYNAMIC DATA EXCHANGE (DDE)
======================================================================
                                                   Revision Date: 8/91
--------------------------------------------------------------------
| INFORMATION PROVIDED IN THIS DOCUMENT AND ANY SOFTWARE THAT MAY    |
| ACCOMPANY THIS DOCUMENT (collectively referred to as an            |
| Application Note) IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY      |
| KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO    |
| THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A     |
| PARTICULAR PURPOSE. The user assumes the entire risk as to the     |
| accuracy and the use of this Application Note. This Application    |
| Note may be copied and distributed subject to the following        |
| conditions: 1) All text must be copied without modification and    |
| all pages must be included; 2) If software is included, all files  |
| on the disk(s) must be copied without modification [the MS-DOS(R)  |
| utility DISKCOPY is appropriate for this purpose]; 3) All          |
| components of this Application Note must be distributed together;  |
| and 4) This Application Note may not be distributed for profit.    |
|                                                                    |
| Copyright 1991 Microsoft Corporation. All Rights Reserved.         |
| Microsoft, MS-DOS, and the Microsoft logo are registered           |
| trademarks and Windows is a trademark of Microsoft Corporation.    |
 --------------------------------------------------------------------


                             INTRODUCTION
                             ============

The Windows dynamic data exchange (DDE) protocol is a set of
guidelines that allows applications to share data freely. DDE uses
either one-time data transfers or ongoing conversations in which
applications send updates to one another as new data becomes
available. This document introduces Windows DDE through some examples
of its use and a detailed example of the operation of the protocol.


DDE COMMUNICATIONS CAPABILITIES
===============================

It is important to understand that no changes are required to the
current or previous shipping versions of Windows to use DDE. Windows
allows for very flexible intertask communication. The primary means of
communication is the passing of messages. Windows applications receive
all of their input in the form of messages. All characters typed at
the keyboard, all mouse activity, and all menu selection events are
sent to the appropriate Windows applications through messages.

In Windows, applications can define private messages that have a
unique meaning throughout the system. The DDE protocol defines some
new messages for communication between the applications that use DDE.
Windows also provides for the sharing of data between applications.
The DDE protocol uses shared memory as the means of transferring data
from application to application. DDE defines some structures to be
used for the contents of the shared memory objects, all of which are
discussed below.


BASIC RULES
===========

DDE is a protocol that allows applications to exchange data on a real-
time basis. To perform such an exchange, the two participating
applications first have to engage in a DDE conversation. The
application that initiates the conversation is known as the client
application, and the application responding to the client is known as
the server application.  A given application can be engaged in several
conversations at the same time and can act as the client application
in some of them and as the server application in others.

Information transferred between applications using DDE can be
formatted in a number of ways. Client applications may not support all
of the formats available or may prefer certain formats. In general,
you do not need to be aware of the different formats, because the
client and server applications automatically determine a format and
use it to transfer information.

A DDE conversation between two applications actually takes place
between two windows, one for each of the participating applications.
An application opens a window for each conversation it engages in
(note that this window is not typically visible).

DDE uses the three-level hierarchy -- application, topic, and item --
to uniquely identify a unit of data. Application is the name of the
DDE server. Item is a data object that can be passed in a DDE data
exchange. Topic is a logical data context. For applications that
operate on file-based documents, topics are usually filenames; for
other applications, they are other application-specific strings. A
syntax example is

  =Signal|NYSE!IBM

which a spreadsheet would read as follows:

  =Application|Topic!Item

This indicates that the cell content is to be the value of the data
item "IBM" in the topic "NYSE" of the application "Signal".

After a conversation has been started, the client application
interacts with the server by issuing transactions. When issuing a
transaction, the client asks the server to preform a given action.
There are six types of transactions: Request, Advise, Unadvise, Poke,
Execute, and Terminate. These are permitted only within an initiated
conversation. DDE conversations are one-way: the client application is
always the one that issues the transactions. If the server wants to
issue a transaction to the client, the server is expected to initiate
a new conversation for that purpose. The server becomes the client in
this new conversation. (The only exception to the one-way rule is the
Terminate transaction, which can be issued by either the client or the
server.)


DDE CONCEPTS
============

All DDE communication between applications occurs on a channel. The
DDE Initiate function is used to open a channel, and the Terminate
function is used to close a channel.

The application that initiates a channel is called the client, and the
other application is called the server. The client controls the
channel and requests services from the server.

The three functions used by the client on an open DDE channel are
Request, Poke, and Execute. Request gets data from the server, Poke
sends data to the server, and Execute sends commands to the server.

Initiate
--------

The Initiate function opens a DDE channel from a client to a server
application. The Initiate function has two parameters, the server
application name and the topic. The application name is the server
program name without the .EXE extension. If the server application is
not running, the Initiate function automatically starts it. (Initiate
may not automatically start the server from some applications; this is
a Microsoft convention.)

The topic identifies something in the server application that you plan
to access. The topic is often the name of a window in the server
application.

Initiate returns a channel number. The channel number is subsequently
used as a parameter to all other DDE functions to identify the channel
in use. You may have more than one channel open by calling the
Initiate function several times.

An error is returned if the server application is not running and
cannot be started, or if the topic is not valid.

Request
-------

The Request function gets data from the server application. The
parameters are the channel number and the item. The channel number is
the value returned by Initiate. The item identifies the data to be
returned.

The server application returns the desired data. An error is returned
if the channel number is not valid, the item is not valid, or the
server cannot return the data.

Poke
----

The Poke function sends data to the server application. The parameters
are the channel number, the item, and the data. The channel number is
the value returned by Initiate. The item identifies the type of data
being sent. The data is the actual data to be sent to the server.

An error is returned if the channel number is not valid, the item is
not valid, or the server is not able to accept the data.

Execute
-------

The Execute function sends commands to the server application. The
parameters are the channel number and the execute string. The channel
number is the value returned by Initiate. The execute string contains
one or more commands to be executed by the server.

Different server applications support different commands. In general,
the commands that can be sent to an application are the commands in
that application's menus. An error is returned if the channel number
is not valid, or if any errors occur when the server executes the
commands in the execute string. Execute does not return data to the
client.

Terminate
---------

The Terminate function closes a DDE channel. The parameter is the
channel number of the DDE channel to close. An error is returned if
the channel number is not valid.


TERMINOLOGY
===========

Dynamic Data Exchange (DDE)
---------------------------

A Windows protocol that allows two Windows applications to communicate
with each other, allowing for the continuous and automatic exchange of
data without user intervention.

Conversation
------------

Two Windows applications using DDE to exchange data. The conversation
is conducted through a channel. DDE client is the application that
initiated the conversation; DDE server is the application that
responds to the DDE client.

Task Identification Number
--------------------------

A unique number that identifies a specific copy of an application when
several copies are running at the same time. The task ID is appended
to the application name to identify the application (for example,
Excel4321).

Item
----

A reference to a piece of data (such as an integer, a string, a range
of cells in a worksheet, a chart, or a bitmap) that can be passed
between two applications engaged in a DDE conversation.

Topic
-----

Information that defines the "subject" of a DDE conversation and
represents some unit of data that is meaningful to the DDE server
conversation. For most applications that operate on files, this is a
filename (for example, SALES.XLS).


USES FOR WINDOWS DYNAMIC DATA EXCHANGE
======================================

The uses for DDE mentioned in this section are intended simply as a
starting point. There are many possibilities for the use of DDE, and
here we can suggest only a few. These are only ideas for the use of
DDE; they do not represent a commitment on the part of Microsoft to
provide these features in any application.

A sample Excel spreadsheet has the following layout:

          STOCK    SHARES     PRICE    EXTENSION
     1    MSFT       3500        78       155000
     2    LOTS        500        25         4000
     3    TATE       2000        35         7000
     4    IBM        1000       148        80000

Without DDE, you could update this spreadsheet using the Clipboard to
manually copy numbers from the stock quote application into the Excel
spreadsheet. This method requires switching between applications and
requires that you pay attention to the price data and undertake the
data exchange when desired.

With DDE, this system is much more automatic, providing the
spreadsheet with the current values for multiple data items without
your intervention. DDE allows you to set up a conversation between the
server and client applications that keeps the spreadsheet informed of
any changes in the value of the stocks that it has asked about.

Once this connection is established, the cell value will always
reflect the most current data available from the server. No per-
transfer intervention on your part is necessary. This facilitates the
analysis of real-time data in a timely manner.

The usefulness of DDE is not restricted to specialized real-time data
acquisition applications. Productivity software in general can benefit
significantly from the protocol. For example, suppose you want to
prepare a report document monthly using a graphics and text word
processor. The report is to include graphics generated in a separate
business graphics package. Without DDE, you must perform a manual
copy-and-paste process to include each month's new graphs in each
month's report document. With DDE, the word processor can establish a
permanent link to the charting application so that any changes you
make to the charting document are reflected in the word processing
document, either automatically or on request. This makes the routine
of document preparation much simpler.


                            DDE AND EXCEL
                            =============

HOW TO USE THE EXCEL DDE MACRO COMMANDS
=======================================

The examples below all execute another copy of Excel. Any application
that supports the DDE protocol could be substituted for Excel. To
understand the information presented, you should be familiar with the
following (see the "Microsoft Excel Functions and Macros" manual for
further reference):

   Constructing a command macro
   The EXEC macro command
   The EXECUTE macro command
   The INDEX macro command
   The INITIATE macro command
   The POKE macro command
   The REQUEST macro command
   The TERMINATE macro command

Using the INITIATE Command
--------------------------

The syntax is as follows:

   =INITIATE(<app_text>,<topic_text>)

      <App_text> is the DDE name of the application you are accessing.
      <Topic_text> is the item in the application you are accessing.

The sample macro below executes another copy of Excel and initiates
two DDE channels to that copy of Excel. The macro is as follows:

   A2 =INITIATE("Excel","system")
   A3 =INITIATE("Excel","Sheet1")
   A4 =TERMINATE(A2)
   A5 =TERMINATE(A3)
   A6 =RETURN()

After this macro is executed, no values will have been placed in new
locations, but you will have successfully opened and closed two DDE
channels.

Please note the following:

1. Each time the INITIATE command is executed, a new DDE channel is
   opened. Each channel is assigned a unique number starting at 0
   (zero). The cells containing the two INITIATE commands will contain
   0 in the first cell and 1 in the second cell as long as another
   channel from another INITIATE was not left open. If another channel
   was left open, the cells will contain the next increment of the
   channel number.

2. In the above example, DDE channels are initiated with the topics of
   "system" and "Sheet1". Any Excel sheet name is a valid topic for
   use in an INITIATE command. The topic of "system" allows you to ask
   Excel for specific system information. The topics are either
   "system" or the names of current documents.

Using the REQUEST Command
-------------------------

The sample macro below executes another copy of Excel and requests a
value from the worksheet. The following assumptions are made in this
example:

1. A second copy of Excel is being used as the second application for
   the DDE link.
2. The value being requested is contained in cell A1 of AMORTIZE.XLS.
3. Your EXCEL directory is the current directory.

The macro is as follows:

   A3 Comment: DDE request from Excel
   A4 =EXEC("excel library\amortize.xls",2)
   A5 chan=INITIATE("Excel"&A4,"amortize.xls")
   A6 =REQUEST(chan,"R1C1")
   A7 =TERMINATE(chan)
   A8 =RETURN()

After this macro is executed, the value in cell A1 of AMORTIZE.XLS can
be found on the macro sheet in the cell containing the REQUEST
command; in this example, that cell is A6.

When you use the REQUEST command to request data from Excel, any
referencing made must be in R1C1-type format. If this format is not
used, the REQUEST command returns a #REF error.

Using the REQUEST Command for System Information
------------------------------------------------

The following example explains how to use the REQUEST command from an
Excel macro with the topic of "system". The macro executes another
copy of Excel, initiates a DDE channel to that copy of Excel with the
topic of "system", and uses the REQUEST command for system
information. This example assumes that a second copy of Excel is being
used as the second application for the DDE link.

The macro is as follows:

   A3 =INITIATE("Excel","system")
   A4 =INDEX(REQUEST(A3,"SysItems"),3)
   A5 =TERMINATE(A3)
   A6 =RETURN()

The request will return an array of the items supported on the topic
"system". You can use the INDEX function to access each element of the
array of items that is returned.

Please note that the system topic "SysItems" returns a list of
available "system" items. Any item returned by "SysItems" can be used
as a "system" item and, thus, can be used in the REQUEST function. For
Excel, the list of available items includes the following:

   SysItems
   Topics
   Status
   Formats
   Selection

Any of these items is legal for use with the "system" topic in Excel.
In the previous example, you could replace your request for "SysItems"
with one of the items returned -- for example, "formats":

   A18 Comment: Getting SysItems from Excel
   A19 =EXEC("excel",2)
   A20 chan=INITIATE("Excel"&A19,"System")
   A21 =REQUEST(chan,"formats")
   A22 =TERMINATE(chan)
   A23 =RETURN()

To make this macro request the formats from Word for Windows instead,
do the following:

1. Delete Cell A19.
2. Change cell A20 to:

      chan=INITIATE("WinWord","System")

You can use the INDEX function to look up values returned by REQUEST.
However, if more than one value is to be returned by REQUEST, you can
use the FORMULA.ARRAY function in place of INDEX to return all of the
values at once.

Using the POKE Command
----------------------

This example explains how to use the POKE command from an Excel macro.
The sample macro below executes another copy of Excel and places a
value into a worksheet. In the following example:

1. A second copy of Excel is being used as the second application for
   the DDE link.
2. The text to be sent over the DDE channel is contained on the macro
   sheet in cell A39.
3. The text will be placed into Sheet1 in the second copy of Excel.

The macro is as follows:

   A39 Comment: DDE Poke to another Excel
   A40 =EXEC("excel",2)
   A41 chan=INITIATE("Excel"&A40,"Sheet1")
   A42 =POKE(chan,"R1C1",A39)
   A43 =TERMINATE(chan)
   A44 =RETURN()

After this macro is executed, the text that is in cell A39 of the
macro sheet will have been placed in cell A1 of Sheet1 in the second
copy of Excel.

When using the POKE command to place a value in another copy of Excel,
any references made to the destination sheet must be in R1C1-type
format. If this format is not used, the POKE statement returns a #REF
error.


Using the EXECUTE Command
-------------------------

The following macro runs another copy of Excel and makes the other
copy of Excel load the file AMORTIZE.XLS from the LIBRARY directory.
Note the use of the defined name {q} for quotation marks; this is
often a useful technique when sending execute strings that contain
quotation marks.

   A54 Comment: DDE Execute makes another instance of Excel load
       AMORTIZE.XLS
   A55 =EXEC("excel",2)
   A56 chan=INITIATE("Excel"&A55,"Sheet1")
   A57 q=CHAR(34)
   A58 =EXECUTE(chan,"[open("&q&"library\amortize.xls"&q&")]")
   A59 =TERMINATE(chan)
   A60 =RETURN()

Appending a Windows Task ID
---------------------------

The EXEC function returns a task ID number for whatever program it
starts. This task ID number can be appended to the <app_text> field of
the INITIATE function for establishing a DDE channel to the specific
instance of the program started by EXEC.

However, if the topic of your INITIATE function is already opened and
the Ignore Remote Requests box under the Options Workspace menu is
selected, you will get the error message

   Remote data not accessible, start application <APPLICATION.EXE>?

where <APPLICATION.EXE> is truncated/expanded to eight characters, as
with any DOS filename. If the filename contains fewer than eight
characters, then as many of the task ID numbers as will fit to make up
eight characters are appended and displayed. Clearing the Ignore
Remote Requests option corrects the problem. This can be done by
choosing Workspace from the Options menu and manually clearing Ignore
Remote Requests, or by using the WORKSPACE function.

Excel Format Information
------------------------

Valid Excel 3.0 DDE formats are the following:

   XLTable
   BIFF3
   SYLK
   WK1
   CSV
   Text
   Rich Text Format
   DIF
   BITMAP
   METAFILEPICT
   Printer_Picture

Excel cycles through these formats with each request for data until it
receives an acknowledgment from the server. Thus, if a server can
supply data only in Text, Excel cycles through all six formats each
time it requests data from the server.

Speed Issues and DDE
--------------------

When Excel receives DDE messages, the messages are posted on the
application's message queue along with all other Windows messages.
Before Excel processes DDE messages, the messages are taken from the
application's queue and stored in a DDE queue. This queue is limited
to eight items at a given time.

The DDE messages are then processed in tandem with Windows messages on
a priority basis (certain Windows messages having greater priority
than the DDE messages). This accounts for the speed problems that
occur when DDE messages are passed to Excel.

Since the DDE queue is fixed at eight items, some items may be lost if
the transmission speed of the DDE messages is increased. At this time,
the DDE message queue's size cannot be increased. The application
sending the DDE data must slow down the rate at which it sends Excel
DDE messages for Excel to process them.

Sending data to Excel using DDE is fastest if Excel's XLTable format
is used. If another format such as Text or CSV is used, Excel must
take the time to parse and error check the data instead of accepting
it directly.

The limit for consecutive messages for the task (application) queue is
eight. There is no inherent limit set on the number of DDE links that
you can establish within a document. The number is limited only by the
amount of available memory.

Using the ON.DATA Command in Excel
----------------------------------

Use the ON.DATA command in Excel when you want a particular macro to
run any time there is any type of update to a particular worksheet via
DDE. The syntax of the formula is:

   =ON.DATA("<document_text>","<macro_text>")

If executed properly, the macro defined by <macro_text> will run every
time there is a DDE update to the worksheet specified by
<document_text>.

When using the ON.DATA command in Excel, you must verify the
following:

1. Ignore Remote Requests is not selected in Excel (from the Options
   menu, choose Workspace). You can ensure that Ignore Remote Requests
   is not selected by issuing the following macro statement before the
   ON.DATA command:

      =WORKSPACE(,,,,,,,false)

2. The argument for <document_text> in the ON.DATA function must refer
   to a sheet name that contains remote references and only the sheet
   name, not including cell references.

   Valid ON.DATA commands look like the following:

      =ON.DATA("Sheet1.xls","Macro1.xlm!R1C1")
      =ON.DATA("Sheet1.xls","Macro1.xlm!Macro_name")

   You must not reference any particular cells. The following would
   not be valid:

      =ON.DATA("Sheet1.xls!$A$1","Macro1.xlm!R1C1")
      =ON.DATA("Sheet1.xls!Area1","Macro1.xlm!Macro_name")

Using the Topic "System" to Obtain Word for Windows System Information
----------------------------------------------------------------------

To request system information from Word for Windows in an Excel macro,
use the topic "system" when initiating a DDE channel. Once a channel
has been opened with the topic "system", Word for Windows recognizes
the topics SysItems, Topics, and Formats.

   Item         Effect
   ----         ------

   SysItems     Returns a list of all items you can use with the
                "system" topic
   Topics       Returns a list of currently open documents, including
                full paths
   Formats      Returns a list of all the Clipboard formats supported
                by Word for Windows

The Excel macro below does the following:

1. Initiates a DDE channel using the topic "system"
2. Uses the topic "Formats" to get the first three formats supported
   by Word for Windows
3. Places the list into cells A10:A12

The macro is as follows:

   A1     Comment: DDE_Example
   A2     =INITIATE("Winword","system")
   A3     =INDEX(REQUEST(A2,"Formats"),1)
   A4     =FORMULA(A3,A10)
   A5     =INDEX(REQUEST(A2,"Formats"),2)
   A6     =FORMULA(A5,A11)
   A7     =INDEX(REQUEST(A2,"Formats"),3)
   A8     =FORMULA(A7,A12)
   A9     =RETURN()
   A10    Rich Text Format
   A11    TEXT
   A12    METAFILEPICT


                       DDE AND WORD FOR WINDOWS
                       ========================

Word for Windows uses two different types of DDE commands: WordBasic
commands, which are designed for complex or custom DDE conversations,
and DDE fields, intended for simple links updating information from
supporting documents, either manually or automatically.


MACRO COMMANDS
==============

When using DDE with Word for Windows as the client you should use the
Windows Dynamic Link Library GetModuleHandle to determine if your
server application is loaded or not (see page 25 in the "Microsoft
Word for Windows Technical Reference). If it is not loaded, issue a
Shell command to load it. You may also specify the document that will
be loaded.

In the example below, a user defined function IsAppLoaded is declared
(see page 19 in the "Microsoft Word for Windows Technical Reference;"
or pages 70-71 of the "Microsoft Word for Windows and OS/2 Technical
Reference"). IsAppLoaded is a library function in the Windows kernel
listed as GetModuleHandle. IsAppLoaded takes a single string parameter
that is the name of the application you are checking on -- in this
case, Server. If Server is already in memory, IsAppLoaded is true,
returning a non-zero value.

In the following routine, the text between <> should appear as one
line without the <> symbol:

   <Declare Function IsAppLoaded Lib "kernel" (name$) As Integer Alias
   "GetModuleHandle">
   Sub Main
     If IsAppLoaded("Server") = 0 then Shell "server"
     chan = DDEInitiate("server", "stockinfo")
     DDETerminate chan
   End Sub

Note: The term "Server" is used here in a general sense. It could be
replaced with any Windows application's DDE name.

If Server is not in memory, the Shell statement will load it. The
second parameter indicates Server should be loaded as an icon. It is
also possible to specify a filename to be loaded when an application
is Shelled. The syntax is

   Shell "<servername> <path\filename>", 2

where <servername> is the name of the network server you want to
access, and path\filename> is the path to and name of the application
to start.

By using the IsAppLoaded function to determine if the server
application needs to be loaded or not, you can avoid the message
"Remote data (<filename>) not accessible: Start application <appname>
? Y/N ? ". This reduces the need for operator intervention.

We recommend that you use the following code syntax when establishing
DDE communication, replacing the references to Excel and ANNUAL.XLS
with the appropriate server name and topic.

In the following routine, the text between <> should appear as one
line without the <> symbol:

   <Declare Function IsAppLoaded Lib "kernel"(name$) As Integer Alias
   "GetModuleHandle">
   Sub Main
     If IsAppLoaded("excel") = 0 Then Shell "excel c:\annual.xls"
     chan1 = DDEInitiate("excel", "annual.xls")
     DDETerminateAll
   End Sub


Each time a DDEInitiate statement is executed, a new instance of the
server will be loaded. For applications permitting only a single
instance to be loaded this method will generate errors. To overcome
this problem, use the topic "system" when establishing the DDE
channel. This will establish the channel to the application's main
window instead of to a specific file (<topic>). Then use the
DDEExecute commands to open and close individual files as needed.

In the following routine, the text between <> should appear as one
line without the <> symbol:

   <Declare Function IsAppLoaded Lib "kernel"(name$) As Integer Alias
   "GetModuleHandle">
   Sub Main
     If IsAppLoaded("server") = 0 Then Shell "server"
     chan1 = DDEInitiate("server", "system")
     DDETerminateAll
   End Sub

Use of the topic "system" with Word for Windows allows access to three
special items -- SysItems, Topics, and Formats.

   Item       Effect
   ----       ------

   SysItems   Returns a list of all items you can use with the
              "system" topic
   Topics     Returns a list of currently open documents, including
              full paths
   Formats    Returns a list of all the Clipboard formats supported by
              Word for Windows

Word returns these values in CF_Text format (ASCII text). Items in a
list are separated by tabs.


COMMAND SYNTAX
==============

DDEInitiate
-----------

When Word is the client application, DDEInitiate is used to attempt to
start a conversation with another application that will be the server.
If the command is successful, a channel number, which will be greater
than 1, is returned. The number of channels that can be opened is
limited by memory.

Syntax:

   DDEInitiate(<App$>, <Topic$>)

where <App$> is a text string indicating the DDE name of the
application that will be the server. <Topic$> will normally be the
name of a document or file, but this is application specific.

When the DDEInitiate command is executed, a DDE channel is opened to
the specified application and file. The DDE channel numbers begin with
1 and increment as each channel is opened. When a channel is
terminated, that channel number will be reused for the next
DDEInitiate.

In normal usage, the return value -- the channel number -- is assigned
to a variable. Referencing the variable is preferable to using the
actual channel number. For example:

   chan = DDEInitiate ("excel","budget.xls")

If Excel and BUDGET.XLS are found and started, the returned channel
number is assigned to the variable chan. Then, you would use chan when
referring to this channel.

If the <app$> or <topic$> is not found, an error is generated. Using
the WordBasic On Error statements, you can trap these errors and
institute error routines to allow the user to respecify the <app$> or
<topic$> so your macro can continue.

In the example below, the application DDE name for Excel is assigned
to the string variable App1$, and the name of the worksheet wanted,
BUDGET.XLS, to Topic1$. Then, the DDEInitiate command is issued, the
variables App1$ and Topic1$ are used.

In the following routine, the text between <> should appear as one
line without the <> symbol:

   <Declare Function IsAppLoaded Lib "kernel"(name$) As Integer Alias
   "GetModuleHandle">
   Sub Main
     If IsAppLoaded("Excel") = 0 Then Shell "excel"
     App1$ = "excel"
     Topic1$ = "budget.xls"
     chan = DDEInitiate (App1$, Topic1$)
   End Sub

DDE Terminate
-------------

Syntax:

   DDETerminate <ChanNum>

DDETerminate closes a DDE channel after all communication is
completed. It is useful when multiple conversations are going on and
you want to end one while maintaining the others. By assigning a
variable to the returned channel number, you can selectively end
individual DDE conversations.

In the example below, DDE channel chan2 is opened and selectively
closed, and another server is opened while maintaining the DDE channel
chan1. Finally, both channels are closed by issuing individual
DDETerminate statements.

In the following routine, the text between <> should appear as one
line without the <> symbol:

   <Declare Function IsAppLoaded Lib "kernel"(name$) As Integer Alias
   "GetModuleHandle">
   Sub Main
     If IsAppLoaded("excel") = 0 Then Shell "excel"
     chan1 = DDEInitiate ("excel", "budget.xls")
     If IsAppLoaded("server") = 0 Then Shell "server"
     chan2 = DDEInitiate ("server", "stockinfo")
     DDETerminate chan2
     If IsAppLoaded("SB4W") = 0 Then Shell "SB4W"
     chan2 = DDEInitiate ("SB4W", "system")
     DDETerminate chan2
     DDETerminate chan1
   End Sub

DDETerminateAll
---------------

Syntax:

   DDETerminateAll

DDETerminateAll terminates all DDE channels in which Word for Windows
is a client. It can be used as a general cleanup to ensure that all
channels have been closed without you having to know which channels
are open.

In the example below, two independent DDE conversations, chan1 and
chan2, are started, and DDETerminateAll closes both sessions.

In the following routine, the text between <> should appear as one
line without the <> symbol:

   <Declare Function IsAppLoaded Lib "kernel"(name$) As Integer Alias
   "GetModuleHandle">
   Sub Main
     If IsAppLoaded("excel") = 0 Then Shell "excel"
     chan1 = DDEInitiate ("excel", "budget.xls")
     If IsAppLoaded("server") = 0 Then Shell "server"
     chan2 = DDEInitiate ("server", "stockinfo")
     DDETerminateAll
   End Sub

DDERequest$
-----------

Syntax:

   data$ = DDERequest$ (<ChanNum>, <Item$>)

DDERequest$ requests specific information from the server on <Item$>
using the DDE channel designated. The channel must have previously
been opened using DDEInitiate. Because data is returned in CF_TEXT
format, it can only be assigned to a string variable. If a numeric
value is needed, use the Val statement to convert the text string to a
numeric. Pictures or text in rich-text format cannot be transferred
using DDERequest$. If DDERequest$ is unsuccessful, a null string ("")
is returned.

In the example below, a DDE channel to Excel and the worksheet
BUGDET.XLS is opened and assigned to chan. A request for information
on the item IBM is sent. If successful, the current value of the
defined name balance is printed on the status line; otherwise, a null
string is returned, and nothing is displayed on the status line.

In the following routine, the text between <> should appear as one
line without the <> symbol:

   <Declare Function IsAppLoaded Lib "kernel"(name$) As Integer Alias
   "GetModuleHandle">
   Sub Main
     If IsAppLoaded("server") = 0 Then Shell "server"
     chan = DDEInitiate ("server", "stockinfo")
     data$ = DDERequest$ (chan, "ibm")
     Print data$
     DDETerminate chan
   End Sub

In the example below, a channel is opened and information from the
<item$> balance is requested. If the reference "balance" is not
defined in the document BUDGET.XLS, a null string is received.

In the following routine, the text between <> should appear as one
line without the <> symbol:

   <Declare Function IsAppLoaded Lib "kernel"(name$) As Integer Alias
   "GetModuleHandle">
   Sub Main
     chan = DDEInitiate ("excel", "budget.xls")
     data$ = DDERequest$ (chan, "balance")
     Print data$
     DDETerminate chan
   End Sub

DDEPoke
-------

Syntax:

   DDEPoke <ChanNum>, <Item$>, <Data$>

DDEPoke is used by a client to send information to the server. The
string variable <Data$> is sent to the location, <Item$>, using
<ChanNum>. If the <Item$> does not exist, a WordBasic error is
generated.

In the example below, after establishing a DDE channel with Server, a
request is made for the <Item$> TOTAL, which is a named reference in
BUDGET.XLS. If the numeric value of the string returned is 0, the
amount $100.00 is POKEd into the cell referenced by TOTAL. If the
named reference TOTAL does not exist in BUDGET.XLS, a WordBasic error
503, "Process failed in other application," is returned.

In the following routine, the text between <> should appear as one
line without the <> symbol:

   <Declare Function IsAppLoaded Lib "kernel"(name$) As Integer Alias
   "GetModuleHandle">
   Sub Main
     If IsAppLoaded("Excel") = 0 Then Shell "excel"
     chan = DDEInitiate ("excel", "c:\accts\budget.xls")
     data$ = DDERequest$ (chan, "total")
     If val(data$) = 0 then DDEPoke chan, "total", "$100.00"
     DDETerminate chan
   End Sub

DDEExecute
----------

Syntax:

   DDEExecute <ChanNum>, <ExecuteString$>

DDEExecute is used by a client to execute a command, function, or
macro in the server. The string variable <ExecuteString$> is the
server's command, function, or macro. If the <ExecuteString$> does not
exist, a WordBasic error is generated.

When executed, the macro below checks to see if Excel is already
running. If it is not, the macro starts Excel. If you don't know what
sheet(s) is currently open when Excel is loaded, use "system" as the
second parameter of the DDEInitiate command. You can then issue an
Excel OPEN command using DDEExecute to open a specific file.

In the following routine, the text between <> should appear as one
line without the <> symbol:

   <Declare Function IsAppLoaded Lib "kernel"(name$) As Integer Alias
   "GetModuleHandle">
   Sub MAIN
     If IsAppLoaded ("EXCEL") = 0 Then Shell "EXCEL.EXE"
     ExecuteString$ = "=B1{enter}"
     ChanNum = DDEInitiate("EXCEL", "C:\WINDOWS\SHEET1.XLS")
     DDEExecute ChanNum, "[App.Restore()][Formula.Goto( " + Chr$(34) +
        "test" + Chr$(34) + ")]"
     DDEExecute ChanNum,  ExecuteString$
     DDEExecute ChanNum, "[App.Minimize()]"
     DDETerminate ChanNum
   End Sub

The Formula.Goto statement in the above DDEExecute statement is the
equivalent of the following Excel macro statement:

   =FORMULA.GOTO("test")


FIELD CODES -- DDEAUTO AND DDE
==============================

DDE field codes are best used when you are working with a document
containing information from supporting documents that changes
periodically. To maintain the most current information in the
dependent document, use a DDE field code to link to the supporting
document. DDEAuto will handle the updating automatically for you --
always using the most current version of the source document. The DDE
field code allows you to manually update the information by pressing
F9.

You can create these fields three different ways:

1. Manually enter the field brackets by pressing CTRL+F9. Type the
   field type and topic-item information.

2. From the Insert menu, choose Fields and select the DDE field types
   in the Insert Field Type box.

3. From the Edit menu, choose Copy and then Paste Link, selecting the
   Auto Update option if desired.

Syntax:

   {DDE [<path>]<appname> <filename> [<reference>]}

   {DDEAuto [<path>]<appname> <filename> [<reference>]}

Note: The braces -- { } -- are not typed; they are inserted when you
choose Field from the Insert menu (or press CTRL+F9).

If a path is specified, it must include double backslashes ( \\ ). The
<reference> is optional. The following field statement example is an
automatic update link to the server BUDGET.XLS file for cells
R1C1:R4C4. Changing the field name from DDEAUTO to DDE will change the
updating linkage from automatic to manual.

   {DDEAuto c:\\apps\\server\\budget.xls R1C1:R4C4}


INCLUDING EXCEL CHARTS IN WORD FOR WINDOWS DOCUMENTS
====================================================

The easiest way to perform a DDE link from an Excel chart to Word for
Windows is to do the following:

1. In Excel, choose Select Chart from the Chart menu.

2. From the Edit menu, choose Copy.

3. Switch to Word for Windows (by pressing ALT+TAB).

4. Position the insertion point at the point where you want to place
   the chart.

5. From the Edit menu, choose Paste Link.

6. In the Paste Link dialog box, select the Auto Update option if you
   want Word for Windows to automatically update the chart whenever it
   changes in Excel. If Auto Update is not selected, you must select
   the chart and recalculate it (by pressing F9) for new charts to
   appear.

When the above procedure is followed, Word inserts one of the
following fields into the document:

    Auto Update Option   Field Inserted in Document
    ------------------   --------------------------

    Selected             {ddeauto Excel Chart1 "" \* mergeformat}
    Not selected         {dde Excel Chart1 "" \* mergeformat}

Once the chart is placed in the Word document, the chart can be scaled
or cropped.


DISPLAYING DDE LINKED PICTURES
==============================

When you use DDE to link a chart in Excel to a document in Word for
Windows using the Auto Update feature, the charts in some cases will
not be identical.

Because Word for Windows wants the format that will look the best when
printed, it asks Excel for a different format than is displayed by
Excel. Therefore, the images will not always match. For example, color
will not be retained in a chart from Excel that is linked to Word for
Windows if the printer driver being used does not support color.

The WIN.INI parameter AskforPrinterPicture= can be used to determine
how Microsoft Word for Windows will display DDE linked pictures. This
parameter affects only DDE links and should be entered in the
[Microsoft Word] section of the WIN.INI file. To modify the WIN.INI,
use a text editor such as Notepad, or use Word for Windows and save
the WIN.INI as Text Only.

The following example allows Word for Windows to display a DDE paste-
linked picture as it would display when printed:

   [Microsoft Word]
   AskforPrinterPicture=1

If a color printer is installed, then the picture displays in color.
Otherwise, it displays in black and white.

The following example allows Word for Windows to display a DDE paste-
linked picture in color, regardless of the installed printer:

   [Microsoft Word]
   AskforPrinterPicture=0


                   DDE AND Q+E FOR MICROSOFT EXCEL
                   ===============================

Q+E can be used with Excel, Word for Windows, or any other application
that supports DDE. For information on using DDE with Q+E, see the "Q+E
for Microsoft Excel User's Guide."